sdtk-kit 1.2.0 → 1.3.1

package/scripts/unified-init.test.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+"use strict";
+
+// Offline unit tests for the unified-init orchestrator (BK-268).
+// No real PowerShell, no network, no child processes — every effectful dep
+// (spawn / resolveBin / powershellCheck / log) is injected as a spy/stub.
+
+const assert = require("assert");
+const {
+  runUnifiedInit,
+  buildInitArgs,
+  TOOLKITS,
+  ToolkitResolveError,
+} = require("../src/lib/unified-init");
+const { parseFlags, buildOpts } = require("../src/commands/init");
+
+// spec/ops/code own the PowerShell runtime-asset payload (install.ps1) and so
+// also accept --skip-runtime-assets. sdtk-design is runtime-aware (places the
+// design-prototype skill under .claude/.codex) but does NOT take that flag.
+const ASSET_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code"];
+const RUNTIME_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code", "sdtk-design"];
+const NON_RUNTIME_KITS = ["sdtk-wiki"];
+
+// Build an injected deps object with a recording spawn spy.
+// `failures` maps toolkit name → exit code to return (default 0).
+// `unresolvable` is a Set of kit package names that resolveBin should reject.
+function makeDeps({ failures = {}, unresolvable = new Set(), psOk = true } = {}) {
+  const spawnCalls = [];
+  const resolveCalls = [];
+  const logs = [];
+  return {
+    spawnCalls,
+    resolveCalls,
+    logs,
+    deps: {
+      spawn(binPath, argv, toolkit) {
+        spawnCalls.push({ binPath, argv, toolkit: toolkit.name });
+        const code = failures[toolkit.name] || 0;
+        return { status: code, stderr: code ? `stub stderr for ${toolkit.name}` : "" };
+      },
+      resolveBin(kitPkg, binName) {
+        resolveCalls.push(kitPkg);
+        if (unresolvable.has(kitPkg)) {
+          throw new ToolkitResolveError(kitPkg);
+        }
+        return `/stub/node_modules/${kitPkg}/bin/${binName}.js`;
+      },
+      powershellCheck() {
+        return { ok: psOk, exe: "pwsh" };
+      },
+      log(line) {
+        logs.push(line);
+      },
+    },
+  };
+}
+
+// Pull the argv recorded for one toolkit's spawn.
+function argvFor(spawnCalls, name) {
+  const call = spawnCalls.find((c) => c.toolkit === name);
+  return call ? call.argv : null;
+}
+
+const tests = [];
+function test(name, fn) {
+  tests.push({ name, fn });
+}
+
+// ── T1 — runtime claude forwards correctly to runtime kits ──────────────────
+test("T1 runtime=claude spawns spec/ops/code with init --runtime claude", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 0);
+  for (const kit of RUNTIME_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(argv, ["init", "--runtime", "claude"], `${kit} argv`);
+  }
+});
+
+// ── T2 — runtime codex ──────────────────────────────────────────────────────
+test("T2 runtime=codex forwards --runtime codex", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "codex" }, h.deps);
+  assert.strictEqual(exitCode, 0);
+  for (const kit of RUNTIME_KITS) {
+    assert.deepStrictEqual(argvFor(h.spawnCalls, kit), ["init", "--runtime", "codex"]);
+  }
+});
+
+// ── T3 — flag forwarding (runtime subset vs full) ───────────────────────────
+test("T3 forwards shared flags to runtime kits; only subset to design/wiki", () => {
+  const h = makeDeps();
+  const opts = {
+    runtime: "claude",
+    runtimeScope: "user",
+    projectPath: "/tmp/proj",
+    force: true,
+    skipRuntimeAssets: true,
+    verbose: true,
+  };
+  runUnifiedInit(opts, h.deps);
+
+  for (const kit of ASSET_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(
+      argv,
+      [
+        "init",
+        "--runtime",
+        "claude",
+        "--runtime-scope",
+        "user",
+        "--project-path",
+        "/tmp/proj",
+        "--force",
+        "--skip-runtime-assets",
+        "--verbose",
+      ],
+      `${kit} full forward`
+    );
+  }
+  // design is runtime-aware (gets --runtime/--runtime-scope) but owns no
+  // PowerShell payload, so it must NOT receive --skip-runtime-assets.
+  {
+    const argv = argvFor(h.spawnCalls, "sdtk-design");
+    assert.deepStrictEqual(
+      argv,
+      [
+        "init",
+        "--runtime",
+        "claude",
+        "--runtime-scope",
+        "user",
+        "--project-path",
+        "/tmp/proj",
+        "--force",
+        "--verbose",
+      ],
+      "sdtk-design runtime-aware forward (no --skip-runtime-assets)"
+    );
+    assert.ok(!argv.includes("--skip-runtime-assets"), "design must not get --skip-runtime-assets");
+  }
+  for (const kit of NON_RUNTIME_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(
+      argv,
+      ["init", "--project-path", "/tmp/proj", "--force", "--verbose"],
+      `${kit} subset`
+    );
+    assert.ok(!argv.includes("--runtime"), `${kit} must not get --runtime`);
+    assert.ok(!argv.includes("--runtime-scope"), `${kit} must not get --runtime-scope`);
+    assert.ok(!argv.includes("--skip-runtime-assets"), `${kit} must not get --skip-runtime-assets`);
+  }
+});
+
+// ── T4 — missing/invalid runtime → exit 2, zero spawns ──────────────────────
+test("T4 missing runtime → exit 2, no spawns", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({}, h.deps);
+  assert.strictEqual(exitCode, 2);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+test("T4b invalid runtime → exit 2, no spawns", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "bogus" }, h.deps);
+  assert.strictEqual(exitCode, 2);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+
+// ── T5 — PowerShell missing → exit 3, zero spawns ───────────────────────────
+test("T5 powershell missing → exit 3, no spawns", () => {
+  const h = makeDeps({ psOk: false });
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 3);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+
+// ── T6 — order spec → ops → code → design → wiki ────────────────────────────
+test("T6 runs all five in registry order", () => {
+  const h = makeDeps();
+  runUnifiedInit({ runtime: "claude" }, h.deps);
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, [
+    "sdtk-spec",
+    "sdtk-ops",
+    "sdtk-code",
+    "sdtk-design",
+    "sdtk-wiki",
+  ]);
+});
+
+// ── T7 — fail-fast default ──────────────────────────────────────────────────
+test("T7 fail-fast: middle failure stops subsequent toolkits, exit = child code", () => {
+  const h = makeDeps({ failures: { "sdtk-code": 7 } });
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 7);
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, ["sdtk-spec", "sdtk-ops", "sdtk-code"]);
+  assert.ok(!order.includes("sdtk-design"), "design must not be spawned after fail");
+  assert.ok(!order.includes("sdtk-wiki"), "wiki must not be spawned after fail");
+});
+
+// ── T8 — --keep-going ───────────────────────────────────────────────────────
+test("T8 keep-going: failure does not stop the rest; aggregate exit non-zero", () => {
+  const h = makeDeps({ failures: { "sdtk-code": 5 } });
+  const { exitCode, results } = runUnifiedInit({ runtime: "claude", keepGoing: true }, h.deps);
+  assert.strictEqual(exitCode, 5);
+  assert.strictEqual(h.spawnCalls.length, 5);
+  const failed = results.find((r) => r.name === "sdtk-code");
+  assert.strictEqual(failed.status, "FAILED");
+  const wiki = results.find((r) => r.name === "sdtk-wiki");
+  assert.strictEqual(wiki.status, "OK");
+});
+
+// ── T9 — unresolvable kit → exit 4 naming the kit ───────────────────────────
+test("T9 unresolvable kit → exit 4, names the kit, fail-fast no spawn", () => {
+  const h = makeDeps({ unresolvable: new Set(["sdtk-spec-kit"]) });
+  const { exitCode, results } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 4);
+  assert.strictEqual(h.spawnCalls.length, 0, "no spawns once first kit unresolvable (fail-fast)");
+  assert.ok(results[0].statusLabel.includes("sdtk-spec-kit"), "kit named in status");
+});
+test("T9b unresolvable kit with --keep-going continues, exit 4", () => {
+  const h = makeDeps({ unresolvable: new Set(["sdtk-ops-kit"]) });
+  const { exitCode } = runUnifiedInit({ runtime: "claude", keepGoing: true }, h.deps);
+  assert.strictEqual(exitCode, 4);
+  // spec + code + design + wiki spawn; ops is skipped (unresolvable)
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, ["sdtk-spec", "sdtk-code", "sdtk-design", "sdtk-wiki"]);
+});
+
+// ── T10 — orchestrator only touches injected deps (no real fs/network/spawn) ─
+test("T10 orchestrator uses only injected deps (no real host access)", () => {
+  const h = makeDeps();
+  // Spy spawn/resolveBin do no real I/O. A successful run that records exactly
+  // the expected spy invocations proves the orchestrator never bypassed the seam.
+  runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(h.spawnCalls.length, 5, "all process work went through injected spawn");
+  assert.deepStrictEqual(h.resolveCalls, [
+    "sdtk-spec-kit",
+    "sdtk-ops-kit",
+    "sdtk-code-kit",
+    "sdtk-design-kit",
+    "sdtk-wiki-kit",
+  ]);
+  // buildInitArgs is pure: same input → same output, no side effects.
+  const a = buildInitArgs(TOOLKITS[0], { runtime: "claude" });
+  const b = buildInitArgs(TOOLKITS[0], { runtime: "claude" });
+  assert.deepStrictEqual(a, b);
+});
+
+// ── T11 — --global shorthand maps to runtime-scope user ─────────────────────
+test("T11 --global parses and maps to runtimeScope=user", () => {
+  const flags = parseFlags(["--runtime", "claude", "--global"]);
+  assert.strictEqual(flags.global, true);
+  const opts = buildOpts(flags);
+  assert.strictEqual(opts.runtimeScope, "user");
+});
+test("T11b explicit --runtime-scope wins over --global", () => {
+  const opts = buildOpts(parseFlags(["--runtime", "codex", "--global", "--runtime-scope", "project"]));
+  assert.strictEqual(opts.runtimeScope, "project");
+});
+test("T11c no scope flag leaves runtimeScope undefined (kits apply their default)", () => {
+  const opts = buildOpts(parseFlags(["--runtime", "codex"]));
+  assert.strictEqual(opts.runtimeScope, undefined);
+});
+test("T11d --global forwards --runtime-scope user to design (runtime-aware)", () => {
+  const h = makeDeps();
+  runUnifiedInit(buildOpts(parseFlags(["--runtime", "claude", "--global"])), h.deps);
+  assert.deepStrictEqual(
+    argvFor(h.spawnCalls, "sdtk-design"),
+    ["init", "--runtime", "claude", "--runtime-scope", "user"]
+  );
+});
+
+// ── runner ──────────────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+for (const t of tests) {
+  try {
+    t.fn();
+    passed += 1;
+    console.log(`  ok  ${t.name}`);
+  } catch (err) {
+    failed += 1;
+    console.error(`FAIL  ${t.name}`);
+    console.error(`      ${err.message}`);
+  }
+}
+console.log("");
+console.log(`unified-init tests: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/src/commands/init.js

@@ -0,0 +1,106 @@
+"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",
+  global: "boolean",
+  "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;
+}
+
+// Pure flags → orchestrator opts mapping (exported for unit testing).
+// --global is a shorthand for --runtime-scope user (installs skills under the
+// user/global runtime home: ~/.claude/skills or ~/.codex/skills). An explicit
+// --runtime-scope wins if both are supplied.
+function buildOpts(flags) {
+  const runtimeScope = flags["runtime-scope"] || (flags.global ? "user" : undefined);
+  return {
+    runtime: flags.runtime,
+    runtimeScope,
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+    skipRuntimeAssets: Boolean(flags["skip-runtime-assets"]),
+    keepGoing: Boolean(flags["keep-going"]),
+    verbose: Boolean(flags.verbose),
+  };
+}
+
+function cmdInit(args) {
+  let flags;
+  try {
+    flags = parseFlags(args);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return 2;
+  }
+
+  const opts = buildOpts(flags);
+
+  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,
+  buildOpts,
+};

package/src/lib/unified-init.js

@@ -0,0 +1,280 @@
+"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` toolkits receive --runtime (+ --runtime-scope) so they place
+// their skills under the correct runtime home (.claude vs .codex). Of those,
+// only `installsRuntimeAssets` toolkits (spec/ops/code, which run install.ps1)
+// also accept --skip-runtime-assets. sdtk-design is runtime-aware (it installs
+// the design-prototype skill into the matching skills dir) but does not own the
+// PowerShell runtime-asset payload. sdtk-wiki is not runtime-aware (it installs
+// no skills) and receives only --project-path / --force / --verbose.
+const TOOLKITS = Object.freeze([
+  { name: "sdtk-spec", kitPkg: "sdtk-spec-kit", binName: "sdtk-spec", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-ops", kitPkg: "sdtk-ops-kit", binName: "sdtk-ops", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-code", kitPkg: "sdtk-code-kit", binName: "sdtk-code", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-design", kitPkg: "sdtk-design-kit", binName: "sdtk-design", acceptsRuntime: true, installsRuntimeAssets: false },
+  { name: "sdtk-wiki", kitPkg: "sdtk-wiki-kit", binName: "sdtk-wiki", acceptsRuntime: false, installsRuntimeAssets: 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.installsRuntimeAssets && 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,
+};