@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/verbs/scaffold.js

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isMethodDomainArchetype, METHOD_DOMAIN_ARCHETYPES, scaffoldDomain, } from "../lib/scaffold/domain.js";
+import { resolveArchetype } from "../lib/scaffold/registry.js";
+import { resolvePathOption } from "./path-option.js";
+const DOMAIN_NAME = /^[a-z][a-z0-9-]*$/;
+export function registerScaffold(program) {
+    const scaffold = program
+        .command("scaffold")
+        .description("Scaffold method-shaped artefacts into an existing SDD repo (ADR 0173)");
+    scaffold
+        .command("domain <name>")
+        .description("Scaffold a platform domain (docs/domains/<name>/) into a platform-root SDD. " +
+        "Writes the generic domain shape; --archetype overlays starter content.")
+        .option("--archetype <id>", `seed from a domain archetype: method tier (${METHOD_DOMAIN_ARCHETYPES.join(" | ")}) ` +
+        "or a registry archetype from a consumed bundle (e.g. core/identity, " +
+        "or bundle-qualified '<bundle>:<id>' — ADR 0176)")
+        .option("--with-contracts", "include a contracts/ subfolder")
+        .option("--target-repo <dir>", "platform-root SDD repo", resolvePathOption, process.cwd())
+        .option("--dry-run", "report planned files without writing")
+        .action(async (name, opts) => {
+        if (!DOMAIN_NAME.test(name)) {
+            fail(`domain name '${name}' must be kebab-case (lowercase, digits, hyphens)`);
+        }
+        const targetRepo = opts.targetRepo ?? process.cwd();
+        await assertPlatformRoot(targetRepo);
+        // Archetype resolution chain (ADR 0176 §4.4): method tier is
+        // built in; anything else resolves against cached bundle
+        // registries — with a helpful listing on miss.
+        let registryArchetype;
+        if (opts.archetype !== undefined && !isMethodDomainArchetype(opts.archetype)) {
+            const resolution = await resolveArchetype(targetRepo, opts.archetype);
+            if (!resolution.ok || !resolution.archetype) {
+                fail(`${resolution.error ?? "archetype resolution failed"} ` +
+                    `(method-tier archetypes: ${METHOD_DOMAIN_ARCHETYPES.join(", ")})`);
+            }
+            registryArchetype = resolution.archetype;
+        }
+        if (opts.dryRun === true) {
+            const label = registryArchetype
+                ? `${registryArchetype.bundleName}:${registryArchetype.id}`
+                : (opts.archetype ?? "none");
+            process.stdout.write(`[DRY-RUN] would scaffold docs/domains/${name}/ ` +
+                `(archetype: ${label}${opts.withContracts ? ", +contracts" : ""})\n`);
+            return;
+        }
+        const { filesWritten } = await scaffoldDomain({
+            name,
+            targetRepo,
+            ...(opts.archetype && isMethodDomainArchetype(opts.archetype)
+                ? { archetype: opts.archetype }
+                : {}),
+            ...(registryArchetype ? { registryArchetype } : {}),
+            ...(opts.withContracts === true ? { withContracts: true } : {}),
+        });
+        if (registryArchetype) {
+            process.stdout.write(`[INFO] archetype ${registryArchetype.bundleName}:${registryArchetype.id} ` +
+                `(tier: ${registryArchetype.tier}) — seed files copied; the domain is adopter-owned from creation\n`);
+        }
+        process.stdout.write(`[PASS] scaffolded domain '${name}' (${filesWritten.length} files):\n`);
+        for (const f of filesWritten)
+            process.stdout.write(`  ${f}\n`);
+    });
+}
+function fail(message) {
+    process.stderr.write(`[FAIL] scaffold domain: ${message}\n`);
+    process.exit(1);
+}
+async function assertPlatformRoot(targetRepo) {
+    let kind = "";
+    try {
+        kind = (await readFile(join(targetRepo, ".sdd-repo-kind"), "utf8")).trim();
+    }
+    catch {
+        fail(`not an SDD repo (no .sdd-repo-kind in ${targetRepo}). ` +
+            "Run inside a platform-root SDD, or pass --target-repo.");
+    }
+    if (kind !== "platform-product") {
+        fail(`domains are scaffolded into a platform-root SDD, but .sdd-repo-kind is '${kind}'. ` +
+            "Domains live in the platform-root, not in application/integration SDDs.");
+    }
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/verbs/snapshot.js

@@ -0,0 +1,134 @@
+import { resolve } from "node:path";
+import { runSnapshotAdvance } from "../lib/snapshot/advance.js";
+import { runSnapshotDiff } from "../lib/snapshot/diff.js";
+import { runSnapshotFold } from "../lib/snapshot/fold.js";
+import { runSnapshotLand } from "../lib/snapshot/land.js";
+import { runSnapshotTargets } from "../lib/snapshot/targets.js";
+import { runSnapshotVerify } from "../lib/snapshot/verify.js";
+const out = (s) => process.stdout.write(s);
+const exit = ({ exitCode }) => {
+    if (exitCode !== 0)
+        process.exit(exitCode);
+};
+/** Repeatable `key=value` option → Map. The value may itself contain `=`. */
+function collectPairs(value, prior) {
+    const i = value.indexOf("=");
+    if (i <= 0)
+        throw new Error(`expected key=value, got '${value}'`);
+    prior.set(value.slice(0, i), value.slice(i + 1));
+    return prior;
+}
+function collectList(value, prior) {
+    prior.push(value);
+    return prior;
+}
+/**
+ * `a=1,b=2` → object (for records like the credential scan and a waiver). A comma
+ * splits only where the next part starts a new `key=`, so free text — a
+ * disposition, a waiver's reason — may contain commas without being cut short.
+ */
+export function record(value) {
+    if (value === undefined)
+        return undefined;
+    const o = {};
+    for (const part of value.split(/,(?=\s*[A-Za-z_]+=)/)) {
+        const i = part.indexOf("=");
+        if (i > 0)
+            o[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+    }
+    return o;
+}
+export function registerSnapshot(program) {
+    const snapshot = program
+        .command("snapshot")
+        .description("Implementation-set snapshots: the deterministic steps of delta-reverse (M-ADR 0180 §2.7, M-ADR 0181 §2.5), run by the reverse-snapshot-delta skill");
+    snapshot
+        .command("fold <area>")
+        .description("Move a flat <repo>@<rev>/ area into its first dated baseline, write its manifest, and list every reference to the old paths")
+        .option("--id <date>", "the date the flat exports were OBSERVED (YYYY-MM-DD); no default")
+        .option("--implementation <id>", "the durable system identity")
+        .option("--key <folder=key>", "canonical_repo_key for a folder (repeatable)", collectPairs, new Map())
+        .option("--scan <root>", "a root to search for references to the old paths — scan the estate, not only the SDD (repeatable)", collectList, [])
+        .option("--sdd-path <path>", "the owning SDD: re-point its evidence pins into the baseline, take keys and role_hint from them")
+        .action(async (area, o) => exit(await runSnapshotFold({
+        areaRoot: resolve(area),
+        ...(o.id !== undefined ? { id: o.id } : {}),
+        ...(o.implementation !== undefined ? { implementation: o.implementation } : {}),
+        keys: o.key,
+        scanRoots: o.scan.map((r) => resolve(r)),
+        ...(o.sddPath !== undefined ? { sddPath: resolve(o.sddPath) } : {}),
+    }, out)));
+    snapshot
+        .command("land <area>")
+        .description("Write a new baseline's manifest: every prior member re-observed, carried (with a reason) or removed (with a reason); refuses without a recorded credential scan")
+        .option("--id <date>", "the date the snapshot was OBSERVED (YYYY-MM-DD); no default, so the processing date cannot slip in")
+        .option("--prior <date>", "the baseline this supersedes (default: the latest earlier one)")
+        .option("--implementation <id>", "the durable system identity (default: the prior baseline's)")
+        .option("--member-date <key=date>", "a member observed on another day than the set (repeatable)", collectPairs, new Map())
+        .option("--carried <key=reason>", "a prior member not re-exported, and why (repeatable)", collectPairs, new Map())
+        .option("--removed <key=reason>", "a prior member that left the set, and why (repeatable)", collectPairs, new Map())
+        .option("--key <folder=key>", "canonical_repo_key for a new member's folder (repeatable)", collectPairs, new Map())
+        .option("--sdd-path <path>", "the owning SDD: a derived key for a new member must be one of its repository ids")
+        .option("--role-hint <key=role>", "role_hint for a member; continuing members otherwise keep the prior baseline's (repeatable)", collectPairs, new Map())
+        .option("--credential-scan <record>", "tool=…,version=…,date=YYYY-MM-DD,result=clean — or result=<findings>,disposition=<what, and why it stands>")
+        .option("--notes <text>", "coherence caveats for the manifest")
+        .action(async (area, o) => {
+        const scan = record(o.credentialScan);
+        exit(await runSnapshotLand({
+            areaRoot: resolve(area),
+            ...(o.id !== undefined ? { id: o.id } : {}),
+            ...(o.prior !== undefined ? { prior: o.prior } : {}),
+            ...(o.implementation !== undefined ? { implementation: o.implementation } : {}),
+            ...(o.sddPath !== undefined ? { sddPath: resolve(o.sddPath) } : {}),
+            memberDates: o.memberDate,
+            carried: o.carried,
+            removed: o.removed,
+            keys: o.key,
+            roleHints: o.roleHint,
+            ...(scan ? { credentialScan: scan } : {}),
+            ...(o.notes !== undefined ? { notes: o.notes } : {}),
+        }, out));
+    });
+    snapshot
+        .command("verify <area>")
+        .description("Check a baseline's provenance: local folder/revision consistency here, canonical-repo confirmation supplied per member or waived on the record; cannot-assert FAILS")
+        .requiredOption("--id <date>", "the baseline to verify (normally T0)")
+        .option("--confirmed <key=how>", "how a member's revision was confirmed on its canonical repo (repeatable)", collectPairs, new Map())
+        .option("--waiver <record>", "who=…,why=…,date=YYYY-MM-DD — recorded in provenance.yaml and printed on every run")
+        .action(async (area, o) => {
+        const w = record(o.waiver);
+        exit(await runSnapshotVerify({ areaRoot: resolve(area), id: o.id, confirmed: o.confirmed, ...(w ? { waiver: w } : {}) }, out));
+    });
+    snapshot
+        .command("diff <area>")
+        .description("Classify members from the two manifests and diff changed members by evidence class into delta.yaml (status: proposed); refuses once any finding carries judgement")
+        .requiredOption("--to <date>", "the new baseline (T1)")
+        .option("--from <date>", "the prior baseline (default: T1's prior_snapshot)")
+        .action(async (area, o) => exit(await runSnapshotDiff({ areaRoot: resolve(area), to: o.to, ...(o.from !== undefined ? { from: o.from } : {}) }, out)));
+    snapshot
+        .command("targets <area>")
+        .description("Route each delta.yaml finding to the SDD artefacts that cite it, recording the grain (file | repo) of each route")
+        .requiredOption("--id <date>", "the baseline whose delta.yaml to route")
+        .option("--sdd-path <path>", "the SDD repo root (defaults to cwd)")
+        .option("--derived <glob>", "SDD-relative glob of GENERATED artefacts (scores, reports, registries) — marked to regenerate, not re-derive (repeatable)", collectList, [])
+        .action(async (area, o) => exit(await runSnapshotTargets({ areaRoot: resolve(area), id: o.id, sddPath: resolve(o.sddPath ?? process.cwd()), derived: o.derived }, out)));
+    snapshot
+        .command("advance <area>")
+        .description("Advance each member's evidence pin to the baseline and append one history entry; refuses before delta.yaml, without impact, on legacy history or an unknown reverse_status")
+        .requiredOption("--to <date>", "the baseline to advance to (T1)")
+        .option("--sdd-path <path>", "the SDD repo root (defaults to cwd)")
+        .option("--member <key>", "limit to these members (repeatable)", collectList, [])
+        .option("--migrate-history", "convert legacy entries: histories to history[] first (phase: scan rows only)")
+        .option("--record-only", "for a pin already moved to --to by hand: write its history row, leave the pin")
+        .option("--notes <key=text>", "prose for a member's history row, beside the notes composed from its findings (repeatable)", collectPairs, new Map())
+        .action(async (area, o) => exit(await runSnapshotAdvance({
+        areaRoot: resolve(area),
+        to: o.to,
+        sddPath: resolve(o.sddPath ?? process.cwd()),
+        ...(o.member.length > 0 ? { members: o.member } : {}),
+        migrateHistory: o.migrateHistory === true,
+        recordOnly: o.recordOnly === true,
+        notes: o.notes,
+    }, out)));
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/verbs/validate.js

@@ -0,0 +1,48 @@
+import { runValidate } from "../lib/validate/index.js";
+import { methodValidationPlan } from "../lib/validate/plan.js";
+import { profileFromRepoKind, readRepoKind } from "../lib/repo-kind.js";
+const LISTABLE = ["platform", "application", "integration"];
+const isListable = (p) => LISTABLE.includes(p);
+import { resolvePathOption } from "./path-option.js";
+export function registerValidate(program) {
+    program
+        .command("validate")
+        .description("Run the method-level validation suite for this SDD repository")
+        .option("--target-repo <dir>", "target SDD repo", resolvePathOption, process.cwd())
+        .option("--platform-root <dir>", "path to the sdd-method (or platform) repo, required for app-dependencies", resolvePathOption)
+        .option("--validator <name>", "run only the named validator")
+        .option("--strict", "treat warnings as failures")
+        .option("--list", "print the method-managed validation job for this repo's profile as JSON (the plan every CI executor runs, the Dagger module included) and run nothing")
+        .option("--profile <profile>", "with --list: the profile to list, instead of reading .sdd-repo-kind (platform | application | integration)")
+        .action(async (opts) => {
+        if (opts.list === true) {
+            let profile;
+            if (opts.profile !== undefined) {
+                if (!isListable(opts.profile)) {
+                    process.stderr.write(`--profile must be platform, application or integration (got: ${opts.profile})\n`);
+                    process.exit(2);
+                }
+                profile = opts.profile;
+            }
+            else {
+                const kind = await readRepoKind(opts.targetRepo);
+                if (kind === null) {
+                    process.stderr.write(`Not an SDD repo (no .sdd-repo-kind in ${opts.targetRepo}); pass --profile\n`);
+                    process.exit(1);
+                }
+                profile = profileFromRepoKind(kind);
+            }
+            process.stdout.write(JSON.stringify({ profile, steps: methodValidationPlan(profile) }, null, 2) + "\n");
+            return;
+        }
+        const { exitCode } = await runValidate({
+            targetRepo: opts.targetRepo,
+            ...(opts.platformRoot ? { platformRoot: opts.platformRoot } : {}),
+            ...(opts.validator ? { validator: opts.validator } : {}),
+            strict: opts.strict === true,
+        });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/verify-program.js

@@ -0,0 +1,122 @@
+// Third entrypoint: the VERIFY surface — M-ADR 0212 §4.3b.
+//
+// A binary that CANNOT WRITE to the repository it is pointed at. That is the
+// whole property, and it is the one a pipeline can rely on: whatever runs
+// `sdd-verify` in CI can judge a repository and cannot change it.
+//
+// Two criteria admit a verb here, and both are required:
+//   1. it does not write to the target repository — TESTED, not read from a
+//      description: the package acceptance check runs every verb in every mode
+//      against a clean checkout and requires `git status --porcelain` to be
+//      empty. Reading help text misfiled four verbs before that test existed
+//      (`sync`, `render`, `catalogue graph`, `metamodel roundtrip`).
+//   2. it has something to act on in an adopter repository today. A read-only
+//      verb can fail this and pass (1): `metamodel roundtrip` is producer-only,
+//      `catalogue migration-map` serves a finished migration. Neither is here.
+//
+// ⚠ The boundary is ABSENCE, not a menu. The package ships only the import
+// closure of this file, so an excluded verb's code is not present to be reached
+// by any path — including `mcp serve`, which exposes the SDD as tools and would
+// hand authoring back through a second door. That is why registration imports
+// per-subcommand registrars (`catalogue-verify.ts`, `pack-validate.ts`) and never
+// a barrel that re-exports a build path.
+//
+// Verbs are the SAME registrars the full CLI uses: one implementation, two
+// surfaces, so behaviour cannot drift between them.
+import { Command, CommanderError } from "commander";
+import { getPackageVersion } from "./lib/package-version.js";
+import { registerCatalogueBaselineCheck, registerCatalogueImpact, registerCatalogueValidate, registerCatalogueVersion, } from "./verbs/catalogue-verify.js";
+import { registerList } from "./verbs/list.js";
+import { registerPackValidate } from "./verbs/pack-validate.js";
+import { registerValidate } from "./verbs/validate.js";
+const SPEC_URL = "https://github.com/tomfosteruk/sdd-method/blob/main/docs/method/cli/sdd-cli-specification.md";
+/** The full surface, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
+export const VERIFY_SURFACE = [
+    "validate",
+    "list",
+    "pack validate",
+    "catalogue validate",
+    "catalogue impact",
+    "catalogue baseline-check",
+    "catalogue version",
+];
+const OUTSIDE = "is not part of sdd-verify, which cannot write to the repository it is pointed at. " +
+    "Authoring and maintenance verbs are in @sdd-method/sdd-cli.";
+/**
+ * Refuse anything outside the surface BEFORE commander parses it. Left to
+ * commander, `sdd-verify sync --help` prints top-level usage and exits 0 — in a
+ * pipeline that is a step that runs nothing and passes, which is the failure
+ * this binary exists to prevent. So an excluded verb fails, loudly, whatever
+ * flags accompany it.
+ */
+export function rejectOutsideSurface(program, argv, outside = OUTSIDE) {
+    const words = argv.filter((a) => !a.startsWith("-"));
+    if (words.length === 0)
+        return;
+    const [verb, sub] = words;
+    if (verb === "help")
+        return;
+    const cmd = program.commands.find((c) => c.name() === verb);
+    if (!cmd)
+        throw new Error(`'${verb}' ${outside}`);
+    const subs = cmd.commands.map((c) => c.name()).filter((n) => n !== "help");
+    if (subs.length > 0 && sub !== undefined && sub !== "help" && !subs.includes(sub)) {
+        throw new Error(`'${verb} ${sub}' ${outside}`);
+    }
+}
+export async function runVerify(argv) {
+    const program = buildVerifyProgram();
+    if (argv.length === 0) {
+        program.outputHelp();
+        return;
+    }
+    rejectOutsideSurface(program, argv);
+    try {
+        await program.parseAsync([...argv], { from: "user" });
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            if (err.code === "commander.help" ||
+                err.code === "commander.helpDisplayed" ||
+                err.code === "commander.version") {
+                return;
+            }
+        }
+        throw err;
+    }
+}
+export function buildVerifyProgram() {
+    const program = new Command();
+    program
+        .name("sdd-verify")
+        .description("Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Cannot write to the repository it is pointed at.")
+        .version(getPackageVersion(), "-v, --version")
+        .addHelpText("after", `\nSpec: ${SPEC_URL}\nAuthoring and maintenance verbs (sync, catalogue build, init, scaffold, …) are in @sdd-method/sdd-cli.`)
+        .exitOverride()
+        .configureOutput({
+        writeOut: (str) => process.stdout.write(str),
+        writeErr: (str) => process.stderr.write(str),
+    });
+    registerVerifySurface(program);
+    return program;
+}
+/**
+ * The verify verbs, registered onto any program. sdd-verify calls it; sdd-maintain calls it too,
+ * which is what makes the personas nest structurally: whatever verify ships, maintain ships.
+ */
+export function registerVerifySurface(program) {
+    registerValidate(program);
+    registerList(program);
+    const pack = program
+        .command("pack")
+        .description("Validate adopter-shipped context-pack seeds (ADR 0151) — read-only");
+    registerPackValidate(pack);
+    const catalogue = program
+        .command("catalogue")
+        .description("Validate and query per-SDD catalogues (ADR 0134) — read-only, never rebuilds");
+    registerCatalogueValidate(catalogue);
+    registerCatalogueImpact(catalogue);
+    registerCatalogueBaselineCheck(catalogue);
+    registerCatalogueVersion(catalogue);
+}
+//# sourceMappingURL=verify-program.js.map

package/dist/verify-version.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.2.0",
+  "built_against_sdd_cli": "1.43.0"
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "sddCliVersion": "1.43.0",
+  "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "sdd-author": "dist/author-bin.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.0",
+    "zod": "^4.3.6",
+    "@duckdb/node-api": "^1.5.5-r.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomfosteruk/sdd-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}