@sdd-method/maintain-cli 0.0.0-stage → 0.1.0-rc.0

package/dist/lib/pack/validate.js

@@ -0,0 +1,49 @@
+// `pack validate` — reads and checks a context-pack seed; writes nothing.
+// Kept free of any import that reaches `./builder.js`, so that importing it
+// cannot drag pack-building code into a package that must not author
+// (M-ADR 0212 §4.3b). `index.ts` re-exports it, so existing imports are unchanged.
+import { validateSeed } from "./schema.js";
+import { loadSeed } from "./seed.js";
+import { getSddCliVersion } from "../package-version.js";
+import { fail, info, pass, section } from "./log.js";
+export async function runPackValidate(opts, stdout = (s) => process.stdout.write(s)) {
+    stdout(section("Pack validate"));
+    let seed;
+    try {
+        seed = await loadSeed(opts.seedPath);
+    }
+    catch (err) {
+        stdout(fail(`Seed load failed: ${err.message}`));
+        return { exitCode: 1, errors: [{ field: "(load)", message: err.message }] };
+    }
+    // A seed key this build does not know is REPORTED rather than dropped in silence.
+    // Not fatal: an older sdd-cli must still build a seed that declares something newer
+    // than itself, exactly as for `.sdd/sdd-manifest.yaml`. Silence here is what let an
+    // adopter follow the schema and get a clean validation with no effect.
+    if (seed.unknownKeys && seed.unknownKeys.length > 0) {
+        stdout(info(`${seed.unknownKeys.length} seed key(s) not understood by sdd-cli ${getSddCliVersion()} ` +
+            `and therefore IGNORED: ${seed.unknownKeys.join(", ")}. If the seed follows a newer ` +
+            `context-pack-seed-schema than this build, upgrade sdd-cli; otherwise remove or correct the key.`));
+    }
+    const validation = validateSeed(seed);
+    if (!validation.ok) {
+        stdout(fail("Seed validation failed:"));
+        for (const e of validation.errors) {
+            stdout(fail(`  ${e.field}: ${e.message}`));
+        }
+        return { exitCode: 1, errors: validation.errors };
+    }
+    stdout(pass(`Seed valid: ${seed.scope} v${seed.version}`));
+    stdout(info(seed.forwardBase
+        ? `Forward base: ${seed.forwardBase.bundle} >= ${seed.forwardBase.minimumVersion}`
+        : "Forward base: none (profile-agnostic pack, ADR 0176 §4.6)"));
+    if (seed.scaffoldSourcePaths) {
+        stdout(info(`Scaffold-source prefixes: ${seed.scaffoldSourcePaths.join(", ")}`));
+    }
+    stdout(info(`Managed paths: ${seed.managedPaths.length}`));
+    if (seed.requiresPack) {
+        stdout(info(`requires_pack: ${seed.requiresPack.name} ${seed.requiresPack.version}`));
+    }
+    return { exitCode: 0, errors: [] };
+}
+//# sourceMappingURL=validate.js.map

package/dist/lib/package-version.js

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Read the package version from package.json at runtime so the various
+ * version-string consumers (CLI --version, MCP server identity,
+ * catalogue error messages) cannot drift from the published version.
+ *
+ * Resolves relative to this module's compiled location:
+ *   - In source layout: src/lib/package-version.ts → package.json (../../)
+ *   - In dist layout:   dist/lib/package-version.js → package.json (../../)
+ *
+ * Cached on first call.
+ */
+let cached;
+let cachedEngine;
+/**
+ * The version of the sdd-cli ENGINE this code is. In @sdd-method/sdd-cli it is the package
+ * version. In a persona package (verify-cli, maintain-cli) the package version is the
+ * persona's own (0.1.0, 1.0.0), while every check and stamp that means "which sdd-cli is
+ * this" (a bundle's minimum_sdd_cli_version, the CLI version stamped into catalogues, the
+ * MCP server identity) must see the engine it was built from. The persona build writes that
+ * as `sddCliVersion` in the package's package.json. Found by maintain-cli's acceptance run:
+ * its sync refused every bundle because 0.1.0 < 1.41.0.
+ */
+export function getSddCliVersion() {
+    if (cachedEngine !== undefined)
+        return cachedEngine;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(resolve(here, "..", "..", "package.json"), "utf8"));
+    cachedEngine = pkg.sddCliVersion ?? pkg.version;
+    return cachedEngine;
+}
+/** The package's own version: what `--version` prints. For the engine version, use getSddCliVersion. */
+export function getPackageVersion() {
+    if (cached !== undefined)
+        return cached;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = resolve(here, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    cached = pkg.version;
+    return cached;
+}
+/**
+ * The @sdd-method/verify-cli version released WITH this sdd-cli (M-ADR 0212
+ * §6.1 Phase 1). The method-managed CI workflow installs exactly this version,
+ * so the CLI that syncs a repository decides which verifier judges it.
+ *
+ * Read from dist/verify-version.json, which the build copies from
+ * scripts/verify-version.json. Never from scripts/ in a built layout: the global
+ * `sdd-cli` on the method's machines is a link into the checkout, so reading the
+ * committed file live would render a version bumped in source but not yet
+ * published into every workflow synced that day, while dist/ still lagged.
+ * Source layout (tests) has no copy and reads scripts/ directly.
+ *
+ * Throws rather than defaults: a missing version must not render a floating install.
+ */
+const cachedPersona = {};
+/**
+ * One exact npm version: X.Y.Z, optionally with a prerelease tag (1.1.0-rc.0), which a release
+ * candidate published under the `next` dist-tag needs so hosted CI can run it before the release.
+ * Never a range, a tag name or a wildcard.
+ */
+export const EXACT_VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$/;
+function personaVersion(persona) {
+    const hit = cachedPersona[persona];
+    if (hit !== undefined)
+        return hit;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fromSource = here.endsWith(`${sep}src${sep}lib`);
+    const file = fromSource
+        ? resolve(here, "..", "..", "scripts", `${persona}-version.json`)
+        : resolve(here, "..", `${persona}-version.json`);
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed.version !== "string" || !EXACT_VERSION.test(parsed.version)) {
+        throw new Error(`${file} has no semver \`version\`; refusing to render an unpinned ${persona}-cli install`);
+    }
+    cachedPersona[persona] = parsed.version;
+    return parsed.version;
+}
+export function getVerifyCliVersion() {
+    return personaVersion("verify");
+}
+/**
+ * The @sdd-method/maintain-cli version released WITH this sdd-cli. The managed CI workflow's
+ * catalogue freshness step installs exactly this version (M-ADR 0218 §5; ruled 2026-10-15, sdm-jts.6).
+ * Read the same way as the verify version, for the same reason (dist/ copy, never scripts/ live).
+ */
+export function getMaintainCliVersion() {
+    return personaVersion("maintain");
+}
+//# sourceMappingURL=package-version.js.map

package/dist/lib/repo-kind.js

@@ -0,0 +1,129 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
+ * layer that additive extensions can compose on top of (per ADR 0135).
+ * The legacy self-contained `reverse-baseline` is retained as a
+ * forward base for compat with adopters who haven't migrated to the
+ * `reverse-extension-baseline` additive shape yet.
+ */
+const FORWARD_BASE_BUNDLES = new Set([
+    "platform-baseline",
+    "app-baseline",
+    "integration-baseline",
+    "reverse-baseline",
+]);
+export const REPO_KIND_FILE = ".sdd-repo-kind";
+/**
+ * Legacy marker filename from the pre-rebrand era. Read-only fallback during
+ * the rebrand transition: `readRepoKind` accepts either filename; `sync`
+ * auto-migrates legacy → canonical. New writes always use `REPO_KIND_FILE`.
+ * Drop after one minor-version overlap.
+ */
+export const LEGACY_REPO_KIND_FILE = ".iteraitive-repo-kind";
+const PROFILE_BY_REPO_KIND = {
+    "platform-product": "platform",
+    "application-product": "application",
+    "integration-product": "integration",
+    "reverse-corpus": "reverse",
+};
+const REPO_KIND_BY_PROFILE = {
+    platform: "platform-product",
+    application: "application-product",
+    integration: "integration-product",
+    reverse: "reverse-corpus",
+};
+/**
+ * Forward-base bundles map 1:1 to a profile. Additive bundles
+ * (`reverse-extension-baseline`) have no profile of their own — they
+ * compose on top of whatever forward base is already locked.
+ */
+const PROFILE_BY_BUNDLE_NAME = {
+    "platform-baseline": "platform",
+    "app-baseline": "application",
+    "integration-baseline": "integration",
+    "reverse-baseline": "reverse",
+};
+const BUNDLE_NAME_BY_PROFILE = {
+    platform: "platform-baseline",
+    application: "app-baseline",
+    integration: "integration-baseline",
+    reverse: "reverse-baseline",
+};
+export function profileFromRepoKind(kind) {
+    return PROFILE_BY_REPO_KIND[kind];
+}
+export function repoKindFromProfile(profile) {
+    return REPO_KIND_BY_PROFILE[profile];
+}
+/**
+ * Returns the profile a bundle authoritatively claims, or null for
+ * additive bundles that don't claim a profile of their own. Accepts
+ * arbitrary strings (adopter pack names per ADR 0151) and returns null
+ * for any name not in the closed sdd-method bundle set.
+ */
+export function profileFromBundleName(name) {
+    if (!isBundleName(name))
+        return null;
+    return PROFILE_BY_BUNDLE_NAME[name] ?? null;
+}
+export function bundleNameFromProfile(profile) {
+    return BUNDLE_NAME_BY_PROFILE[profile];
+}
+/**
+ * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
+ * layer that additive extensions compose on top of. Additive bundles
+ * (sdd-method's `reverse-extension-baseline` and ADR 0151 adopter
+ * packs) return false. Accepts arbitrary strings; unknown names return
+ * false.
+ */
+export function isForwardBase(name) {
+    if (!isBundleName(name))
+        return false;
+    return FORWARD_BASE_BUNDLES.has(name);
+}
+/**
+ * Maps repo-kind → forward-base bundle name. Used when migrating a
+ * legacy v1 lock file (which doesn't record bundle name) to v2.
+ */
+export function bundleNameFromRepoKind(kind) {
+    return BUNDLE_NAME_BY_PROFILE[PROFILE_BY_REPO_KIND[kind]];
+}
+export function isRepoKind(value) {
+    return value in PROFILE_BY_REPO_KIND;
+}
+const ALL_BUNDLE_NAMES = new Set([
+    "platform-baseline",
+    "app-baseline",
+    "integration-baseline",
+    "reverse-baseline",
+    "reverse-extension-baseline",
+]);
+export function isBundleName(value) {
+    return ALL_BUNDLE_NAMES.has(value);
+}
+export async function readRepoKind(repoRoot) {
+    // Canonical first; fall back to legacy marker during the rebrand transition.
+    for (const filename of [REPO_KIND_FILE, LEGACY_REPO_KIND_FILE]) {
+        const path = join(repoRoot, filename);
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const value = raw.trim();
+        if (!isRepoKind(value)) {
+            throw new Error(`Unrecognised ${filename} value: ${JSON.stringify(value)} at ${path}`);
+        }
+        return value;
+    }
+    return null;
+}
+export async function writeRepoKind(repoRoot, kind) {
+    await writeFile(join(repoRoot, REPO_KIND_FILE), `${kind}\n`, "utf8");
+}
+//# sourceMappingURL=repo-kind.js.map

package/dist/lib/scripts.js

@@ -0,0 +1,7 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveBundledScript(name) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..", "scripts", name);
+}
+//# sourceMappingURL=scripts.js.map

package/dist/lib/snapshot/catalogue-diff.js

@@ -0,0 +1,219 @@
+// `sdd-cli catalogue diff` — the catalogue consequence of a snapshot update,
+// attributed at FILE grain (reverse-snapshot-delta step 10).
+//
+// It BUILDS both sides itself, in this one process: BEFORE from `git archive
+// <ref>` of the SDD, AFTER from the working tree, each into a temporary output
+// directory. Committed catalogues are never read — they are as old as their last
+// build — and one process means one CLI, so a CLI change between the builds
+// cannot appear as changed rows. Nothing is written into the SDD, its catalogues
+// or its .git.
+//
+// Attribution is at file grain because catalogue rows carry no source-file
+// provenance, so "every row names a finding" is not checkable:
+//   - every SDD source file changed since <ref> must appear in some finding's
+//     targets (the pin bookkeeping `snapshot advance` writes is exempt), through
+//     a PRECISE target: grain `file`, grain `confirmed` (narrowed by hand), or a
+//     plain string written by hand. A file reached only through a `repo`-grain
+//     target is attributed BY MENTION ONLY, and fails: a repo-grain target names
+//     every artefact that mentions the member, so in a component-heavy SDD it
+//     covers almost any edit and the check would pass by construction. Narrowing
+//     is bounded by the files actually edited, not by the targets routed;
+//   - files the method bundle manages (the lock's managed_paths) are excluded — a
+//     method sync changes them, not the snapshot — and counted;
+//   - an attributed file edited by more than one commit is LISTED: attribution is by
+//     file, so its other edits ride on the finding unless a reader checks;
+//   - catalogue rows that changed while NO file changed (bookkeeping included)
+//     are unattributed by construction — the builder moved, not the snapshot.
+// Exit 1 on any unattributed change.
+import { execFile as execFileCb } from "node:child_process";
+import { mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { parse } from "yaml";
+import { runCatalogueBuild } from "../catalogue/build.js";
+const execFile = promisify(execFileCb);
+const EXEMPT = [/^catalogues\//, /^repos\/[^/]+\/reverse-(history|metadata)\.yaml$/];
+/**
+ * Files the method bundle manages — the lock's managed_paths, at the ref and now
+ * (a sync adds and retires them), plus the lock itself. A run that spans a method
+ * sync changes them, and no snapshot finding caused that.
+ */
+export function managedPathsOf(lockText) {
+    const out = new Set();
+    if (!lockText)
+        return out;
+    const lock = (parse(lockText) ?? {});
+    for (const b of lock.bundles ?? []) {
+        for (const e of b.managed_paths ?? []) {
+            const m = String(e).match(/^[0-9a-f]{64}\s+(.+)$/);
+            out.add(m ? m[1] : String(e));
+        }
+    }
+    return out;
+}
+async function git(cwd, args) {
+    // core.quotepath=false: git otherwise ESCAPES non-ASCII paths ("\342\200\224…",
+    // quoted), so an ADR titled with an em dash never equals its delta.yaml target —
+    // measured: 9 unattributed files on one SDD, 4 of them genuinely targeted.
+    return (await execFile("git", ["-c", "core.quotepath=false", "-C", cwd, ...args], { maxBuffer: 64 * 1024 * 1024 })).stdout;
+}
+/** Every file changed since `ref`, tracked or untracked. */
+export async function changedFiles(sddPath, ref) {
+    const tracked = (await git(sddPath, ["diff", "--name-only", ref, "--"])).split("\n");
+    const untracked = (await git(sddPath, ["ls-files", "--others", "--exclude-standard"])).split("\n");
+    return [...new Set([...tracked, ...untracked].filter((p) => p !== ""))].sort();
+}
+/** The changed files that must be attributed: minus catalogues and advance's pin bookkeeping. */
+export async function changedSourceFiles(sddPath, ref) {
+    return (await changedFiles(sddPath, ref)).filter((p) => !EXEMPT.some((re) => re.test(p)));
+}
+/** Every target, and whether it is precise (file / confirmed grain, or hand-written) or a repo-grain mention. */
+export function targetSet(delta) {
+    const findings = delta?.findings ?? [];
+    const out = new Map();
+    for (const f of findings) {
+        for (const t of f.targets ?? []) {
+            let artefact = null;
+            let precise = true;
+            if (typeof t === "string")
+                artefact = t;
+            else if (t && typeof t === "object" && typeof t.artefact === "string") {
+                artefact = t.artefact;
+                precise = t.grain !== "repo";
+            }
+            if (artefact !== null)
+                out.set(artefact, (out.get(artefact) ?? false) || precise);
+        }
+    }
+    return [...out].map(([artefact, precise]) => ({ artefact, precise }));
+}
+/** "precise" | "mention" | null — how, if at all, a changed file is attributed. */
+export function attributed(file, targets) {
+    const hits = targets.filter((t) => t.artefact === file || (t.artefact.endsWith("/") && file.startsWith(t.artefact)));
+    if (hits.length === 0)
+        return null;
+    return hits.some((t) => t.precise) ? "precise" : "mention";
+}
+async function rowSets(dir) {
+    const out = new Map();
+    for (const f of await readdir(dir)) {
+        if (!f.endsWith(".csv"))
+            continue;
+        const lines = (await readFile(join(dir, f), "utf8")).split("\n").filter((l) => l !== "");
+        out.set(f.replace(/\.csv$/, ""), lines.slice(1));
+    }
+    return out;
+}
+export function rowDelta(before, after) {
+    const count = new Map();
+    for (const r of before)
+        count.set(r, (count.get(r) ?? 0) + 1);
+    let added = 0;
+    for (const r of after) {
+        const c = count.get(r) ?? 0;
+        if (c > 0)
+            count.set(r, c - 1);
+        else
+            added++;
+    }
+    let removed = 0;
+    for (const c of count.values())
+        removed += c;
+    return { added, removed };
+}
+/** Attributed files edited by more than one commit in `from..HEAD`, one line each. */
+export async function coEdits(sddPath, from, files) {
+    const out = [];
+    for (const f of files) {
+        const commits = (await git(sddPath, ["log", "--format=%h %s", `${from}..HEAD`, "--", f])).split("\n").filter((l) => l !== "");
+        if (commits.length > 1)
+            out.push(`  ${f}: ${commits.length} commits — ${commits.map((c) => c.slice(0, 60)).join(" | ")}`);
+    }
+    return out;
+}
+export async function runCatalogueDiff(inputs, write) {
+    const { sddPath, from } = inputs;
+    const delta = parse(await readFile(inputs.attribute, "utf8"));
+    const targets = targetSet(delta);
+    const work = await mkdtemp(join(tmpdir(), "sdd-cli-catalogue-diff-"));
+    try {
+        await git(sddPath, ["rev-parse", "--verify", `${from}^{commit}`]);
+        const beforeTree = join(work, "before-tree");
+        await mkdir(beforeTree);
+        await execFile("git", ["-C", sddPath, "archive", "-o", join(work, "before.tar"), from]);
+        await execFile("tar", ["-xf", join(work, "before.tar"), "-C", beforeTree]);
+        const sink = () => { };
+        const b = await runCatalogueBuild({ sddPath: beforeTree, outDir: join(work, "before") }, sink);
+        const a = await runCatalogueBuild({ sddPath, outDir: join(work, "after") }, sink);
+        write(`built both sides in one process (schema ${a.schemaVersion}); before exit ${b.exitCode}, after exit ${a.exitCode}\n`);
+        // A side that failed to build compared partial catalogues, so its row delta
+        // measures the failure, not the change (empty-set sweep, R2, ruled 2026-09-29).
+        if (b.exitCode !== 0 || a.exitCode !== 0) {
+            const which = [b.exitCode !== 0 ? `before (${from})` : "", a.exitCode !== 0 ? "after (working tree)" : ""]
+                .filter(Boolean)
+                .join(" and ");
+            write(`\nFAIL: the ${which} build failed — the comparison would measure the failure, not the change. Fix the build first\n`);
+            return { exitCode: 1 };
+        }
+        const before = await rowSets(join(work, "before"));
+        const after = await rowSets(join(work, "after"));
+        const changedCatalogues = [];
+        for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+            const d = rowDelta(before.get(name) ?? [], after.get(name) ?? []);
+            if (d.added + d.removed > 0)
+                changedCatalogues.push([name, d]);
+        }
+        const lockNow = await readFile(join(sddPath, "method-baseline.lock"), "utf8").catch(() => null);
+        const lockThen = await git(sddPath, ["show", `${from}:method-baseline.lock`]).catch(() => null);
+        const managed = new Set([...managedPathsOf(lockNow), ...managedPathsOf(lockThen), "method-baseline.lock"]);
+        const all = (await changedFiles(sddPath, from)).filter((p) => !p.startsWith("catalogues/"));
+        const byBundle = all.filter((p) => managed.has(p));
+        const files = all.filter((p) => !EXEMPT.some((re) => re.test(p)) && !managed.has(p));
+        if (byBundle.length > 0)
+            write(`${byBundle.length} changed file(s) are managed by the method bundle (method-baseline.lock) — excluded from attribution\n`);
+        const unattributed = files.filter((f) => attributed(f, targets) === null);
+        const byMention = files.filter((f) => attributed(f, targets) === "mention");
+        write(`\nsource files changed since ${from}: ${files.length} — ${files.length - unattributed.length - byMention.length} attributed precisely, ` +
+            `${byMention.length} by mention only, ${unattributed.length} unattributed\n`);
+        for (const f of byMention)
+            write(`  BY MENTION ONLY ${f} — narrow the target that names it (grain: confirmed) or record the finding it belongs to\n`);
+        for (const f of unattributed)
+            write(`  UNATTRIBUTED ${f}\n`);
+        // Attribution is by FILE: a finding that targets a file covers every edit to it in
+        // the window, including edits the snapshot did not cause (a schema sync riding on a
+        // citation re-point). The tool cannot tell which commit is the snapshot's, so every
+        // attributed file edited by more than one commit is listed for a reader to check.
+        const coEdited = await coEdits(sddPath, from, files.filter((x) => attributed(x, targets) === "precise"));
+        if (coEdited.length > 0) {
+            write(`\n${coEdited.length} attributed file(s) were edited by more than one commit — their other edits are NOT attributed by this check; confirm each belongs to a finding:\n`);
+            for (const l of coEdited)
+                write(`${l}\n`);
+        }
+        write(`\ncatalogues with changed rows: ${changedCatalogues.length}\n`);
+        for (const [name, d] of changedCatalogues)
+            write(`  ${name}: +${d.added} -${d.removed}\n`);
+        let failed = unattributed.length > 0 || byMention.length > 0;
+        // Exempt files (the pin bookkeeping) are excused from attribution, not from
+        // feeding catalogues: they count here, or advance's own edits look like drift.
+        if (all.length === 0 && changedCatalogues.length > 0) {
+            write("\nUNATTRIBUTED: catalogue rows changed while no file did — that is the builder, not the snapshot\n");
+            failed = true;
+        }
+        if (failed) {
+            write("\nFAIL: each unattributed change is an unrecorded finding or an unintended edit — resolve which\n");
+            return { exitCode: 1 };
+        }
+        if (files.length === 0) {
+            // Vacuously true of an empty set: say so rather than claim attribution.
+            write(`\nNOTHING TO ATTRIBUTE: 0 source files changed since ${from} — no finding was needed, and none was checked\n`);
+            return { exitCode: 0 };
+        }
+        write(`\nPASS: every changed source file (${files.length}) is a precise target of some finding\n`);
+        return { exitCode: 0 };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=catalogue-diff.js.map