fix(cli): honor help before required args and accept store tag aliases

[bcdonadio]

Summary

Fixes #602 and #603.

• Bug: lcm store --help is rejected instead of displaying help #602: lcm store --help (and lcm <known-command> --help) was rejected instead of displaying help. Commander validates required operands before subcommand actions, so the per-action opts.help checks were unreachable. runCli now preflights known help requests before identity validation, legacy-home migration, package metadata reads, and parseAsync, while preserving unknown-command, empty-argv, pseudo-help, and -- terminator behavior.
• Bug: lcm store documents --tags, but only accepts --tag #603: lcm store documented --tags but only accepted --tag. Store tag aliases are now registered as one occurrence-ordered option accepting both --tag and --tags (repeatable), while export --tags stays comma-separated.

MoM workflow

• Plan review: gpt-5.6-luna (max effort) — APPROVED
• Adversarial review: cortex-hq/zai-org-GLM-5.2 + xai/grok-4.5 (max effort) — no actionable findings
• Second-pass review: anthropic/claude-opus-5 (medium effort) — APPROVED

Changeset

.changeset/clear-store-help-aliases.md — patch

[qodo-code-review]

PR Summary by Qodo

Fix CLI help preflight and allow lcm store --tag/--tags aliases

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Preflight known --help requests before required-arg validation and side effects.
• Accept repeatable --tag and --tags aliases for lcm store, preserving order.
• Update help/docs/templates and add tests to lock in help and tag behavior.

Diagram

graph TD
  U(["User argv"]) --> RC["runCli"] --> CH["resolveCustomHelpRequest"] --> H["cli-help: printHelp/hasCommandHelp"] --> X(["exit 0"])
  RC --> P["Commander parseAsync"] --> A["Command actions"] --> S[("Side effects: daemon/FS/identity")]
  subgraph Legend
    direction LR
    _u(["Entry"]) ~~~ _m["Module/function"] ~~~ _io[("I/O / side effects")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Make required operands optional and validate inside actions

• ➕ Commander would not reject cmd --help due to missing operands
• ➕ Keeps help handling localized per command
• ➖ Weakens CLI contract (required args no longer enforced by parser)
• ➖ Requires duplicating validation logic in every action
• ➖ Harder to guarantee no side effects before help across the codebase

2. Rely on Commander’s built-in help flows exclusively

• ➕ Less custom code in the entrypoint
• ➕ Standard Commander behavior where supported
• ➖ Does not reliably address nested/known-command help before required-arg validation
• ➖ Still risks side effects if action handlers run before custom help rendering

Recommendation: Keep the PR’s approach: a centralized, early preflight in runCli that recognizes only known help topics (via hasCommandHelp) and exits before any validation/side effects. This preserves strict required-arg validation for real executions while making lcm --help safe and predictable. The added tests around unknown commands, -- terminator behavior, and side-effect avoidance make this the most robust option.

Files changed (10) +218 / -71

Bug fix (2) +45 / -64

lcm.tsPreflight known help before parsing/validation; add store '--tag/--tags' aliases +37/-61

Preflight known help before parsing/validation; add store '--tag/--tags' aliases

• Moves custom help detection to the start of 'runCli' and gates it on known help topics to avoid swallowing unknown-command behavior. Enhances help resolution to respect '--' terminators and 'help <topic>' forms, removes unreachable per-action help checks, and registers a single occurrence-ordered '--tag, --tags <tag>' option for 'store' while preserving existing 'export --tags' semantics.

bin/lcm.ts

cli-help.tsUpdate store help text and export 'hasCommandHelp' +8/-3

Update store help text and export 'hasCommandHelp'

• Updates 'store' usage/options/examples to show '--tag, --tags <tag>' and adds a note explaining ordering and the difference vs 'export --tags'. Exports 'hasCommandHelp()' so 'runCli' can safely preflight only known help topics.

src/cli-help.ts

Tests (4) +149 / -5

lcm-run-cli.test.tsAdd regression tests for help preflight, terminator handling, and tag ordering +115/-4

Add regression tests for help preflight, terminator handling, and tag ordering

• Adds a broad table-driven suite asserting that known-command help exits before required validation and before any side effects (daemon start, identity/config operations, package.json reads). Adds coverage for unknown-command '--help', '--' terminator behavior, 'help <topic>' pseudo-command, store tag alias ordering, and preserving 'export --tags' comma-splitting.

test/bin/lcm-run-cli.test.ts

memory-command-routing.test.tsAssert store registers a single option with both '--tag' and '--tags' +13/-0

Assert store registers a single option with both '--tag' and '--tags'

• Verifies Commander option registration for 'store' uses one option entry with the combined flags string '--tag, --tags <tag>' (ensuring one occurrence-ordered collector).

test/bin/memory-command-routing.test.ts

cli-help.test.tsTest 'hasCommandHelp' and store help output for tag aliases +16/-1

Test 'hasCommandHelp' and store help output for tag aliases

• Adds unit tests for 'hasCommandHelp' topic detection and validates that store help output contains the combined alias flags and mixed-spelling example invocation.

test/cli-help.test.ts

template-service.test.tsUpdate connector template snapshot assertions for store tag docs +5/-0

Update connector template snapshot assertions for store tag docs

• Adjusts template generation expectations to include the new store tag examples and alias wording, and to avoid invalid shell tokens like '--tag,' showing up in invocations.

test/connectors/template-service.test.ts

Documentation (3) +19 / -2

copilot-instructions.mdDocument testing and CLI example conventions +2/-0

Document testing and CLI example conventions

• Adds guidance to require direct tests for exported helpers and warns against copying Commander option-declaration commas into shell invocations. Reinforces preserving legacy fallbacks while testing branches deterministically.

.github/copilot-instructions.md

cli.mdExplain early help preflight and store tag alias behavior +14/-1

Explain early help preflight and store tag alias behavior

• Documents that help for known commands is resolved before required-argument validation and side effects. Clarifies that 'store' accepts repeatable single-tag '--tag/--tags' aliases (order preserved) while 'export --tags' remains comma-separated.

docs/cli.md

command-reference.mdRefresh command reference with store tag alias examples +3/-1

Refresh command reference with store tag alias examples

• Expands the connector template command reference to include tagged 'lcm store' examples and explicitly calls out '--tag'/'--tags' as repeatable aliases that can be mixed in order.

src/connectors/templates/sections/command-reference.md

Other (1) +5 / -0

clear-store-help-aliases.mdAdd patch changeset for help preflight + store tag aliases +5/-0

Add patch changeset for help preflight + store tag aliases

• Introduces a patch-level changeset noting that help is honored before required arguments and that store accepts both '--tag' and '--tags'. This drives release/versioning automation.

.changeset/clear-store-help-aliases.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR fixes CLI help handling so --help is honored before Commander’s required-argument validation (notably for lcm store --help), and aligns the lcm store tag option contract with documentation by accepting both --tag and --tags as repeatable aliases while keeping export --tags as a comma-separated filter.

Changes:

• Preflight known --help requests in runCli before identity validation, legacy-home migration, package metadata reads, or parseAsync.
• Register a single occurrence-ordered lcm store tag option with both --tag and --tags long aliases, preserving mixed-order input.
• Update CLI help/docs/templates and add tests covering help preflight and tag alias behavior.

Reviewed changes

Copilot reviewed 7 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
bin/lcm.ts	Adds early custom help resolution in runCli and registers store tag aliases as one repeatable option.
src/cli-help.ts	Updates store help text to reflect --tag/--tags aliases and exports hasCommandHelp for preflight gating.
docs/cli.md	Documents early help resolution (before required args) and clarifies store vs export tag semantics.
src/connectors/templates/sections/command-reference.md	Updates command reference to show tagged store usage and alias guidance.
test/bin/lcm-run-cli.test.ts	Adds tests ensuring help exits before side effects and validates tag alias ordering + export --tags behavior.
test/bin/memory-command-routing.test.ts	Verifies store registers exactly one option carrying both --tag and --tags.
test/cli-help.test.ts	Tests hasCommandHelp and ensures store help prints the ordered alias flags/examples.
test/connectors/template-service.test.ts	Asserts generated connector rules content reflects updated store examples and avoids comma-syntax in invocations.
.github/copilot-instructions.md	Adds review guidance about direct tests for exported helpers and avoiding comma-syntax in shell invocations.
.changeset/clear-store-help-aliases.md	Adds a patch changeset describing the behavior fixes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗