@produck/agent-toolkit 0.1.3 → 0.1.5

package/README.md

@@ -8,76 +8,86 @@ Central CLI toolkit for organization-level AI execution workflows.
 - agent-toolkit run-capture
 - agent-toolkit summarize-log
 - agent-toolkit validate-commit-msg
+- agent-toolkit sync-instructions
 
 ## Examples
 
 Run preflight checks:
 
+```bash
 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
+```
 
 Summarize captured output:
 
+```bash
 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
+```
 
-## Local verification
-
-From repository root:
-
-npm --prefix tools/agent-toolkit run verify
-npm --prefix tools/agent-toolkit run pack:check
-
-## Manual publish
-
-Lerna-like release flow (recommended):
+Manual per-repository instruction distribution (write .instructions.md):
 
-0) Interactive mode (TTY):
+```bash
+npm exec --package=@produck/agent-toolkit@latest \
+  agent-toolkit sync-instructions --cwd .
+```
 
-npm --prefix tools/agent-toolkit run release
+Use organization source file instead of built-in template:
 
-Interactive prompts let you choose:
+```bash
+npm exec --package=@produck/agent-toolkit@latest \
+  agent-toolkit sync-instructions --cwd . \
+  --source path/to/org/.instructions.md --force
+```
 
-- version level: patch/minor/major
-- action: dry-run or publish
-- vcs mode: commit+tag / commit only / no commit+no tag
+Built-in template location (for review and updates):
 
-Default choices:
+- `templates/default.instructions.md`
+- `templates/help/*.txt`
 
-- patch
-- dry-run
-- commit + tag
+## Local verification
 
-Interactive mode handles both:
+From repository root:
 
-- version bump level (patch/minor/major)
-- action mode (dry-run or publish)
-- auto commit and tag after dry-run
+```bash
+npm --workspace @produck/agent-toolkit run verify
+npm --workspace @produck/agent-toolkit run pack:check
+```
 
-Non-interactive flags:
+## Publishing
 
-- `npm --prefix tools/agent-toolkit run release -- patch --publish`
-- `npm --prefix tools/agent-toolkit run release -- patch --no-tag`
-- `npm --prefix tools/agent-toolkit run release -- patch --no-commit --no-tag`
+Publishing is centralized at workspace root via lerna, not via
+package-level release scripts.
 
-Note:
+From monorepo root (`produck/.github`):
 
-- Release requires a clean working tree in `tools/agent-toolkit` before start.
+```bash
+npm run format:check
+npm run test
+npm run publish:dry-run
+npm run publish
+```
 
-Low-level commands (optional):
+Notes:
 
-npm --prefix tools/agent-toolkit run publish:dry-run
-npm --prefix tools/agent-toolkit run publish:latest
+- `publish:dry-run` validates package contents by running `npm pack --dry-run`
+  across non-private workspace packages.
+- `publish` runs lerna publish flow from workspace root.
 
 ## GitHub workflow
 
@@ -87,12 +97,20 @@ Repository includes manual workflow:
 
 Workflow behavior:
 
-- Always runs verify, pack:check, and publish:dry-run.
+- Always runs verify and pack:check for `@produck/agent-toolkit`.
 - Does not publish to npm.
-- Used as release gate before manual publish.
+- Used as release gate before workspace-level publish.
 
 Release policy:
 
 - Default organization usage is @latest.
-- Run verify and publish:dry-run before publish:latest.
+- Run format:check and test first, then workspace `publish:dry-run` before
+  `publish`.
 - Keep rollback option by republishing previous stable version if needed.
+
+Rollback quick steps:
+
+1. Check latest published version:
+   `npm view @produck/agent-toolkit version`
+2. Fix source and rerun workspace publish flow with a new version.
+3. Push commit and tags.

package/bin/agent-toolkit.mjs

@@ -1,10 +1,32 @@
 #!/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 = [];
@@ -53,52 +75,35 @@ function hasFlag(options, key) {
 }
 
 function printMainHelp() {
-  console.log([
-    'agent-toolkit commands:',
-    '  preflight',
-    '  run-capture',
-    '  summarize-log',
-    '  validate-commit-msg',
-    '',
-    'Use:',
-    '  agent-toolkit <command> --help',
-  ].join('\n'));
+  printTemplate('help/main.txt');
 }
 
 function printPreflightHelp() {
-  console.log([
-    'Usage:',
-    '  agent-toolkit preflight [--cwd <dir>] [--require <path>] ...',
-    '    [--ensure-dir <path>] ... [--json <file>]',
-  ].join('\n'));
+  printTemplate('help/preflight.txt');
 }
 
 function printRunCaptureHelp() {
-  console.log([
-    'Usage:',
-    '  agent-toolkit run-capture --out <logFile> --cmd <command>',
-    '    [--cwd <directory>] [--meta <metaFile>] [--allow-pipe]',
-  ].join('\n'));
+  printTemplate('help/run-capture.txt');
 }
 
 function printSummarizeHelp() {
-  console.log([
-    'Usage:',
-    '  agent-toolkit summarize-log --file <logFile>',
-    '    [--last <lineCount>] [--match <regex>] [--max <lineCount>]',
-  ].join('\n'));
+  printTemplate('help/summarize-log.txt');
 }
 
 function printValidateHelp() {
-  console.log([
-    'Usage:',
-    '  agent-toolkit validate-commit-msg --file <message-file>',
-    '',
-    'Rules:',
-    '  - Every line must start with [TAG]',
-    '  - No empty lines are allowed',
-    '  - Optional target form: [TAG] <target>: <summary>',
-  ].join('\n'));
+  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) {
@@ -357,6 +362,59 @@ function runValidateCommitMsg(options) {
   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);
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, content, 'utf8');
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
 function main() {
   const parsed = parseCommonArgs(process.argv.slice(2));
   const command = parsed.positional[0] || '';
@@ -384,6 +442,10 @@ function main() {
       printValidateHelp();
       process.exit(0);
     }
+    if (command === 'sync-instructions') {
+      printSyncInstructionsHelp();
+      process.exit(0);
+    }
   }
 
   if (command === 'preflight') {
@@ -406,6 +468,11 @@ function main() {
     return;
   }
 
+  if (command === 'sync-instructions') {
+    runSyncInstructions(options);
+    return;
+  }
+
   console.error(`Unknown command: ${command}`);
   printMainHelp();
   process.exit(2);

package/package.json

@@ -1,25 +1,23 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/produck/.github.git",
-    "directory": "tools/agent-toolkit"
+    "directory": "packages/agent-toolkit"
   },
   "bin": {
     "agent-toolkit": "bin/agent-toolkit.mjs"
   },
   "scripts": {
     "verify": "node ./bin/agent-toolkit.mjs --help && node ./bin/agent-toolkit.mjs preflight --cwd . --require package.json",
-    "pack:check": "npm pack --dry-run",
-    "publish:dry-run": "npm publish --dry-run --access public",
-    "publish:latest": "npm publish --access public",
-    "release": "node ./bin/release.mjs"
+    "pack:check": "npm pack --dry-run"
   },
   "files": [
-    "bin"
+    "bin",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
@@ -27,5 +25,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "gitHead": "13afa6b9d747360fedf569a619274d90a038c0f3"
 }

package/templates/default.instructions.md

@@ -0,0 +1,21 @@
+# Organization Collaboration Instructions
+
+This repository follows organization-level AI and engineering rules.
+
+## Required Rules
+
+- Commit message format must follow bracketed TAG policy.
+- Keep root .editorconfig aligned with organization baseline:
+  - If missing, create from organization sample.
+  - If present, add missing required keys only (minimal merge).
+- Repository owners generate and own eslint.config.mjs.
+- AI must not rewrite full eslint config; only add missing
+  @produck/eslint-rules integration as minimal patch.
+- Repository-specific ESLint overrides must layer on top of
+  @produck/eslint-rules.
+
+## References
+
+- docs/ai-collaboration.md
+- docs/commit-convention.md
+- docs/nodejs-initialization.md

package/templates/help/main.txt

@@ -0,0 +1,9 @@
+agent-toolkit commands:
+  preflight
+  run-capture
+  summarize-log
+  validate-commit-msg
+  sync-instructions
+
+Use:
+  agent-toolkit <command> --help

package/templates/help/preflight.txt

@@ -0,0 +1,3 @@
+Usage:
+  agent-toolkit preflight [--cwd <dir>] [--require <path>] ...
+    [--ensure-dir <path>] ... [--json <file>]

package/templates/help/run-capture.txt

@@ -0,0 +1,3 @@
+Usage:
+  agent-toolkit run-capture --out <logFile> --cmd <command>
+    [--cwd <directory>] [--meta <metaFile>] [--allow-pipe]

package/templates/help/summarize-log.txt

@@ -0,0 +1,3 @@
+Usage:
+  agent-toolkit summarize-log --file <logFile>
+    [--last <lineCount>] [--match <regex>] [--max <lineCount>]

package/templates/help/sync-instructions.txt

@@ -0,0 +1,8 @@
+Usage:
+  agent-toolkit sync-instructions [--cwd <dir>] [--out <file>]
+    [--source <file>] [--force] [--dry-run]
+
+Behavior:
+  - Writes organization instruction entrypoint template to target file.
+  - Defaults to <cwd>/.instructions.md when --out is not provided.
+  - If target exists, command fails unless --force is set.

package/templates/help/validate-commit-msg.txt

@@ -0,0 +1,7 @@
+Usage:
+  agent-toolkit validate-commit-msg --file <message-file>
+
+Rules:
+  - Every line must start with [TAG]
+  - No empty lines are allowed
+  - Optional target form: [TAG] <target>: <summary>

package/bin/release.mjs

@@ -1,271 +0,0 @@
-#!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import readline from 'node:readline/promises';
-
-const LEVELS = new Set(['patch', 'minor', 'major']);
-
-function usage() {
-  console.log([
-    'Usage:',
-    '  node ./bin/release.mjs',
-    '  node ./bin/release.mjs <patch|minor|major> [--publish] [--no-commit] [--no-tag]',
-    '  node ./bin/release.mjs --interactive',
-    '',
-    'Behavior:',
-    '  1) bump version (no git tag)',
-    '  2) run verify',
-    '  3) run publish:dry-run',
-    '  4) auto commit version change (default)',
-    '  5) auto create git tag (default)',
-    '  6) optionally publish latest when --publish is set',
-    '',
-    'Interactive mode defaults:',
-    '  - release level: patch',
-    '  - publish mode: dry-run',
-    '  - auto commit: enabled',
-    '  - auto tag: enabled',
-  ].join('\n'));
-}
-
-function runNpm(args) {
-  const result = spawnSync('npm', args, {
-    stdio: 'inherit',
-    cwd: process.cwd(),
-    shell: true,
-  });
-
-  if (result.error) {
-    console.error(`[release] failed to run npm ${args.join(' ')}:`);
-    console.error(result.error.message);
-    process.exit(1);
-  }
-
-  if (result.status !== 0) {
-    process.exit(result.status ?? 1);
-  }
-}
-
-function runGit(args) {
-  const result = spawnSync('git', args, {
-    stdio: 'inherit',
-    cwd: process.cwd(),
-  });
-
-  if (result.error) {
-    console.error(`[release] failed to run git ${args.join(' ')}:`);
-    console.error(result.error.message);
-    process.exit(1);
-  }
-
-  if (result.status !== 0) {
-    process.exit(result.status ?? 1);
-  }
-}
-
-function getDirtyFiles() {
-  const result = spawnSync('git', ['status', '--porcelain'], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    cwd: process.cwd(),
-    encoding: 'utf8',
-  });
-
-  if (result.error || result.status !== 0) {
-    console.error('[release] unable to check git status');
-    process.exit(1);
-  }
-
-  return result.stdout
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
-}
-
-function ensureReleaseWorkspaceClean() {
-  const dirty = getDirtyFiles();
-  if (dirty.length === 0) {
-    return;
-  }
-
-  console.error('[release] working tree is not clean before release:');
-  for (const line of dirty) {
-    console.error(`  ${line}`);
-  }
-  console.error('[release] commit/stash changes and retry');
-  process.exit(2);
-}
-
-function commitAndTag(version, shouldCommit, shouldTag) {
-  if (shouldCommit) {
-    const message = `[UPGRADE] <infra>: release @produck/agent-toolkit ${version}`;
-    console.log(`[release] commit version bump: ${message}`);
-    runGit(['add', 'package.json']);
-    runGit(['commit', '-m', message]);
-  }
-
-  if (shouldTag) {
-    const tag = `agent-toolkit-v${version}`;
-    console.log(`[release] create tag: ${tag}`);
-    runGit(['tag', '-a', tag, '-m', `[UPGRADE] <infra>: tag ${tag}`]);
-  }
-}
-
-function bumpPreview(version, level) {
-  const parts = version.split('.').map((v) => Number(v));
-  if (parts.length !== 3 || parts.some((v) => Number.isNaN(v))) {
-    return `unknown (${version})`;
-  }
-
-  const [major, minor, patch] = parts;
-  if (level === 'patch') {
-    return `${major}.${minor}.${patch + 1}`;
-  }
-  if (level === 'minor') {
-    return `${major}.${minor + 1}.0`;
-  }
-  return `${major + 1}.0.0`;
-}
-
-async function askInteractive(currentVersion) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  try {
-    console.log(`[release] current version: ${currentVersion}`);
-    console.log('[release] select release level:');
-    console.log(`  1) patch (default) -> ${bumpPreview(currentVersion, 'patch')}`);
-    console.log(`  2) minor           -> ${bumpPreview(currentVersion, 'minor')}`);
-    console.log(`  3) major           -> ${bumpPreview(currentVersion, 'major')}`);
-
-    const levelAnswer = (
-      await rl.question('Choose level [1/2/3] (default: 1): ')
-    ).trim();
-
-    let level = 'patch';
-    if (levelAnswer === '2') {
-      level = 'minor';
-    } else if (levelAnswer === '3') {
-      level = 'major';
-    } else if (levelAnswer && levelAnswer !== '1') {
-      console.error(`Invalid level choice: ${levelAnswer}`);
-      process.exit(2);
-    }
-
-    console.log('[release] select publish mode:');
-    console.log('  1) dry-run only (default)');
-    console.log('  2) publish latest after dry-run');
-
-    const publishAnswer = (
-      await rl.question('Choose mode [1/2] (default: 1): ')
-    ).trim();
-
-    let shouldPublish = false;
-    if (publishAnswer === '2') {
-      shouldPublish = true;
-    } else if (publishAnswer && publishAnswer !== '1') {
-      console.error(`Invalid publish choice: ${publishAnswer}`);
-      process.exit(2);
-    }
-
-    console.log('[release] auto commit and tag settings:');
-    console.log('  1) commit + tag (default)');
-    console.log('  2) commit only');
-    console.log('  3) no commit, no tag');
-
-    const vcsAnswer = (
-      await rl.question('Choose vcs mode [1/2/3] (default: 1): ')
-    ).trim();
-
-    let shouldCommit = true;
-    let shouldTag = true;
-    if (vcsAnswer === '2') {
-      shouldCommit = true;
-      shouldTag = false;
-    } else if (vcsAnswer === '3') {
-      shouldCommit = false;
-      shouldTag = false;
-    } else if (vcsAnswer && vcsAnswer !== '1') {
-      console.error(`Invalid vcs choice: ${vcsAnswer}`);
-      process.exit(2);
-    }
-
-    return { level, shouldPublish, shouldCommit, shouldTag };
-  } finally {
-    rl.close();
-  }
-}
-
-function runRelease(level, shouldPublish, shouldCommit, shouldTag) {
-  if (!LEVELS.has(level)) {
-    console.error(`Invalid release level: ${level}`);
-    usage();
-    process.exit(2);
-  }
-
-  ensureReleaseWorkspaceClean();
-
-  const pkgFile = path.resolve('package.json');
-  const before = JSON.parse(fs.readFileSync(pkgFile, 'utf8')).version;
-
-  console.log(`[release] bump version: ${level}`);
-  runNpm(['version', level, '--no-git-tag-version']);
-
-  const after = JSON.parse(fs.readFileSync(pkgFile, 'utf8')).version;
-  console.log(`[release] version ${before} -> ${after}`);
-
-  console.log('[release] verify toolkit');
-  runNpm(['run', 'verify']);
-
-  console.log('[release] publish dry-run');
-  runNpm(['run', 'publish:dry-run']);
-
-  commitAndTag(after, shouldCommit, shouldTag);
-
-  if (shouldPublish) {
-    console.log('[release] publish latest');
-    runNpm(['run', 'publish:latest']);
-  } else {
-    console.log('[release] publish skipped (interactive default: dry-run)');
-  }
-}
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  usage();
-  process.exit(0);
-}
-
-const interactiveRequested = args.length === 0 || args.includes('--interactive');
-if (interactiveRequested) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    console.error('Interactive mode requires a TTY.');
-    usage();
-    process.exit(2);
-  }
-
-  const pkgFile = path.resolve('package.json');
-  const currentVersion = JSON.parse(fs.readFileSync(pkgFile, 'utf8')).version;
-  const interactive = await askInteractive(currentVersion);
-  runRelease(
-    interactive.level,
-    interactive.shouldPublish,
-    interactive.shouldCommit,
-    interactive.shouldTag
-  );
-  process.exit(0);
-}
-
-const level = args[0];
-const shouldPublish = args.includes('--publish');
-const shouldCommit = !args.includes('--no-commit');
-const shouldTag = !args.includes('--no-tag');
-
-if (shouldTag && !shouldCommit) {
-  console.error('[release] --no-commit cannot be combined with tag enabled');
-  process.exit(2);
-}
-
-runRelease(level, shouldPublish, shouldCommit, shouldTag);