what: add --version flag, .gitignore/mdfmtignore cleanup, empty-file test

why: --version was returning 'Unknown flag' error instead of
printing the package version. Also cleaned up stale .tgz artifact,
converted .mdfmtignore from template to real config patterns,
added empty/whitespace-only input test coverage.

Author: CodeSigils

.gitignore

@@ -16,7 +16,7 @@ tmp/
 .pnpm-store/
 .yarn/
 .cache/
-*.tgz
+pack/
 
 # Agent/tool local state
 .agents/

.mdfmtignore

@@ -1,9 +1,10 @@
-# .mdfmtignore — files and directories to skip with --all
+# .mdfmtignore — files and directories to skip when using --all
 # One pattern per line. Lines starting with # are comments.
 # Patterns ending with / match directory prefixes.
 # Patterns containing * are treated as simple globs where *
 # matches any characters except a path separator (/).
-# Examples:
-#   vendor/        skip the vendor/ directory entirely
-#   *.generated.md skip any file matching this pattern
-#   tmp/           skip the tmp/ directory
+
+node_modules/
+pack/
+*.structure.json
+*.snap

README.md

@@ -102,6 +102,7 @@ mdfmt [options] <path...>
 | `--dry-run`, `-n` | Run pipe-safety preflight, preview changes without writing         |
 | `--audit-tables`  | Print table row cell counts and pipe hazards without writing       |
 | `--no-repair`     | Report repairable table issues instead of modifying them           |
+| `--version`       | Print version number and exit                                      |
 | `--help`, `-h`    | Display help message                                               |
 
 ### File exclusion

SKILL.md

@@ -83,6 +83,7 @@ binary. See the README for details on per-platform auto-wiring.
 - `--dry-run`, `-n`: Run pipe-safety preflight, then show what would be changed without writing files
 - `--audit-tables`: Print table row cell counts and pipe hazards without writing; use before/after agent table edits
 - `--no-repair`: In write modes, report repairable table issues instead of modifying them
+- `--version`: Print version number and exit
 - `--help`, `-h`: Display help message
 
 ### File exclusion

src/index.js

@@ -36,9 +36,9 @@ const { buildSnapshot, validateStructure, loadSnapshot, saveSnapshot, compareSna
 const SKILL_DIR = resolve(__dirname, "..");
 const FORMATTER_MODULE = join(SKILL_DIR, "src", "format-content.mjs");
 const NODE_RUNTIME_MIN_VERSION = 24;
-const LONG_FLAGS = new Set(["check", "fix", "all", "guard", "verify", "fences", "validate", "doctor", "dry-run", "audit-tables", "no-repair", "help"]);
+const LONG_FLAGS = new Set(["check", "fix", "all", "guard", "verify", "fences", "validate", "doctor", "dry-run", "audit-tables", "no-repair", "help", "version"]);
 const SHORT_FLAGS = { h: "help", n: "dry-run" };
-const READ_ONLY_FLAGS = new Set(["check", "validate", "fences", "verify", "doctor", "help", "dry-run", "audit-tables"]);
+const READ_ONLY_FLAGS = new Set(["check", "validate", "fences", "verify", "doctor", "help", "dry-run", "audit-tables", "version"]);
 const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"]);
 
 /**
@@ -48,10 +48,10 @@ const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"]);
  * Throws on unknown flags. The -- separator stops flag parsing.
  *
  * @param {string[]} argv - Process argv array (e.g. process.argv).
- * @returns {{ _: string[], check: boolean, fix: boolean, all: boolean, guard: boolean, verify: boolean, fences: boolean, validate: boolean, doctor: boolean, 'dry-run': boolean, 'audit-tables': boolean, 'no-repair': boolean, help: boolean }}
+ * @returns {{ _: string[], check: boolean, fix: boolean, all: boolean, guard: boolean, verify: boolean, fences: boolean, validate: boolean, doctor: boolean, 'dry-run': boolean, 'audit-tables': boolean, 'no-repair': boolean, help: boolean, version: boolean }}
  */
 function parseArgs(argv) {
-  const args = { _: [], check: false, fix: false, all: false, guard: false, verify: false, fences: false, validate: false, doctor: false, "dry-run": false, "audit-tables": false, "no-repair": false, help: false };
+  const args = { _: [], check: false, fix: false, all: false, guard: false, verify: false, fences: false, validate: false, doctor: false, "dry-run": false, "audit-tables": false, "no-repair": false, help: false, version: false };
 
   for (let i = 2; i < argv.length; i++) {
     const arg = argv[i];
@@ -95,6 +95,7 @@ Options:
   --dry-run, -n     Run pipe-safety preflight, then preview changes
   --audit-tables    Print table row cell counts and pipe hazards without writing
   --no-repair       In write modes, report repairable table issues instead of modifying them
+  --version         Print version number and exit
   --help, -h        Show this help
 
 File exclusion:
@@ -1016,6 +1017,11 @@ function processFile(filePath, args) {
  */
 function main(argv = process.argv) {
   const args = parseArgs(argv);
+  if (args.version) {
+    const pkg = JSON.parse(readFileSync(join(SKILL_DIR, "package.json"), "utf8"));
+    console.log(pkg.version);
+    return 0;
+  }
   if (args.doctor) return runDoctor() ? 0 : 1;
   if (args.help || (args._.length === 0 && !args.all)) {
     printHelp();

test/integration/cli.test.js

@@ -414,6 +414,14 @@ describe('markdown formatter CLI integration', () => {
     assert.match(result.stdout, /--doctor/);
   });
 
+  it('--version prints package version and exits 0', () => {
+    const pkg = JSON.parse(require('fs').readFileSync(join(ROOT, 'package.json'), 'utf8'));
+    const result = runCli(['--version']);
+
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+    assert.equal(result.stdout.trim(), pkg.version);
+  });
+
   it('--validate blocks on adjacent pipes', () => {
     const file = 'test/fixtures/violations/table-adjacent-pipes.md';
 

test/unit/format-content.test.js

@@ -158,4 +158,15 @@ describe('format-content micro-formatter', () => {
     assert.doesNotMatch(result, /\r\n/, 'CRLF should be converted to LF');
     assert.match(result, /\n$/, 'should end with LF newline');
   });
+
+  it('handles empty string and whitespace-only input', () => {
+    // Empty string becomes final newline only
+    assert.equal(formatContent(''), '\n');
+    // 2+ trailing spaces preserved as hard line breaks
+    assert.equal(formatContent('   \n  \n'), '   \n  \n');
+    // Multiple blank lines preserved (no trailing whitespace to strip)
+    assert.equal(formatContent('\n\n\n'), '\n\n\n');
+    // Single line with only spaces: trailing spaces preserved, final newline added
+    assert.equal(formatContent('     '), '     \n');
+  });
 });

test/unit/formatter.test.js

@@ -48,6 +48,13 @@ describe('formatter CLI helper unit tests', () => {
     assert.deepStrictEqual(args._, []);
   });
 
+  it('parses --version as a read-only flag', () => {
+    const args = parseArgs(['node', 'index.js', '--version']);
+
+    assert.equal(args.version, true);
+    assert.deepStrictEqual(args._, []);
+  });
+
   it('reports runtime readiness from --doctor checks', () => {
     const { result, output } = collectDoctor();