Skip to content

fix(cli): describe exact leaf command paths - #36

Merged
phodal merged 1 commit into
QoderAI:mainfrom
rrrrrredy:fix/describe-leaf-command-paths
Jul 31, 2026
Merged

fix(cli): describe exact leaf command paths#36
phodal merged 1 commit into
QoderAI:mainfrom
rrrrrredy:fix/describe-leaf-command-paths

Conversation

@rrrrrredy

Copy link
Copy Markdown
Contributor

Summary

command describe now resolves the complete registered command path. Describing
a leaf returns that leaf's canonical path and metadata without executing its
capability.

Why

Traceability and Scope

  • Spec/ADR, if applicable:
    docs/specs/2026-07-31-33-describe-leaf-command-paths.md
  • Acceptance criteria addressed: AC-1 through AC-5
  • Canonical owners changed: scripts/better-harness-cli/registry.mjs and
    scripts/better-harness-cli/cli.mjs
  • Explicit non-goals: command dispatch, registry contents, OpenCLI schema,
    capability-owned scripts, and global option parsing

Change Type

  • Feature
  • Bug fix
  • Tests only
  • Documentation/community
  • Refactor with no intended behavior change
  • Dependency, packaging, or infrastructure

Test and Review Evidence

Check Result
node --test --test-concurrency=1 test/better-harness-cli.test.mjs test/scripts-refactor-contract.test.mjs 39 passed, 0 failed, 1 Windows symlink-permission skip
node scripts/doc-link-graph/cli.mjs skills/better-harness 34 files and 50 links
node --test test/doc-link-graph.test.mjs 6 passed, 0 failed
npm run pack:verify Passed: 359 npm entries and 382 runtime-zip entries
node --test 1015 passed, 10 failed, 3 skipped; all failures were Windows EBUSY cleanup or EPERM symlink host errors
Same-name checks on untouched origin/main Reproduced the same EBUSY/EPERM failure classes; no changed CLI assertion failed
git diff --check Passed

Manual or visual evidence:

  • command describe harness render --json returns name: "render",
    path: ["harness", "render"], and the registered render script.
  • Human output identifies Command: harness render.
  • Unknown leaves return UNKNOWN_SUBCOMMAND; third path segments return
    INVALID_COMMAND_PATH.

Risk and Recovery

  • Compatibility and cross-platform impact: parent descriptions and aliases are
    unchanged; leaf JSON gains an additive canonical path field.
  • Package, plugin, schema, or generated-file impact: no schema or package
    boundary change; the frozen root-help fixture and changelog are updated.
  • Rollback or recovery path: revert this commit to restore parent-only
    description behavior.
  • Residual risk or unverified boundary: local Windows symlink tests require
    privileges unavailable on this host; CI remains the cross-platform gate.

AI Involvement

  • Level: Assisted
  • Human review and validation: I defined the expected behavior and reviewed the
    focused, full, documentation, and package validation results before submission.

Checklist

  • I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
  • The change is focused and does not include unrelated local or generated state.
  • Tests and documentation match the behavior actually delivered.
  • Markdown links were checked when documentation moved or changed.
  • Cross-platform behavior was considered for Windows, macOS, and Linux.
  • Package/runtime verification was run when shipped files or dependencies changed.
  • User-facing or compatibility changes are recorded in CHANGELOG.md.
  • I have the right to contribute this work under the repository's MIT License.

Resolve two-segment command describe requests through the root registry so human and JSON output identify the exact registered leaf without invoking its capability. Unknown leaves and longer paths now fail instead of falling back to parent metadata.

Implements QoderAI#33 using docs/specs/2026-07-31-33-describe-leaf-command-paths.md. Focused CLI and frozen-contract tests passed; broader Windows failures were limited to baseline EBUSY and EPERM host behavior.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
@phodal
phodal merged commit 1f4e522 into QoderAI:main Jul 31, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

command describe ignores leaf command paths

2 participants