dw-sdlc 0.2.0 → 0.3.0

package/dist/agentic-config.js

@@ -1,5 +1,5 @@
 // Reads what a repository declares for an agent: the committed config, the machine's local layer over it,
-// and what the repository implies; an invalid layer is dropped whole. The guardrails plugin's
+// and what the repository implies; an invalid layer is dropped whole. The sdlc plugin's
 // `hooks/config.jq` is the same merge for the guards; this file is the reference, and the tests run both.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";

package/dist/commands/doctor.d.ts

@@ -40,9 +40,11 @@ export type Inputs = {
 };
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
-/** The marketplace Claude Code registers this repository under, and the plugin id inside it. */
+/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
 export declare const MARKETPLACE = "dw-sdlc";
-export declare const PLUGIN_ID = "guardrails@dw-sdlc";
+export declare const PLUGIN = "sdlc";
+export declare const PLUGIN_ID = "sdlc@dw-sdlc";
+export declare const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
 export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;
@@ -53,5 +55,5 @@ export declare function rtkConfigPath(home: string, platform?: string, env?: Rec
 export declare function rtkExcludes(toml: string | undefined): string[];
 export declare function diagnose(inputs: Inputs): Check[];
 export declare function render(checks: Check[]): string;
-export declare const summary = "one PASS / WARN / FAIL line per machine check the guardrails rely on";
+export declare const summary = "one PASS / WARN / FAIL line per machine check the sdlc plugin relies on";
 export declare function run(argv: string[]): number;

package/dist/commands/doctor.js

@@ -1,19 +1,22 @@
-// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the guardrails rely on, for the
+// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the sdlc plugin relies on, for the
 // repository holding --root and the user's home; it installs nothing. FAIL is a guard that does not guard
-// (no jq, plugin absent or disabled, an invalid config), WARN a layer missing or loose, INFO one that does not apply.
+// (no jq, plugin absent or disabled, an invalid config), WARN a layer missing, loose or out of step, INFO one that does not apply.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { findRepository, resolveConfig } from "../agentic-config.js";
+import { EXACT_VERSION, parseCatalog, parsePins } from "../pins.js";
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export function claudeConfigDir(env, home) {
     return env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 }
-/** The marketplace Claude Code registers this repository under, and the plugin id inside it. */
+/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
 export const MARKETPLACE = "dw-sdlc";
-export const PLUGIN_ID = `guardrails@${MARKETPLACE}`;
+export const PLUGIN = "sdlc";
+export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+export const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export const RTK_FIND_EXEC_FIXED = "0.46.0";
 export const PNPM_MINIMUM_RELEASE_AGE = 10080;
@@ -64,7 +67,7 @@ function liveCheckout(probe, claude) {
 function pluginOrigin(probe, claude, installPath) {
     const checkout = liveCheckout(probe, claude);
     if (checkout !== undefined) {
-        return `runs live from ${checkout}/plugins/guardrails; a change there is in the next session`;
+        return `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
     }
     return `installed at ${installPath}; a change reaches it through claude plugin update`;
 }
@@ -72,7 +75,7 @@ function pluginOrigin(probe, claude, installPath) {
 function runningPluginRoot(probe, claude) {
     const checkout = liveCheckout(probe, claude);
     if (checkout !== undefined) {
-        return join(checkout, "plugins", "guardrails");
+        return join(checkout, "plugins", PLUGIN);
     }
     const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
     const list = status === 0 ? parseJson(stdout) : undefined;
@@ -110,6 +113,57 @@ function checkPlugin(probe, claude) {
         detail: `${version} enabled; ${pluginOrigin(probe, claude, String(entry.installPath ?? ""))}`
     };
 }
+/** The `version` of the package.json in `dir`, or undefined when there is none. */
+function manifestVersion(probe, dir) {
+    const manifest = parseJson(probe.read(join(dir, "package.json")));
+    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
+}
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+function checkPackage(probe, claude, root) {
+    const name = "package";
+    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
+    if (root === undefined || manifest === undefined) {
+        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
+    }
+    let spec;
+    try {
+        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
+    }
+    catch {
+        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
+    }
+    if (spec === undefined) {
+        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
+    }
+    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
+    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
+    if (pinned === undefined) {
+        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
+    }
+    const plugin = runningPluginRoot(probe, claude);
+    if (plugin === undefined) {
+        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
+    }
+    const linked = manifestVersion(probe, join(plugin, PACKAGE));
+    if (linked === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    if (linked !== pinned) {
+        const remedy = versionBefore(linked, pinned)
+            ? `claude plugin update ${PLUGIN_ID}`
+            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
+        };
+    }
+    return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
+}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -286,6 +340,7 @@ export function diagnose(inputs) {
     return [
         checkJq(probe),
         checkPlugin(probe, claude),
+        checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),
@@ -296,11 +351,11 @@ export function diagnose(inputs) {
 export function render(checks) {
     return checks.map((check) => `${check.level.padEnd(5)} ${check.name.padEnd(17)} ${check.detail}`).join("\n");
 }
-export const summary = "one PASS / WARN / FAIL line per machine check the guardrails rely on";
+export const summary = "one PASS / WARN / FAIL line per machine check the sdlc plugin relies on";
 const USAGE = `Usage: dw-sdlc doctor [--root <dir>] [--home <dir>]
   or:  pnpm guardrails:doctor [--root <dir>] [--home <dir>], in a checkout of dw-sdlc
 
-One PASS / WARN / FAIL line per machine check the guardrails rely on; read-only. Exit 1 when any
+One PASS / WARN / FAIL line per machine check the sdlc plugin relies on; read-only. Exit 1 when any
 check fails. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
 --home reads <home>/.claude.`;
 function repositoryConfig(root) {

package/dist/commands/references-setup.js

@@ -25,7 +25,7 @@ const IGNORED = "references/*";
 const TRACKED = ["!references/AGENTS.md", "!references/CLAUDE.md"];
 /** Lines that ignore references/ itself: git never looks inside it, so no exception tracks the Router. */
 const WHOLE = new Set(["references", "references/", "/references", "/references/"]);
-const IGNORE_COMMENT = "# References are cloned on each machine by the references plugin; only the Router is tracked.";
+const IGNORE_COMMENT = "# References are cloned on each machine by the sdlc plugin; only the Router is tracked.";
 export const summary = "set a repository up to declare References: the Router, its table and the ignore rules";
 const USAGE = `Usage: dw-sdlc references setup [--root <dir>] [--dry-run | --check]
   or:  pnpm references:setup with the same flags, in a checkout of dw-sdlc

package/dist/commands/setup.js

@@ -1,4 +1,4 @@
-// `dw-sdlc setup` sets a repository and this machine up for the guardrails plugin: the four files its USAGE
+// `dw-sdlc setup` sets a repository and this machine up for the sdlc plugin: the four files its USAGE
 // names, each written only when its content would change, so a run is safe to repeat. Existing content is
 // merged, never replaced: other keys stay, and a settings file that is not JSON is refused.
 import { spawnSync } from "node:child_process";
@@ -35,7 +35,7 @@ function isCommitOnProtected(value) {
 }
 /** Where Claude Code registers the plugin: the marketplace name and the plugin's name inside it. */
 const MARKETPLACE = "dw-sdlc";
-const PLUGIN = "guardrails";
+const PLUGIN = "sdlc";
 /** The plugin's link to the dw-sdlc package, which carries the schema. */
 const PACKAGE_LINK = "dw-sdlc";
 function isObject(value) {

package/dist/pins.d.ts

@@ -1,5 +1,7 @@
 /** Versions by package name: what package.json pins, or what a catalog lists. */
 export type Pins = Record<string, string>;
+/** A pin that names one version: `x.y.z`, a pre-release tag allowed. */
+export declare const EXACT_VERSION: RegExp;
 /**
  * The default catalog in pnpm-workspace.yaml's text: each `name: version` line of its top-level
  * `catalog:` block, a comment after the key allowed. Without the block, it is empty.

package/dist/pins.js

@@ -3,7 +3,8 @@
 // ref without `{name}` reads neither file, so a broken manifest fails only the References that name one.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+/** A pin that names one version: `x.y.z`, a pre-release tag allowed. */
+export const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
 /** The two ways a pin names the default catalog: by its name, or by pnpm's shorthand. */
 const DEFAULT_CATALOG = new Set(["catalog:", "catalog:default"]);
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {

package/templates/router.md

@@ -28,7 +28,7 @@ No Reference is declared yet: `/sdlc-references-add <repository>` adds one.
   `AGENTS.md`. It describes _that_ repository; `claudeMdExcludes` in `.claude/settings.json` keeps
   Claude Code from loading them.
 - **Missing is normal.** CI, a fresh clone and a new worktree have none of them until a local Claude
-  Code session starts with the references plugin enabled, which syncs them. A directory that is
+  Code session starts with the sdlc plugin enabled, which syncs them. A directory that is
   absent is not a broken link, and neither is a path its entry's `skip` leaves out.
 - **A starting point, not the whole field.** The list is hand-picked, and each clone is its ref at
   the last sync. Research into a feature or an approach reads the matching entries first, then looks