test(cli): cover generic setup alias

[devkade]

Summary

• Tightens the generic runtime CLI setup slice from Normalize reusable identifiers away from product names #205 by making npm run setup:cli point users to runctl --help first while preserving kapi --help compatibility.
• Extends install tests to prove both globally installed shims (runctl and kapi) work from isolated prefix and production-style installs.
• Updates the product-name audit to classify the setup helper as a compatibility filename with generic user-facing guidance.

Linked issue

Refs #205

Problem

Issue #205 is normalizing reusable surfaces away from product names without breaking existing compatibility contracts. PR #206 added the generic runctl bin, but the setup helper still printed a Kapi-first completion message and tests only asserted the installed kapi shim. That left the documented npm run setup:cli → runctl --help path less directly guarded.

Options considered

1. Rename scripts/setup-kapi-cli.mjs immediately.
   • Pros: removes another product-named file.
   • Cons: broader compatibility/script-surface change; not necessary for the user-facing setup behavior.
2. Keep the script filename but change user-facing output and tests.
   • Pros: small, compatibility-safe, directly guards the new canonical runtime command.
   • Cons: the historical filename remains as a justified compatibility surface.
3. Do nothing and rely on package bin metadata.
   • Pros: no churn.
   • Cons: leaves the setup helper and regression tests biased toward the legacy alias.

Selected approach

Selected option: option 2.

Why this one: it moves the user-visible setup path toward runctl without creating a breaking script rename or over-expanding #205 into a broad product-name migration.

Risks/trade-offs: scripts/setup-kapi-cli.mjs remains product-named. The audit explicitly classifies that as compatibility filename debt for a later scoped migration.

Implementation by file/surface

• scripts/setup-kapi-cli.mjs: adds setupCompletionMessage() and prints Runtime CLI setup complete. Run: runctl --help (or kapi --help for compatibility).
• test/cli-bin.test.ts: asserts the helper message, verifies runctl and kapi shims after setup:cli, and verifies both shims in production-style npm install -g --omit=dev installs.
• docs/product-name-audit.md: adds setup-helper classification while preserving the existing runtime entrypoint and slash-command compatibility classifications.

Why this fixes it

The setup command now guides users to the canonical generic runtime command while retaining the legacy command in the same message. The install tests prove runctl is not just listed in package.json; it is actually installed and executable in the setup and production-install paths.

QA / Verification

• npm ci — pass
• git diff --check — pass
• npm test -- test/cli-bin.test.ts — pass; package script shape ran the full test/*.test.ts suite plus test/cli-bin.test.ts (517 tests, 506 pass, 11 skipped)
• npm run check — pass
• npm run check:unused — pass
• npm run quality:budgets — pass with existing non-failing code_smells budget warning

Anomalies observed

• npm test -- test/cli-bin.test.ts does not narrow to only that file because the package script is tsx --test test/*.test.ts; it ran the full suite plus the explicit file argument.
• npm ci/verification produced recurring mode-only churn on src/cli/kapi-review-cli.ts; it was reset before staging and is not included in the commit.
• This was a direct Ragna bounded follow-up slice after the existing Normalize reusable identifiers away from product names #205 PR merged; no new Ilchul/Kapi worker was started for this small test/setup-hardening PR.

Risks / Follow-up

• Normalize reusable identifiers away from product names #205 remains open because broader reusable identifier cleanup remains: package metadata, file/module names, service/store types, slash-command compatibility contracts, and external integration names still need classification or scoped migration.
• A future scoped issue/PR can decide whether setup-kapi-cli.mjs itself should gain a generic filename/alias.

kapi-agent review expectations and current-head merge gate

• Expected review scope: small test/setup/docs slice, 40 changed lines before commit (33 insertions / 7 deletions) and below the 200 changed-line gate.
• Merge gate: require current-head kapi-agent formal APPROVED review, successful kapi-agent/review check, successful formal approval gate, mergeable PR state, and local verification evidence above before merge.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

The original goal is a bounded follow-up to issue #205: make the generic runtime CLI path user-visible through npm run setup:cli while preserving the existing kapi compatibility alias. The semantic scope is small and coherent: one setup message change, targeted install/bin coverage, and an audit-doc classification update. There is no prior kapi-agent feedback on this PR, so no review/fix ping-pong was required.

What changed

• scripts/setup-kapi-cli.mjs now exposes setupCompletionMessage() and prints runctl --help first, with kapi --help explicitly retained for compatibility.
• test/cli-bin.test.ts now verifies the setup message and checks both installed shims, runctl and kapi, in isolated setup and production-style global install flows.
• docs/product-name-audit.md documents the setup helper filename as compatibility debt while keeping user-facing guidance generic.

Why this is correct

The implementation changes only the user-facing completion text and leaves the installation mechanics intact. The tests exercise the actual installed commands rather than only package metadata, which directly guards the intended contract: runctl is the canonical generic runtime command, and kapi remains executable as a compatibility alias.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 40 changed lines, below the 200-line semantic review threshold.
• Revision-explanation status: not required; found in the PR body.
• Ilchul review harness gate: PASS — neutral/comment verdict, no blocking findings.
• Inspected files: scripts/setup-kapi-cli.mjs, test/cli-bin.test.ts, docs/product-name-audit.md, and package.json.

Remaining risks and approval rationale

Remaining risk is low: the historical scripts/setup-kapi-cli.mjs filename remains product-named, but this is explicitly documented as compatibility debt and intentionally outside this PR’s scope. Approval is justified because the behavioral change is narrow, compatibility is preserved, and the new tests cover the setup and production-install contracts that could regress.

Blocking issues

None.

Warnings / risks

• scripts/setup-kapi-cli.mjs: the filename remains product-specific, but the audit correctly classifies it as compatibility filename debt for a later scoped migration.

Suggestions

• In a future migration slice, consider adding a generic setup script alias before renaming or deprecating setup-kapi-cli.mjs, so existing automation has a transition path.

Looks good

• The setup output now clearly prefers runctl --help while preserving kapi --help.
• The tests validate real installed shims in both setup and production-style install paths, which is the right level for this contract.
• The product-name audit stays aligned with the implementation and explains why the remaining product-named setup helper is intentional.

Verification notes

Verifier gate status: PASS — npm ci && npm run verify exited 0. Size gate status: PASS — 40 changed lines. Revision-explanation status: not required and present. Ilchul review harness gate: PASS with no blocking findings.

---

Engine: pi

[devkade]

@kapi-agent review

Revision explanation for current head 8c9f132d3ffcefa23bb937b82555008454b04584:

What changed:

• Added a generic setup completion message that points to runctl --help first while preserving kapi --help compatibility.
• Extended setup/install tests to execute both installed runctl and kapi shims.
• Updated the product-name audit to classify the setup helper filename as compatibility debt with generic user-facing output.

Why this closes the current gate:

• This is a bounded follow-up to Normalize reusable identifiers away from product names #205 after PR feat(cli): add generic runtime command alias #206 introduced the runctl bin.
• The slice keeps the legacy setup script path stable and changes only user-facing guidance plus regression coverage.

Verification:

• npm ci passed.
• git diff --check passed.
• npm test -- test/cli-bin.test.ts passed; package script ran the full test/*.test.ts suite plus the explicit file argument.
• npm run check passed.
• npm run check:unused passed.
• npm run quality:budgets passed with existing non-failing budget warning.