@produck/agent-toolkit 0.1.5 → 0.2.1

package/README.md

@@ -14,51 +14,66 @@ Central CLI toolkit for organization-level AI execution workflows.
 
 Run preflight checks:
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
 ```
 
 Capture long output safely:
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit run-capture --cwd . --cmd "npm run test" --out logs/test.log
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit run-capture --cwd . --cmd "npm run test" --out logs/test.log
 ```
 
 Summarize captured output:
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
 ```
 
 Validate commit message format:
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
 ```
 
-Manual per-repository instruction distribution (write .instructions.md):
+Manual per-repository instruction distribution (write .github/instructions/produck/\*.instructions.md):
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit sync-instructions --cwd .
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd .
 ```
 
-Use organization source file instead of built-in template:
+Legacy repository bootstrap behavior:
+
+- If `.github/copilot-instructions.md` is missing, sync-instructions initializes it.
+- The initialized file guides repository owners to keep organization baseline in
+  `.github/instructions/produck/*.instructions.md` and put local-only rules in
+  `.github/copilot-instructions.md`.
+
+Use organization source directory instead of built-in assets:
 
-```bash
-npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit sync-instructions --cwd . \
-  --source path/to/org/.instructions.md --force
 ```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd . --source path/to/org/.github/distribution/produck --force --prune
+```
+
+Built-in command-local resource locations (for review and updates):
+
+- `bin/command/*/help.txt`
+- `bin/command/sync-instructions/user-space-bootstrap.md`
+
+Publish-time generated instruction assets:
+
+- `publish-assets/instructions/produck/*.instructions.md`
+- Generated from `.github/distribution/produck/*.instructions.md` via
+  `prepack`
+- Included in npm package, ignored in git working tree
+
+Downstream source maintenance in policy repository:
+
+- Maintain source files directly under `.github/distribution/produck/*.instructions.md`
 
-Built-in template location (for review and updates):
+Organization-only instruction source (not published):
 
-- `templates/default.instructions.md`
-- `templates/help/*.txt`
+- `.github/instructions/produck/*.instructions.md`
 
 ## Local verification
 

package/bin/agent-toolkit.mjs

@@ -1,418 +1,48 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
-
-const ALLOWED_TAGS = ['INIT', 'ADD', 'REMOVE', 'FIX', 'REFACTOR', 'UPGRADE'];
-const ALLOWED_TARGETS = ['docs', 'test', 'ci', 'deps', 'api', 'schema', 'infra'];
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const TEMPLATE_ROOT = path.resolve(SCRIPT_DIR, '../templates');
-const DEFAULT_INSTRUCTIONS_TEMPLATE_PATH = path.resolve(TEMPLATE_ROOT, 'default.instructions.md');
-
-function loadTemplateFile(relativePath) {
-  const templatePath = path.resolve(TEMPLATE_ROOT, relativePath);
-  if (!fs.existsSync(templatePath)) {
-    console.error(`Template file not found: ${templatePath}`);
-    process.exit(2);
-  }
-
-  return fs.readFileSync(templatePath, 'utf8');
-}
-
-function printTemplate(relativePath) {
-  let content = loadTemplateFile(relativePath);
-  if (!content.endsWith('\n')) {
-    content = `${content}\n`;
-  }
-  process.stdout.write(content);
-}
-
-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 };
-}
-
-function getSingle(options, key, fallback = '') {
-  if (!options[key] || options[key].length === 0) {
-    return fallback;
-  }
-  return String(options[key][options[key].length - 1]);
-}
-
-function getMulti(options, key) {
-  if (!options[key]) {
-    return [];
-  }
-  return options[key].map((v) => String(v));
-}
-
-function hasFlag(options, key) {
-  return Boolean(options[key]);
-}
-
-function printMainHelp() {
-  printTemplate('help/main.txt');
-}
-
-function printPreflightHelp() {
-  printTemplate('help/preflight.txt');
-}
-
-function printRunCaptureHelp() {
-  printTemplate('help/run-capture.txt');
-}
-
-function printSummarizeHelp() {
-  printTemplate('help/summarize-log.txt');
-}
-
-function printValidateHelp() {
-  printTemplate('help/validate-commit-msg.txt');
-}
-
-function printSyncInstructionsHelp() {
-  printTemplate('help/sync-instructions.txt');
-}
-
-function loadDefaultInstructionsTemplate() {
-  let content = loadTemplateFile('default.instructions.md');
-  if (!content.endsWith('\n')) {
-    content = `${content}\n`;
-  }
-  return content;
-}
-
-function runPreflight(options) {
-  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
-  const required = getMulti(options, '--require');
-  const ensureDir = getMulti(options, '--ensure-dir');
-  const jsonFile = getSingle(options, '--json', '');
-
-  if (!fs.existsSync(cwd)) {
-    console.error(`CWD does not exist: ${cwd}`);
-    process.exit(2);
-  }
-
-  const report = {
-    cwd,
-    required: [],
-    ensuredDirectories: [],
-    ok: true,
-  };
-
-  for (const rel of required) {
-    const resolved = path.resolve(cwd, rel);
-    const exists = fs.existsSync(resolved);
-    report.required.push({ path: rel, resolved, 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 });
-  }
-
-  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');
-  }
-
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  if (!report.ok) {
-    process.exit(2);
-  }
-}
-
-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;
-
-    outStream.write('\n');
-    outStream.write(`# finishedAt: ${new Date(endAt).toISOString()}\n`);
-    outStream.write(`# exitCode: ${String(code)}\n`);
-    outStream.write(`# signal: ${signal ? String(signal) : 'none'}\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');
-
-    if (typeof code === 'number') {
-      process.exit(code);
-    }
-    process.exit(1);
-  });
-}
-
-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');
-}
-
-function validateCommitLine(line, lineNo) {
-  if (line.trim() === '') {
-    return `Line ${lineNo}: empty line is not allowed`;
-  }
-
-  const head = line.match(/^\[([A-Z]+)\]\s+/);
-  if (!head) {
-    return `Line ${lineNo}: must start with [TAG] followed by a space`;
-  }
-
-  const tag = head[1];
-  if (!ALLOWED_TAGS.includes(tag)) {
-    return `Line ${lineNo}: tag [${tag}] is not allowed`;
-  }
-
-  const rest = line.slice(head[0].length);
-  if (rest.trim() === '') {
-    return `Line ${lineNo}: summary is required after tag`;
-  }
-
-  const targetMatch = rest.match(/^<([^>]+)>:\s+(.+)$/);
-  if (targetMatch) {
-    const target = targetMatch[1];
-    const summary = targetMatch[2];
-    if (!ALLOWED_TARGETS.includes(target)) {
-      return `Line ${lineNo}: target <${target}> is not allowed`;
-    }
-    if (summary.trim() === '') {
-      return `Line ${lineNo}: summary is required after target`;
-    }
-  }
-
-  return null;
-}
-
-function runValidateCommitMsg(options) {
-  const file = getSingle(options, '--file', '');
-  if (!file) {
-    printValidateHelp();
-    process.exit(2);
-  }
-
-  const filePath = path.resolve(file);
-  if (!fs.existsSync(filePath)) {
-    console.error(`Message file not found: ${filePath}`);
-    process.exit(2);
-  }
-
-  const raw = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
-  const lines = raw.endsWith('\n') ? raw.slice(0, -1).split('\n') : raw.split('\n');
-
-  if (lines.length === 0 || (lines.length === 1 && lines[0].trim() === '')) {
-    console.error('Commit message is empty');
-    process.exit(2);
-  }
-
-  const errors = [];
-  for (let i = 0; i < lines.length; i += 1) {
-    const err = validateCommitLine(lines[i], i + 1);
-    if (err) {
-      errors.push(err);
-    }
-  }
-
-  if (errors.length > 0) {
-    console.error('Commit message validation failed:');
-    for (const err of errors) {
-      console.error(`- ${err}`);
-    }
-    process.exit(1);
-  }
-
-  console.log('Commit message validation passed');
-}
-
-function runSyncInstructions(options) {
-  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
-  const outArg = getSingle(options, '--out', '.instructions.md');
-  const sourceArg = getSingle(options, '--source', '');
-  const force = hasFlag(options, '--force');
-  const dryRun = hasFlag(options, '--dry-run');
-
-  if (!fs.existsSync(cwd)) {
-    console.error(`CWD does not exist: ${cwd}`);
-    process.exit(2);
-  }
-
-  const outPath = path.resolve(cwd, outArg);
-  let content = loadDefaultInstructionsTemplate();
-
-  if (sourceArg) {
-    const sourcePath = path.resolve(cwd, sourceArg);
-    if (!fs.existsSync(sourcePath)) {
-      console.error(`Source file does not exist: ${sourcePath}`);
-      process.exit(2);
-    }
-    content = fs.readFileSync(sourcePath, 'utf8');
-    if (!content.endsWith('\n')) {
-      content = `${content}\n`;
-    }
-  }
-
-  const exists = fs.existsSync(outPath);
-  if (exists && !force) {
-    console.error(`Target already exists: ${outPath}`);
-    console.error('Use --force to overwrite.');
-    process.exit(2);
-  }
-
-  const report = {
-    cwd,
-    outPath,
-    source: sourceArg ? path.resolve(cwd, sourceArg) : DEFAULT_INSTRUCTIONS_TEMPLATE_PATH,
-    exists,
-    overwritten: exists && force,
-    dryRun,
-  };
-
-  if (dryRun) {
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    process.exit(0);
+import { printMainHelp } from './command/main/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 {
+  printSyncInstructionsHelp,
+  runSyncInstructions,
+} from './command/sync-instructions/index.mjs';
+import { hasFlag, parseCommonArgs } from './command/shared/args.mjs';
+import {
+  printValidateCommitMsgHelp,
+  runValidateCommitMsg,
+} from './command/validate-commit-msg/index.mjs';
+
+const COMMANDS = {
+  preflight: {
+    printHelp: printPreflightHelp,
+    run: runPreflight,
+  },
+  'run-capture': {
+    printHelp: printRunCaptureHelp,
+    run: runCapture,
+  },
+  'summarize-log': {
+    printHelp: printSummarizeHelp,
+    run: runSummarize,
+  },
+  'validate-commit-msg': {
+    printHelp: printValidateCommitMsgHelp,
+    run: runValidateCommitMsg,
+  },
+  'sync-instructions': {
+    printHelp: printSyncInstructionsHelp,
+    run: runSyncInstructions,
+  },
+};
+
+function printCommandHelp(command) {
+  const entry = COMMANDS[command];
+  if (!entry) {
+    printMainHelp();
+    return;
   }
-
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, content, 'utf8');
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  entry.printHelp();
 }
 
 function main() {
@@ -426,56 +56,18 @@ function main() {
   }
 
   if (hasFlag(options, '--help') || hasFlag(options, '-h')) {
-    if (command === 'preflight') {
-      printPreflightHelp();
-      process.exit(0);
-    }
-    if (command === 'run-capture') {
-      printRunCaptureHelp();
-      process.exit(0);
-    }
-    if (command === 'summarize-log') {
-      printSummarizeHelp();
-      process.exit(0);
-    }
-    if (command === 'validate-commit-msg') {
-      printValidateHelp();
-      process.exit(0);
-    }
-    if (command === 'sync-instructions') {
-      printSyncInstructionsHelp();
-      process.exit(0);
-    }
-  }
-
-  if (command === 'preflight') {
-    runPreflight(options);
-    return;
-  }
-
-  if (command === 'run-capture') {
-    runCapture(options);
-    return;
-  }
-
-  if (command === 'summarize-log') {
-    runSummarize(options);
-    return;
-  }
-
-  if (command === 'validate-commit-msg') {
-    runValidateCommitMsg(options);
-    return;
+    printCommandHelp(command);
+    process.exit(0);
   }
 
-  if (command === 'sync-instructions') {
-    runSyncInstructions(options);
-    return;
+  const entry = COMMANDS[command];
+  if (!entry) {
+    console.error(`Unknown command: ${command}`);
+    printMainHelp();
+    process.exit(2);
   }
 
-  console.error(`Unknown command: ${command}`);
-  printMainHelp();
-  process.exit(2);
+  entry.run(options);
 }
 
 main();