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

package/dist/lib/sync/settings-merge.js

@@ -0,0 +1,216 @@
+/**
+ * `.claude/settings.json` merge pass during `sdd-cli sync`. Method-
+ * managed `mcpServers` entries (see src/lib/mcp-seed/) get upserted;
+ * any adopter-added entries or other top-level keys are preserved.
+ *
+ * The file cannot ship in the method baseline bundle because it
+ * carries per-adopter absolute paths. That's why this is a separate
+ * sync step, outside the bundle-driven `copyManagedFiles` path.
+ *
+ * Conflict handling mirrors ADR 0114: if the adopter has manually
+ * modified a method-owned entry, sync refuses unless
+ * `--allow-overwrite` is passed.
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { buildMethodManagedServers, detectManagedDrift, upsertMethodManagedServers, } from "../mcp-seed/index.js";
+import { buildMethodManagedHooks, detectHooksDrift, upsertMethodManagedHooks, } from "../hooks-seed/index.js";
+export const SETTINGS_REL_PATH = ".claude/settings.json";
+export async function syncMethodManagedSettings(opts) {
+    const absPath = join(opts.targetRepo, SETTINGS_REL_PATH);
+    const existing = await readSettings(absPath);
+    // No profile gets an SDD_REPO_PATH any more (ruled 2026-10-01). It was written for platform
+    // repos only because the resolver treated a marker-bearing repo as one candidate among its
+    // marker-bearing siblings (MULTIPLE_SDDS_FOUND in the reverse estate's layout). The resolver now
+    // lets a platform-product repo serve itself, so the env var, an absolute, machine-specific
+    // path in a COMMITTED file, is no longer needed. A value left by an older sync that points at
+    // the repo itself is this tool's own output and is removed (normaliseSddRepoPathForDrift); a
+    // value pointing anywhere else is the adopter's and is still drift. App/integration repos
+    // configure their sibling platform SDD as before.
+    const owned = buildMethodManagedServers({});
+    // Drift is detected against a PATH-NORMALISED view of the existing file,
+    // not the raw bytes. Reason, measured on a live estate: the F27 defect
+    // wrote the literal CLI argument (".") as SDD_REPO_PATH. Once the
+    // generator was fixed to emit the absolute form, a strict comparison
+    // classified the defect's own historical output as an ADOPTER
+    // modification and refused to correct it — while the only offered remedy,
+    // --allow-overwrite, is the flag that rewrites genuinely adopter-owned
+    // keys. A repair that requires the dangerous flag is not a repair. So: an
+    // existing SDD_REPO_PATH that RESOLVES (from the target repo) to the same
+    // absolute path as the generated value is the tool's own output in an
+    // older costume, and is treated as regenerable, never as drift. The raw
+    // `existing` still flows into the upsert below, so the merge rewrites the
+    // stale form to the canonical one — the sync self-heals instead of
+    // wedging. A path that resolves DIFFERENTLY is still drift.
+    const drifted = detectManagedDrift(normaliseSddRepoPathForDrift(existing, owned, opts.targetRepo), owned);
+    // Computed from the state as READ, before any upsert: which method-managed ids
+    // were absent from the file this run opened. Combined with `hadPreviousSync`
+    // that is a re-seed; without it, a first seeding. Deliberately not derived
+    // from the upsert's `added`, which cannot tell the two apart — that conflation
+    // IS the defect.
+    const absentOnRead = absentManagedIds(existing, owned);
+    const reseeded = opts.hadPreviousSync === true ? absentOnRead : [];
+    const hooksActive = opts.agentHarness === "claude-code";
+    const ownedHooks = hooksActive ? buildMethodManagedHooks() : undefined;
+    const hooksDrifted = hooksActive && ownedHooks
+        ? detectHooksDrift(existing, ownedHooks)
+        : [];
+    if ((drifted.length > 0 || hooksDrifted.length > 0) && !opts.allowOverwrite) {
+        return {
+            path: SETTINGS_REL_PATH,
+            drifted,
+            added: [],
+            // Reported even on the refusal path: the re-seed was OBSERVED when the
+            // file was read, and it stays true whether or not this run went on to
+            // write. Zeroing it here would make a refusal hide a second finding.
+            reseeded,
+            updated: [],
+            unchanged: [],
+            hooksChangedEvents: [],
+            hooksDrifted,
+            wroteFile: false,
+            refused: true,
+        };
+    }
+    if (opts.checkOnly) {
+        return {
+            path: SETTINGS_REL_PATH,
+            drifted,
+            added: [],
+            reseeded,
+            updated: [],
+            unchanged: [],
+            hooksChangedEvents: [],
+            hooksDrifted,
+            wroteFile: false,
+            refused: false,
+        };
+    }
+    const mcpResult = upsertMethodManagedServers(existing, owned);
+    let nextSettings = mcpResult.settings;
+    let hooksChangedEvents = [];
+    if (hooksActive && ownedHooks) {
+        const hooksResult = upsertMethodManagedHooks(nextSettings, ownedHooks);
+        nextSettings = hooksResult.settings;
+        hooksChangedEvents = [...hooksResult.changedEvents];
+    }
+    const changed = mcpResult.changed || hooksChangedEvents.length > 0;
+    if (!changed) {
+        return {
+            path: SETTINGS_REL_PATH,
+            drifted,
+            added: mcpResult.added,
+            reseeded,
+            updated: mcpResult.updated,
+            unchanged: mcpResult.unchanged,
+            hooksChangedEvents: [],
+            hooksDrifted,
+            wroteFile: false,
+            refused: false,
+        };
+    }
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, JSON.stringify(nextSettings, null, 2) + "\n", "utf8");
+    return {
+        path: SETTINGS_REL_PATH,
+        drifted,
+        added: mcpResult.added,
+        reseeded,
+        updated: mcpResult.updated,
+        unchanged: mcpResult.unchanged,
+        hooksChangedEvents,
+        hooksDrifted,
+        wroteFile: true,
+        refused: false,
+    };
+}
+/**
+ * Method-managed ids absent from the settings file as read.
+ *
+ * A missing or malformed `mcpServers` map counts every managed id as absent —
+ * `readSettings` already collapses an unparseable file to `{}`, and a file whose
+ * managed block was destroyed rather than edited is exactly the re-seed case
+ * this exists to name.
+ */
+function absentManagedIds(existing, owned) {
+    const servers = existing["mcpServers"];
+    const present = servers && typeof servers === "object" && !Array.isArray(servers)
+        ? servers
+        : {};
+    return Object.keys(owned)
+        .filter((id) => !(id in present))
+        .sort();
+}
+async function readSettings(absPath) {
+    if (!(await fileExists(absPath)))
+        return {};
+    const raw = await readFile(absPath, "utf8");
+    if (raw.trim().length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* fall through — treat malformed as empty so we at least seed method content */
+    }
+    return {};
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A view of `existing` for drift detection ONLY: where a method-managed
+ * entry's `env.SDD_REPO_PATH` resolves (from the target repo) to the same
+ * absolute path as the generated value, substitute the generated form.
+ *
+ * This makes "the tool's own older output" (the F27 relative-path defect,
+ * or a lexically different spelling of the same location) compare as
+ * pristine, so the merge proceeds and REWRITES it — while a path that
+ * resolves somewhere else entirely remains drift and still refuses.
+ * Never used for the write: the raw `existing` flows into the upsert, so
+ * the correction actually lands on disk.
+ */
+function normaliseSddRepoPathForDrift(existing, owned, targetRepo) {
+    const servers = existing["mcpServers"];
+    if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+        return existing;
+    }
+    const current = servers;
+    const out = {};
+    let touched = false;
+    for (const [id, entry] of Object.entries(current)) {
+        const existingPath = entry?.env?.["SDD_REPO_PATH"];
+        const ownedPath = owned[id]?.env?.["SDD_REPO_PATH"];
+        if (typeof existingPath === "string" &&
+            ownedPath === undefined &&
+            resolve(targetRepo, existingPath) === resolve(targetRepo)) {
+            // The retired platform SDD_REPO_PATH, pointing at the repo itself: regenerable, so the
+            // drift view drops it and the write (which replaces the entry whole) removes it.
+            const { SDD_REPO_PATH: _dropped, ...rest } = entry.env ?? {};
+            const { env: _env, ...bare } = entry;
+            out[id] = Object.keys(rest).length > 0 ? { ...bare, env: rest } : bare;
+            touched = true;
+        }
+        else if (typeof existingPath === "string" &&
+            typeof ownedPath === "string" &&
+            existingPath !== ownedPath &&
+            resolve(targetRepo, existingPath) === resolve(ownedPath)) {
+            out[id] = { ...entry, env: { ...entry.env, SDD_REPO_PATH: ownedPath } };
+            touched = true;
+        }
+        else {
+            out[id] = entry;
+        }
+    }
+    return touched ? { ...existing, mcpServers: out } : existing;
+}
+//# sourceMappingURL=settings-merge.js.map

package/dist/lib/sync/yaml-block-merge.js

@@ -0,0 +1,120 @@
+/**
+ * Merge-aware write for files with `# method-managed: begin/end`
+ * markers. The method block is replaced; content outside the block
+ * (including content above a lone trailing block, or below it, or
+ * both) is preserved verbatim.
+ *
+ * Conflict model (per ADR 0114, narrowed to block scope):
+ *  - If the existing file has no markers, treat it as adopter-authored.
+ *    Refuse to replace unless `allowOverwrite` is true.
+ *  - If the existing file has markers, upsert the block. Lines outside
+ *    the markers survive unchanged.
+ *  - Drift inside the block does not block here — callers compare the
+ *    in-block slice to the incoming slice separately if they need
+ *    refuse-on-drift semantics (see `detectBlockDrift`).
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export function mergeMarkedBlock(opts) {
+    const existing = opts.existing ?? "";
+    const { begin, end } = opts.markers;
+    const beginIdx = existing.indexOf(begin);
+    const endIdx = existing.indexOf(end, beginIdx === -1 ? 0 : beginIdx);
+    if (existing === "") {
+        return {
+            output: opts.incomingBlock.endsWith("\n")
+                ? opts.incomingBlock
+                : opts.incomingBlock + "\n",
+            refused: false,
+            changed: true,
+            preAdopter: "",
+            postAdopter: "",
+        };
+    }
+    if (beginIdx === -1 || endIdx === -1) {
+        // Existing file has no markers — treat as adopter-authored.
+        if (!opts.allowOverwrite) {
+            return {
+                output: existing,
+                refused: true,
+                changed: false,
+                preAdopter: existing,
+                postAdopter: "",
+            };
+        }
+        // Overwrite: replace the whole file with the method block.
+        return {
+            output: opts.incomingBlock.endsWith("\n")
+                ? opts.incomingBlock
+                : opts.incomingBlock + "\n",
+            refused: false,
+            changed: existing !== opts.incomingBlock,
+            preAdopter: existing,
+            postAdopter: "",
+        };
+    }
+    let preAdopter = existing.slice(0, beginIdx);
+    let postAdopter = existing.slice(endIdx + end.length);
+    if (opts.scaffold?.pre !== undefined && preAdopter.trim() === "") {
+        preAdopter = opts.scaffold.pre;
+    }
+    if (opts.scaffold?.post !== undefined && postAdopter.trim() === "") {
+        postAdopter = opts.scaffold.post;
+    }
+    const output = preAdopter +
+        opts.incomingBlock +
+        (postAdopter.startsWith("\n") ? postAdopter : "\n" + postAdopter);
+    const finalOutput = output.endsWith("\n") ? output : output + "\n";
+    return {
+        output: finalOutput,
+        refused: false,
+        changed: finalOutput !== existing,
+        preAdopter,
+        postAdopter,
+    };
+}
+/**
+ * Detect whether the method block in `existing` differs from the
+ * incoming block. Returns true if the adopter has edited inside the
+ * markers (drift); false if no markers, exact match, or no file.
+ * Callers use this to implement refuse-on-drift policy where desired.
+ */
+export function detectBlockDrift(existing, incomingBlock, markers) {
+    if (!existing)
+        return false;
+    const beginIdx = existing.indexOf(markers.begin);
+    const endIdx = existing.indexOf(markers.end, beginIdx === -1 ? 0 : beginIdx);
+    if (beginIdx === -1 || endIdx === -1)
+        return false;
+    const currentBlock = existing.slice(beginIdx, endIdx + markers.end.length);
+    return currentBlock !== incomingBlock.trimEnd();
+}
+/**
+ * Apply the merge and write the result to disk. Creates the target
+ * directory if absent.
+ */
+export async function writeMarkedBlockFile(absPath, incomingBlock, markers, allowOverwrite, scaffold) {
+    const existing = await tryReadFile(absPath);
+    const result = mergeMarkedBlock({
+        existing,
+        incomingBlock,
+        markers,
+        allowOverwrite,
+        scaffold,
+    });
+    if (!result.refused && result.changed) {
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, result.output, "utf8");
+    }
+    return result;
+}
+async function tryReadFile(path) {
+    try {
+        await access(path);
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=yaml-block-merge.js.map

package/dist/lib/validate/aggregate.js

@@ -0,0 +1,51 @@
+const WARN_MARKER = "[WARN]";
+// A validator that ran over an EMPTY population says so with an `[N/A]` line
+// and prints no `[PASS]`. Counting it as passed is the vacuous pass the
+// empty-set sweep measured (an empty platform SDD validated `passed=8`); it is
+// counted apart instead (R1, ruled 2026-09-29). Exit codes are unchanged: a
+// run that measured nothing neither passes nor fails the gate — it is named.
+// A script that measured PART of its population prints real `[PASS]` lines,
+// so a stray `[N/A]` on one sub-check never demotes a real pass.
+const NA_LINE = /^\[N\/A\]/m;
+const PASS_LINE = /^\[PASS\]/m;
+export function classifyResult(r, opts) {
+    if (r.status === "skip")
+        return "skipped";
+    if (r.exitCode !== 0)
+        return "failed";
+    const hasWarn = r.stdout.includes(WARN_MARKER);
+    if (opts.strict && hasWarn)
+        return "failed";
+    if (NA_LINE.test(r.stdout) && !PASS_LINE.test(r.stdout))
+        return "not-measured";
+    return hasWarn ? "warned" : "passed";
+}
+export function aggregateResults(results, opts) {
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    let warned = 0;
+    let notMeasured = 0;
+    for (const r of results) {
+        const outcome = classifyResult(r, opts);
+        if (r.status === "run" && r.exitCode === 0 && r.stdout.includes(WARN_MARKER))
+            warned++;
+        if (outcome === "skipped")
+            skipped++;
+        else if (outcome === "failed")
+            failed++;
+        else if (outcome === "not-measured")
+            notMeasured++;
+        else
+            passed++;
+    }
+    return {
+        exitCode: failed > 0 ? 1 : 0,
+        passed,
+        failed,
+        skipped,
+        warned,
+        notMeasured,
+    };
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/lib/validate/bundle-coherence.js

@@ -0,0 +1,74 @@
+// Profile → bundle coherence (A2 of the bundle-migration plan).
+//
+// A repo's declared profile (`.sdd/sdd-manifest.yaml`) and the forward base
+// its lock carries can silently disagree: a reclassification edits the
+// manifest, nothing re-syncs the bundle, and no instrument notices — the
+// registration/adoption-lag class. Measured instance: two platform-subsystem
+// repos carried app-baseline for eight days, found by a human sweep.
+//
+// REPORTING-ONLY: a mismatch prints a [REPORT] line with the migration path
+// and exits 0. Gating is a later, deliberate change-set once both estates
+// read 0 (the scores-coverage precedent, M-ADR 0205 §4.5).
+import { readLockFile, findForwardBase } from "../lock-file.js";
+import { loadSddManifest, } from "../catalogue/manifest-loader.js";
+import { getSddCliVersion } from "../package-version.js";
+/**
+ * Manifest profile → the forward base that profile expects. Profiles with no
+ * entry (support-repo, organisation-profile) carry no expectation — silence,
+ * not a guess. NOTE: platform-subsystem is a CATEGORY under platform-profile,
+ * so the two measured mismatch repos resolve through the platform-profile row.
+ */
+const EXPECTED_FORWARD_BASE = {
+    "platform-profile": "platform-baseline",
+    "application-product": "app-baseline",
+    "integration-product": "integration-baseline",
+};
+export async function checkBundleCoherence(targetRepo) {
+    const lines = [];
+    const lock = await readLockFile(targetRepo);
+    const forwardBase = findForwardBase(lock);
+    if (!forwardBase) {
+        return {
+            exitCode: 0,
+            stdout: "",
+            skipped: "no forward base in method-baseline.lock — nothing to check",
+        };
+    }
+    let profile;
+    try {
+        const manifest = await loadSddManifest(targetRepo, {
+            cliVersion: getSddCliVersion(),
+        });
+        profile = manifest.profile;
+    }
+    catch (err) {
+        // Reporting-only: an absent/invalid manifest is its own (already-gated)
+        // problem; this check must not double-report it as a bundle mismatch.
+        return {
+            exitCode: 0,
+            stdout: "",
+            skipped: `manifest unavailable (${err.message.split("\n")[0]})`,
+        };
+    }
+    const expected = EXPECTED_FORWARD_BASE[profile];
+    if (expected === undefined) {
+        // Nothing to compare is not a pass: counting it as one inflated the
+        // suite's "passed" figure for profiles that carry no expectation.
+        return {
+            exitCode: 0,
+            stdout: "",
+            skipped: `profile '${profile}' declares no forward-base expectation — nothing to compare`,
+        };
+    }
+    if (forwardBase.name === expected) {
+        lines.push(`[PASS] bundle-coherence: profile '${profile}' ↔ forward base '${forwardBase.name}'\n`);
+        return { exitCode: 0, stdout: lines.join("") };
+    }
+    lines.push(`[REPORT] bundle-coherence: profile '${profile}' expects forward base '${expected}' ` +
+        `but the lock carries '${forwardBase.name}' — profile and bundle disagree. ` +
+        `Migration path: sdd-cli sync --bundle <${expected} tarball> --replace-bundle ${forwardBase.name} --dry-run, ` +
+        `review the three-way split, then re-run with --yes. ` +
+        `(Reporting-only; this check does not gate.)\n`);
+    return { exitCode: 0, stdout: lines.join("") };
+}
+//# sourceMappingURL=bundle-coherence.js.map