@produck/agent-toolkit 0.2.0 → 0.3.3

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/{templates/help/main.txt → 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/main/index.mjs

@@ -0,0 +1,11 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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');
+
+export function printMainHelp() {
+  printTextResource(HELP_FILE);
+}

package/bin/command/preflight/help.txt

@@ -0,0 +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

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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 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', '');
+
+  const report = {
+    cwd,
+    dryRun,
+    ok: true,
+    required: [],
+    ensuredDirs: [],
+    workspacePackageJson: null,
+  };
+
+  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 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 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/run-capture/index.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+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');
+
+export function printRunCaptureHelp() {
+  printTextResource(HELP_FILE);
+}
+
+export function runCapture(options) {
+  const out = getSingle(options, '--out', '');
+  const cmd = getSingle(options, '--cmd', '');
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const meta = getSingle(options, '--meta', '');
+  const allowPipe = hasFlag(options, '--allow-pipe');
+
+  if (!out || !cmd) {
+    printRunCaptureHelp();
+    process.exit(2);
+  }
+
+  if (!allowPipe && cmd.includes('|')) {
+    console.error('Blocked command containing pipe. Use --allow-pipe if needed.');
+    process.exit(2);
+  }
+
+  const outPath = path.resolve(out);
+  const metaPath = meta ? path.resolve(meta) : `${outPath}.meta.json`;
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+
+  const startAt = Date.now();
+  const outStream = fs.createWriteStream(outPath, { encoding: 'utf8' });
+
+  outStream.write(`# command: ${cmd}\n`);
+  outStream.write(`# cwd: ${cwd}\n`);
+  outStream.write(`# startedAt: ${new Date(startAt).toISOString()}\n\n`);
+
+  const child = spawn(cmd, {
+    cwd,
+    shell: true,
+    env: process.env,
+  });
+
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+
+  child.stdout.on('data', (chunk) => {
+    stdoutBytes += chunk.length;
+    outStream.write(chunk);
+  });
+
+  child.stderr.on('data', (chunk) => {
+    stderrBytes += chunk.length;
+    outStream.write(chunk);
+  });
+
+  child.on('error', (error) => {
+    outStream.write(`\n[agent-toolkit] spawn error: ${error.message}\n`);
+  });
+
+  child.on('close', (code, signal) => {
+    const endAt = Date.now();
+    const durationMs = endAt - startAt;
+    const signalLabel = String(signal).replace(/^null$/, 'none');
+    const numberCode = Number(code);
+    const isNumberCode = Number(typeof code === 'number');
+    const normalizedExitCode = isNumberCode * numberCode + (1 - isNumberCode);
+
+    outStream.write('\n');
+    outStream.write(`# finishedAt: ${new Date(endAt).toISOString()}\n`);
+    outStream.write(`# exitCode: ${String(code)}\n`);
+    outStream.write(`# signal: ${signalLabel}\n`);
+    outStream.end();
+
+    const report = {
+      command: cmd,
+      cwd,
+      startedAt: new Date(startAt).toISOString(),
+      finishedAt: new Date(endAt).toISOString(),
+      durationMs,
+      exitCode: code,
+      signal,
+      stdoutBytes,
+      stderrBytes,
+      outputFile: outPath,
+    };
+
+    fs.writeFileSync(metaPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+    process.exit(normalizedExitCode);
+  });
+}

package/bin/command/shared/args.mjs

@@ -0,0 +1,45 @@
+export function parseCommonArgs(argv) {
+  const positional = [];
+  const options = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith('--')) {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) {
+        if (!options[token]) {
+          options[token] = [];
+        }
+        options[token].push(true);
+      } else {
+        if (!options[token]) {
+          options[token] = [];
+        }
+        options[token].push(next);
+        i += 1;
+      }
+      continue;
+    }
+    positional.push(token);
+  }
+
+  return { positional, options };
+}
+
+export function getSingle(options, key, fallback = '') {
+  if (!options[key] || options[key].length === 0) {
+    return fallback;
+  }
+  return String(options[key][options[key].length - 1]);
+}
+
+export function getMulti(options, key) {
+  if (!options[key]) {
+    return [];
+  }
+  return options[key].map((v) => String(v));
+}
+
+export function hasFlag(options, key) {
+  return Boolean(options[key]);
+}

package/bin/command/shared/text-resource.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+
+export function loadTextResource(filePath) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`Resource file not found: ${filePath}`);
+    process.exit(2);
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+export function printTextResource(filePath) {
+  let content = loadTextResource(filePath);
+  if (!content.endsWith('\n')) {
+    content = `${content}\n`;
+  }
+
+  process.stdout.write(content);
+}

package/bin/command/summarize-log/index.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle } 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');
+
+export function printSummarizeHelp() {
+  printTextResource(HELP_FILE);
+}
+
+export function runSummarize(options) {
+  const file = getSingle(options, '--file', '');
+  const last = Number(getSingle(options, '--last', '0')) || 0;
+  const match = getSingle(options, '--match', '');
+  const max = Number(getSingle(options, '--max', '200')) || 200;
+
+  if (!file) {
+    printSummarizeHelp();
+    process.exit(2);
+  }
+
+  const filePath = path.resolve(file);
+  if (!fs.existsSync(filePath)) {
+    console.error(`Log file does not exist: ${filePath}`);
+    process.exit(2);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const allLines = raw.split(/\r?\n/);
+
+  let lines = allLines;
+  let mode = 'all';
+
+  if (match) {
+    const pattern = new RegExp(match, 'i');
+    lines = allLines.filter((line) => pattern.test(line));
+    mode = 'match';
+  }
+
+  if (last > 0) {
+    lines = lines.slice(-last);
+    mode = mode === 'match' ? 'match+last' : 'last';
+  }
+
+  if (max > 0 && lines.length > max) {
+    lines = lines.slice(0, max);
+  }
+
+  const header = [
+    `# file: ${filePath}`,
+    `# totalLines: ${allLines.length}`,
+    `# selectedLines: ${lines.length}`,
+    `# mode: ${mode}`,
+    '',
+  ].join('\n');
+
+  process.stdout.write(header);
+  process.stdout.write(lines.join('\n'));
+  process.stdout.write('\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