sdtk-kit 1.2.0 → 1.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 SDTK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 SDTK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,135 +1,190 @@
-# sdtk-kit
-
-> Install all five SDTK toolkits in one command.
-
-```bash
-npm install -g sdtk-kit
-```
-
-After install, all five SDTK CLI tools are available globally:
-
-| CLI           | Toolkit        | Purpose                                          |
-|---------------|----------------|--------------------------------------------------|
-| `sdtk-spec`   | SDTK-SPEC      | Spec-first SDLC: PM → BA → ARCH → DEV → QA     |
-| `sdtk-design` | SDTK-DESIGN    | MVP design: idea → prototype → handoff           |
-| `sdtk-code`   | SDTK-CODE      | Governed coding: handoff → PR with review gates  |
-| `sdtk-ops`    | SDTK-OPS       | Operations: deploy → smoke → sign-off            |
-| `sdtk-wiki`   | SDTK-WIKI      | Local second brain: your project memory          |
-
-## Quick start
-
-```bash
-# Initialize the spec toolkit in your project
-sdtk-spec init --runtime claude   # or --runtime codex
-
-# Generate a 17-file spec scaffold for your first feature
-sdtk-spec generate --feature-key MY_FEATURE
-```
-
-## Unified vs standalone install
-
-You have two install options:
-
-**Option 1 — Install everything at once (recommended for new projects)**
-
-```bash
-npm install -g sdtk-kit
-```
-
-npm installs all five sub-toolkits as dependencies. All CLI binaries land on PATH in one step.
-
-**Option 2 — Install individual toolkits**
-
-```bash
-npm install -g sdtk-spec-kit    # spec / planning
-npm install -g sdtk-design-kit  # design
-npm install -g sdtk-code-kit    # coding
-npm install -g sdtk-ops-kit     # operations
-npm install -g sdtk-wiki-kit    # local second brain
-```
-
-Use Option 2 if you only need one or two toolkits, or if you want granular version control per toolkit.
-
-Both options are permanently supported. `sdtk-kit` does not replace the standalone packages.
-
-## How the unified CLI works (maintainer note)
-
-`sdtk-kit` declares the five sub-toolkits as dependencies AND ships thin bin
-shims (`bin/sdtk-*.js`) that re-export each sub-package's CLI. This is required
-because `npm install -g <pkg>` only links the bin entries of the top-level
-package, never of its dependencies. A pure deps-only meta-package would install
-the sub-toolkits but leave zero CLIs on PATH.
-
-Do not remove the `bin` field or the `bin/` shims — they are the mechanism that
-puts `sdtk-spec`, `sdtk-code`, `sdtk-ops`, `sdtk-design`, and `sdtk-wiki` on PATH
-after a global install.
-
-## Version pinning model
-
-`sdtk-kit` uses caret-range dependencies (`^X.Y.Z`) on each sub-toolkit. This means:
-
-- **Patch and minor updates** of sub-toolkits are picked up automatically when you run `npm update -g sdtk-kit`.
-- **Major version bumps** in any sub-toolkit require a coordinated `sdtk-kit` major-bump and re-publish.
-- If you need exact version control per toolkit, use standalone packages instead.
-
-Current pinned versions (as of sdtk-kit v1.0.0):
-
-| Package          | Version |
-|------------------|---------|
-| sdtk-spec-kit    | ^0.4.7  |
-| sdtk-code-kit    | ^0.1.3  |
-| sdtk-ops-kit     | ^0.2.4  |
-| sdtk-design-kit  | ^0.3.0  |
-| sdtk-wiki-kit    | ^0.1.4  |
-
-## Updating
-
-```bash
-npm update -g sdtk-kit
-```
-
-This updates all sub-toolkits within their caret ranges.
-
-## Uninstalling
-
-To remove sdtk-kit and its sub-toolkits:
-
-```bash
-npm uninstall -g sdtk-kit
-```
-
-Note: `npm uninstall` removes the package and its transitive dependencies. If you had any sub-toolkits installed standalone _before_ installing sdtk-kit, npm may or may not remove them depending on your npm version. Run `npm uninstall -g sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-design-kit sdtk-wiki-kit` to be sure.
-
-## Troubleshooting
-
-**Command not found after install**
-
-Re-open your terminal. npm global installs require a new shell session on some systems.
-
-Check your global prefix:
-
-```bash
-npm config get prefix
-```
-
-Ensure `<prefix>/bin` is in `PATH`.
-
-**Windows PATH issues**
-
-On Windows, npm global binaries land in `%APPDATA%\npm`. Make sure this is in your `PATH`. Run `npm config get prefix` to confirm the location.
-
-**Binary collision**
-
-If you have standalone sub-toolkits installed at different versions than what `sdtk-kit` pins, `npm install -g sdtk-kit` will upgrade them to the pinned versions. To keep a standalone version pinned, install it standalone after sdtk-kit:
-
-```bash
-npm install -g sdtk-kit
-npm install -g sdtk-spec-kit@0.4.6  # pin to an older version
-```
-
-## Links
-
-- Docs: [https://sdtk.dev](https://sdtk.dev)
-- Source: [https://github.com/codexsdtk/sdtk-toolkit](https://github.com/codexsdtk/sdtk-toolkit)
-- Issues: [https://github.com/codexsdtk/sdtk-toolkit/issues](https://github.com/codexsdtk/sdtk-toolkit/issues)
-- License: MIT
+# sdtk-kit
+
+> Install all five SDTK toolkits in one command.
+
+```bash
+npm install -g sdtk-kit
+```
+
+After install, all five SDTK CLI tools — plus the unified `sdtk` orchestrator — are available globally:
+
+| CLI           | Toolkit        | Purpose                                          |
+|---------------|----------------|--------------------------------------------------|
+| `sdtk`        | (all five)     | One-command setup: `sdtk init --runtime <r>`     |
+| `sdtk-spec`   | SDTK-SPEC      | Spec-first SDLC: PM → BA → ARCH → DEV → QA     |
+| `sdtk-design` | SDTK-DESIGN    | MVP design: idea → prototype → handoff           |
+| `sdtk-code`   | SDTK-CODE      | Governed coding: handoff → PR with review gates  |
+| `sdtk-ops`    | SDTK-OPS       | Operations: deploy → smoke → sign-off            |
+| `sdtk-wiki`   | SDTK-WIKI      | Local second brain: your project memory          |
+
+## Quick start
+
+```bash
+# Set up the chosen runtime for the whole suite in one command
+sdtk init --runtime claude   # or --runtime codex
+
+# Generate a 17-file spec scaffold for your first feature
+sdtk-spec generate --feature-key MY_FEATURE
+```
+
+## Unified init: `sdtk init`
+
+`sdtk init --runtime <claude|codex>` initialises **all five toolkits** in one step
+— mirroring how `npm install -g sdtk-kit` installs every toolkit at once. It runs
+each toolkit's own, already-shipped `init` in order:
+
+```
+sdtk-spec → sdtk-ops → sdtk-code   (with --runtime <r>)
+sdtk-design → sdtk-wiki            (their own non-runtime init)
+```
+
+```bash
+sdtk init --runtime claude
+sdtk init --runtime codex --project-path ./my-app
+sdtk init --runtime claude --keep-going    # continue past a failing toolkit
+```
+
+Options: `--runtime <claude|codex>` (required), `--runtime-scope <scope>`,
+`--project-path <path>`, `--force`, `--skip-runtime-assets`, `--keep-going`
+(default is fail-fast — stop at the first failing toolkit), `--verbose`.
+`--runtime`, `--runtime-scope`, and `--skip-runtime-assets` apply to the runtime
+toolkits (spec/ops/code); `sdtk-design` and `sdtk-wiki` receive only
+`--project-path`, `--force`, and `--verbose`.
+
+`sdtk init` is a thin orchestrator: it re-implements no init logic, writes no files
+itself, and runs no PowerShell of its own — every side effect happens inside the
+delegated per-toolkit init. The per-toolkit CLIs remain fully available standalone.
+
+## Unified vs standalone install
+
+You have two install options:
+
+**Option 1 — Install everything at once (recommended for new projects)**
+
+```bash
+npm install -g sdtk-kit
+```
+
+npm installs all five sub-toolkits as dependencies. All CLI binaries land on PATH in one step.
+
+**Option 2 — Install individual toolkits**
+
+```bash
+npm install -g sdtk-spec-kit    # spec / planning
+npm install -g sdtk-design-kit  # design
+npm install -g sdtk-code-kit    # coding
+npm install -g sdtk-ops-kit     # operations
+npm install -g sdtk-wiki-kit    # local second brain
+```
+
+Use Option 2 if you only need one or two toolkits, or if you want granular version control per toolkit.
+
+Both options are permanently supported. `sdtk-kit` does not replace the standalone packages.
+
+## How the unified CLI works (maintainer note)
+
+`sdtk-kit` declares the five sub-toolkits as dependencies AND ships thin bin
+shims (`bin/sdtk-*.js`) that re-export each sub-package's CLI. This is required
+because `npm install -g <pkg>` only links the bin entries of the top-level
+package, never of its dependencies. A pure deps-only meta-package would install
+the sub-toolkits but leave zero CLIs on PATH.
+
+The umbrella also ships its own `sdtk` orchestrator bin (`bin/sdtk.js` + `src/`),
+which delegates `sdtk init` to each sub-toolkit's published bin via subprocess
+(`require.resolve` of the kit's `package.json` `bin` map, spawned with the current
+Node). It adds no new dependency and re-implements no init logic.
+
+Do not remove the `bin` field, the `bin/` shims, or `bin/sdtk.js` + `src/` — they
+are the mechanism that puts `sdtk`, `sdtk-spec`, `sdtk-code`, `sdtk-ops`,
+`sdtk-design`, and `sdtk-wiki` on PATH after a global install.
+
+## Version pinning model
+
+`sdtk-kit` uses caret-range dependencies (`^X.Y.Z`) on each sub-toolkit. This means:
+
+- **Patch and minor updates** of sub-toolkits are picked up automatically when you run `npm update -g sdtk-kit`.
+- **Major version bumps** in any sub-toolkit require a coordinated `sdtk-kit` major-bump and re-publish.
+- If you need exact version control per toolkit, use standalone packages instead.
+
+Current dependency ranges (as of sdtk-kit v1.3.0):
+
+| Package          | Version |
+|------------------|---------|
+| sdtk-spec-kit    | ^0.4.7  |
+| sdtk-code-kit    | ^0.3.0  |
+| sdtk-ops-kit     | ^0.2.4  |
+| sdtk-design-kit  | ^0.3.0  |
+| sdtk-wiki-kit    | ^0.2.0  |
+
+## Updating
+
+```bash
+npm update -g sdtk-kit
+```
+
+This updates all sub-toolkits within their caret ranges.
+
+## Uninstalling
+
+To remove sdtk-kit and its sub-toolkits:
+
+```bash
+npm uninstall -g sdtk-kit
+```
+
+Note: `npm uninstall` removes the package and its transitive dependencies. If you had any sub-toolkits installed standalone _before_ installing sdtk-kit, npm may or may not remove them depending on your npm version. Run `npm uninstall -g sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-design-kit sdtk-wiki-kit` to be sure.
+
+## Troubleshooting
+
+**Command not found after install**
+
+Re-open your terminal. npm global installs require a new shell session on some systems.
+
+Check your global prefix:
+
+```bash
+npm config get prefix
+```
+
+Ensure `<prefix>/bin` is in `PATH`.
+
+**Only three CLIs are visible after installing sdtk-kit**
+
+If `sdtk-spec`, `sdtk-code`, and `sdtk-ops` are visible but `sdtk-design` or `sdtk-wiki` are missing, the usual cause is a stale global install, an old npm prefix on `PATH`, or a shell command cache rather than the current `sdtk-kit` package.
+
+Reset and verify from a fresh shell:
+
+```bash
+npm uninstall -g sdtk-kit sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-design-kit sdtk-wiki-kit
+npm cache verify
+npm install -g sdtk-kit@latest
+hash -r
+command -v sdtk-spec sdtk-code sdtk-ops sdtk-design sdtk-wiki
+sdtk-spec --version
+sdtk-code --version
+sdtk-ops --version
+sdtk-design --version
+sdtk-wiki --version
+```
+
+On Windows PowerShell, close and reopen the terminal after reinstalling, then use `where.exe sdtk-spec`, `where.exe sdtk-design`, and the same `--version` commands.
+
+**Windows PATH issues**
+
+On Windows, npm global binaries land in `%APPDATA%\npm`. Make sure this is in your `PATH`. Run `npm config get prefix` to confirm the location.
+
+**Binary collision**
+
+If you have standalone sub-toolkits installed at different versions than what `sdtk-kit` pins, `npm install -g sdtk-kit` will upgrade them to the pinned versions. To keep a standalone version pinned, install it standalone after sdtk-kit:
+
+```bash
+npm install -g sdtk-kit
+npm install -g sdtk-spec-kit@0.4.6  # pin to an older version
+```
+
+## Links
+
+- Docs: [https://sdtk.dev](https://sdtk.dev)
+- Source: [https://github.com/codexsdtk/sdtk-toolkit](https://github.com/codexsdtk/sdtk-toolkit)
+- Issues: [https://github.com/codexsdtk/sdtk-toolkit/issues](https://github.com/codexsdtk/sdtk-toolkit/issues)
+- License: MIT

package/bin/sdtk-code.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-
-// Bin shim — re-exports the sdtk-code CLI from the sdtk-code-kit dependency.
-// See bin/sdtk-spec.js for the rationale behind these shims.
-require("sdtk-code-kit/bin/sdtk-code.js");
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-code CLI from the sdtk-code-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-code-kit/bin/sdtk-code.js");

package/bin/sdtk-design.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-
-// Bin shim — re-exports the sdtk-design CLI from the sdtk-design-kit dependency.
-// See bin/sdtk-spec.js for the rationale behind these shims.
-require("sdtk-design-kit/bin/sdtk-design.js");
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-design CLI from the sdtk-design-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-design-kit/bin/sdtk-design.js");

package/bin/sdtk-ops.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-
-// Bin shim — re-exports the sdtk-ops CLI from the sdtk-ops-kit dependency.
-// See bin/sdtk-spec.js for the rationale behind these shims.
-require("sdtk-ops-kit/bin/sdtk-ops.js");
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-ops CLI from the sdtk-ops-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-ops-kit/bin/sdtk-ops.js");

package/bin/sdtk-spec.js

@@ -1,12 +1,12 @@
-#!/usr/bin/env node
-"use strict";
-
-// Bin shim — re-exports the sdtk-spec CLI from the sdtk-spec-kit dependency.
-//
-// Why this exists: `npm install -g <pkg>` only links the bin entries of the
-// top-level package, NOT of its dependencies. A pure meta-package (deps only,
-// no bin) therefore installs the sub-packages but leaves no CLI on PATH.
-//
-// Each sub-toolkit CLI reads process.argv directly, so requiring its bin
-// entry here runs it with the real arguments unchanged.
-require("sdtk-spec-kit/bin/sdtk.js");
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-spec CLI from the sdtk-spec-kit dependency.
+//
+// Why this exists: `npm install -g <pkg>` only links the bin entries of the
+// top-level package, NOT of its dependencies. A pure meta-package (deps only,
+// no bin) therefore installs the sub-packages but leaves no CLI on PATH.
+//
+// Each sub-toolkit CLI reads process.argv directly, so requiring its bin
+// entry here runs it with the real arguments unchanged.
+require("sdtk-spec-kit/bin/sdtk.js");

package/bin/sdtk-wiki.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-
-// Bin shim — re-exports the sdtk-wiki CLI from the sdtk-wiki-kit dependency.
-// See bin/sdtk-spec.js for the rationale behind these shims.
-require("sdtk-wiki-kit/bin/sdtk-wiki.js");
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-wiki CLI from the sdtk-wiki-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-wiki-kit/bin/sdtk-wiki.js");

package/bin/sdtk.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict";
+
+// `sdtk` — unified entry point for the SDTK suite (BK-268).
+//
+//   sdtk init --runtime <claude|codex>   one-command setup for all five toolkits
+//   sdtk --help                          top-level help
+//   sdtk --version                       sdtk-kit version + resolved per-kit versions
+//   sdtk                                 no args → help
+//
+// `init` delegates to each toolkit's own shipped init (see src/lib/unified-init.js).
+
+const SUB_KITS = [
+  "sdtk-spec-kit",
+  "sdtk-ops-kit",
+  "sdtk-code-kit",
+  "sdtk-design-kit",
+  "sdtk-wiki-kit",
+];
+
+function helpText() {
+  return [
+    "sdtk — unified SDTK suite CLI",
+    "",
+    "Usage:",
+    "  sdtk init --runtime <claude|codex> [options]   Initialise all five toolkits",
+    "  sdtk --help                                    Show this help",
+    "  sdtk --version                                 Show versions",
+    "",
+    "init options:",
+    "  --runtime <claude|codex>   Required. Runtime to install for spec/ops/code.",
+    "  --runtime-scope <scope>    Optional. Forwarded to the runtime toolkits.",
+    "  --project-path <path>      Optional. Target project directory.",
+    "  --force                    Re-initialise existing assets.",
+    "  --skip-runtime-assets      Skip runtime asset install (runtime toolkits).",
+    "  --keep-going               Continue past a failing toolkit (default: fail-fast).",
+    "  --verbose                  Verbose per-toolkit output.",
+    "",
+    "Runs: sdtk-spec → sdtk-ops → sdtk-code (with --runtime) → sdtk-design → sdtk-wiki",
+    "(sdtk-design and sdtk-wiki run their own non-runtime init).",
+    "",
+    "Standalone per-toolkit CLIs remain available: sdtk-spec, sdtk-ops, sdtk-code,",
+    "sdtk-design, sdtk-wiki.",
+    "",
+    "Docs: https://sdtk.dev",
+  ].join("\n");
+}
+
+function versionText() {
+  // eslint-disable-next-line global-require
+  const self = require("../package.json");
+  const lines = [`sdtk-kit ${self.version}`];
+  for (const kit of SUB_KITS) {
+    let version = "not resolved";
+    try {
+      // eslint-disable-next-line global-require
+      version = require(`${kit}/package.json`).version;
+    } catch (err) {
+      version = "not resolved";
+    }
+    lines.push(`  ${kit.padEnd(15)} ${version}`);
+  }
+  return lines.join("\n");
+}
+
+function main(argv) {
+  const command = argv[0];
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    console.log(helpText());
+    return 0;
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log(versionText());
+    return 0;
+  }
+
+  if (command === "init") {
+    // eslint-disable-next-line global-require
+    const { cmdInit } = require("../src/commands/init");
+    return cmdInit(argv.slice(1));
+  }
+
+  console.error(`sdtk: unknown command '${command}'.`);
+  console.error("Run `sdtk --help` for usage.");
+  return 2;
+}
+
+process.exitCode = main(process.argv.slice(2));