@produck/agent-toolkit 0.1.3 → 0.1.4

package/README.md

@@ -8,43 +8,60 @@ 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:
 
 npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+ agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
 
 Capture long output safely:
 
 npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit run-capture --cwd . --cmd "npm run test" --out logs/test.log
+ 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"
+ agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
 
 Validate commit message format:
 
 npm exec --package=@produck/agent-toolkit@latest \
-  agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
+ agent-toolkit validate-commit-msg --file .git/COMMIT_EDITMSG
+
+Manual per-repository instruction distribution (write .instructions.md):
+
+npm exec --package=@produck/agent-toolkit@latest \
+ agent-toolkit sync-instructions --cwd .
+
+Use organization source file instead of built-in template:
+
+npm exec --package=@produck/agent-toolkit@latest \
+ agent-toolkit sync-instructions --cwd . \
+ --source path/to/org/.instructions.md --force
+
+Built-in template location (for review and updates):
+
+- `templates/default.instructions.md`
+- `templates/help/*.txt`
 
 ## Local verification
 
 From repository root:
 
-npm --prefix tools/agent-toolkit run verify
-npm --prefix tools/agent-toolkit run pack:check
+npm --workspace @produck/agent-toolkit run verify
+npm --workspace @produck/agent-toolkit run pack:check
 
 ## Manual publish
 
 Lerna-like release flow (recommended):
 
-0) Interactive mode (TTY):
+0. Interactive mode (TTY):
 
-npm --prefix tools/agent-toolkit run release
+npm --workspace @produck/agent-toolkit run release
 
 Interactive prompts let you choose:
 
@@ -66,18 +83,22 @@ Interactive mode handles both:
 
 Non-interactive flags:
 
-- `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`
+- `npm --workspace @produck/agent-toolkit run release -- patch --publish`
+- `npm --workspace @produck/agent-toolkit run release -- patch --no-tag`
+- `npm --workspace @produck/agent-toolkit run release -- patch --no-commit --no-tag`
 
 Note:
 
-- Release requires a clean working tree in `tools/agent-toolkit` before start.
+- Release requires a clean working tree in `packages/agent-toolkit` before
+  start.
+- After release success, push commit and tags:
+  - `git -C d:/workspace/PRODUCK/.github push`
+  - `git -C d:/workspace/PRODUCK/.github push --tags`
 
 Low-level commands (optional):
 
-npm --prefix tools/agent-toolkit run publish:dry-run
-npm --prefix tools/agent-toolkit run publish:latest
+npm --workspace @produck/agent-toolkit run publish:dry-run
+npm --workspace @produck/agent-toolkit run publish:latest
 
 ## GitHub workflow
 
@@ -96,3 +117,10 @@ Release policy:
 - Default organization usage is @latest.
 - Run verify and publish:dry-run before publish:latest.
 - 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 run release again 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.4",
   "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": "a2e293bea6a90e6fcbf9d0df03ba4fdf3a13ef00"
 }

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);