agentxchain 2.2.0 → 2.4.0

package/README.md

@@ -26,6 +26,22 @@ Or run without installing:
 npx agentxchain init --governed -y
 ```
 
+## Testing
+
+The CLI currently uses two runners on purpose: a 36-file Vitest coexistence slice for fast feedback and `node --test` for the full suite.
+
+```bash
+npm run test:vitest
+npm run test:node
+npm test
+```
+
+- `npm run test:vitest`: the current 36-file Vitest slice
+- `npm run test:node`: full integration, subprocess, and E2E suite
+- `npm test`: both runners in sequence; this is the CI requirement today
+
+Duplicate execution remains intentional for the current 36-file slice until a later slice explicitly changes the redundancy model. For watch mode, run `npx vitest`.
+
 ## Quick Start
 
 ### Governed workflow
@@ -51,6 +67,7 @@ Built-in governed templates:
 - `generic`: baseline governed scaffold
 - `api-service`: API contract, operational readiness, error budget
 - `cli-tool`: command surface, platform support, distribution checklist
+- `library`: public API, compatibility policy, release and adoption checklist
 - `web-app`: user flows, UI acceptance, browser support
 
 `step` writes a turn-scoped bundle under `.agentxchain/dispatch/turns/<turn_id>/` and expects a staged result at `.agentxchain/staging/<turn_id>/turn-result.json`. Typical continuation:

package/bin/agentxchain.js

@@ -79,6 +79,7 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { templateValidateCommand } from '../src/commands/template-validate.js';
 import {
   multiInitCommand,
   multiStatusCommand,
@@ -86,6 +87,14 @@ import {
   multiApproveGateCommand,
   multiResyncCommand,
 } from '../src/commands/multi.js';
+import { intakeRecordCommand } from '../src/commands/intake-record.js';
+import { intakeTriageCommand } from '../src/commands/intake-triage.js';
+import { intakeApproveCommand } from '../src/commands/intake-approve.js';
+import { intakePlanCommand } from '../src/commands/intake-plan.js';
+import { intakeStartCommand } from '../src/commands/intake-start.js';
+import { intakeScanCommand } from '../src/commands/intake-scan.js';
+import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
+import { intakeStatusCommand } from '../src/commands/intake-status.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -102,7 +111,7 @@ program
   .description('Create a new AgentXchain project folder')
   .option('-y, --yes', 'Skip prompts, use defaults')
   .option('--governed', 'Create a governed project (orchestrator-owned state)')
-  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, web-app')
+  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 
@@ -328,6 +337,12 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateListCommand);
 
+templateCmd
+  .command('validate')
+  .description('Validate the built-in governed template registry and current project template binding')
+  .option('-j, --json', 'Output as JSON')
+  .action(templateValidateCommand);
+
 const multiCmd = program
   .command('multi')
   .description('Multi-repo coordinator orchestration');
@@ -363,4 +378,85 @@ multiCmd
   .option('--dry-run', 'Detect divergence without resyncing')
   .action(multiResyncCommand);
 
+// --- Intake (v3) -----------------------------------------------------------
+
+const intakeCmd = program
+  .command('intake')
+  .description('Continuous governed delivery intake — record signals, triage intents, view status');
+
+intakeCmd
+  .command('record')
+  .description('Record a delivery trigger event and create a detected intent')
+  .option('--file <path>', 'Read event payload from a JSON file')
+  .option('--stdin', 'Read event payload from stdin')
+  .option('--source <source>', 'Inline event source (manual, ci_failure, git_ref_change, schedule)')
+  .option('--signal <json>', 'Inline signal object (JSON string, requires --source)')
+  .option('--evidence <json>', 'Inline evidence entry (JSON string, requires --source)')
+  .option('--category <category>', 'Optional event category override')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeRecordCommand);
+
+intakeCmd
+  .command('triage')
+  .description('Triage a detected intent — set priority, template, charter, and acceptance')
+  .requiredOption('--intent <id>', 'Intent ID to triage')
+  .option('--priority <level>', 'Priority level (p0, p1, p2, p3)')
+  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app)')
+  .option('--charter <text>', 'Delivery charter text')
+  .option('--acceptance <text>', 'Comma-separated acceptance criteria')
+  .option('--suppress', 'Suppress the intent instead of triaging')
+  .option('--reject', 'Reject a triaged intent')
+  .option('--reason <text>', 'Reason for suppress or reject')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeTriageCommand);
+
+intakeCmd
+  .command('approve')
+  .description('Approve a triaged intent for planning')
+  .option('--intent <id>', 'Intent ID to approve')
+  .option('--approver <name>', 'Name of the approving authority', 'operator')
+  .option('--reason <text>', 'Reason for approval')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeApproveCommand);
+
+intakeCmd
+  .command('plan')
+  .description('Generate planning artifacts and transition an approved intent to planned')
+  .option('--intent <id>', 'Intent ID to plan')
+  .option('--project-name <name>', 'Project name for template substitution')
+  .option('--force', 'Overwrite existing planning artifacts')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakePlanCommand);
+
+intakeCmd
+  .command('start')
+  .description('Start governed execution for a planned intent')
+  .option('--intent <id>', 'Intent ID to start')
+  .option('--role <role>', 'Override the default entry role for the governed phase')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeStartCommand);
+
+intakeCmd
+  .command('scan')
+  .description('Scan a structured source snapshot into intake events')
+  .requiredOption('--source <id>', 'Source type: ci_failure, git_ref_change, schedule')
+  .option('--file <path>', 'Path to snapshot JSON file')
+  .option('--stdin', 'Read snapshot from stdin')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeScanCommand);
+
+intakeCmd
+  .command('resolve')
+  .description('Resolve an executing intent by reading the governed run outcome')
+  .option('--intent <id>', 'Intent ID to resolve')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeResolveCommand);
+
+intakeCmd
+  .command('status')
+  .description('Show current intake state — events, intents, and aggregate counts')
+  .option('--intent <id>', 'Show detail for a specific intent')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeStatusCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
   ],
   "scripts": {
     "dev": "node bin/agentxchain.js",
-    "test": "node --test test/*.test.js",
+    "test": "npm run test:vitest && npm run test:node",
+    "test:vitest": "vitest run --reporter=verbose",
+    "test:node": "node --test test/*.test.js",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
@@ -46,12 +48,17 @@
   "homepage": "https://agentxchain.dev",
   "dependencies": {
     "@anthropic-ai/tokenizer": "0.0.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
     "inquirer": "^12.0.0",
-    "ora": "^8.0.0"
+    "ora": "^8.0.0",
+    "zod": "^4.3.6"
   },
   "engines": {
     "node": ">=18.17.0 || >=20.5.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.2"
   }
 }

package/scripts/publish-from-tag.sh

@@ -58,16 +58,21 @@ echo "Publishing ${PACKAGE_NAME}@${RELEASE_VERSION} from ${TAG}"
 echo "Running strict release preflight..."
 bash scripts/release-preflight.sh --strict --target-version "${RELEASE_VERSION}"
 
-echo "Running npm publish..."
-if [[ -n "${NPM_TOKEN:-}" ]]; then
-  echo "Publish auth mode: token"
-  TMP_NPMRC="$(mktemp "${TMPDIR:-/tmp}/agentxchain-npmrc.XXXXXX")"
-  chmod 600 "$TMP_NPMRC"
-  printf '%s\n' "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$TMP_NPMRC"
-  NPM_CONFIG_USERCONFIG="$TMP_NPMRC" npm publish --access public
+EXISTING_VERSION="$(npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" version 2>/dev/null || true)"
+if [[ "$EXISTING_VERSION" == "$RELEASE_VERSION" ]]; then
+  echo "Registry already serves ${PACKAGE_NAME}@${RELEASE_VERSION}; skipping npm publish and proceeding to verification."
 else
-  echo "Publish auth mode: trusted publishing (OIDC)"
-  npm publish --access public
+  echo "Running npm publish..."
+  if [[ -n "${NPM_TOKEN:-}" ]]; then
+    echo "Publish auth mode: token"
+    TMP_NPMRC="$(mktemp "${TMPDIR:-/tmp}/agentxchain-npmrc.XXXXXX")"
+    chmod 600 "$TMP_NPMRC"
+    printf '%s\n' "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$TMP_NPMRC"
+    NPM_CONFIG_USERCONFIG="$TMP_NPMRC" npm publish --access public
+  else
+    echo "Publish auth mode: trusted publishing (OIDC)"
+    npm publish --access public
+  fi
 fi
 
 echo "Verifying registry visibility..."

package/scripts/release-postflight.sh

@@ -11,7 +11,7 @@ cd "$CLI_DIR"
 
 TARGET_VERSION=""
 TAG=""
-RETRY_ATTEMPTS="${RELEASE_POSTFLIGHT_RETRY_ATTEMPTS:-6}"
+RETRY_ATTEMPTS="${RELEASE_POSTFLIGHT_RETRY_ATTEMPTS:-12}"
 RETRY_DELAY_SECONDS="${RELEASE_POSTFLIGHT_RETRY_DELAY_SECONDS:-10}"
 
 usage() {
@@ -75,6 +75,7 @@ FAIL=0
 TARBALL_URL=""
 REGISTRY_CHECKSUM=""
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
+PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const names = Object.keys(pkg.bin || {}); if (names.length !== 1) { console.error('package.json bin must declare exactly one entry'); process.exit(1); } console.log(names[0]);")"
 
 pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
 fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
@@ -96,6 +97,45 @@ trim_last_line() {
   printf '%s\n' "$1" | awk 'NF { line=$0 } END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line }'
 }
 
+run_install_smoke() {
+  if [[ -z "$TARBALL_URL" ]]; then
+    echo "registry tarball metadata unavailable for install smoke" >&2
+    return 1
+  fi
+
+  local smoke_root
+  local bin_path
+  local install_status
+  local version_status
+
+  smoke_root="$(mktemp -d "${TMPDIR:-/tmp}/agentxchain-postflight.XXXXXX")"
+  bin_path="${smoke_root}/bin/${PACKAGE_BIN_NAME}"
+
+  # Isolate the install from CI auth environment (OIDC tokens from actions/setup-node
+  # are scoped for publish, not read, and can cause npm install to fail on public packages).
+  local smoke_npmrc="${smoke_root}/.npmrc"
+  echo "registry=https://registry.npmjs.org/" > "$smoke_npmrc"
+
+  env -u NODE_AUTH_TOKEN NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
+    npm install --global --prefix "$smoke_root" "$TARBALL_URL" >/dev/null 2>&1
+  install_status=$?
+  if [[ "$install_status" -ne 0 ]]; then
+    rm -rf "$smoke_root"
+    return "$install_status"
+  fi
+
+  if [[ ! -x "$bin_path" ]]; then
+    echo "installed binary missing at ${bin_path}" >&2
+    rm -rf "$smoke_root"
+    return 1
+  fi
+
+  "$bin_path" --version
+  version_status=$?
+  rm -rf "$smoke_root"
+  return "$version_status"
+}
+
 run_with_retry() {
   local __output_var="$1"
   local description="$2"
@@ -201,7 +241,7 @@ else
 fi
 
 echo "[5/5] Install smoke"
-if run_with_retry EXEC_OUTPUT "install smoke" nonempty "" npm exec --yes --package "${PACKAGE_NAME}@${TARGET_VERSION}" -- agentxchain --version; then
+if run_with_retry EXEC_OUTPUT "install smoke" nonempty "" run_install_smoke; then
   EXEC_VERSION="$(trim_last_line "$EXEC_OUTPUT")"
   if [[ "$EXEC_VERSION" == "$TARGET_VERSION" ]]; then
     pass "published CLI executes and reports ${TARGET_VERSION}"

package/src/commands/init.js

@@ -483,6 +483,7 @@ async function initGoverned(opts) {
     console.error('    generic       Default governed scaffold');
     console.error('    api-service   Governed scaffold for a backend service');
     console.error('    cli-tool      Governed scaffold for a CLI tool');
+    console.error('    library       Governed scaffold for a reusable package');
     console.error('    web-app       Governed scaffold for a web application');
     process.exit(1);
   }

package/src/commands/intake-approve.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { approveIntent } from '../lib/intake.js';
+
+export async function intakeApproveCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
+    } else {
+      console.log(chalk.red('agentxchain.json not found'));
+    }
+    process.exit(2);
+  }
+
+  if (!opts.intent) {
+    const msg = '--intent <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  const result = approveIntent(root, opts.intent, {
+    approver: opts.approver || undefined,
+    reason: opts.reason || undefined,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    console.log(chalk.green(`  Approved intent ${result.intent.intent_id}`));
+    console.log(chalk.dim(`  Approver: ${result.intent.approved_by}`));
+    console.log(chalk.dim(`  Status: triaged → approved`));
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}

package/src/commands/intake-plan.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { planIntent } from '../lib/intake.js';
+import { basename } from 'node:path';
+
+export async function intakePlanCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
+    } else {
+      console.log(chalk.red('agentxchain.json not found'));
+    }
+    process.exit(2);
+  }
+
+  if (!opts.intent) {
+    const msg = '--intent <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  const result = planIntent(root, opts.intent, {
+    projectName: opts.projectName || undefined,
+    force: opts.force || false,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    console.log(chalk.green(`  Planned intent ${result.intent.intent_id}`));
+    console.log(chalk.dim(`  Template: ${result.intent.template}`));
+    if (result.artifacts_generated.length > 0) {
+      console.log(chalk.dim('  Generated planning artifacts:'));
+      for (const a of result.artifacts_generated) {
+        console.log(chalk.dim(`    ${a}`));
+      }
+    } else {
+      console.log(chalk.dim('  No template-specific planning artifacts to generate.'));
+    }
+    console.log(chalk.dim(`  Status: approved → planned`));
+    console.log('');
+  } else if (result.conflicts) {
+    console.log('');
+    console.log(chalk.red(`  Cannot plan intent ${opts.intent}`));
+    console.log(chalk.red('  Existing planning artifacts would be overwritten:'));
+    for (const c of result.conflicts) {
+      console.log(chalk.red(`    ${c}`));
+    }
+    console.log(chalk.yellow('  Use --force to overwrite, or remove the existing files first.'));
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}

package/src/commands/intake-record.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findProjectRoot } from '../lib/config.js';
+import { recordEvent } from '../lib/intake.js';
+
+export async function intakeRecordCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
+    } else {
+      console.log(chalk.red('agentxchain.json not found'));
+    }
+    process.exit(2);
+  }
+
+  let payload;
+  try {
+    payload = parsePayload(opts);
+  } catch (err) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: err.message }, null, 2));
+    } else {
+      console.log(chalk.red(err.message));
+    }
+    process.exit(1);
+  }
+
+  const result = recordEvent(root, payload);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    if (result.deduplicated) {
+      console.log('');
+      console.log(chalk.yellow(`  Event already recorded: ${result.event.event_id} (deduplicated)`));
+      if (result.intent) {
+        console.log(chalk.dim(`  Linked intent: ${result.intent.intent_id} (${result.intent.status})`));
+      }
+    } else {
+      console.log('');
+      console.log(chalk.green(`  Recorded event ${result.event.event_id}`));
+      console.log(chalk.green(`  Created intent ${result.intent.intent_id} (detected)`));
+    }
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}
+
+function parsePayload(opts) {
+  if (opts.file) {
+    const raw = readFileSync(resolve(opts.file), 'utf8');
+    return JSON.parse(raw);
+  }
+
+  if (opts.stdin) {
+    const raw = readFileSync(0, 'utf8');
+    return JSON.parse(raw);
+  }
+
+  if (opts.source) {
+    if (!opts.signal) throw new Error('--source requires --signal');
+    if (!opts.evidence) throw new Error('--source requires --evidence');
+
+    const signal = JSON.parse(opts.signal);
+    let evidence;
+    if (Array.isArray(opts.evidence)) {
+      evidence = opts.evidence.map(e => JSON.parse(e));
+    } else {
+      evidence = [JSON.parse(opts.evidence)];
+    }
+
+    return {
+      source: opts.source,
+      signal,
+      evidence,
+      category: opts.category || undefined,
+    };
+  }
+
+  throw new Error('one of --file, --stdin, or --source is required');
+}

package/src/commands/intake-resolve.js

@@ -0,0 +1,45 @@
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { resolveIntent } from '../lib/intake.js';
+
+export async function intakeResolveCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
+    } else {
+      console.log(chalk.red('agentxchain.json not found'));
+    }
+    process.exit(2);
+  }
+
+  if (!opts.intent) {
+    const msg = '--intent <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  const result = resolveIntent(root, opts.intent);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    if (result.no_change) {
+      console.log(chalk.yellow(`  Intent ${opts.intent} — run still ${result.run_outcome}, no transition`));
+    } else {
+      console.log(chalk.green(`  Resolved intent ${opts.intent}`));
+      console.log(chalk.dim(`  ${result.previous_status} → ${result.new_status}`));
+      console.log(chalk.dim(`  Run outcome: ${result.run_outcome}`));
+    }
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}

package/src/commands/intake-scan.js

@@ -0,0 +1,87 @@
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findProjectRoot } from '../lib/config.js';
+import { scanSource, SCAN_SOURCES } from '../lib/intake.js';
+
+export async function intakeScanCommand(opts) {
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
+    } else {
+      console.log(chalk.red('agentxchain.json not found'));
+    }
+    process.exit(2);
+  }
+
+  if (!opts.source) {
+    const msg = `--source is required. Supported scan sources: ${SCAN_SOURCES.join(', ')}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (!opts.file && !opts.stdin) {
+    const msg = 'one of --file or --stdin is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (opts.file && opts.stdin) {
+    const msg = '--file and --stdin are mutually exclusive';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  let snapshot;
+  try {
+    let raw;
+    if (opts.file) {
+      raw = readFileSync(resolve(opts.file), 'utf8');
+    } else {
+      raw = readFileSync(0, 'utf8');
+    }
+    snapshot = JSON.parse(raw);
+  } catch (err) {
+    const msg = opts.file
+      ? `failed to read snapshot from ${opts.file}: ${err.message}`
+      : `failed to read snapshot from stdin: ${err.message}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(opts.file && err.code === 'ENOENT' ? 2 : 1);
+  }
+
+  const result = scanSource(root, opts.source, snapshot);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    console.log(chalk.green(`  Scan complete: ${result.scanned} item(s) processed`));
+    console.log(`  Created:      ${result.created}`);
+    console.log(`  Deduplicated: ${result.deduplicated}`);
+    if (result.rejected > 0) {
+      console.log(chalk.yellow(`  Rejected:     ${result.rejected}`));
+    }
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}