@produck/agent-toolkit 0.1.5 → 0.2.1

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/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/index.mjs

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

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-instructions/help.txt

@@ -0,0 +1,11 @@
+Usage:
+  agent-toolkit sync-instructions [--cwd <dir>] [--out <file>]
+    [--source <file-or-dir>] [--force] [--prune] [--dry-run]
+
+Behavior:
+  - Syncs one or multiple .instructions.md files to target path.
+  - Defaults to <cwd>/.github/instructions/produck when --out is not provided.
+  - If --source is a directory, all *.instructions.md files in that directory are synced.
+  - If --source is omitted, built-in namespaced assets are used.
+  - Existing changed files require --force.
+  - --prune deletes unmanaged leftovers only when file contains managed marker.

package/bin/command/sync-instructions/index.mjs

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle, hasFlag } from '../shared/args.mjs';
+import { loadTextResource, printTextResource } from '../shared/text-resource.mjs';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(COMMAND_DIR, '../../..');
+const PUBLISH_ASSETS_ROOT = path.resolve(PACKAGE_ROOT, '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';
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const USER_SPACE_BOOTSTRAP_FILE = path.resolve(COMMAND_DIR, 'user-space-bootstrap.md');
+
+export function printSyncInstructionsHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function loadDefaultInstructionsTemplate() {
+  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 = loadTextResource(USER_SPACE_BOOTSTRAP_FILE);
+  content = content.replace(/\{\{NAMESPACE_GLOB\}\}/g, `${namespaceDisplayPath}/*.instructions.md`);
+  if (!content.endsWith('\n')) {
+    content = `${content}\n`;
+  }
+  return content;
+}
+
+export function runSyncInstructions(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  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 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 path does not exist: ${sourcePath}`);
+      process.exit(2);
+    }
+    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 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,
+    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) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  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`);
+}