@produck/agent-toolkit 0.2.1 → 0.3.3

package/README.md

@@ -4,42 +4,86 @@ Central CLI toolkit for organization-level AI execution workflows.
 
 ## Commands
 
+- agent-toolkit enforce-node-baseline
 - agent-toolkit preflight
 - agent-toolkit run-capture
 - agent-toolkit summarize-log
+- agent-toolkit sync-coverage-script
+- agent-toolkit sync-husky-hooks
 - agent-toolkit validate-commit-msg
 - agent-toolkit sync-instructions
 
 ## Examples
 
+Run default mandatory baseline flow in downstream repository root:
+
+```
+npm exec -- agent-toolkit
+```
+
+Equivalent explicit form:
+
+```
+npm exec -- agent-toolkit enforce-node-baseline --cwd .
+```
+
 Run preflight checks:
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+npm exec -- agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+```
+
+Run one-shot mandatory baseline steps for downstream monorepo (1 -> 2 -> 3):
+
+```
+npm exec -- agent-toolkit enforce-node-baseline --cwd .
+```
+
+Validate monorepo root workspace package.json baseline:
+
+```
+npm exec -- agent-toolkit preflight --cwd . --check-workspace-package-json package.json
 ```
 
 Capture long output safely:
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit run-capture --cwd . --cmd "npm run test" --out logs/test.log
+npm exec -- agent-toolkit run-capture --cwd . --cmd "npm run test" --out logs/test.log
 ```
 
 Summarize captured output:
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
+npm exec -- agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
+```
+
+Deploy organization coverage script and pinned local c8 devDependency to
+workspace packages:
+
+```
+npm exec -- agent-toolkit sync-coverage-script --cwd .
+```
+
+Deploy organization local anti-drift husky hooks to repository root:
+
+```
+npm exec -- agent-toolkit sync-husky-hooks --cwd .
 ```
 
+This command pins root local hook dependencies (`husky` and
+`@produck/agent-toolkit`) and syncs `.husky/pre-commit` and
+`.husky/commit-msg`.
+
 Validate commit message format:
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
+npm exec -- agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
 ```
 
 Manual per-repository instruction distribution (write .github/instructions/produck/\*.instructions.md):
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd .
+npm exec -- agent-toolkit sync-instructions --cwd .
 ```
 
 Legacy repository bootstrap behavior:
@@ -52,7 +96,7 @@ Legacy repository bootstrap behavior:
 Use organization source directory instead of built-in assets:
 
 ```
-npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd . --source path/to/org/.github/distribution/produck --force --prune
+npm exec -- agent-toolkit sync-instructions --cwd . --source path/to/org/.github/distribution/produck --force --prune
 ```
 
 Built-in command-local resource locations (for review and updates):

package/bin/agent-toolkit.mjs

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
 import { printMainHelp } from './command/main/index.mjs';
+import {
+  printEnforceNodeBaselineHelp,
+  runEnforceNodeBaseline,
+} from './command/enforce-node-baseline/index.mjs';
 import { printPreflightHelp, runPreflight } from './command/preflight/index.mjs';
 import { printRunCaptureHelp, runCapture } from './command/run-capture/index.mjs';
 import { printSummarizeHelp, runSummarize } from './command/summarize-log/index.mjs';
+import {
+  printSyncCoverageScriptHelp,
+  runSyncCoverageScript,
+} from './command/sync-coverage-script/index.mjs';
+import { printSyncHuskyHooksHelp, runSyncHuskyHooks } from './command/sync-husky-hooks/index.mjs';
 import {
   printSyncInstructionsHelp,
   runSyncInstructions,
@@ -14,6 +23,10 @@ import {
 } from './command/validate-commit-msg/index.mjs';
 
 const COMMANDS = {
+  'enforce-node-baseline': {
+    printHelp: printEnforceNodeBaselineHelp,
+    run: runEnforceNodeBaseline,
+  },
   preflight: {
     printHelp: printPreflightHelp,
     run: runPreflight,
@@ -26,6 +39,14 @@ const COMMANDS = {
     printHelp: printSummarizeHelp,
     run: runSummarize,
   },
+  'sync-coverage-script': {
+    printHelp: printSyncCoverageScriptHelp,
+    run: runSyncCoverageScript,
+  },
+  'sync-husky-hooks': {
+    printHelp: printSyncHuskyHooksHelp,
+    run: runSyncHuskyHooks,
+  },
   'validate-commit-msg': {
     printHelp: printValidateCommitMsgHelp,
     run: runValidateCommitMsg,
@@ -36,6 +57,8 @@ const COMMANDS = {
   },
 };
 
+const DEFAULT_COMMAND = 'enforce-node-baseline';
+
 function printCommandHelp(command) {
   const entry = COMMANDS[command];
   if (!entry) {
@@ -50,17 +73,19 @@ function main() {
   const command = parsed.positional[0] || '';
   const options = parsed.options;
 
-  if (!command || command === '--help' || command === '-h') {
+  if (command === '--help' || command === '-h' || (!command && hasFlag(options, '--help'))) {
     printMainHelp();
     process.exit(0);
   }
 
+  const effectiveCommand = command || DEFAULT_COMMAND;
+
   if (hasFlag(options, '--help') || hasFlag(options, '-h')) {
-    printCommandHelp(command);
+    printCommandHelp(effectiveCommand);
     process.exit(0);
   }
 
-  const entry = COMMANDS[command];
+  const entry = COMMANDS[effectiveCommand];
   if (!entry) {
     console.error(`Unknown command: ${command}`);
     printMainHelp();

package/bin/build-publish-assets.mjs

@@ -8,6 +8,8 @@ const PACKAGE_ROOT = path.resolve(SCRIPT_DIR, '..');
 const REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..');
 const SOURCE_DIR = path.resolve(REPO_ROOT, '.github/distribution/produck');
 const OUTPUT_DIR = path.resolve(PACKAGE_ROOT, 'publish-assets/instructions/produck');
+const SOURCE_TOOLING_BASELINE_PATH = path.resolve(SOURCE_DIR, 'tooling-version-baseline.json');
+const OUTPUT_TOOLING_BASELINE_PATH = path.resolve(OUTPUT_DIR, 'tooling-version-baseline.json');
 const LEGACY_OUTPUT_PATH = path.resolve(
   PACKAGE_ROOT,
   'publish-assets/instructions/org.instructions.md',
@@ -39,6 +41,47 @@ function validateSourceFile(fileName, text) {
   }
 }
 
+function readAndValidateToolingBaseline() {
+  if (!fs.existsSync(SOURCE_TOOLING_BASELINE_PATH)) {
+    throw new Error(`Missing tooling baseline source file: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  let baseline;
+  try {
+    baseline = JSON.parse(fs.readFileSync(SOURCE_TOOLING_BASELINE_PATH, 'utf8'));
+  } catch {
+    throw new Error(`Invalid tooling baseline JSON: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  const c8Version = baseline?.tools?.c8?.version;
+  const lernaVersion = baseline?.tools?.lerna?.version;
+  const coverageScriptTemplate = baseline?.coverage?.scriptTemplate;
+
+  if (typeof baseline.schemaVersion !== 'number') {
+    throw new Error(`Invalid tooling baseline schemaVersion in: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  if (typeof c8Version !== 'string' || c8Version.trim() === '') {
+    throw new Error(`Invalid tools.c8.version in: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  if (typeof lernaVersion !== 'string' || lernaVersion.trim() === '') {
+    throw new Error(`Invalid tools.lerna.version in: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  if (typeof coverageScriptTemplate !== 'string' || coverageScriptTemplate.trim() === '') {
+    throw new Error(`Invalid coverage.scriptTemplate in: ${SOURCE_TOOLING_BASELINE_PATH}`);
+  }
+
+  if (!coverageScriptTemplate.includes('{c8.version}')) {
+    throw new Error(
+      `coverage.scriptTemplate must include {c8.version} in: ${SOURCE_TOOLING_BASELINE_PATH}`,
+    );
+  }
+
+  return `${JSON.stringify(baseline, null, 2)}\n`;
+}
+
 function readSourceEntries() {
   if (!fs.existsSync(SOURCE_DIR)) {
     throw new Error(`Missing source directory: ${SOURCE_DIR}`);
@@ -94,6 +137,12 @@ function run() {
     process.stdout.write(`Generated ${outPath} from ${entry.sourcePath}\n`);
   }
 
+  const toolingBaselineText = readAndValidateToolingBaseline();
+  fs.writeFileSync(OUTPUT_TOOLING_BASELINE_PATH, toolingBaselineText, 'utf8');
+  process.stdout.write(
+    `Generated ${OUTPUT_TOOLING_BASELINE_PATH} from ${SOURCE_TOOLING_BASELINE_PATH}\n`,
+  );
+
   cleanStaleManagedFiles(expectedNames);
 
   if (fs.existsSync(LEGACY_OUTPUT_PATH)) {

package/bin/command/enforce-node-baseline/help.txt

@@ -0,0 +1,19 @@
+Usage:
+  agent-toolkit enforce-node-baseline [--cwd <dir>] [--source <file-or-dir>]
+    [--force] [--prune] [--workspace <path>] ... [--check] [--dry-run]
+    [--json <file>]
+
+Behavior:
+  - Runs mandatory baseline flow in fixed order:
+    1) sync-instructions
+    2) preflight
+    3) sync-coverage-script
+    4) sync-husky-hooks
+  - Stops at first failed step and exits non-zero
+  - Prints one combined JSON report for all executed steps
+
+Rules:
+  - --check runs non-mutating validation mode for step 1, step 3, and step 4
+  - --dry-run runs non-mutating preview mode for step 1, step 3, and step 4
+  - --check takes precedence over --dry-run
+  - --workspace filters coverage sync targets in step 3

package/bin/command/enforce-node-baseline/index.mjs

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { getMulti, getSingle, hasFlag } from '../shared/args.mjs';
+import { printTextResource } from '../shared/text-resource.mjs';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const TOOLKIT_BIN = path.resolve(COMMAND_DIR, '../../agent-toolkit.mjs');
+
+export function printEnforceNodeBaselineHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function parseJsonOrNull(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+function runToolkitSubcommand(cwd, args) {
+  const result = spawnSync(process.execPath, [TOOLKIT_BIN, ...args], {
+    cwd,
+    encoding: 'utf8',
+  });
+
+  const stdout = String(result.stdout || '');
+  const stderr = String(result.stderr || '');
+  const status = typeof result.status === 'number' ? result.status : 1;
+
+  return {
+    args,
+    status,
+    ok: status === 0,
+    report: parseJsonOrNull(stdout),
+    stdout,
+    stderr,
+  };
+}
+
+function buildStepReport(name, stepResult) {
+  const hasParsedReport = Boolean(stepResult.report);
+
+  return {
+    name,
+    args: stepResult.args,
+    status: stepResult.status,
+    ok: stepResult.ok,
+    report: stepResult.report,
+    stdout: hasParsedReport ? '' : stepResult.stdout,
+    stderr: stepResult.stderr,
+  };
+}
+
+export function runEnforceNodeBaseline(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const source = getSingle(options, '--source', '');
+  const force = hasFlag(options, '--force');
+  const prune = hasFlag(options, '--prune');
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run') && !check;
+  const jsonFile = getSingle(options, '--json', '');
+  const workspaces = getMulti(options, '--workspace');
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const mode = check ? 'check' : dryRun ? 'dry-run' : 'sync';
+  const report = {
+    cwd,
+    mode,
+    ok: true,
+    steps: [],
+  };
+
+  const syncInstructionsArgs = ['sync-instructions', '--cwd', cwd];
+  if (source) {
+    syncInstructionsArgs.push('--source', source);
+  }
+  if (force) {
+    syncInstructionsArgs.push('--force');
+  }
+  if (prune) {
+    syncInstructionsArgs.push('--prune');
+  }
+  if (mode !== 'sync') {
+    syncInstructionsArgs.push('--dry-run');
+  }
+
+  const preflightArgs = [
+    'preflight',
+    '--cwd',
+    cwd,
+    '--require',
+    'package.json',
+    '--check-workspace-package-json',
+    'package.json',
+  ];
+
+  const syncCoverageArgs = ['sync-coverage-script', '--cwd', cwd];
+  for (const workspacePath of workspaces) {
+    syncCoverageArgs.push('--workspace', workspacePath);
+  }
+  if (check) {
+    syncCoverageArgs.push('--check');
+  } else if (dryRun) {
+    syncCoverageArgs.push('--dry-run');
+  }
+
+  const syncHuskyArgs = ['sync-husky-hooks', '--cwd', cwd];
+  if (check) {
+    syncHuskyArgs.push('--check');
+  } else if (dryRun) {
+    syncHuskyArgs.push('--dry-run');
+  }
+
+  const plan = [
+    { name: 'sync-instructions', args: syncInstructionsArgs },
+    { name: 'preflight', args: preflightArgs },
+    { name: 'sync-coverage-script', args: syncCoverageArgs },
+    { name: 'sync-husky-hooks', args: syncHuskyArgs },
+  ];
+
+  for (const step of plan) {
+    const stepResult = runToolkitSubcommand(cwd, step.args);
+    report.steps.push(buildStepReport(step.name, stepResult));
+
+    if (!stepResult.ok) {
+      report.ok = false;
+      break;
+    }
+  }
+
+  if (jsonFile) {
+    const outPath = path.resolve(cwd, jsonFile);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) {
+    process.exit(2);
+  }
+}

package/bin/command/main/help.txt

@@ -1,9 +1,16 @@
 agent-toolkit commands:
+  enforce-node-baseline
   preflight
   run-capture
   summarize-log
+  sync-coverage-script
+  sync-husky-hooks
   validate-commit-msg
   sync-instructions
 
+Default:
+  agent-toolkit
+  # equivalent to: agent-toolkit enforce-node-baseline
+
 Use:
   agent-toolkit <command> --help

package/bin/command/preflight/help.txt

@@ -1,3 +1,9 @@
 Usage:
   agent-toolkit preflight [--cwd <dir>] [--require <path>] ...
     [--ensure-dir <path>] ... [--json <file>]
+    [--check-workspace-package-json <path>]
+
+Rules for --check-workspace-package-json:
+  - `private` must be true
+  - `workspaces` must be a non-empty array of explicit paths (no glob tokens)
+  - `scripts` must include deps:install, test, produck:coverage, lint

package/bin/command/preflight/index.mjs

@@ -2,53 +2,142 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { getMulti, getSingle } from '../shared/args.mjs';
+import { getSingle, hasFlag } from '../shared/args.mjs';
 import { printTextResource } from '../shared/text-resource.mjs';
 
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
 const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
+const REQUIRED_WORKSPACE_FIELDS = ['private', 'workspaces', 'scripts'];
+const REQUIRED_WORKSPACE_SCRIPTS = ['deps:install', 'test', 'produck:coverage', 'lint'];
 
 export function printPreflightHelp() {
   printTextResource(HELP_FILE);
 }
 
+function validateWorkspacePackageJson(cwd, checkPath) {
+  const packagePath = path.resolve(cwd, checkPath);
+  const check = {
+    file: checkPath,
+    ok: true,
+    exists: true,
+    validJson: true,
+    missingFields: [],
+    missingScripts: [],
+    wildcardWorkspaces: [],
+    scriptTypeValid: true,
+  };
+
+  if (!fs.existsSync(packagePath)) {
+    check.ok = false;
+    check.exists = false;
+    return check;
+  }
+
+  let json;
+  try {
+    json = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  } catch {
+    check.ok = false;
+    check.validJson = false;
+    return check;
+  }
+
+  check.missingFields = REQUIRED_WORKSPACE_FIELDS.filter((field) => {
+    return !(field in json);
+  });
+
+  if (typeof json.scripts !== 'object' || json.scripts === null || Array.isArray(json.scripts)) {
+    check.scriptTypeValid = false;
+    check.ok = false;
+  } else {
+    check.missingScripts = REQUIRED_WORKSPACE_SCRIPTS.filter((scriptName) => {
+      return !(scriptName in json.scripts);
+    });
+  }
+
+  const workspaceList = Array.isArray(json.workspaces)
+    ? json.workspaces.map((entry) => String(entry))
+    : [];
+  if (!Array.isArray(json.workspaces)) {
+    check.wildcardWorkspaces = ['<non-array-workspaces>'];
+    check.ok = false;
+  } else {
+    check.wildcardWorkspaces = workspaceList.filter((entry) => GLOB_TOKEN_PATTERN.test(entry));
+  }
+
+  if (json.private !== true) {
+    check.ok = false;
+  }
+
+  if (check.missingFields.length > 0 || check.missingScripts.length > 0) {
+    check.ok = false;
+  }
+
+  if (check.wildcardWorkspaces.length > 0) {
+    check.ok = false;
+  }
+
+  return check;
+}
+
 export function runPreflight(options) {
   const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
-  const required = getMulti(options, '--require');
-  const ensureDir = getMulti(options, '--ensure-dir');
+  const requireTargets = options['--require'] || [];
+  const ensureDirs = options['--ensure-dir'] || [];
+  const checkWorkspacePackageJson = getSingle(options, '--check-workspace-package-json', '');
+  const dryRun = hasFlag(options, '--dry-run');
   const jsonFile = getSingle(options, '--json', '');
 
-  if (!fs.existsSync(cwd)) {
-    console.error(`CWD does not exist: ${cwd}`);
-    process.exit(2);
-  }
-
   const report = {
     cwd,
-    required: [],
-    ensuredDirectories: [],
+    dryRun,
     ok: true,
+    required: [],
+    ensuredDirs: [],
+    workspacePackageJson: null,
   };
 
-  for (const rel of required) {
-    const resolved = path.resolve(cwd, rel);
-    const exists = fs.existsSync(resolved);
-    report.required.push({ path: rel, resolved, exists });
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  for (const target of requireTargets) {
+    const absolute = path.resolve(cwd, String(target));
+    const exists = fs.existsSync(absolute);
+    report.required.push({ target: String(target), absolute, exists });
     if (!exists) {
       report.ok = false;
     }
   }
 
-  for (const rel of ensureDir) {
-    const resolved = path.resolve(cwd, rel);
-    fs.mkdirSync(resolved, { recursive: true });
-    report.ensuredDirectories.push({ path: rel, resolved, created: true });
+  for (const dir of ensureDirs) {
+    const absolute = path.resolve(cwd, String(dir));
+    const existedBefore = fs.existsSync(absolute);
+    if (!dryRun && !existedBefore) {
+      fs.mkdirSync(absolute, { recursive: true });
+    }
+    report.ensuredDirs.push({
+      target: String(dir),
+      absolute,
+      existedBefore,
+      existsAfter: fs.existsSync(absolute),
+    });
+  }
+
+  if (checkWorkspacePackageJson) {
+    const workspaceCheck = validateWorkspacePackageJson(cwd, checkWorkspacePackageJson);
+    report.workspacePackageJson = workspaceCheck;
+    if (!workspaceCheck.ok) {
+      report.ok = false;
+    }
   }
 
   if (jsonFile) {
-    const out = path.resolve(cwd, jsonFile);
-    fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    const outPath = path.resolve(cwd, jsonFile);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
   }
 
   process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);

package/bin/command/sync-coverage-script/help.txt

@@ -0,0 +1,22 @@
+Usage:
+  agent-toolkit sync-coverage-script [--cwd <dir>]
+    [--workspace <path>] ... [--check] [--dry-run] [--json <file>]
+
+Behavior:
+  - Applies organization-required coverage script to workspace package.json files
+  - Organization-reserved script key is scripts.produck:coverage
+  - Applies organization-required pinned local c8 devDependency to workspace
+    package.json files
+  - Target script is rendered from organization tooling baseline file
+    (lookup order):
+    1) .github/distribution/produck/tooling-version-baseline.json
+    2) publish-assets/instructions/produck/tooling-version-baseline.json
+  - Baseline template:
+    c8 --reporter=lcov --reporter=html --reporter=text-summary npm test
+
+Rules:
+  - When --workspace is omitted, root package.json workspaces are used
+  - Root workspaces must be explicit paths (no glob tokens)
+  - Workspace package.json files must pin devDependencies.c8 to baseline version
+  - --check validates without writing and exits non-zero on mismatch
+  - --dry-run prints planned changes without writing