dw-sdlc 0.0.0-stage → 0.1.0

package/dist/commands/gate.js

@@ -0,0 +1,175 @@
+// `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config.
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../checks/check.js";
+import { enabledChecks } from "../checks/index.js";
+import { annotation, failureJson, failureLine } from "../report.js";
+export const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
+const USAGE = `Usage: dw-sdlc gate [--json] [--root <dir>]
+
+Runs the Gate of the repository holding --root (default: the current directory): each Step of
+gate.steps in order from the repository root, its output passed through, stopping at the first that
+fails; then every Check under gate.checks, the run scripts and then the Checks the package ships,
+none stopping the next. Prints one line per failure: the file where there is one, the rule, the
+remedy; under GitHub Actions each line is also a workflow annotation. --json prints one document
+instead and sends the commands' own output to stderr.
+
+Exit 0 when everything passes, 1 when a Step or a Check fails, 2 when the Gate cannot run: an
+invalid config layer, a Step or Check whose command the shell cannot find or execute, or a Check
+missing an input it reads.`;
+const EXIT_CODES = { pass: 0, fail: 1, error: 2 };
+/** What the shell answers for a command it cannot find, and for one it cannot execute. */
+const NOT_RUNNABLE = { 127: "was not found", 126: "could not be executed" };
+const SKIPPED = { status: "skipped", exitCode: null };
+const REMEDIES = {
+    invalidLayer: "fix the file; the Gate runs once every layer is valid",
+    failed: "fix what it printed above",
+    stepNotRunnable: "install the command or fix gate.steps in the agentic config",
+    checkNotRunnable: "install the command or fix gate.checks.run in the agentic config",
+    checkStopped: "fix what stopped it, or report it to dw-sdlc"
+};
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" }, root: { type: "string" } }
+        });
+        return { help: values.help === true, json: values.json === true, root: values.root };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function configFailure({ file, path, message }) {
+    const where = path === "" ? message : `${path}: ${message}`;
+    return { file, rule: "config", message: where, remedy: REMEDIES.invalidLayer };
+}
+/**
+ * Runs `command` through `sh -c` from `root`, stdin closed and stderr passed through; stdout too, or
+ * onto stderr when `--json` keeps stdout for the document. `detail` says what went wrong, when it did.
+ */
+function runCommand(command, root, json) {
+    const result = spawnSync(command, { shell: true, cwd: root, stdio: ["ignore", json ? 2 : "inherit", "inherit"] });
+    if (result.error !== undefined) {
+        return { status: "error", exitCode: null, detail: `could not start: ${result.error.message}` };
+    }
+    if (result.status === 0) {
+        return { status: "pass", exitCode: 0 };
+    }
+    if (result.status === null) {
+        return { status: "fail", exitCode: null, detail: `was stopped by ${result.signal ?? "a signal"}` };
+    }
+    const notRunnable = NOT_RUNNABLE[result.status];
+    if (notRunnable !== undefined) {
+        return { status: "error", exitCode: result.status, detail: `${notRunnable} (exit ${result.status})` };
+    }
+    return { status: "fail", exitCode: result.status, detail: `exited ${result.status}` };
+}
+/** Runs one Check the package ships, its failures named by the Check; one it cannot judge is an error. */
+function runShipped(check, root) {
+    try {
+        const failures = check.run(root).map((finding) => ({ rule: check.name, ...finding }));
+        const status = failures.length === 0 ? "pass" : "fail";
+        return { status, exitCode: EXIT_CODES[status], failures };
+    }
+    catch (error) {
+        const finding = error instanceof CannotRun
+            ? error.finding
+            : {
+                message: `stopped: ${error instanceof Error ? error.message : String(error)}`,
+                remedy: REMEDIES.checkStopped
+            };
+        return { status: "error", exitCode: EXIT_CODES.error, failures: [{ rule: check.name, ...finding }] };
+    }
+}
+function worst(outcomes) {
+    const statuses = new Set(outcomes.map(({ status }) => status));
+    return statuses.has("error") ? "error" : statuses.has("fail") ? "fail" : "pass";
+}
+function runGate(root, json) {
+    const log = json ? process.stderr : process.stdout;
+    const { config, problems } = resolveConfig(root);
+    const gateCommand = config.gate.command ?? null;
+    if (problems.length > 0) {
+        return { status: "error", command: gateCommand, steps: [], checks: [], failures: problems.map(configFailure) };
+    }
+    const failures = [];
+    /** Runs one Step or Check and records its failure under `rule`, if it has one. */
+    const runOne = (command, rule, notRunnable) => {
+        const { detail, ...outcome } = runCommand(command, root, json);
+        if (detail !== undefined) {
+            const remedy = outcome.status === "error" ? notRunnable : REMEDIES.failed;
+            failures.push({ rule, message: `${JSON.stringify(command)} ${detail}`, remedy });
+        }
+        return outcome;
+    };
+    const steps = [];
+    let stopped = false;
+    for (const step of config.gate.steps) {
+        if (stopped) {
+            steps.push({ command: step, ...SKIPPED });
+            continue;
+        }
+        log.write(`gate: step ${step}\n`);
+        const outcome = runOne(step, "step", REMEDIES.stepNotRunnable);
+        steps.push({ command: step, ...outcome });
+        stopped = outcome.status !== "pass";
+    }
+    const checks = [];
+    for (const check of config.gate.checks.run) {
+        if (stopped) {
+            checks.push({ ...check, ...SKIPPED });
+            continue;
+        }
+        log.write(`gate: check ${check.name}\n`);
+        checks.push({ ...check, ...runOne(check.command, check.name, REMEDIES.checkNotRunnable) });
+    }
+    for (const check of enabledChecks(config.gate.checks)) {
+        if (stopped) {
+            checks.push({ name: check.name, command: null, ...SKIPPED });
+            continue;
+        }
+        log.write(`gate: check ${check.name}\n`);
+        const { failures: found, ...outcome } = runShipped(check, root);
+        failures.push(...found);
+        checks.push({ name: check.name, command: null, ...outcome });
+    }
+    return { status: worst([...steps, ...checks]), command: gateCommand, steps, checks, failures };
+}
+function verdict(report) {
+    if (report.status === "pass") {
+        return `gate: green — ${plural(report.steps.length, "step")}, ${plural(report.checks.length, "check")}`;
+    }
+    const failures = plural(report.failures.length, "failure");
+    return report.status === "fail" ? `gate: failed — ${failures}` : `gate: cannot run — ${failures}`;
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc gate: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const report = runGate(repositoryRoot(cli.root ?? process.cwd()), cli.json);
+    const actions = process.env.GITHUB_ACTIONS === "true";
+    if (cli.json) {
+        const document = { ...report, failures: report.failures.map(failureJson) };
+        process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+        // The runner reads workflow commands from stderr as from stdout, so stdout stays one document.
+        for (const failure of actions ? report.failures : []) {
+            process.stderr.write(`${annotation(failure)}\n`);
+        }
+    }
+    else {
+        const lines = report.failures.flatMap((failure) => actions ? [failureLine(failure), annotation(failure)] : [failureLine(failure)]);
+        process.stdout.write(`${[...lines, verdict(report)].join("\n")}\n`);
+    }
+    return EXIT_CODES[report.status];
+}

package/dist/commands/primitives.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "name the Primitives that own each path, with their summaries and documents";
+export declare function run(argv: string[]): number;

package/dist/commands/primitives.js

@@ -0,0 +1,106 @@
+// `dw-sdlc primitives --paths <files>`: for each path, the Primitives of the catalogue that name it,
+// with their summaries and the documents to read, or that none does.
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { primitivesNaming, readCatalogue } from "../catalogue.js";
+import { catalogueFile } from "../checks/primitives.js";
+export const summary = "name the Primitives that own each path, with their summaries and documents";
+const USAGE = `Usage: dw-sdlc primitives --paths <file>... [--json] [--root <dir>]
+
+Prints, for each path, the Primitives of the catalogue whose code names it, the file itself or the
+nearest directory above it: the id, the name, the summary and the documents to read; or that no
+Primitive names it. A path is read from the current directory. The catalogue is the one the
+primitives Check reads, in the repository holding --root (default: the current directory). --json
+prints one document instead.
+
+Exit 0 with an answer for every path, 2 when there is no catalogue to read or it is not one.`;
+const REMEDIES = {
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    invalid: "fix the catalogue; dw-sdlc gate names each problem under the primitives Check"
+};
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                paths: { type: "boolean" },
+                root: { type: "string" }
+            }
+        });
+        const cli = {
+            help: values.help === true,
+            json: values.json === true,
+            paths: values.paths === true,
+            files: positionals,
+            root: values.root
+        };
+        return cli.help || cli.paths ? cli : { error: "name the paths with --paths" };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * `path` with every symbolic link in it resolved, as git reports the root: the nearest part on disk
+ * resolved and the rest kept, so a deleted file still maps into the repository.
+ */
+function realPath(path) {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+    const parent = dirname(path);
+    return parent === path ? path : join(realPath(parent), basename(path));
+}
+function brief({ id, name, summary: what, docs }) {
+    return { id, name, summary: what, docs };
+}
+function plain(path, primitives) {
+    if (primitives.length === 0) {
+        return [`${path}: no Primitive names this path`];
+    }
+    return primitives.flatMap(({ id, name, summary: what, docs }) => [
+        `${path}: ${id} (${name}) — ${what}`,
+        `  read: ${docs.join(", ")}`
+    ]);
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc primitives: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const root = repositoryRoot(cli.root ?? process.cwd());
+    const file = catalogueFile(resolveConfig(root).config.gate.checks);
+    const read = readCatalogue(root, file);
+    if (read.state !== "valid") {
+        const problems = read.state === "missing"
+            ? [`the catalogue does not exist — ${REMEDIES.missing}`]
+            : read.problems.map((problem) => `${problem} — ${REMEDIES.invalid}`);
+        process.stderr.write(problems.map((problem) => `dw-sdlc primitives: ${file}: ${problem}\n`).join(""));
+        return 2;
+    }
+    const answers = cli.files.map((path) => {
+        const fromRoot = relative(root, realPath(resolve(path)));
+        return { path, primitives: primitivesNaming(read.catalogue, fromRoot) };
+    });
+    if (cli.json) {
+        const paths = answers.map(({ path, primitives }) => ({ path, primitives: primitives.map(brief) }));
+        process.stdout.write(`${JSON.stringify({ paths }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(answers
+            .flatMap(({ path, primitives }) => plain(path, primitives))
+            .map((line) => `${line}\n`)
+            .join(""));
+    }
+    return 0;
+}

package/dist/commands/references-setup.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "set a repository up to declare References: the Router, its table and the ignore rules";
+export declare function run(argv: string[]): number;

package/dist/commands/references-setup.js

@@ -0,0 +1,213 @@
+// `dw-sdlc references setup` sets a repository up to declare References. Five files, each written only
+// when it would change, so a repeat with nothing changed writes nothing:
+//
+//   references/AGENTS.md       the Router, from templates/router.md when there is none; on every run the
+//                              block between its two markers, a table of each Reference's dir and when
+//                              from the key, while the text around the block stays the author's
+//   references/CLAUDE.md       a symlink to AGENTS.md, so Claude Code loads the Router; written once
+//   .claude/settings.json      claudeMdExcludes for the clones' own CLAUDE.md and AGENTS.md
+//   .gitignore                 references/* and the two exceptions that keep the Router tracked
+//   .ai/agentic.config.json    an empty references key when the config has none
+//
+// Existing content stays: a list gains the entries it lacks at its end, and nothing is removed or
+// reordered. A settings file or a config that is not a JSON object is refused, not rewritten, and so
+// is an ignore file that ignores references/ itself and a Router with one marker and not the other,
+// or whose key fails the parser. --check writes nothing and exits 1 when any file would change.
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { CONFIG, isObject, readReferences } from "../references-key.js";
+import { renderBlock, withBlock } from "../router-block.js";
+const ROUTER = "references/AGENTS.md";
+const ROUTER_LINK = "references/CLAUDE.md";
+const SETTINGS = ".claude/settings.json";
+const IGNORE = ".gitignore";
+const TEMPLATE = join(import.meta.dirname, "..", "..", "templates", "router.md");
+/** A clone's own agent files at any depth; Claude Code matches the globs against absolute paths. */
+const EXCLUDES = [
+    "**/references/*/CLAUDE.md",
+    "**/references/*/**/CLAUDE.md",
+    "**/references/*/AGENTS.md",
+    "**/references/*/**/AGENTS.md"
+];
+/** Every clone ignored, then the Router and its symlink tracked: an exception counts after its pattern. */
+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.";
+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
+
+Sets the repository at --root, or the one the current directory sits in, up to declare References:
+the Router in ${ROUTER} with its CLAUDE.md symlink and, between its two markers, the table of each
+Reference's dir and when from the references key, claudeMdExcludes in ${SETTINGS} for the clones'
+own agent files, the ${IGNORE} lines that keep every clone out of git but the Router, and an empty
+references key in ${CONFIG}. Every file is written only when it would change, and the text around
+the Router's table never; --dry-run reports without writing, and --check does the same and exits 1
+when a file would change. Prints one line per file. Exit 1 when a file is refused, 2 on a bad
+argument.`;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function fail(message) {
+    console.error(`references:setup: ${message}`);
+    process.exit(2);
+}
+function render(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** The JSON object `text` holds, or undefined when it holds anything else. */
+function parseObject(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return isObject(parsed) ? parsed : undefined;
+}
+class Writer {
+    steps = [];
+    root;
+    dryRun;
+    constructor(root, dryRun) {
+        this.root = root;
+        this.dryRun = dryRun;
+    }
+    record(file, changed, write) {
+        if (changed && !this.dryRun) {
+            const path = join(this.root, file);
+            mkdirSync(dirname(path), { recursive: true });
+            write(path);
+        }
+        this.steps.push({ file, outcome: changed ? "wrote" : "unchanged" });
+    }
+    /** The text `change` gives `file`, from what `file` holds now; written when the two differ. */
+    put(file, change) {
+        const path = join(this.root, file);
+        const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
+        const next = change(current);
+        if ("refusal" in next) {
+            this.steps.push({ file, outcome: "refused", detail: next.refusal });
+            return;
+        }
+        this.record(file, next.text !== current, (target) => {
+            writeFileSync(target, next.text);
+        });
+    }
+    /** `file`, made by `make` when nothing sits at its path, a dangling symlink included; never replaced. */
+    create(file, make) {
+        this.record(file, lstatSync(join(this.root, file), { throwIfNoEntry: false }) === undefined, make);
+    }
+}
+/** The settings with claudeMdExcludes holding every glob of EXCLUDES, those it lacks appended. */
+function withExcludes(current) {
+    if (current === undefined) {
+        return { text: render({ claudeMdExcludes: EXCLUDES }) };
+    }
+    const settings = parseObject(current);
+    if (settings === undefined) {
+        return { refusal: "is not a JSON object; fix it by hand first" };
+    }
+    const value = settings.claudeMdExcludes ?? [];
+    if (!Array.isArray(value)) {
+        return { refusal: "claudeMdExcludes is not a list; fix it by hand first" };
+    }
+    const existing = value;
+    const missing = EXCLUDES.filter((glob) => !existing.includes(glob));
+    return { text: missing.length === 0 ? current : render({ ...settings, claudeMdExcludes: [...existing, ...missing] }) };
+}
+/**
+ * The ignore file with the lines it lacks appended. Without `references/*` all three go in, so each
+ * exception lands after the pattern it excepts; with it, only the exceptions it lacks.
+ */
+function withIgnoreLines(current) {
+    const text = current ?? "";
+    const lines = text.split(/\r?\n/).map((line) => line.trimEnd());
+    if (lines.some((line) => WHOLE.has(line))) {
+        return { refusal: `ignores references/ itself, so no exception tracks the Router; ignore ${IGNORED} instead` };
+    }
+    const ignored = lines.includes(IGNORED);
+    const missing = ignored ? TRACKED.filter((line) => !lines.includes(line)) : [IGNORE_COMMENT, IGNORED, ...TRACKED];
+    if (missing.length === 0) {
+        return { text };
+    }
+    const head = text === "" || text.endsWith("\n") ? text : `${text}\n`;
+    const gap = head !== "" && !ignored ? "\n" : "";
+    return { text: `${head}${gap}${missing.join("\n")}\n` };
+}
+/** The config with an empty `references` key when it has none, inserted so its own layout stays. */
+function withEmptyKey(current) {
+    if (current === undefined) {
+        return { text: render({ references: [] }) };
+    }
+    const config = parseObject(current);
+    if (config === undefined) {
+        return { refusal: "is not a JSON object; fix it by hand first" };
+    }
+    if (Object.hasOwn(config, "references")) {
+        return { text: current };
+    }
+    const close = current.lastIndexOf("}");
+    const body = current.slice(0, close).trimEnd();
+    const comma = body.endsWith("{") ? "" : ",";
+    return { text: `${body}${comma}\n  "references": []\n${current.slice(close)}` };
+}
+/** The repository `dir` sits in, or `dir` itself outside one. */
+function toplevel(dir) {
+    const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : dir;
+}
+function setup(root, dryRun) {
+    const writer = new Writer(root, dryRun);
+    const template = readFileSync(TEMPLATE, "utf8");
+    const reading = readReferences(root);
+    writer.put(ROUTER, (current) => {
+        if ("problem" in reading) {
+            return { refusal: `${reading.problem}; the table comes from the key, so fix it first` };
+        }
+        const next = withBlock(current ?? template, renderBlock(reading.references ?? []));
+        return "problem" in next ? { refusal: next.problem } : next;
+    });
+    writer.create(ROUTER_LINK, (path) => {
+        symlinkSync("AGENTS.md", path);
+    });
+    writer.put(SETTINGS, withExcludes);
+    writer.put(IGNORE, withIgnoreLines);
+    writer.put(CONFIG, withEmptyKey);
+    return writer.steps;
+}
+export function run(argv) {
+    let values;
+    try {
+        values = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                root: { type: "string" },
+                "dry-run": { type: "boolean" },
+                check: { type: "boolean" }
+            }
+        }).values;
+    }
+    catch (error) {
+        fail(`${messageOf(error)}\n\n${USAGE}`);
+    }
+    if (values.help === true) {
+        console.log(USAGE);
+        return 0;
+    }
+    const check = values.check === true;
+    const dryRun = values["dry-run"] === true || check;
+    const steps = setup(toplevel(values.root ?? process.cwd()), dryRun);
+    for (const step of steps) {
+        const verb = step.outcome === "wrote" && dryRun ? "would write" : step.outcome;
+        console.log(`${verb.padEnd(11)} ${step.file}${step.detail === undefined ? "" : ` — ${step.detail}`}`);
+    }
+    const refused = steps.some((step) => step.outcome === "refused");
+    return refused || (check && steps.some((step) => step.outcome === "wrote")) ? 1 : 0;
+}

package/dist/commands/references-sync.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "bring every declared Reference to its ref under references/";
+export declare function run(argv: string[]): Promise<number>;