SpecsCLICli Tool Validation
Implementation Notes: CLI Tool Validation Command
Implementation Notes
Summary
- Implemented
dp -v,dp tools ensure, and conditionalagent-browserbrowser setup skip. - Spec folder:
apps/wiki/content/docs/project/specs/cli/cli-tool-validation. - Delivery review completed after fixing all accepted findings.
Execution Mode
- parallel
Deviations From the Plan
- Added
CHANGELOG.mdupdates because these changes are shipping under the still-pending2.2.0npm release line.
Surprises and Decisions
@effect/clibuilt-in version support is long-only, so-vmust be handled at the root entrypoint.agent-browser installdownloads Chrome for Testing even when system Chrome is usable by runtime launch; Harness should skip only that ensure command when a usable browser executable is already present.dp tools ensuremust not execute repo-owned install contracts; it reads tool IDs from.devpunks/settings.json, but install contracts come from the trusted stable baseline with bundled fallback.- Package manager detection now happens only when a missing or outdated tool needs repair, so already-present tools can validate without Bun/pnpm/npm on PATH.
Sanity Checks
| Check | Result | Notes |
|---|---|---|
bun run --cwd apps/cli test -- src/core/tools.test.ts src/cli/tools-command.test.ts | passed | Vitest package runner, 16 tests. |
bun run --cwd apps/cli check-types | passed | TypeScript no-emit. |
bun run --cwd apps/cli build | passed | Built standalone dist executable. |
node ./scripts/assert-dist-commands.mjs from apps/cli | passed | Dist root help exposes tools, tools ensure --help works, and dist -v includes package version. |
bun run --cwd apps/cli check | passed | Oxlint and Oxfmt check. |
.agents/skills/autoreview/scripts/autoreview --mode local --prompt <scoped CLI validate prompt> | passed | Final run clean: no accepted/actionable findings. |
node -e "JSON.parse(require('fs').readFileSync('apps/wiki/content/docs/project/specs/cli/meta.json','utf8')); console.log('meta ok')" | passed | Routed spec metadata is valid JSON. |
git diff --check | passed | No whitespace errors. |
UI Evidence Links
No UI surfaces changed.
Acceptance Criteria Status
| Criterion | Status | Notes |
|---|---|---|
dp -v prints the same version as dp --version. | met | Built-dist assertion verifies -v includes package version. |
A dp tools ensure command exists under the tools command group and is discoverable from help. | met | Command registered and dist root/subcommand help assertions cover it. |
dp tools ensure checks Harness required external tools using the same registry/install behavior as scaffold setup/update. | met | runEnsureTools calls ensureToolsInstalledBestEffort. |
dp tools ensure can run outside a scaffolded repo and validates the default required toolchain. | met | Tools-command test covers default fallback. |
dp tools ensure can run inside a scaffolded repo and uses .devpunks/settings.json. | met | Tools-command test covers settings-backed tools. |
| Missing installable tools are installed or reported with recovery-quality errors. | met | Uses best-effort installer with tools-ensure-specific recovery guidance. |
| Already-present tools are reported as present and are not reinstalled. | met | Existing and new tool tests cover already-present paths, including no package manager on PATH. |
agent-browser validation does not trigger Chrome installation when a usable browser exists. | met | Core tools tests cover present and missing package cases with system Chrome. |
Existing setup/update required-tool checks inherit the agent-browser Chrome-presence fix. | met | Shared ensureToolsInstalled path owns the skip behavior. |
Focused CLI tests cover -v, tools ensure, already-present tools, missing installs, and agent-browser existing-Chrome path. | met | Unit tests plus dist assertion cover these behaviors. |
Operator docs and runbooks explain when to use dp tools ensure. | met | Updated CLI README, docs README, root runbook, and routed project runbook. |
Manual Review Checklist
| Area | Check | How to perform | Expected result |
|---|---|---|---|
| CLI version | Short version flag | Run dp -v after installing/building the CLI. | Prints the package version and exits zero. |
| CLI validation | Required tool repair | Run dp tools ensure in a repo with .devpunks/settings.json. | Reports each required tool and installs or reports failures. |
| Browser setup | Existing Chrome skip | Run dp tools ensure on a machine with Chrome/Chromium/Brave already installed. | Does not force a Chrome-for-Testing download through agent-browser install. |
Pre-existing Issues
- None identified.
Out of Scope Observations
- A future read-only
dp tools ensure --checkmode may be useful for CI, but is outside this request. - Unrelated
create-planskill/mirror changes are present in the worktree and are quarantined from this CLI validation delivery.
Remaining Work
- None for this scope.
Review
- First delivery review found stale-baseline manifest contract handling; fixed by resolving trusted stable/bundled baselines and refusing to execute repo-owned
toolContracts. - Second delivery review found repo-supplied contract command execution risk; fixed by ignoring repo-owned contracts for execution and documenting the trust boundary.
- Third delivery review found browser skip false positives and package-manager over-requirement; fixed by aligning skip candidates with
agent-browserdiscovery and deferring package manager detection until repair is needed. - Fourth delivery review found scaffold/update-specific recovery copy in
dp tools ensure; fixed with tools-ensure-specific failure guidance. - Final autoreview result: clean, no accepted/actionable findings.
Docs Ingest
- No-op. The docs-affecting changes are already the routed project artifacts for this scope: CLI README, root docs/runbook, routed project runbook, spec, plan, and implementation notes. No additional concept/flow ingest page is needed.
Steering
| Date | Feedback | Changes |
|---|---|---|
| 2026-06-23 | User clarified goalify means create an active goal for this thread. | Created active goal and continued delivery. |
| 2026-06-23 | User called out invalid create-plan/delivery usage. | Repaired PLAN.md into T-task graph, ran plan review, mandatory delivery review, docs-ingest no-op, and closeout evidence. |
| 2026-06-23 | User clarified the tool check command should live under /tools as dp tools ensure. | Renamed the root command to a tools ensure subcommand across CLI, tests, docs, and closeout artifacts. |