@dzhechkov/harness-cli 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,13 @@
     ".dz-manifest.json",
     "sbom.json"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "@dzhechkov/harness-core": "^0.4.0",
     "@dzhechkov/harness-presets": "^0.5.0",
@@ -75,12 +82,5 @@
     "url": "https://github.com/djd1m/dz-harness-hub.git",
     "directory": "packages/@dzhechkov/harness-cli"
   },
-  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  }
-}
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme"
+}

package/sbom.json

@@ -175,7 +175,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5bd26341b4a5885c116432bf621b7fdb4172b2604db47ad3c1c001deb4fe6ed4"
+          "content": "00a53276d145112e3c2ae5ca2950ac74877ea4b069b2b81040d49c5903eb6482"
         }
       ]
     },

package/src/cli.ts

@@ -242,6 +242,7 @@ import {
   isUsablePlaneResult,
   renderDeliveryReview,
   scanSkillsLayout,
+  declaredPluginSurface,
   parseInitFacts,
   verifyRegistration,
   buildContentProbePrompt,
@@ -449,6 +450,8 @@ Usage:
   dz import-ecc [--local-path <dir>] [--select id,id,...] [--limit N] [--output <dir>] [--force]
   dz help
 
+Global: --version | -v [--json]   (prints this CLI's own semver on one line, exit 0; "unknown" + exit 1 when unresolvable)
+
 Workflows: author loop-plan/1 plans with dz workflow init/validate/render; gate them with dz workflow-lint; read runs with dz workflow-trace (the ADR-005 templates are retired)
 
 Targets: ${TARGET_NAMES.join(', ')}
@@ -935,8 +938,8 @@ function workflowInitPlan(name: string, pattern: string): object {
       ...base,
       steps: [
         { stepId: 'fan', kind: 'fanout', phase: 'Work', concurrency: 'pipeline', budget: { maxAgents: 8 } },
-        { stepId: 'a', kind: 'agent', phase: 'Work', prompt: 'TODO: stage A per item', budget: { maxAgents: 4 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
-        { stepId: 'b', kind: 'agent', phase: 'Work', prompt: 'TODO: stage B per item', budget: { maxAgents: 4 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'a', kind: 'agent', phase: 'Work', prompt: 'TODO: stage A per item', budget: { maxAgents: 4 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'b', kind: 'agent', phase: 'Work', prompt: 'TODO: stage B per item', budget: { maxAgents: 4 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
         { stepId: 'jn', kind: 'join', phase: 'Work', deps: ['fan'] },
       ],
       fanouts: [{ stage: 'fan', registry: ['item1', 'item2', 'item3'], maxFanout: 3, chain: ['a', 'b'] }],
@@ -948,10 +951,10 @@ function workflowInitPlan(name: string, pattern: string): object {
       ...base,
       steps: [
         { stepId: 'fan', kind: 'fanout', phase: 'Lanes', concurrency: 'barrier', budget: { maxAgents: 6 } },
-        { stepId: 'lane', kind: 'agent', phase: 'Lanes', prompt: 'TODO: one lane', budget: { maxAgents: 6 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'lane', kind: 'agent', phase: 'Lanes', prompt: 'TODO: one lane', budget: { maxAgents: 6 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
         { stepId: 'jn', kind: 'join', phase: 'Lanes', deps: ['fan'] },
         // the consumer hangs off the BARRIER (jn), never the fork — barrier-postdominates teaches this
-        { stepId: 'synthesize', kind: 'agent', phase: 'Synthesize', deps: ['jn'], prompt: 'TODO: synthesize across lanes', budget: { maxAgents: 1 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'synthesize', kind: 'agent', phase: 'Synthesize', deps: ['jn'], prompt: 'TODO: synthesize across lanes', budget: { maxAgents: 1 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
       ],
       fanouts: [{ stage: 'fan', registry: ['lane1', 'lane2', 'lane3'], maxFanout: 3, chain: ['lane'] }],
       joins: [{ stage: 'jn', forStage: 'fan', joinPolicy: 'all-activated', onInvalid: 'named-failure' }],
@@ -961,8 +964,8 @@ function workflowInitPlan(name: string, pattern: string): object {
     return {
       ...base,
       steps: [
-        { stepId: 'work', kind: 'agent', phase: 'Work', prompt: 'TODO: produce the artifact', budget: { maxAgents: 2 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
-        { stepId: 'gate', kind: 'gate', phase: 'Gate', deps: ['work'], prompt: 'TODO: gate check (parse the verdict, never synthesize one)', budget: { maxAgents: 1 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'work', kind: 'agent', phase: 'Work', prompt: 'TODO: produce the artifact', budget: { maxAgents: 2 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        { stepId: 'gate', kind: 'gate', phase: 'Gate', deps: ['work'], prompt: 'TODO: gate check (parse the verdict, never synthesize one)', budget: { maxAgents: 1 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
       ],
       gates: [{ stepId: 'gate', kind: 'parse-verdict', failRoute: 'work', maxRedos: 1 }],
     };
@@ -970,7 +973,7 @@ function workflowInitPlan(name: string, pattern: string): object {
   // minimal default: one agent step
   return {
     ...base,
-    steps: [{ stepId: 'main', kind: 'agent', phase: 'Work', prompt: 'TODO: the one step', budget: { maxAgents: 1 } }], // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+    steps: [{ stepId: 'main', kind: 'agent', phase: 'Work', prompt: 'TODO: the one step', budget: { maxAgents: 1 }, tools: [] }], // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
   };
 }
 
@@ -1161,8 +1164,12 @@ function cmdWorkflowLint(options: Map<string, string>, flags: Set<string>, cwd:
 /** `dz workflow-trace` — timeline + invariant runner over a run's trace.jsonl. Scope is CAPPED
  * (AM-8): <runDir|--slug|--run>, --invariants, --html, --json. NO watch/filter/compare/search/
  * retention/access-control — adding one needs an ADR amendment (the surface test pins this). */
-/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
-function traceBundleToolVersion(): string {
+/**
+ * This CLI's OWN semver, read from its package.json. `unknown` is honest; a throw is not, and an
+ * invented number is worse than either — a downstream version guard that is handed a fabricated
+ * version happily calls a binary it should have refused.
+ */
+function dzOwnVersion(): string {
   try {
     const req = createRequire(import.meta.url);
     const pkg = req('../package.json') as { version?: unknown };
@@ -1170,6 +1177,11 @@ function traceBundleToolVersion(): string {
   } catch { return 'unknown'; }
 }
 
+/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
+function traceBundleToolVersion(): string {
+  return dzOwnVersion();
+}
+
 /** Resolve a run the SAME three ways the timeline reader does — positional, --slug, --run — so a
  * bundle can never address a run by a scheme the rest of the command does not understand. */
 function resolveTraceRun(options: Map<string, string>, cwd: string, positional: string | undefined):
@@ -8151,7 +8163,11 @@ const PROBE_SCRUB_ENV = [
  * lands, then kill it — the model never answers, so the probe costs ~no tokens. Never throws:
  * every failure becomes an `error` string, which the pure classifier turns into `inconclusive`.
  */
-function probeInitStream(projectDir: string, timeoutMs: number): Promise<{ stream: string; error: string | null }> {
+function probeInitStream(
+  projectDir: string,
+  timeoutMs: number,
+  pluginDir: string | null = null,
+): Promise<{ stream: string; error: string | null }> {
   return new Promise((resolveProbe) => {
     const env: NodeJS.ProcessEnv = { ...process.env };
     for (const key of PROBE_SCRUB_ENV) delete env[key];
@@ -8181,7 +8197,12 @@ function probeInitStream(projectDir: string, timeoutMs: number): Promise<{ strea
 
     try {
       // NOT `--bare`: that mode skips plugin credentials and fails with "Not logged in".
-      child = spawn('claude', ['-p', 'ok', '--output-format', 'stream-json', '--verbose'], {
+      const args = ['-p', 'ok', '--output-format', 'stream-json', '--verbose'];
+      // Session-scoped plugin load — the marketplace-free vehicle (ADR-003 D-3). Without this the
+      // probe reads a session in which the plugin was never loaded, and reports its commands
+      // missing for a reason that has nothing to do with the package under test.
+      if (pluginDir !== null) args.push('--plugin-dir', pluginDir);
+      child = spawn('claude', args, {
         cwd: projectDir,
         env,
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -8255,8 +8276,11 @@ async function cmdSkillsVerify(
 ): Promise<number> {
   const json = flags.has('json');
   if (flags.has('help')) {
-    write('dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--timeout <s>] [--json]');
+    write('dz skills-verify [--dir <project>] [--expect a,b] [--expect-commands a,b] [--plugin-dir <dir>] [--static] [--strict] [--timeout <s>] [--json]');
     write('  Verifies that a project\'s .claude/skills/ actually register in Claude Code.');
+    write('  --plugin-dir <dir>  load a plugin into the probe session (session-scoped, no marketplace);');
+    write('                      with no --expect-commands, the expectation defaults to the manifest\'s own commands[]');
+    write('  --expect-commands   slash commands that MUST appear in the session listing, e.g. loop-designer:init');
     write('  --static  layout scan only (no Claude session, CI-safe): flags dirs that can never register');
     write('  --live-content  ADVISORY extra turn: ask a live model to name the skills and quote one, proving');
     write('                  the CONTENT is usable — registration is not usability. Never changes the exit code.');
@@ -8266,8 +8290,9 @@ async function cmdSkillsVerify(
   }
 
   const allowedFlags = new Set(['json', 'help', 'static', 'strict', 'live-content']);
-  const allowedOptions = new Set(['dir', 'expect', 'timeout']);
-  const usage = '  allowed: --dir <project>, --expect a,b, --timeout <s>, --static, --strict, --live-content, --json';
+  const allowedOptions = new Set(['dir', 'expect', 'expect-commands', 'plugin-dir', 'timeout']);
+  const usage =
+    '  allowed: --dir <project>, --expect a,b, --expect-commands a,b, --plugin-dir <dir>, --timeout <s>, --static, --strict, --live-content, --json';
   if (options.has('_positional_0')) {
     const message = `unexpected argument "${options.get('_positional_0')}"`;
     write(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz skills-verify: ${message}\n${usage}`);
@@ -8297,6 +8322,28 @@ async function cmdSkillsVerify(
         .filter(Boolean)
     : scan.registrable;
 
+  // A plugin loaded with `--plugin-dir` is session-scoped, so its surface is NOT on the project's
+  // disk and `scan.registrable` cannot describe it. The manifest can — and defaulting to the
+  // manifest's own `commands[]` keeps the gate honest without a hand-typed list that silently
+  // drifts from the manifest it is supposed to be checking. An UNREADABLE manifest is refused
+  // rather than defaulted to an empty expectation: an empty expectation passes without checking.
+  const pluginDir = options.has('plugin-dir') ? resolve(cwd, options.get('plugin-dir') ?? '') : null;
+  let expectedCommands = options.has('expect-commands')
+    ? (options.get('expect-commands') ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+  if (pluginDir !== null && !options.has('expect-commands')) {
+    const surface = declaredPluginSurface(pluginDir);
+    if (surface === null) {
+      const message = `cannot read ${join(pluginDir, '.claude-plugin', 'plugin.json')} (or it declares no name) — pass --expect-commands explicitly`;
+      write(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz skills-verify: ${message}`);
+      return 1;
+    }
+    expectedCommands = surface.commands;
+  }
+
   // ── L1 only: deterministic, no session, safe for CI ──
   if (flags.has('static')) {
     const exitCode = scan.findings.length > 0 ? 1 : 0;
@@ -8307,6 +8354,11 @@ async function cmdSkillsVerify(
       if (!scan.exists) write('  no .claude/skills/ directory here');
       for (const f of scan.findings) write(`  [${f.kind}] ${f.detail}`);
       write(scan.findings.length ? `  ${scan.findings.length} layout problem(s) — these can never register` : '  no layout problems found');
+      // Advisories were collected but never PRINTED in static mode: a `.claude-plugin/plugin.json`
+      // under `.claude/skills` produced "no layout problems found" and nothing else, so the one
+      // shape most likely to be a silent non-registration was invisible in exactly the mode CI and
+      // humans run most. Reported, still never fatal (that distinction is the whole point).
+      for (const a of scan.advisories) write(`  [${a.kind}] ADVISORY: ${a.detail}`);
       write('  (static is a PROXY — run without --static to read the real registration listing)');
     }
     return exitCode;
@@ -8317,7 +8369,7 @@ async function cmdSkillsVerify(
   const timeoutMs = Number.isFinite(timeoutSec) && timeoutSec > 0 ? timeoutSec * 1000 : 180_000;
   if (!json) write(`dz skills-verify: starting a session in ${projectDir} to read the real registration listing…`);
 
-  const { stream, error } = await probeInitStream(projectDir, timeoutMs);
+  const { stream, error } = await probeInitStream(projectDir, timeoutMs, pluginDir);
 
   // `init.skills` carries names, not provenance: a USER-level skill of the same name would satisfy
   // the expectation while the project's own copy stays broken. Collect the collisions so the
@@ -8342,6 +8394,7 @@ async function cmdSkillsVerify(
       // The provenance check RAN (that is what `checked: true` asserts) — see `ambiguous` above.
       provenance: { checked: true, ambiguous },
       ...(options.has('expect') ? { expected } : {}),
+      ...(expectedCommands.length > 0 ? { expectedCommands } : {}),
     },
     { resolvePath: canonical },
   );
@@ -9295,6 +9348,26 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   };
   const { command, options, optionLists, flags } = parseArgs(argv);
 
+  // ── `dz --version` / `dz -v` / `dz version` — PRE-DISPATCH, before the help branch ──
+  //
+  // Until now `dz --version` printed the whole USAGE manual and exited 0 (MEASURED 2026-08-17,
+  // reproducer `node dist/bin.js --version`). Exit 0 plus prose is the worst possible answer for a
+  // caller that must decide whether a `dz` it found on PATH is safe to invoke: the status code says
+  // "fine" and there is no number to parse. Any wrapper guarding a version range needs exactly one
+  // parseable line. Recognised only as the FIRST token (or the `version` subcommand) so that a
+  // later positional `-v` belonging to a subcommand keeps its own meaning.
+  if (argv[0] === '--version' || argv[0] === '-v' || command === 'version') {
+    const version = dzOwnVersion();
+    if (flags.has('json')) {
+      write(JSON.stringify({ name: 'dz', version, node: process.version, schemas: { loopPlan: 'loop-plan/1' } }));
+    } else {
+      write(version);
+    }
+    // An unresolvable version is a FAILURE, not a value: exiting 0 with the literal `unknown` would
+    // let a guard treat "I could not tell you" as "I answered you".
+    return version === 'unknown' ? 1 : 0;
+  }
+
   if (command === '' || command === 'help' || flags.has('help')) {
     write(USAGE);
     return 0;

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dzhechko
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.