Prepare package CLI and workspace contract

[fitz123]

Summary

• add the Minime package CLI entrypoint and workspace/path contract resolver
• add workspace/config validators plus source, built, and package-installed compatibility tests
• package first-party Pi extension artifacts for npm pack / installed execution
• preserve source-checkout runtime compatibility while adding explicit --workspace and env path overrides

Validation

Ralphex completed successfully on this branch with:

• cd bot && npm test
• cd bot && npm run typecheck
• cd bot && npm run validate-config
• cd bot && npm run build
• cd bot && npm run workspace:validate -- --workspace ./test-fixtures/minimal-workspace
• built CLI help/config/workspace validation
• cd bot && npm pack --dry-run

Notes

This is package/workspace-contract groundwork only. Full minime-bot repo creation and production workspace migration remain future work. A follow-up #148 continuation plan will reconcile the control-workspace vs agent-workspace semantics and retire schema/write-guard from the final package contract.

Closes #148

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

Pull request overview

This PR lays the groundwork for making the bot/ package installable and runnable via a packaged CLI, by introducing a centralized workspace/path contract resolver, structural (no-decrypt) workspace/config validators, and packaging-compatible Pi extension artifacts with cross-layout test coverage.

Changes:

• Added minime-bot CLI entrypoint plus workspace/config validation commands backed by a shared workspace contract resolver.
• Implemented workspace contract + validator (effective-path diagnostics, schema allow-list parsing parity with the live guard, agent workspace containment checks).
• Updated build/packaging to generate dist/ and Pi extension artifacts for npm pack / installed execution, with fixtures and tests covering source/built/installed layouts.

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Documents new packaged CLI and workspace/config validation commands and path override semantics.
docs/plans/completed/2026-06-06-issue-148-package-cli-workspace-contract.md	Captures the implementation plan and acceptance criteria for Issue #148 groundwork.
config.local.yaml.example	Clarifies agent workspaceCwd containment expectations under the resolved workspace root.
CLAUDE.md	Records workspace contract defaults and packaging artifact expectations for contributors.
bot/test-fixtures/minimal-workspace/schema.md	Adds minimal workspace schema fixture for validator/guard parity tests.
bot/test-fixtures/minimal-workspace/crons.yaml	Adds minimal crons fixture for workspace validation.
bot/test-fixtures/minimal-workspace/config.yaml	Adds minimal config fixture (relative workspaceCwd) for workspace validation.
bot/test-fixtures/minimal-workspace/agent-workspace/.gitkeep	Ensures agent workspace directory exists in the minimal fixture.
bot/src/workspace-validator.ts	Introduces structural workspace contract validation (config/crons/schema/paths).
bot/src/workspace-contract.ts	Adds centralized path/workspace resolution with CLI/env/fallback precedence + diagnostics.
bot/src/session-store.ts	Routes default session store path through the workspace contract.
bot/src/pi-rpc-protocol.ts	Updates Pi spawn env + wrapper resolution to use the workspace contract and packaged wrapper artifacts.
bot/src/pi-extensions/write-allowlist-schema.ts	Adds a shared schema allow-list parser/resolver used by validator and live guard.
bot/src/pi-extensions/README.md	Documents wrapper vs helper split and the generated artifact strategy under dist/extensions/pi/.
bot/src/message-thread-cache.ts	Routes default cache path through workspace contract (source layout vs explicit workspace).
bot/src/message-content-index.ts	Routes default index path through workspace contract (source layout vs explicit workspace).
bot/src/cron-runner.ts	Switches default crons/config resolution to workspace contract and preserves guard/schema env in cron Pi spawns.
bot/src/config.ts	Switches default config resolution to workspace contract; resolves relative agent workspaces against workspace root; avoids side effects on import.
bot/src/cli.ts	Adds minime-bot CLI entrypoint with config validate and workspace validate.
bot/src/tests/workspace-validator.test.ts	Adds validator/guard schema parity and containment tests, including installed-package-like layout.
bot/src/tests/workspace-contract.test.ts	Adds resolver precedence/override/diagnostics tests across source/built/installed modes.
bot/src/tests/session-store.test.ts	Updates default session store path test to align with workspace-contract routing.
bot/src/tests/project-naming.test.ts	Updates expectations to reflect workspace-contract-based default config resolution.
bot/src/tests/pi-rpc-protocol.test.ts	Adds wrapper artifact relpath mapping tests and stricter workspace containment/schema propagation tests.
bot/src/tests/package-install.test.ts	Adds pack/install fixture test covering installed CLI execution and wrapper importability/resource discovery.
bot/src/tests/message-thread-cache.test.ts	Adds tests for default cache path behavior under source layout vs explicit workspace root.
bot/src/tests/message-content-index.test.ts	Adds tests for default index path behavior under source layout vs explicit workspace root.
bot/src/tests/cron-runner.test.ts	Adds tests for resolving relative agent workspaces against the config/workspace root.
bot/src/tests/cron-runner-pi.test.ts	Ensures guarded env is built before context assembly and preserves guard/schema env through hardened cron env.
bot/src/tests/cron-merge.test.ts	Adds tests for workspace-contract-driven default crons path and workspace-relative crons override.
bot/src/tests/config-defaults.test.ts	Adds tests for workspace-contract-driven config defaults and workspace-relative overrides (incl. SOPS path anchoring).
bot/src/tests/cli.test.ts	Adds CLI behavior tests for help, config/workspace validation, and bin-style shim execution.
bot/scripts/clean-package-dist.mjs	Adds dist cleanup step used by build/packaging.
bot/scripts/build-package-artifacts.mjs	Generates packaged Pi wrapper artifacts under dist/extensions/pi/ and ensures CLI is executable.
bot/package.json	Adds CLI bin mapping, build/prepare/prepack scripts, packaging files allowlist, and new dependencies.
bot/package-lock.json	Updates lockfile for new deps and bin metadata.
bot/.claude/extensions/guardian-protect-files.ts	Switches the guard wrapper to the shared schema resolver/parser to align with validator behavior.

Files not reviewed (1)

• bot/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@copilot please re-review — fixes pushed since the last review

Addressed with b67e087: workspace root validation now uses the same safe stat path checks, so unreadable paths no longer crash validation.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• bot/package-lock.json: Language not supported

[fitz123]

@copilot please re-review — fixes pushed since the last review

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• bot/package-lock.json: Language not supported

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review completed. All previously identified issues have been properly addressed:

• Error handling in workspace-validator.ts (commit 2c1ed89): safeStat() wrapper now handles stat errors gracefully in existsAsDirectory(), existsAsFile(), and describePathKind()
• Trailing path separator handling (commit 6357efc): piExtensionRelpathForDir() now strips trailing slashes before checking endsWith()

Tests pass (1540/1541, with 1 unrelated ffmpeg test failure), typecheck passes, and workspace validation CLI works correctly.

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review completed. All issues from the latest review have been properly addressed:

• PI_GUARD_WORKSPACE_ROOT_ENV canonicalization (commits c68cb58, 3b75df4): realpathSync now imported and used in buildPiSpawnEnv at line 399 to ensure guard root is a physical path
• package.json engines constraint (commit c68cb58): Added "engines": { "node": ">=22.19.0" }
• README Node version documentation (commit c68cb58): Updated prerequisites (line 75) and CLI section (line 378) to document Node >=22.19.0 requirement

Tests pass (1542/1543, with 1 unrelated ffmpeg test failure). TypeScript compilation successful.

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review completed on the latest head (9c696cf). The latest fixes look correct (CLI workspace fallback wording + canonical cron guard root expectation), and I didn’t find new issues. Validation checks run:

• cd bot && npm run lint ✅
• cd bot && node --experimental-test-module-mocks --import tsx --test src/__tests__/cli.test.ts src/__tests__/cron-runner-pi.test.ts ✅
• parallel_validation (Code Review + CodeQL) ✅ (no findings)

I also checked the recent failed workflow run (PII & Secrets Scan run 27068712450): failure was from gitleaks reporting a commit-message leak (leaks found: 1), not from these code paths.

[fitz123]

@copilot please re-review — fixes pushed since the last review

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review completed. All review issues have been properly addressed:

• Error handling (workspace-validator.ts): safeStat() wrapper handles stat errors gracefully
• Path normalization (pi-rpc-protocol.ts): Trailing slashes stripped before endsWith() check
• Guard root canonicalization: realpathSync applied to PI_GUARD_WORKSPACE_ROOT_ENV (line 399)
• Node version constraint: Added engines.node >=22.19.0 to package.json
• Documentation: Updated README prerequisites and CLI section
• CLI help text: Clarified package-installed workspace fallback behavior (commit 9c696cf)

Validation results:

• Tests: 1542/1543 passing (1 unrelated ffmpeg failure)
• Typecheck: passed
• Workspace validation: passed

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• bot/package-lock.json: Language not supported

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review complete. All previously identified issues have been properly addressed in commits 5894383 and 9c696cf:

Fixed issues:

• ✅ Error handling (workspace-validator.ts): safeStat() wrapper handles stat errors gracefully
• ✅ Path normalization (pi-rpc-protocol.ts): Trailing slashes stripped before endsWith() check
• ✅ Guard root canonicalization: realpathSync applied to PI_GUARD_WORKSPACE_ROOT_ENV
• ✅ Node version constraint: engines.node >=22.19.0 added to package.json
• ✅ Documentation: README prerequisites and CLI section updated
• ✅ CLI help text: Package-installed workspace fallback clarified
• ✅ Bash parameter expansion (.claude/hooks/protect-files.sh): Fixed using sed for path normalization

Validation results:

• Typecheck: ✅ passed
• Tests: 128/128 passing (workspace-validator, CLI, pi-rpc-protocol, safety-hooks)
• CI checks: ✅ all passing on current HEAD (PII & Secrets Scan, Author Identity Check, Code Review)

The gitleaks failure mentioned in earlier comments was from commit 87105e0 and has been resolved in subsequent commits.

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review complete. The schema path propagation issue has been properly addressed in commit 6ece37c:

Fixed issue:

• ✅ MINIME_SCHEMA_PATH propagation to subagent children: buildPiSubagentChildSpawnEnv now accepts a schemaPath parameter (defaulting to process.env[MINIME_SCHEMA_PATH_ENV]), resolves it with the new resolveOptionalChildSchemaPath helper (handling both absolute and relative paths), and propagates it to the child environment. This prevents schema divergence when parent processes use overrides.

Test coverage:

• New test validates that relative schema paths are correctly resolved against the guard workspace root and propagated to child environments
• All 91 Pi RPC protocol tests passing ✅
• All 15 workspace validator and CLI tests passing ✅

CI status:

• PII & Secrets Scan: ✅ passing (commit 6ece37c)
• Author Identity Check: ✅ passing (commit 6ece37c)
• Typecheck: ✅ passing

[fitz123]

@copilot please re-review — fixes pushed since the last review

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• bot/package-lock.json: Language not supported

[Copilot]

@copilot please re-review — fixes pushed since the last review

Re-review complete on HEAD 6ece37c. The schema path propagation fix looks correct:

• resolveOptionalChildSchemaPath properly handles both absolute paths (passed through as-is) and relative paths (resolved against the canonicalized realGuardWorkspaceRoot)
• buildPiSubagentChildSpawnEnv defaults schemaPath to process.env[MINIME_SCHEMA_PATH_ENV] so callers that don't explicitly pass it still get propagation automatically
• The new test validates relative schema path resolution end-to-end

Local validation:

• Typecheck: ✅ passed
• pi-rpc-protocol tests: ✅ 91/91
• workspace-validator + CLI tests: ✅ 15/15
• CI (PII & Secrets Scan, Author Identity Check): ✅ all passing on HEAD