@izkac/forgekit 0.1.0

package/src/defer.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Forge deferral registry — deferred wiring is tracked debt, not a checkbox.
+ *
+ * Usage:
+ *   forge defer add --task <id> --reason "<why deferred>"
+ *   forge defer resolve --task <id>
+ *   forge defer list
+ *   [--session <id>]
+ *
+ * Unresolved deferrals block `forge phase done|finish`.
+ */
+
+import { loadSession, readActive } from './lib.mjs';
+import { addDeferral, loadDeferrals, resolveDeferral } from './integrity.mjs';
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith('--') ? args[0] : 'list';
+
+if (args[0] === '--help' || sub === 'help') {
+  process.stdout.write(
+    'Usage: forge defer [add --task <id> --reason "<why>" | resolve --task <id> | list] [--session <id>]\n',
+  );
+  process.exit(0);
+}
+
+let sessionId = null;
+let task = null;
+let reason = null;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--task' && args[i + 1]) {
+    task = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--reason' && args[i + 1]) {
+    reason = args[i + 1];
+    i += 1;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  sessionId = active?.sessionId;
+}
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { dir } = loadSession(sessionId);
+
+try {
+  if (sub === 'add') {
+    const doc = addDeferral(dir, { task: task ?? '', reason: reason ?? '' });
+    process.stdout.write(JSON.stringify(doc, null, 2));
+    process.stdout.write('\n');
+  } else if (sub === 'resolve') {
+    if (!task) throw new Error('resolve requires --task <id>');
+    const doc = resolveDeferral(dir, task);
+    process.stdout.write(JSON.stringify(doc, null, 2));
+    process.stdout.write('\n');
+  } else if (sub === 'list') {
+    const doc = loadDeferrals(dir);
+    const open = doc.deferrals.filter((d) => !d.resolvedAt).length;
+    process.stdout.write(JSON.stringify({ open, ...doc }, null, 2));
+    process.stdout.write('\n');
+  } else {
+    throw new Error(`Unknown subcommand: ${sub}`);
+  }
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+}

package/src/doctor.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * Forge readiness checks (OpenSpec project + CLI).
+ *
+ * Usage:
+ *   forge doctor
+ *   forge doctor --json
+ *   forge doctor --install
+ *   forge doctor --warn-only   # always exit 0 (for forge:new)
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  OPENSPEC_PACKAGE,
+  OPENSPEC_INSTALL_CMD,
+  resolveProjectPlanEngine,
+} from './plan-engine.mjs';
+
+export { OPENSPEC_PACKAGE, OPENSPEC_INSTALL_CMD };
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    json: false,
+    install: false,
+    warnOnly: false,
+    cwd: null,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--install') opts.install = true;
+    else if (arg === '--warn-only') opts.warnOnly = true;
+    else if (arg === '--cwd') opts.cwd = argv[++i];
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--') continue;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: forge doctor [options]
+
+Check planning-engine readiness. OpenSpec projects: config + CLI availability.
+Specs-engine projects (.forge/config.json → plan.engine: specs): specs/changes/ layout.
+
+Options:
+  --json        Machine-readable report
+  --install     Attempt: ${OPENSPEC_INSTALL_CMD}
+  --warn-only   Print warnings but exit 0 (used by forge:new)
+  --cwd <path>  Project root (default: process.cwd())
+  --help
+`);
+}
+
+/**
+ * @param {{ cwd: string, existsSync?: typeof fs.existsSync }} opts
+ */
+export function checkOpenSpecProject(opts) {
+  const existsSync = opts.existsSync ?? fs.existsSync;
+  const configPath = path.join(opts.cwd, 'openspec', 'config.yaml');
+  const ok = existsSync(configPath);
+  return {
+    id: 'openspec-project',
+    ok,
+    configPath,
+    message: ok
+      ? 'openspec/config.yaml found'
+      : 'openspec/config.yaml missing — run openspec init in the repo root if this is a new project',
+  };
+}
+
+/**
+ * @param {{
+ *   runCommand?: (cmd: string, args: string[], opts?: { cwd?: string }) => { status: number | null, stdout: string, stderr: string },
+ *   cwd?: string,
+ * }} [opts]
+ */
+export function checkOpenSpecCli(opts = {}) {
+  const run =
+    opts.runCommand ??
+    ((cmd, args, runOpts = {}) => {
+      // Prefer argv form without shell. On Windows, fall back to a single
+      // shell string so `.cmd` shims resolve without DEP0190 (args+shell).
+      let result = spawnSync(cmd, args, {
+        encoding: 'utf8',
+        shell: false,
+        cwd: runOpts.cwd,
+      });
+      if (result.error && process.platform === 'win32') {
+        const line = [cmd, ...args].join(' ');
+        result = spawnSync(line, {
+          encoding: 'utf8',
+          shell: true,
+          cwd: runOpts.cwd,
+        });
+      }
+      return {
+        status: result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        error: result.error,
+      };
+    });
+
+  const attempt = run('openspec', ['--version'], { cwd: opts.cwd });
+  if (attempt.status === 0) {
+    const version = String(attempt.stdout || '').trim().split(/\r?\n/)[0] || 'unknown';
+    return {
+      id: 'openspec-cli',
+      ok: true,
+      version,
+      message: `openspec CLI available (${version})`,
+      installCommand: OPENSPEC_INSTALL_CMD,
+    };
+  }
+
+  return {
+    id: 'openspec-cli',
+    ok: false,
+    version: null,
+    message:
+      `openspec CLI not found on PATH. Install with:\n  ${OPENSPEC_INSTALL_CMD}\n` +
+      `Then re-run: forge doctor`,
+    installCommand: OPENSPEC_INSTALL_CMD,
+    detail: String(attempt.stderr || attempt.stdout || attempt.error || '').trim() || null,
+  };
+}
+
+/**
+ * @param {{ cwd: string, dir: string, existsSync?: typeof fs.existsSync }} opts
+ */
+export function checkSpecsProject(opts) {
+  const existsSync = opts.existsSync ?? fs.existsSync;
+  const changesPath = path.join(opts.cwd, opts.dir, 'changes');
+  const ok = existsSync(changesPath);
+  return {
+    id: 'specs-project',
+    ok,
+    changesPath,
+    message: ok
+      ? `${opts.dir}/changes/ found (built-in specs engine)`
+      : `${opts.dir}/changes/ missing — run \`forge init --no-openspec\` to scaffold the specs engine`,
+  };
+}
+
+/**
+ * @param {{
+ *   cwd?: string,
+ *   install?: boolean,
+ *   existsSync?: typeof fs.existsSync,
+ *   runCommand?: Function,
+ * }} [opts]
+ */
+export function runDoctorChecks(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const engine = resolveProjectPlanEngine(cwd, { useUserDefault: false });
+
+  if (engine.engine === 'specs') {
+    const project = checkSpecsProject({
+      cwd,
+      dir: engine.dir,
+      existsSync: opts.existsSync,
+    });
+    const cli = {
+      id: 'openspec-cli',
+      ok: true,
+      skipped: true,
+      version: null,
+      message: 'built-in specs engine — OpenSpec CLI not required',
+      installCommand: OPENSPEC_INSTALL_CMD,
+    };
+    return {
+      ok: project.ok,
+      engine: engine.engine,
+      checks: { project, cli },
+      installCommand: OPENSPEC_INSTALL_CMD,
+      actions: [],
+    };
+  }
+
+  const project = checkOpenSpecProject({ cwd, existsSync: opts.existsSync });
+  let cli = checkOpenSpecCli({ cwd, runCommand: opts.runCommand });
+
+  /** @type {string[]} */
+  const actions = [];
+
+  if (opts.install && !cli.ok) {
+    actions.push(OPENSPEC_INSTALL_CMD);
+    const run =
+      opts.runCommand ??
+      ((cmd, args) => {
+        let result = spawnSync(cmd, args, {
+          encoding: 'utf8',
+          shell: false,
+          cwd,
+        });
+        if (result.error && process.platform === 'win32') {
+          result = spawnSync([cmd, ...args].join(' '), {
+            encoding: 'utf8',
+            shell: true,
+            cwd,
+          });
+        }
+        return {
+          status: result.status,
+          stdout: result.stdout || '',
+          stderr: result.stderr || '',
+          error: result.error,
+        };
+      });
+    const installResult = run('npm', ['install', '-g', OPENSPEC_PACKAGE], { cwd });
+    actions.push(
+      installResult.status === 0
+        ? 'install: ok'
+        : `install: failed (${String(installResult.stderr || installResult.stdout || '').trim() || installResult.status})`,
+    );
+    cli = checkOpenSpecCli({ cwd, runCommand: opts.runCommand });
+  }
+
+  const ok = project.ok && cli.ok;
+  return {
+    ok,
+    engine: engine.engine,
+    checks: { project, cli },
+    installCommand: OPENSPEC_INSTALL_CMD,
+    actions,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{
+ *   cwd?: string,
+ *   stdout?: NodeJS.WritableStream,
+ *   stderr?: NodeJS.WritableStream,
+ *   existsSync?: typeof fs.existsSync,
+ *   runCommand?: Function,
+ * }} [io]
+ */
+export function runDoctor(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const cwd = io.cwd ?? process.cwd();
+
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`${msg}\n`);
+    return 2;
+  }
+
+  if (opts.help) {
+    printHelp();
+    return 0;
+  }
+
+  const report = runDoctorChecks({
+    cwd: opts.cwd ?? cwd,
+    install: opts.install,
+    existsSync: io.existsSync,
+    runCommand: io.runCommand,
+  });
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    const { project, cli } = report.checks;
+    stdout.write(`Forge doctor (plan engine: ${report.engine ?? 'openspec'})\n`);
+    stdout.write(`  [${project.ok ? 'ok' : 'FAIL'}] ${project.message}\n`);
+    stdout.write(`  [${cli.ok ? 'ok' : 'FAIL'}] ${cli.message}\n`);
+    if (!cli.ok) {
+      stdout.write(`\nOffer: install OpenSpec CLI?\n  ${cli.installCommand}\n`);
+      stdout.write(`Or re-run with: forge doctor --install\n`);
+    }
+    for (const action of report.actions) {
+      stdout.write(`  action: ${action}\n`);
+    }
+    stdout.write(report.ok ? '\nAll checks passed.\n' : '\nDoctor found issues.\n');
+  }
+
+  if (opts.warnOnly) return 0;
+  return report.ok ? 0 : 1;
+}
+
+/**
+ * Warn-only helper for forge:new (never throws).
+ * @param {{
+ *   cwd?: string,
+ *   stderr?: NodeJS.WritableStream,
+ *   existsSync?: typeof fs.existsSync,
+ *   runCommand?: Function,
+ * }} [opts]
+ */
+export function warnIfDoctorFails(opts = {}) {
+  const stderr = opts.stderr ?? process.stderr;
+  try {
+    const report = runDoctorChecks({
+      cwd: opts.cwd ?? process.cwd(),
+      existsSync: opts.existsSync,
+      runCommand: opts.runCommand,
+    });
+    if (!report.ok) {
+      stderr.write('[forge:doctor] plan-engine readiness check failed:\n');
+      if (!report.checks.project.ok) {
+        stderr.write(`  - ${report.checks.project.message}\n`);
+      }
+      if (!report.checks.cli.ok) {
+        stderr.write(`  - ${report.checks.cli.message}\n`);
+      }
+      if (!report.checks.cli.ok) {
+        stderr.write(`  Install: ${report.installCommand}\n`);
+        stderr.write('  Or: forge doctor --install\n');
+      }
+    }
+    return report;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`[forge:doctor] check error: ${msg}\n`);
+    return null;
+  }
+}
+
+const isMain =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  process.exitCode = runDoctor(process.argv.slice(2));
+}

package/src/doctor.test.mjs

@@ -0,0 +1,114 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { Writable } from 'node:stream';
+import {
+  OPENSPEC_INSTALL_CMD,
+  checkOpenSpecCli,
+  checkOpenSpecProject,
+  runDoctor,
+  runDoctorChecks,
+  warnIfDoctorFails,
+} from './doctor.mjs';
+
+function capture() {
+  let text = '';
+  const stream = new Writable({
+    write(chunk, _enc, cb) {
+      text += String(chunk);
+      cb();
+    },
+  });
+  return { stream, text: () => text };
+}
+
+test('checkOpenSpecProject ok when config exists', () => {
+  const result = checkOpenSpecProject({
+    cwd: '/repo',
+    existsSync: (p) => p.replace(/\\/g, '/') === '/repo/openspec/config.yaml',
+  });
+  assert.equal(result.ok, true);
+});
+
+test('checkOpenSpecProject fails when missing', () => {
+  const result = checkOpenSpecProject({
+    cwd: '/repo',
+    existsSync: () => false,
+  });
+  assert.equal(result.ok, false);
+});
+
+test('checkOpenSpecCli ok when version exits 0', () => {
+  const result = checkOpenSpecCli({
+    runCommand: () => ({ status: 0, stdout: '1.2.0\n', stderr: '' }),
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.version, '1.2.0');
+});
+
+test('checkOpenSpecCli missing offers install', () => {
+  const result = checkOpenSpecCli({
+    runCommand: () => ({ status: 1, stdout: '', stderr: 'not found' }),
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.message, /@fission-ai\/openspec/);
+  assert.equal(result.installCommand, OPENSPEC_INSTALL_CMD);
+});
+
+test('runDoctorChecks aggregates', () => {
+  const report = runDoctorChecks({
+    cwd: '/repo',
+    existsSync: () => true,
+    runCommand: () => ({ status: 0, stdout: '1.0.0', stderr: '' }),
+  });
+  assert.equal(report.ok, true);
+});
+
+test('runDoctor --warn-only exits 0 on failure', () => {
+  const out = capture();
+  const err = capture();
+  const code = runDoctor(['--warn-only'], {
+    cwd: '/repo',
+    stdout: out.stream,
+    stderr: err.stream,
+    existsSync: () => true,
+    runCommand: () => ({ status: 1, stdout: '', stderr: 'missing' }),
+  });
+  assert.equal(code, 0);
+  assert.match(out.text(), /FAIL|not found|Install/i);
+});
+
+test('runDoctor exits 1 when CLI missing', () => {
+  const out = capture();
+  const err = capture();
+  const code = runDoctor([], {
+    cwd: '/repo',
+    stdout: out.stream,
+    stderr: err.stream,
+    existsSync: () => true,
+    runCommand: () => ({ status: 1, stdout: '', stderr: 'missing' }),
+  });
+  assert.equal(code, 1);
+  assert.match(out.text(), /npm install -g @fission-ai\/openspec/);
+});
+
+test('warnIfDoctorFails writes to stderr', () => {
+  const err = capture();
+  const report = warnIfDoctorFails({
+    cwd: '/repo',
+    stderr: err.stream,
+    existsSync: () => false,
+    runCommand: () => ({ status: 1, stdout: '', stderr: '' }),
+  });
+  assert.equal(report.ok, false);
+  assert.match(err.text(), /forge:doctor/);
+  assert.match(err.text(), /install/i);
+});
+
+test('path join uses openspec/config.yaml', () => {
+  const result = checkOpenSpecProject({
+    cwd: path.join('S:', 'Projects', 'janus'),
+    existsSync: (p) => p.endsWith(path.join('openspec', 'config.yaml')),
+  });
+  assert.equal(result.ok, true);
+});