@produck/agent-toolkit 0.1.4 → 0.2.0

package/README.md

@@ -14,91 +14,95 @@ Central CLI toolkit for organization-level AI execution workflows.
 
 Run preflight checks:
 
-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:
 
-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:
 
-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:
 
-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):
 
-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:
 
-npm exec --package=@produck/agent-toolkit@latest \
- agent-toolkit sync-instructions --cwd . \
- --source path/to/org/.instructions.md --force
+- 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`.
 
-Built-in template location (for review and updates):
-
-- `templates/default.instructions.md`
-- `templates/help/*.txt`
+Use organization source directory instead of built-in assets:
 
-## Local verification
+```
+npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd . --source path/to/org/.github/distribution/produck --force --prune
+```
 
-From repository root:
-
-npm --workspace @produck/agent-toolkit run verify
-npm --workspace @produck/agent-toolkit run pack:check
+Built-in template location (for review and updates):
 
-## Manual publish
+- `templates/user-space-bootstrap.md`
+- `templates/help/*.txt`
 
-Lerna-like release flow (recommended):
+Publish-time generated instruction assets:
 
-0. Interactive mode (TTY):
+- `publish-assets/instructions/produck/*.instructions.md`
+- Generated from `.github/distribution/produck/*.instructions.md` via
+  `prepack`
+- Included in npm package, ignored in git working tree
 
-npm --workspace @produck/agent-toolkit run release
+Downstream source maintenance in policy repository:
 
-Interactive prompts let you choose:
+- Maintain source files directly under `.github/distribution/produck/*.instructions.md`
 
-- version level: patch/minor/major
-- action: dry-run or publish
-- vcs mode: commit+tag / commit only / no commit+no tag
+Organization-only instruction source (not published):
 
-Default choices:
+- `.github/instructions/produck/*.instructions.md`
 
-- 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 --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`
+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 `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`
+```bash
+npm run format:check
+npm run test
+npm run publish:dry-run
+npm run publish
+```
 
-Low-level commands (optional):
+Notes:
 
-npm --workspace @produck/agent-toolkit run publish:dry-run
-npm --workspace @produck/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
 
@@ -108,19 +112,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 run release again with a new version.
+2. Fix source and rerun workspace publish flow with a new version.
 3. Push commit and tags.

package/bin/agent-toolkit.mjs

@@ -8,7 +8,12 @@ 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');
+const PUBLISH_ASSETS_ROOT = path.resolve(SCRIPT_DIR, '../publish-assets');
+const PUBLISH_INSTRUCTIONS_ROOT = path.resolve(PUBLISH_ASSETS_ROOT, 'instructions');
+const PUBLISH_NAMESPACE_ROOT = path.resolve(PUBLISH_INSTRUCTIONS_ROOT, 'produck');
+const MANAGED_MARKER = '<!-- managed-by: @produck/agent-toolkit -->';
+const DEFAULT_NAMESPACE_OUT_DIR = '.github/instructions/produck';
+const USER_SPACE_ENTRYPOINT = '.github/copilot-instructions.md';
 
 function loadTemplateFile(relativePath) {
   const templatePath = path.resolve(TEMPLATE_ROOT, relativePath);
@@ -99,7 +104,63 @@ function printSyncInstructionsHelp() {
 }
 
 function loadDefaultInstructionsTemplate() {
-  let content = loadTemplateFile('default.instructions.md');
+  if (fs.existsSync(PUBLISH_NAMESPACE_ROOT)) {
+    const names = fs
+      .readdirSync(PUBLISH_NAMESPACE_ROOT)
+      .filter((name) => name.endsWith('.instructions.md'))
+      .sort((a, b) => a.localeCompare(b));
+    const entries = names.map((name) => {
+      const abs = path.resolve(PUBLISH_NAMESPACE_ROOT, name);
+      let text = fs.readFileSync(abs, 'utf8');
+      if (!text.endsWith('\n')) {
+        text = `${text}\n`;
+      }
+      return {
+        fileName: name,
+        content: text,
+        sourcePath: abs,
+      };
+    });
+    return {
+      type: 'dir',
+      sourcePath: PUBLISH_NAMESPACE_ROOT,
+      entries,
+    };
+  }
+
+  console.error('No built-in instruction assets found.');
+  console.error('Run prepack/publish to generate publish-assets, or pass --source explicitly.');
+  process.exit(2);
+}
+
+function readInstructionEntriesFromDirectory(sourceDir) {
+  const names = fs
+    .readdirSync(sourceDir)
+    .filter((name) => name.endsWith('.instructions.md'))
+    .sort((a, b) => a.localeCompare(b));
+  return names.map((name) => {
+    const sourcePath = path.resolve(sourceDir, name);
+    let content = fs.readFileSync(sourcePath, 'utf8');
+    if (!content.endsWith('\n')) {
+      content = `${content}\n`;
+    }
+    return {
+      fileName: name,
+      content,
+      sourcePath,
+    };
+  });
+}
+
+function isManagedFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return content.includes(MANAGED_MARKER);
+}
+
+function buildUserSpaceBootstrapContent(namespaceDirPath, cwd) {
+  const namespaceDisplayPath = path.relative(cwd, namespaceDirPath).replace(/\\/g, '/');
+  let content = loadTemplateFile('user-space-bootstrap.md');
+  content = content.replace(/\{\{NAMESPACE_GLOB\}\}/g, `${namespaceDisplayPath}/*.instructions.md`);
   if (!content.endsWith('\n')) {
     content = `${content}\n`;
   }
@@ -364,45 +425,166 @@ function runValidateCommitMsg(options) {
 
 function runSyncInstructions(options) {
   const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
-  const outArg = getSingle(options, '--out', '.instructions.md');
+  const outArg = getSingle(options, '--out', DEFAULT_NAMESPACE_OUT_DIR);
   const sourceArg = getSingle(options, '--source', '');
   const force = hasFlag(options, '--force');
   const dryRun = hasFlag(options, '--dry-run');
+  const prune = hasFlag(options, '--prune');
 
   if (!fs.existsSync(cwd)) {
     console.error(`CWD does not exist: ${cwd}`);
     process.exit(2);
   }
 
-  const outPath = path.resolve(cwd, outArg);
-  let content = loadDefaultInstructionsTemplate();
+  const defaults = loadDefaultInstructionsTemplate();
+  let sourceType = defaults.type;
+  let sourceResolved = defaults.sourcePath;
+  let entries = defaults.entries;
 
   if (sourceArg) {
     const sourcePath = path.resolve(cwd, sourceArg);
     if (!fs.existsSync(sourcePath)) {
-      console.error(`Source file does not exist: ${sourcePath}`);
+      console.error(`Source path does not exist: ${sourcePath}`);
       process.exit(2);
     }
-    content = fs.readFileSync(sourcePath, 'utf8');
-    if (!content.endsWith('\n')) {
-      content = `${content}\n`;
+    const stat = fs.statSync(sourcePath);
+    if (stat.isDirectory()) {
+      sourceType = 'dir';
+      sourceResolved = sourcePath;
+      entries = readInstructionEntriesFromDirectory(sourcePath);
+      if (entries.length === 0) {
+        console.error(`No .instructions.md files in source directory: ${sourcePath}`);
+        process.exit(2);
+      }
+    } else {
+      sourceType = 'file';
+      sourceResolved = sourcePath;
+      let content = fs.readFileSync(sourcePath, 'utf8');
+      if (!content.endsWith('\n')) {
+        content = `${content}\n`;
+      }
+      entries = [
+        {
+          fileName: path.basename(sourcePath),
+          content,
+          sourcePath,
+        },
+      ];
+    }
+  }
+
+  const outPath = path.resolve(cwd, outArg);
+  const outLooksLikeFile = outArg.endsWith('.md');
+
+  if (outLooksLikeFile && entries.length > 1) {
+    console.error('Target --out is a file path but source has multiple instruction files.');
+    console.error('Use an output directory for multi-file sync.');
+    process.exit(2);
+  }
+
+  if (outLooksLikeFile) {
+    const entry = entries[0];
+    const exists = fs.existsSync(outPath);
+    if (exists && !force) {
+      const current = fs.readFileSync(outPath, 'utf8');
+      if (current !== entry.content) {
+        console.error(`Target already exists: ${outPath}`);
+        console.error('Use --force to overwrite.');
+        process.exit(2);
+      }
+    }
+
+    const report = {
+      mode: 'single-file',
+      cwd,
+      sourceType,
+      source: sourceResolved,
+      outPath,
+      exists,
+      overwritten: exists && force,
+      dryRun,
+      prune: false,
+      initializedUserSpaceEntry: false,
+      userSpaceEntryPath: null,
+    };
+
+    if (dryRun) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      process.exit(0);
+    }
+
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, entry.content, 'utf8');
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  const outDir = outPath;
+  const planned = entries.map((entry) => {
+    return {
+      fileName: entry.fileName,
+      sourcePath: entry.sourcePath,
+      targetPath: path.resolve(outDir, entry.fileName),
+      content: entry.content,
+    };
+  });
+
+  const targetSet = new Set(planned.map((item) => item.targetPath));
+  const unchanged = [];
+  for (const item of planned) {
+    if (fs.existsSync(item.targetPath)) {
+      const current = fs.readFileSync(item.targetPath, 'utf8');
+      if (current === item.content) {
+        unchanged.push(item.targetPath);
+      }
     }
   }
 
-  const exists = fs.existsSync(outPath);
-  if (exists && !force) {
-    console.error(`Target already exists: ${outPath}`);
+  const toWrite = planned.filter((item) => !unchanged.includes(item.targetPath));
+  const conflicts = toWrite.filter((item) => fs.existsSync(item.targetPath));
+  if (conflicts.length > 0 && !force) {
+    console.error('Some target files already exist and would change:');
+    for (const item of conflicts) {
+      console.error(`- ${item.targetPath}`);
+    }
     console.error('Use --force to overwrite.');
     process.exit(2);
   }
 
+  const pruneDeletes = [];
+  if (prune && fs.existsSync(outDir)) {
+    const existing = fs
+      .readdirSync(outDir)
+      .filter((name) => name.endsWith('.instructions.md'))
+      .map((name) => path.resolve(outDir, name));
+    for (const existingPath of existing) {
+      if (!targetSet.has(existingPath) && isManagedFile(existingPath)) {
+        pruneDeletes.push(existingPath);
+      }
+    }
+  }
+
+  const userSpaceEntryPath = path.resolve(cwd, USER_SPACE_ENTRYPOINT);
+  const shouldInitUserSpaceEntry = !fs.existsSync(userSpaceEntryPath);
+
   const report = {
+    mode: 'directory',
     cwd,
-    outPath,
-    source: sourceArg ? path.resolve(cwd, sourceArg) : DEFAULT_INSTRUCTIONS_TEMPLATE_PATH,
-    exists,
-    overwritten: exists && force,
+    sourceType,
+    source: sourceResolved,
+    outDir,
     dryRun,
+    force,
+    prune,
+    initializedUserSpaceEntry: shouldInitUserSpaceEntry,
+    userSpaceEntryPath,
+    files: planned.map((item) => ({
+      fileName: item.fileName,
+      sourcePath: item.sourcePath,
+      targetPath: item.targetPath,
+      unchanged: unchanged.includes(item.targetPath),
+    })),
+    deleteFiles: pruneDeletes,
   };
 
   if (dryRun) {
@@ -410,8 +592,21 @@ function runSyncInstructions(options) {
     process.exit(0);
   }
 
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, content, 'utf8');
+  fs.mkdirSync(outDir, { recursive: true });
+  for (const item of toWrite) {
+    fs.writeFileSync(item.targetPath, item.content, 'utf8');
+  }
+
+  if (shouldInitUserSpaceEntry) {
+    fs.mkdirSync(path.dirname(userSpaceEntryPath), { recursive: true });
+    const userSpaceBootstrap = buildUserSpaceBootstrapContent(outDir, cwd);
+    fs.writeFileSync(userSpaceEntryPath, userSpaceBootstrap, 'utf8');
+  }
+
+  for (const filePath of pruneDeletes) {
+    fs.unlinkSync(filePath);
+  }
+
   process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 }
 

package/bin/build-publish-assets.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+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 LEGACY_OUTPUT_PATH = path.resolve(
+  PACKAGE_ROOT,
+  'publish-assets/instructions/org.instructions.md',
+);
+const MANAGED_MARKER = '<!-- managed-by: @produck/agent-toolkit -->';
+
+function normalize(text) {
+  return text.replace(/\r\n/g, '\n').trimEnd() + '\n';
+}
+
+function readFrontmatter(text) {
+  const match = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) {
+    return '';
+  }
+  return match[1];
+}
+
+function validateSourceFile(fileName, text) {
+  const frontmatter = readFrontmatter(text);
+  if (!frontmatter) {
+    throw new Error(`Missing frontmatter in source file: ${fileName}`);
+  }
+  if (!/^applyTo:\s*["'][^"']+["']\s*$/m.test(frontmatter)) {
+    throw new Error(`Missing applyTo in source file: ${fileName}`);
+  }
+  if (!text.includes(MANAGED_MARKER)) {
+    throw new Error(`Missing managed marker in source file: ${fileName}`);
+  }
+}
+
+function readSourceEntries() {
+  if (!fs.existsSync(SOURCE_DIR)) {
+    throw new Error(`Missing source directory: ${SOURCE_DIR}`);
+  }
+
+  const fileNames = fs
+    .readdirSync(SOURCE_DIR)
+    .filter((name) => name.endsWith('.instructions.md'))
+    .sort((a, b) => a.localeCompare(b));
+
+  if (fileNames.length === 0) {
+    throw new Error(`No source instruction files in: ${SOURCE_DIR}`);
+  }
+
+  return fileNames.map((fileName) => {
+    const sourcePath = path.resolve(SOURCE_DIR, fileName);
+    const text = normalize(fs.readFileSync(sourcePath, 'utf8'));
+    validateSourceFile(fileName, text);
+    return {
+      fileName,
+      sourcePath,
+      text,
+    };
+  });
+}
+
+function cleanStaleManagedFiles(expectedNames) {
+  if (!fs.existsSync(OUTPUT_DIR)) {
+    return;
+  }
+  const existing = fs.readdirSync(OUTPUT_DIR).filter((name) => name.endsWith('.instructions.md'));
+  for (const name of existing) {
+    if (expectedNames.has(name)) {
+      continue;
+    }
+    const filePath = path.resolve(OUTPUT_DIR, name);
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (content.includes(MANAGED_MARKER)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+}
+
+function run() {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  const sourceEntries = readSourceEntries();
+  const expectedNames = new Set(sourceEntries.map((entry) => entry.fileName));
+
+  for (const entry of sourceEntries) {
+    const outPath = path.resolve(OUTPUT_DIR, entry.fileName);
+    fs.writeFileSync(outPath, entry.text, 'utf8');
+    process.stdout.write(`Generated ${outPath} from ${entry.sourcePath}\n`);
+  }
+
+  cleanStaleManagedFiles(expectedNames);
+
+  if (fs.existsSync(LEGACY_OUTPUT_PATH)) {
+    fs.unlinkSync(LEGACY_OUTPUT_PATH);
+    process.stdout.write(`Removed legacy ${LEGACY_OUTPUT_PATH}\n`);
+  }
+}
+
+run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
@@ -12,12 +12,14 @@
     "agent-toolkit": "bin/agent-toolkit.mjs"
   },
   "scripts": {
+    "prepack": "node ./bin/build-publish-assets.mjs",
     "verify": "node ./bin/agent-toolkit.mjs --help && node ./bin/agent-toolkit.mjs preflight --cwd . --require package.json",
     "pack:check": "npm pack --dry-run"
   },
   "files": [
     "bin",
-    "templates"
+    "templates",
+    "publish-assets"
   ],
   "publishConfig": {
     "access": "public"
@@ -26,5 +28,5 @@
     "node": ">=18.0.0"
   },
   "license": "MIT",
-  "gitHead": "a2e293bea6a90e6fcbf9d0df03ba4fdf3a13ef00"
+  "gitHead": "8fbe9d26ada86a17e4f0444c2342e3904ba0f7f2"
 }