fix(cli): --meta takes one key=value per flag; fix CLI examples (#54)

[adrianbrowning]

Closes #54

Summary

The docs gave about 70 example commands the CLI rejects. While fixing them I found a real CLI bug that broke even more of them.

--meta swallowed the file after it. It was declared variadic (<key=value...>), so in

mdcode list --meta type=example README.md

it read README.md as a second key=value pair, then read stdin, found nothing and exited 0. Every documented --meta … FILE example was affected, including one in the shipped Agent Skill.

-.option("-m, --meta <key=value...>", "Filter by custom metadata")
+.option("-m, --meta <key=value>", META_FLAG_HELP, collect)   // repeatable, like --name

• I changed it on all seven commands. This matches the flags reference ("can specify multiple times"). No doc used the multi-value form -m a=b c=d.
• parseFilterOptions now splits at the first =, so --meta expr=a=b keeps a=b. FilterCliOptions.meta is typed Array<string>; it was declared Record but used as an array.

Docs (packages/mdcode/README.md, examples/CLI_EXAMPLES.md):

• list, run and dump read one file. Their examples now pass docs/guide.md instead of docs/ or docs/*.md, and use a shell loop where several documents make sense.
• extract, update and validate take several files. docs/ became docs/*.md.
• --file matches exactly. Glob values became exact file= values. The "Wildcards and Patterns" section became "No Wildcards", which suggests a shared metadata value for groups. The "Test All Code Blocks" workflows now use -m kind=test on one document.
• The flags reference no longer calls --file a "pattern", and describes repeatable --meta. Changes from Earlier Versions has an entry for --meta. The TransformerMeta JSDoc ("supports glob patterns") is corrected.

The skill needed no change: it already described the real behaviour, and its --meta example now works. The Intent records mark the gap resolved (batch 2 in skill_spec.md) and the reviews are recorded.

Evidence

• Before: mdcode list --json --meta type=example README.md returned "blocks":[]. Putting the file before the flag returned the block.
  After: both return the block.
• New test in cli-integration.test.ts: "--meta takes one key=value, so a file after it is still the file to read". It covers a file after --meta, repeated -m combined with AND, and a value with =. It failed on the variadic build ("doc.md must be read, not taken as a second key=value") and passes now.
• A throwaway scan of both docs, which tokenises every mdcode … line, now finds no list/run/dump with several files or a directory, and no glob --file value. The only hits left are shell for loops.
• A second test, "every command reads the file that follows --meta", runs list, update, validate --for extract, extract, run and dump with --meta kind=keep doc.md and checks each selects only the keep block. It fails on main's cli.ts (list must read doc.md after --meta) and passes now.
• pnpm exec intent maintainer check --base origin/main: 0 pending. pnpm check passes (pre-push).

Merge Danger

Door: two-way

Blast Radius: CLI flags

-m a=b c=d, several pairs after one flag, no longer works. Write -m a=b -m c=d instead. No docs or tests used that form, and it's in the changelog. The bump is a patch: the old form silently swallowed file arguments, so this is a bug fix.

[github-actions]

The changes in this PR will be included in the next version bump.

Patch releases

• mdcode-ts 0.0.4 → 0.0.5

Bump files in this PR

• meta-flag.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run