@izkac/forgekit 0.1.0

package/bin/forge.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Forge CLI — session orchestration, prefs, models, project init.
+ *
+ * Usage: forge <command> [args...]
+ * Install: forge install → forgekit install --skills forge …
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(__dirname, '..', 'src');
+
+/** @type {Record<string, { script: string, aliases?: string[], prependArgs?: string[] }>} */
+const COMMANDS = {
+  new: { script: 'new-session.mjs', aliases: ['session-new'] },
+  status: { script: 'session-status.mjs' },
+  cleanup: { script: 'cleanup-sessions.mjs' },
+  phase: { script: 'set-phase.mjs', aliases: ['set-phase'] },
+  prefs: { script: 'set-prefs.mjs' },
+  models: { script: 'set-models.mjs' },
+  'resolve-model': { script: 'resolve-model.mjs' },
+  doctor: { script: 'doctor.mjs' },
+  evidence: { script: 'record-evidence.mjs' },
+  reminder: { script: 'session-reminder.mjs' },
+  overlay: { script: 'vendor-openspec-overlays.mjs', aliases: ['overlays'] },
+  install: { script: 'install.mjs', prependArgs: ['--skills', 'forge'] },
+  init: { script: 'init.mjs' },
+  triage: { script: 'triage-prompt.mjs' },
+  change: { script: 'change.mjs' },
+  spine: { script: 'spine.mjs' },
+  defer: { script: 'defer.mjs' },
+  'integrity-check': { script: 'integrity-check.mjs', aliases: ['integrity'] },
+  score: { script: 'score-cli.mjs', aliases: ['scorecard'] },
+};
+
+function printHelp() {
+  process.stdout.write(`Forge — disciplined development workflow
+
+Usage:
+  forge <command> [args...]
+
+Commands:
+  new <slug>              Create a Forge session under .forge/
+  status                  Show active session
+  phase <phase>           Update session phase
+  cleanup                 Prune old/finished sessions
+  prefs [pace]            Get/set pace preferences
+  models [lane]           Get/set subagent billing (included|metered)
+  resolve-model --tier …  Resolve subagent model JSON
+  doctor                  Plan-engine readiness (OpenSpec or specs)
+  evidence                Stamp tier-2 test-evidence.md
+  reminder                Session reminder (for hooks)
+  overlay                 Re-apply OpenSpec vendor overlays in this project
+  install                 Alias → forgekit install --skills forge
+  init                    Wire Forge commands/hooks/rules into this project
+  triage                  Classify whether a prompt needs Forge triage
+  change new|archive      Specs-engine change scaffold / archive
+  spine init|check        Capability→runtime spine matrix (spine.json)
+  defer add|resolve|list  Deferral registry (deferred wiring = tracked debt)
+  integrity-check         Mechanical integrity gate (runs at phase done)
+  score [--write]         L2 session scorecard (auto-written at phase done)
+
+Prefer \`forgekit install\` to pick multiple skills + agents at once.
+
+Global:
+  forge --help
+  forge <command> --help
+`);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+const [cmd, ...rest] = argv;
+const entry = COMMANDS[cmd] ?? Object.values(COMMANDS).find((c) => c.aliases?.includes(cmd));
+
+if (!entry) {
+  process.stderr.write(`Unknown command: ${cmd}\n\n`);
+  printHelp();
+  process.exit(1);
+}
+
+const args = [...(entry.prependArgs ?? []), ...rest];
+const r = spawnSync(process.execPath, [path.join(SRC, entry.script), ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    FORGEKIT_ROOT: path.resolve(__dirname, '..', '..', '..'),
+    FORGEKIT_CLI_ROOT: path.resolve(__dirname, '..'),
+  },
+});
+
+process.exit(r.status ?? 1);

package/bin/forgekit.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Forgekit meta CLI — install / list / update / uninstall skills across agents.
+ *
+ * Skill day-to-day commands stay on `forge` and `review`.
+ *
+ * Usage: forgekit <command> [args...]
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(__dirname, '..', 'src');
+
+/** @type {Record<string, { script: string, prependArgs?: string[] }>} */
+const COMMANDS = {
+  install: { script: 'install.mjs' },
+  list: { script: 'install.mjs', prependArgs: ['--list'] },
+  update: { script: 'install.mjs', prependArgs: ['--update'] },
+  uninstall: { script: 'install.mjs', prependArgs: ['--uninstall'] },
+};
+
+function printHelp() {
+  process.stdout.write(`Forgekit — portable agent skills
+
+Usage:
+  forgekit <command> [args...]
+
+Commands:
+  install                 Install skills into ~/.cursor|claude|codex/skills/
+  list                    Show installed / missing / outdated (skill × agent)
+  update                  Reinstall outdated skills
+  uninstall               Remove installed skill directories
+
+Install picks skills and agents (interactive on TTY, or via flags).
+Also asks about planning engine (OpenSpec vs specs) and ADRs:
+
+  forgekit install
+  forgekit install --skills forge,thorough-code-review --agents cursor,claude
+  forgekit install --adr --adr-dir docs/adr --adr-project
+  forgekit install --all-skills --all-agents --force
+  forgekit list
+  forgekit update
+  forgekit uninstall --skills forge --agents cursor
+
+Day-to-day skill CLIs (same package):
+
+  forge …                 Forge workflow sessions
+  review …                Thorough code review pipeline
+
+  forge install …         Alias → forgekit install --skills forge …
+  review install …        Alias → forgekit install --skills thorough-code-review …
+`);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+const [cmd, ...rest] = argv;
+const entry = COMMANDS[cmd];
+
+if (!entry) {
+  process.stderr.write(`Unknown command: ${cmd}\n\n`);
+  printHelp();
+  process.exit(1);
+}
+
+const args = [...(entry.prependArgs ?? []), ...rest];
+const r = spawnSync(process.execPath, [path.join(SRC, entry.script), ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    FORGEKIT_ROOT: path.resolve(__dirname, '..', '..', '..'),
+    FORGEKIT_CLI_ROOT: path.resolve(__dirname, '..'),
+  },
+});
+
+process.exit(r.status ?? 1);

package/bin/review.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Review CLI — thorough-code-review scaffolding, render, export, signals.
+ *
+ * Usage: review <command> [args...]
+ * Install: review install → forgekit install --skills thorough-code-review …
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(__dirname, '..', 'src');
+const REVIEW_SRC = path.join(SRC, 'review');
+
+/** @type {Record<string, { script: string, prependArgs?: string[] }>} */
+const COMMANDS = {
+  new: { script: path.join(REVIEW_SRC, 'new-review.mjs') },
+  render: { script: path.join(REVIEW_SRC, 'render.mjs') },
+  export: { script: path.join(REVIEW_SRC, 'export.mjs') },
+  carryforward: { script: path.join(REVIEW_SRC, 'carryforward.mjs') },
+  merge: { script: path.join(REVIEW_SRC, 'merge-tentative.mjs') },
+  signals: { script: path.join(REVIEW_SRC, 'signals.mjs') },
+  install: {
+    script: path.join(SRC, 'install.mjs'),
+    prependArgs: ['--skills', 'thorough-code-review'],
+  },
+};
+
+function printHelp() {
+  process.stdout.write(`Review — thorough code review tooling
+
+Usage:
+  review <command> [args...]
+
+Commands:
+  new <slug>              Scaffold .reviews/<id>-review.json
+  render                  Generate markdown from JSON
+  export                  Validate + summarize (+ optional CI gate)
+  carryforward            Inherit prior verdicts for unchanged files
+  merge                   Merge scout tentative JSON shards
+  signals                 Plan typecheck/lint/test grounding commands
+  install                 Alias → forgekit install --skills thorough-code-review
+
+Prefer \`forgekit install\` to pick multiple skills + agents at once.
+
+Global:
+  review --help
+  review <command> --help
+
+After install, invoke the skill explicitly in your agent (it does not auto-load).
+`);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+const [cmd, ...rest] = argv;
+const entry = COMMANDS[cmd];
+
+if (!entry) {
+  process.stderr.write(`Unknown command: ${cmd}\n\n`);
+  printHelp();
+  process.exit(1);
+}
+
+const args = [...(entry.prependArgs ?? []), ...rest];
+const r = spawnSync(process.execPath, [entry.script, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    FORGEKIT_ROOT: path.resolve(__dirname, '..', '..', '..'),
+    FORGEKIT_CLI_ROOT: path.resolve(__dirname, '..'),
+  },
+});
+
+process.exit(r.status ?? 1);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@izkac/forgekit",
+  "version": "0.1.0",
+  "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
+  "type": "module",
+  "bin": {
+    "forgekit": "./bin/forgekit.mjs",
+    "forge": "./bin/forge.mjs",
+    "review": "./bin/review.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor",
+    "scripts"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs",
+    "test": "node scripts/run-tests.mjs",
+    "lint": "eslint src bin scripts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/izkac/forgekit.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/izkac/forgekit#readme",
+  "bugs": {
+    "url": "https://github.com/izkac/forgekit/issues"
+  },
+  "keywords": [
+    "forge",
+    "openspec",
+    "agent-skills",
+    "cursor",
+    "claude",
+    "codex"
+  ],
+  "license": "MIT"
+}

package/scripts/prepack.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Copy skills/ and templates/ from the monorepo root into packages/cli/vendor/
+ * so the published npm package is self-contained.
+ *
+ * Usage: node packages/cli/scripts/prepack.mjs
+ * Triggered by npm prepack in @izkac/forgekit.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cliRoot = path.resolve(__dirname, '..');
+const monoRoot = path.resolve(cliRoot, '..', '..');
+const vendorRoot = path.join(cliRoot, 'vendor');
+
+/**
+ * @param {string} src
+ * @param {string} dest
+ */
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(from, to);
+    else fs.copyFileSync(from, to);
+  }
+}
+
+/**
+ * Best-effort clear. On Windows EPERM, leave the tree and overwrite in place.
+ * @param {string} dir
+ * @returns {boolean} true if cleared
+ */
+function tryEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true;
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      fs.rmSync(path.join(dir, entry.name), {
+        recursive: true,
+        force: true,
+        maxRetries: 5,
+        retryDelay: 100,
+      });
+    }
+    return true;
+  } catch (err) {
+    process.stderr.write(
+      `prepack: could not empty ${dir} (${err.code || err.message}); overwriting in place\n`,
+    );
+    return false;
+  }
+}
+
+function main() {
+  const skillsSrc = path.join(monoRoot, 'skills');
+  const templatesSrc = path.join(monoRoot, 'templates');
+  if (!fs.existsSync(skillsSrc) || !fs.existsSync(templatesSrc)) {
+    if (fs.existsSync(path.join(vendorRoot, 'skills'))) {
+      process.stdout.write(`prepack: vendor already present at ${vendorRoot}\n`);
+      return;
+    }
+    throw new Error(
+      `prepack: monorepo skills/templates not found at ${monoRoot} and vendor/ missing`,
+    );
+  }
+
+  fs.mkdirSync(vendorRoot, { recursive: true });
+  tryEmptyDir(vendorRoot);
+  copyDirRecursive(skillsSrc, path.join(vendorRoot, 'skills'));
+  copyDirRecursive(templatesSrc, path.join(vendorRoot, 'templates'));
+  process.stdout.write(`prepack: vendored skills + templates → ${vendorRoot}\n`);
+}
+
+main();

package/scripts/run-tests.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Run all src test files (*.test.mjs) via node --test.
+ *
+ * Node 20 does not expand globs passed to `node --test`; Node 22+ does.
+ * Explicit file discovery keeps CI green on the engines.node >=20 matrix.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cliRoot = path.resolve(__dirname, '..');
+const srcRoot = path.join(cliRoot, 'src');
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findTestFiles(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findTestFiles(full));
+    else if (entry.name.endsWith('.test.mjs')) out.push(full);
+  }
+  return out;
+}
+
+const files = findTestFiles(srcRoot).sort();
+if (files.length === 0) {
+  console.error(`No *.test.mjs files under ${srcRoot}`);
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ['--test', ...files], {
+  cwd: cliRoot,
+  stdio: 'inherit',
+});
+process.exit(result.status ?? 1);

package/src/adr.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * ADR project/user config + scaffolding for forgekit.
+ *
+ * User defaults:  ~/.forgekit/config.json  → { adr: { enabled, dir } }
+ * Project:        <repo>/.forge/config.json → { adr: { enabled, dir, decisionsDoc } }
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  loadProjectConfig,
+  loadUserConfig,
+  saveProjectConfig,
+  saveUserConfig as saveUserConfigBase,
+  userConfigPath,
+  projectConfigPath,
+} from './config.mjs';
+import { resolveAsset } from './paths.mjs';
+
+export {
+  loadProjectConfig,
+  loadUserConfig,
+  userConfigPath,
+  projectConfigPath,
+};
+
+export const DEFAULT_ADR_DIR = 'docs/adr';
+export const ADR_SKILLS = Object.freeze(['archive-to-adr', 'git-resolve-adr-conflict']);
+
+/**
+ * @param {string} adrDir posix-ish relative path
+ * @returns {string}
+ */
+export function decisionsDocFor(adrDir) {
+  const normalized = normalizeAdrDir(adrDir);
+  const parent = path.posix.dirname(normalized);
+  if (!parent || parent === '.') return 'decisions.md';
+  return path.posix.join(parent, 'decisions.md');
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizeAdrDir(raw) {
+  let s = String(raw ?? '')
+    .trim()
+    .replace(/\\/g, '/');
+  if (!s) s = DEFAULT_ADR_DIR;
+  s = s.replace(/^\.\/+/, '').replace(/\/+$/, '');
+  if (!s) s = DEFAULT_ADR_DIR;
+  if (path.isAbsolute(s) || s.startsWith('..') || s.split('/').includes('..')) {
+    throw new Error(
+      `ADR directory must be a relative path inside the repo (got: ${raw})`,
+    );
+  }
+  return s;
+}
+
+/**
+ * @param {{ adr?: { enabled?: boolean, dir?: string } }} patch
+ * @param {string} [home]
+ */
+export function saveUserConfig(patch, home) {
+  return saveUserConfigBase(patch, home);
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ adr: { enabled: boolean, dir?: string, decisionsDoc?: string } }} patch
+ */
+export function writeProjectAdrConfig(cwd, patch) {
+  const current = loadProjectConfig(cwd);
+  const enabled = Boolean(patch.adr.enabled);
+  /** @type {{ enabled: boolean, dir?: string, decisionsDoc?: string }} */
+  const adr = { enabled };
+  if (enabled) {
+    const curAdr =
+      current.adr && typeof current.adr === 'object'
+        ? /** @type {{ dir?: string, decisionsDoc?: string }} */ (current.adr)
+        : {};
+    const dir = normalizeAdrDir(patch.adr.dir ?? curAdr.dir ?? DEFAULT_ADR_DIR);
+    adr.dir = dir;
+    adr.decisionsDoc =
+      patch.adr.decisionsDoc ?? curAdr.decisionsDoc ?? decisionsDocFor(dir);
+  }
+  return saveProjectConfig(cwd, { adr });
+}
+
+/**
+ * @returns {string}
+ */
+export function resolveAdrTemplatesRoot() {
+  return resolveAsset('templates/adr');
+}
+
+/**
+ * @param {string} template
+ * @param {Record<string, string>} vars
+ */
+function renderTemplate(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+
+/**
+ * Relative link from adr README to decisions doc.
+ * @param {string} adrDir
+ * @param {string} decisionsDoc
+ */
+export function decisionsRelFromAdrReadme(adrDir, decisionsDoc) {
+  const fromDir = adrDir.replace(/\/+$/, '');
+  const target = decisionsDoc.replace(/\\/g, '/');
+  const rel = path.posix.relative(fromDir, target);
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+/**
+ * Scaffold decisions.md, adr README, optional hooks.
+ * @param {string} cwd
+ * @param {{ dir?: string, decisionsDoc?: string, force?: boolean, hooks?: boolean }} opts
+ */
+export function scaffoldAdr(cwd, opts = {}) {
+  const dir = normalizeAdrDir(opts.dir ?? DEFAULT_ADR_DIR);
+  const decisionsDoc = opts.decisionsDoc ?? decisionsDocFor(dir);
+  const templates = resolveAdrTemplatesRoot();
+  const force = Boolean(opts.force);
+  /** @type {{ file: string, status: string }[]} */
+  const files = [];
+
+  const write = (relPath, body) => {
+    const dest = path.join(cwd, ...relPath.split('/'));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest) && !force) {
+      files.push({ file: relPath, status: 'skipped' });
+      return;
+    }
+    fs.writeFileSync(dest, body, 'utf8');
+    files.push({ file: relPath, status: 'written' });
+  };
+
+  const decisionsTpl = fs.readFileSync(path.join(templates, 'decisions.md'), 'utf8');
+  write(decisionsDoc, renderTemplate(decisionsTpl, { ADR_DIR: dir }));
+
+  const readmeTpl = fs.readFileSync(path.join(templates, 'README.md'), 'utf8');
+  write(
+    path.posix.join(dir, 'README.md'),
+    renderTemplate(readmeTpl, {
+      ADR_DIR: dir,
+      DECISIONS_REL: decisionsRelFromAdrReadme(dir, decisionsDoc),
+    }),
+  );
+
+  if (opts.hooks !== false) {
+    const hooksSrc = path.join(templates, 'hooks');
+    if (fs.existsSync(hooksSrc)) {
+      const hooksDestRel = 'scripts/hooks';
+      for (const name of fs.readdirSync(hooksSrc)) {
+        const from = path.join(hooksSrc, name);
+        if (!fs.statSync(from).isFile()) continue;
+        write(path.posix.join(hooksDestRel, name), fs.readFileSync(from, 'utf8'));
+      }
+    }
+  }
+
+  const config = writeProjectAdrConfig(cwd, {
+    adr: { enabled: true, dir, decisionsDoc },
+  });
+
+  return { dir, decisionsDoc, files, config };
+}
+
+/**
+ * @param {string} cwd
+ */
+export function disableProjectAdr(cwd) {
+  return writeProjectAdrConfig(cwd, { adr: { enabled: false } });
+}
+
+/**
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isGitRepo(cwd) {
+  return fs.existsSync(path.join(cwd, '.git'));
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ home?: string }} [opts]
+ * @returns {{ enabled: boolean, dir: string, decisionsDoc: string, source: string }}
+ */
+export function resolveProjectAdr(cwd, opts = {}) {
+  const project = loadProjectConfig(cwd);
+  const projectAdr =
+    project.adr && typeof project.adr === 'object'
+      ? /** @type {{ enabled?: boolean, dir?: string, decisionsDoc?: string }} */ (project.adr)
+      : null;
+  if (projectAdr && typeof projectAdr.enabled === 'boolean') {
+    const dir = normalizeAdrDir(projectAdr.dir ?? DEFAULT_ADR_DIR);
+    return {
+      enabled: projectAdr.enabled,
+      dir,
+      decisionsDoc: projectAdr.decisionsDoc ?? decisionsDocFor(dir),
+      source: 'project',
+    };
+  }
+  const user = loadUserConfig(opts.home);
+  const userAdr =
+    user.adr && typeof user.adr === 'object'
+      ? /** @type {{ enabled?: boolean, dir?: string }} */ (user.adr)
+      : null;
+  if (userAdr && typeof userAdr.enabled === 'boolean') {
+    const dir = normalizeAdrDir(userAdr.dir ?? DEFAULT_ADR_DIR);
+    return {
+      enabled: userAdr.enabled,
+      dir,
+      decisionsDoc: decisionsDocFor(dir),
+      source: 'user',
+    };
+  }
+  if (fs.existsSync(path.join(cwd, DEFAULT_ADR_DIR))) {
+    return {
+      enabled: true,
+      dir: DEFAULT_ADR_DIR,
+      decisionsDoc: decisionsDocFor(DEFAULT_ADR_DIR),
+      source: 'heuristic',
+    };
+  }
+  return {
+    enabled: false,
+    dir: DEFAULT_ADR_DIR,
+    decisionsDoc: decisionsDocFor(DEFAULT_ADR_DIR),
+    source: 'default',
+  };
+}