@erclx/aitk 0.22.0 → 0.22.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -66,7 +66,7 @@ Full help: `aitk <command> --help`.
 | `aitk init [path]`       | Bootstrap a project with selected toolkit domains                                              |
 | `aitk sync [path]`       | Sync all installed domains in a target project                                                 |
 | `aitk sync --check`      | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
-| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed)                                                  |
+| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
 | `aitk sandbox reset`     | Reset sandbox to baseline                                                                      |
 | `aitk sandbox clean`     | Wipe the sandbox                                                                               |
 | `aitk sandbox check`     | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
@@ -189,7 +189,7 @@ inside an already-open frame.
 
 ### Sandbox scenarios
 
-Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `aitk` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
@@ -222,7 +222,7 @@ Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a ma
 
 ### Scenario coverage
 
-`aitk sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing.
+`aitk sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing. Where that tree does not ship it exits 1 and prints no percentage, since a denominator nobody looked at is not a coverage result. A tree that is present and holds no scenarios is a real zero and still reports one.
 
 ```bash
 aitk sandbox coverage --json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/sandbox.ts

@@ -17,6 +17,7 @@ import {
   type Verdict,
 } from '@/sandbox/expect'
 import {
+  frameError,
   intro,
   logError,
   logInfo,
@@ -29,6 +30,34 @@ import {
 
 const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
 
+/**
+ * Reports that the scenario tree does not ship, and answers whether it reported,
+ * so a caller that sees `true` returns without touching the tree.
+ *
+ * `scripts/sandbox` is excluded from the published package, so an installed
+ * `aitk` resolves `SANDBOX_DIR` to a directory that is not there. Both entry
+ * points that walk the tree ask here rather than carrying a check each, because
+ * absence is a property of the install rather than of a verb, and a second copy
+ * of the question is a second message to keep true. `check` reads the tree as
+ * well, through `expectFilePath`, and needs no guard because its provisioned-tree
+ * check already stops an installed run before the read.
+ *
+ * The distinction it preserves is between an absent tree and an empty one. Only
+ * the second is a real zero, and a coverage percentage over a denominator nobody
+ * looked at reads as a suite that examined everything and found it clean.
+ *
+ * The frame opens and closes here, so this runs before `intro` rather than
+ * inside an open frame.
+ */
+function reportAbsentScenarioTree(): boolean {
+  if (existsSync(SANDBOX_DIR)) return false
+
+  frameError('sandbox is toolkit-only and is absent from an installed aitk')
+  process.exitCode = 1
+
+  return true
+}
+
 /**
  * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
  * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
@@ -217,6 +246,8 @@ function reportCoverage(report: CoverageReport): void {
 }
 
 function runCoverage(options: CoverageOptions): void {
+  if (reportAbsentScenarioTree()) return
+
   intro('aitk sandbox coverage')
 
   const report = collectCoverage(PROJECT_ROOT)
@@ -284,6 +315,8 @@ export function register(program: Command): void {
     .allowExcessArguments(true)
     .passThroughOptions()
     .action(async (_opts: unknown, cmd: Command) => {
+      if (reportAbsentScenarioTree()) return
+
       const args = cmd.args
 
       if (args.length === 0) {
@@ -336,7 +369,8 @@ export function register(program: Command): void {
         '  aitk sandbox coverage',
         '  aitk sandbox coverage --json',
         '',
-        'Exit codes: 0 always, unless --strict and a scenario declares nothing.',
+        'Exit codes: 0, unless --strict and a scenario declares nothing.',
+        'Where the scenario tree does not ship, exits 1 without a report.',
       ].join('\n'),
     )
     .action((options: CoverageOptions) => {