sdtk-kit 1.2.0 → 1.3.0

package/src/commands/init.js

@@ -0,0 +1,95 @@
+"use strict";
+
+// `sdtk init` command (umbrella). Parses flags, wires real effectful deps, and
+// delegates to the pure orchestrator in src/lib/unified-init.js.
+
+const { spawnSync } = require("child_process");
+const {
+  runUnifiedInit,
+  resolveToolkitBin,
+  checkPowerShellAvailable,
+} = require("../lib/unified-init");
+
+// Minimal local flag parser (the umbrella has no shared args lib, and we must not
+// import a child kit's internal lib). Supports `--flag value`, `--flag=value`,
+// and boolean `--flag`.
+const FLAG_DEFS = Object.freeze({
+  runtime: "string",
+  "runtime-scope": "string",
+  "project-path": "string",
+  force: "boolean",
+  "skip-runtime-assets": "boolean",
+  "keep-going": "boolean",
+  verbose: "boolean",
+});
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+    let key = arg.slice(2);
+    let value;
+    const eq = key.indexOf("=");
+    if (eq !== -1) {
+      value = key.slice(eq + 1);
+      key = key.slice(0, eq);
+    }
+    const type = FLAG_DEFS[key];
+    if (!type) {
+      throw new Error(`Unknown flag: --${key}`);
+    }
+    if (type === "boolean") {
+      flags[key] = true;
+    } else {
+      if (value === undefined) {
+        value = args[i + 1];
+        i += 1;
+      }
+      if (value === undefined) {
+        throw new Error(`Flag --${key} requires a value.`);
+      }
+      flags[key] = value;
+    }
+  }
+  return flags;
+}
+
+function cmdInit(args) {
+  let flags;
+  try {
+    flags = parseFlags(args);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return 2;
+  }
+
+  const opts = {
+    runtime: flags.runtime,
+    runtimeScope: flags["runtime-scope"],
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+    skipRuntimeAssets: Boolean(flags["skip-runtime-assets"]),
+    keepGoing: Boolean(flags["keep-going"]),
+    verbose: Boolean(flags.verbose),
+  };
+
+  const deps = {
+    spawn(binPath, argv) {
+      return spawnSync(process.execPath, [binPath, ...argv], { stdio: "inherit" });
+    },
+    resolveBin: resolveToolkitBin,
+    powershellCheck: () => checkPowerShellAvailable(spawnSync),
+    log: (line) => console.log(line),
+  };
+
+  const { exitCode } = runUnifiedInit(opts, deps);
+  return exitCode;
+}
+
+module.exports = {
+  cmdInit,
+  parseFlags,
+};

package/src/lib/unified-init.js

@@ -0,0 +1,274 @@
+"use strict";
+
+// Unified-init orchestrator (pure logic).
+//
+// BK-268: `sdtk init --runtime <claude|codex>` delegates to each toolkit's own,
+// already-shipped `init`. This module re-implements NO init logic, performs NO
+// filesystem writes, NO network calls, and runs NO PowerShell of its own — every
+// side effect happens inside the delegated per-kit init it spawns.
+//
+// All effectful operations (process spawn, bin resolution, PowerShell pre-flight,
+// logging) are passed in through an injected `deps` seam so the orchestrator runs
+// fully offline under test.
+
+const path = require("path");
+
+const VALID_RUNTIMES = Object.freeze(["claude", "codex"]);
+
+// Ordered target registry. `binName` is the bin key in each kit's package.json
+// (resolved through its `bin` map at runtime, so a kit renaming its bin file
+// across a minor version does not break us — see R1 in the implementation plan).
+// `acceptsRuntime: false` toolkits run their own non-runtime init and receive
+// only the flags they accept (--project-path / --force / --verbose).
+const TOOLKITS = Object.freeze([
+  { name: "sdtk-spec", kitPkg: "sdtk-spec-kit", binName: "sdtk-spec", acceptsRuntime: true },
+  { name: "sdtk-ops", kitPkg: "sdtk-ops-kit", binName: "sdtk-ops", acceptsRuntime: true },
+  { name: "sdtk-code", kitPkg: "sdtk-code-kit", binName: "sdtk-code", acceptsRuntime: true },
+  { name: "sdtk-design", kitPkg: "sdtk-design-kit", binName: "sdtk-design", acceptsRuntime: false },
+  { name: "sdtk-wiki", kitPkg: "sdtk-wiki-kit", binName: "sdtk-wiki", acceptsRuntime: false },
+]);
+
+// Mirrors sdtk-{spec,ops,code} scope.js: claude defaults to project, codex to user.
+// Used only for the honest scope label in the summary; the orchestrator forwards
+// --runtime-scope only when the user supplies it, so each kit applies this same
+// default independently.
+function defaultScope(runtime) {
+  return runtime === "claude" ? "project" : "user";
+}
+
+class ToolkitResolveError extends Error {
+  constructor(kitPkg) {
+    super(`Toolkit '${kitPkg}' could not be resolved. Is it installed as a dependency of sdtk-kit?`);
+    this.name = "ToolkitResolveError";
+    this.kitPkg = kitPkg;
+    this.exitCode = 4;
+  }
+}
+
+// Resolve a toolkit's executable bin via its package.json `bin` map (drift-safe).
+// Default `deps.resolveBin`. Throws ToolkitResolveError when the kit or its bin
+// entry cannot be found.
+function resolveToolkitBin(kitPkg, binName) {
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${kitPkg}/package.json`);
+  } catch (err) {
+    throw new ToolkitResolveError(kitPkg);
+  }
+  // eslint-disable-next-line global-require
+  const pkg = require(pkgJsonPath);
+  const binField = pkg.bin;
+  let rel;
+  if (typeof binField === "string") {
+    rel = binField;
+  } else if (binField && typeof binField === "object") {
+    rel = binField[binName] || Object.values(binField)[0];
+  }
+  if (!rel) {
+    throw new ToolkitResolveError(kitPkg);
+  }
+  return path.resolve(path.dirname(pkgJsonPath), rel);
+}
+
+// Default `deps.powershellCheck`. Single pre-flight availability probe mirroring
+// sdtk-code/src/lib/powershell.js resolution (win32 → powershell.exe, else pwsh).
+// Runs a no-op command; returns { ok, exe } and never throws.
+function checkPowerShellAvailable(spawnSync) {
+  const exe = process.platform === "win32" ? "powershell.exe" : "pwsh";
+  try {
+    const res = spawnSync(
+      exe,
+      ["-NoProfile", "-NonInteractive", "-Command", "$null"],
+      { stdio: "ignore" }
+    );
+    if (res && res.error && res.error.code === "ENOENT") {
+      return { ok: false, exe };
+    }
+    return { ok: true, exe };
+  } catch (err) {
+    return { ok: false, exe };
+  }
+}
+
+// Build the forwarded `init` flag args for one toolkit (no leading "init").
+// Runtime kits get --runtime (+ runtime-scope / skip-runtime-assets); non-runtime
+// kits receive only the accepted subset.
+function buildInitArgs(toolkit, opts) {
+  const args = [];
+  if (toolkit.acceptsRuntime) {
+    args.push("--runtime", opts.runtime);
+    if (opts.runtimeScope) {
+      args.push("--runtime-scope", opts.runtimeScope);
+    }
+  }
+  if (opts.projectPath) {
+    args.push("--project-path", opts.projectPath);
+  }
+  if (opts.force) {
+    args.push("--force");
+  }
+  if (toolkit.acceptsRuntime && opts.skipRuntimeAssets) {
+    args.push("--skip-runtime-assets");
+  }
+  if (opts.verbose) {
+    args.push("--verbose");
+  }
+  return args;
+}
+
+function normalizeExitCode(res) {
+  if (res && typeof res.status === "number") {
+    return res.status;
+  }
+  if (res && typeof res.exitCode === "number") {
+    return res.exitCode;
+  }
+  // Spawn failure (e.g. error without numeric status) → non-zero.
+  return 1;
+}
+
+// Render the final per-toolkit summary table (spec §5). Pure.
+function renderSummary(results, opts, scopeLabel) {
+  const rows = results.map((r) => {
+    const runtimeCol = r.acceptsRuntime ? opts.runtime : "-";
+    const scopeCol = r.acceptsRuntime ? scopeLabel : "-";
+    return { toolkit: r.name, runtime: runtimeCol, scope: scopeCol, status: r.statusLabel || r.status };
+  });
+  const headers = { toolkit: "toolkit", runtime: "runtime", scope: "scope", status: "status" };
+  const width = (key) =>
+    Math.max(headers[key].length, ...rows.map((row) => String(row[key]).length));
+  const w = {
+    toolkit: width("toolkit"),
+    runtime: width("runtime"),
+    scope: width("scope"),
+    status: width("status"),
+  };
+  const pad = (val, key) => String(val).padEnd(w[key]);
+  const line = (row) =>
+    `  ${pad(row.toolkit, "toolkit")}  ${pad(row.runtime, "runtime")}  ${pad(row.scope, "scope")}  ${pad(
+      row.status,
+      "status"
+    )}`.replace(/\s+$/, "");
+  const out = ["Summary", line(headers)];
+  for (const row of rows) {
+    out.push(line(row));
+  }
+  return out.join("\n");
+}
+
+// Core orchestrator. `deps` = { spawn, resolveBin, powershellCheck, log }.
+//   spawn(binPath, argv, toolkit) → { status|exitCode, stderr? }
+//   resolveBin(kitPkg, binName)   → absolute bin path (throws ToolkitResolveError)
+//   powershellCheck()             → { ok, exe }
+//   log(line)                     → progress/summary sink
+// Returns { exitCode, results }. Never writes files / opens sockets itself.
+function runUnifiedInit(opts, deps) {
+  const spawn = deps.spawn;
+  const resolveBin = deps.resolveBin || resolveToolkitBin;
+  const powershellCheck = deps.powershellCheck;
+  const log = deps.log || (() => {});
+
+  // 1. Required, validated --runtime (no spawns on failure). Exit 2.
+  if (!opts.runtime || !VALID_RUNTIMES.includes(opts.runtime)) {
+    log(`Error: --runtime is required and must be one of: ${VALID_RUNTIMES.join(", ")}.`);
+    return { exitCode: 2, results: [] };
+  }
+
+  // 2. Single PowerShell pre-flight, fail-closed (no spawns on failure). Exit 3.
+  const ps = powershellCheck();
+  if (!ps || !ps.ok) {
+    const exe = (ps && ps.exe) || "pwsh";
+    log(
+      `Error: PowerShell not found (tried: ${exe}). All runtime toolkit inits require ` +
+        "PowerShell. Install PowerShell and ensure it is on PATH, then retry."
+    );
+    return { exitCode: 3, results: [] };
+  }
+
+  const scopeLabel = opts.runtimeScope || defaultScope(opts.runtime);
+  log(`SDTK unified init — runtime: ${opts.runtime}, scope: ${scopeLabel}`);
+
+  const results = [];
+  let firstFailure = 0;
+  const total = TOOLKITS.length;
+
+  for (let i = 0; i < total; i += 1) {
+    const toolkit = TOOLKITS[i];
+    const idx = `[${i + 1}/${total}]`;
+    const suffix = toolkit.acceptsRuntime ? "" : "   (not runtime-aware)";
+
+    let binPath;
+    try {
+      binPath = resolveBin(toolkit.kitPkg, toolkit.binName);
+    } catch (err) {
+      const code = typeof err.exitCode === "number" ? err.exitCode : 4;
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "FAILED",
+        statusLabel: `FAILED (kit '${toolkit.kitPkg}' not found)`,
+        exitCode: code,
+      });
+      log(`  ${idx} ${toolkit.name} … FAILED — kit '${toolkit.kitPkg}' not resolvable`);
+      if (!firstFailure) {
+        firstFailure = code;
+      }
+      if (!opts.keepGoing) {
+        break;
+      }
+      continue;
+    }
+
+    const argv = ["init", ...buildInitArgs(toolkit, opts)];
+    const res = spawn(binPath, argv, toolkit);
+    const code = normalizeExitCode(res);
+
+    if (code === 0) {
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "OK",
+        exitCode: 0,
+      });
+      log(`  ${idx} ${toolkit.name} … OK${suffix}`);
+    } else {
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "FAILED",
+        statusLabel: `FAILED (exit ${code})`,
+        exitCode: code,
+      });
+      log(`  ${idx} ${toolkit.name} … FAILED (exit ${code})`);
+      if (res && res.stderr) {
+        log(String(res.stderr).trimEnd());
+      }
+      if (!firstFailure) {
+        firstFailure = code;
+      }
+      if (!opts.keepGoing) {
+        break;
+      }
+    }
+  }
+
+  log("");
+  log(renderSummary(results, opts, scopeLabel));
+  const exitCode = firstFailure || 0;
+  if (exitCode === 0) {
+    log(`All toolkits initialised for the ${opts.runtime} runtime.`);
+  }
+  return { exitCode, results };
+}
+
+module.exports = {
+  VALID_RUNTIMES,
+  TOOLKITS,
+  ToolkitResolveError,
+  defaultScope,
+  resolveToolkitBin,
+  checkPowerShellAvailable,
+  buildInitArgs,
+  renderSummary,
+  runUnifiedInit,
+};