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

package/dist/lib/snapshot/fold.js

@@ -0,0 +1,208 @@
+// `sdd-cli snapshot fold` — move a flat `source/<repo>@<rev>/` area into its
+// first dated baseline (delta-reverse.md §1), once per area.
+//
+// Then it LISTS every reference to the old paths it can find under the scan
+// roots — relative and absolute alike, since citations use both and a search
+// for one form misses the other. The list is a print, not a control: nothing
+// fails if a reference is left, so the report says so. Scan the whole estate,
+// not only the owning SDD — other SDDs cite this area's baselines.
+//
+// With --sdd-path it also does what it knows how to do: each member's
+// reverse-metadata.yaml whose source_path names a folded folder is re-pointed
+// into the baseline (a minimal text edit), its canonical_repo_key is taken from
+// that metadata rather than guessed from the folder name, and role_hint is
+// derived from its profile where the method defines the mapping
+// (`support-repo` → `ancillary`, delta-reverse.md §1) and left unset otherwise.
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { parse, stringify } from "yaml";
+import { setTopLevelScalars } from "./advance.js";
+import { SnapshotError, baselineIds, deriveKey, knownRepositoryIds, exists, isIsoDate, manifestPath, memberFolders, splitFolder, } from "./manifest.js";
+const ROLE_BY_PROFILE = { "support-repo": "ancillary" };
+/** The same mapping by M-ADR 0213's scope, which replaces the per-repo profile: a support repo is ancillary. */
+const ROLE_BY_SCOPE = { support: "ancillary" };
+/** reverse-metadata.yaml files under <sdd>/repos, by the folder their source_path names. */
+async function pinsByFolder(sddPath) {
+    const out = new Map();
+    const repos = join(sddPath, "repos");
+    if (!(await exists(repos)))
+        return out;
+    for (const e of await readdir(repos, { withFileTypes: true })) {
+        const file = join(repos, e.name, "reverse-metadata.yaml");
+        if (!e.isDirectory() || !(await exists(file)))
+            continue;
+        const text = await readFile(file, "utf8");
+        const meta = (parse(text) ?? {});
+        const folder = String(meta.source_path ?? "").split("/").pop() || String(meta.exported_folder_name ?? "");
+        if (folder)
+            out.set(folder, { file, text, meta });
+    }
+    return out;
+}
+const SKIP = new Set([".git", "node_modules"]);
+// Scripts cite snapshot paths too (a research extractor hard-coding an export): a
+// scan of docs alone reported fewer references than a rewriter reading scripts.
+const TEXT = /\.(md|ya?ml|json|jsonl|txt|adoc|csv|properties|toml|py|ts|js|mjs|sh|mermaid|puml|html)$/i;
+/**
+ * A folder name is a PATH citation only with a `/` beside it: `source/<folder>`,
+ * `<folder>/src/…`. Bare, it is a name — `exported_folder_name: <folder>` is
+ * correct after a fold and must not be reported as stale.
+ */
+export function citesPath(line, folder) {
+    for (let i = line.indexOf(folder); i >= 0; i = line.indexOf(folder, i + 1)) {
+        if (line[i - 1] === "/" || line[i + folder.length] === "/")
+            return true;
+    }
+    return false;
+}
+async function references(root, folders, id) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP.has(e.name) && !isIsoDate(e.name))
+                    await walk(full);
+            }
+            else if (e.isFile() && TEXT.test(e.name) && (await stat(full)).size <= 4 * 1024 * 1024) {
+                const lines = (await readFile(full, "utf8")).split("\n");
+                lines.forEach((line, i) => {
+                    for (const f of folders) {
+                        if (citesPath(line, f) && !line.includes(`${id}/${f}`)) {
+                            out.push(`${relative(root, full).split(sep).join("/")}:${i + 1}: ${f}`);
+                            break;
+                        }
+                    }
+                });
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+export async function runSnapshotFold(inputs, write) {
+    try {
+        const { areaRoot, id } = inputs;
+        const today = inputs.today ?? new Date().toISOString().slice(0, 10);
+        if (id === undefined)
+            throw new SnapshotError("--id is required: the date the flat exports were OBSERVED");
+        if (!isIsoDate(id) || id > today)
+            throw new SnapshotError(`--id '${id}' is not a past or present YYYY-MM-DD date`);
+        if (!inputs.implementation)
+            throw new SnapshotError("--implementation is required: the durable system identity (M-ADR 0181 §2.5)");
+        const existing = await baselineIds(areaRoot);
+        for (const b of existing) {
+            if (await exists(manifestPath(areaRoot, b)))
+                throw new SnapshotError(`${areaRoot} is already folded (baseline ${b} has a manifest)`);
+        }
+        const folders = await memberFolders(areaRoot);
+        if (folders.length === 0)
+            throw new SnapshotError(`no flat <repo>@<revision>/ folders directly under ${areaRoot}`);
+        const pins = inputs.sddPath ? await pinsByFolder(inputs.sddPath) : new Map();
+        const known = inputs.sddPath ? await knownRepositoryIds(inputs.sddPath) : new Set();
+        const problems = [];
+        const unverified = [];
+        const members = folders.map((f) => {
+            const { stem, revision } = splitFolder(f);
+            const pin = pins.get(f);
+            const role = pin ? (ROLE_BY_SCOPE[String(pin.meta.repo_scope ?? "")] ?? ROLE_BY_PROFILE[String(pin.meta.profile ?? "")]) : undefined;
+            let key = inputs.keys?.get(f) ?? (pin?.meta.canonical_repo_key ? String(pin.meta.canonical_repo_key) : undefined);
+            if (key === undefined) {
+                const d = deriveKey(f, stem, known);
+                key = d.key;
+                if (d.problem)
+                    problems.push(d.problem);
+                if (d.unverified)
+                    unverified.push(`${f} -> '${d.key}'`);
+            }
+            return {
+                canonical_repo_key: key,
+                exported_folder_name: f,
+                source_revision: revision,
+                ...(role ? { role_hint: role } : {}),
+            };
+        });
+        // Refused before anything moves: a key written wrong is a record every later
+        // verb, binding and catalogue inherits.
+        if (problems.length > 0)
+            throw new SnapshotError(`${problems.length} derived key(s) are not repository ids:\n  - ${problems.join("\n  - ")}`);
+        for (const u of unverified)
+            write(`UNVERIFIED key (no --sdd-path, so no repository ids to check against): ${u}\n`);
+        const target = join(areaRoot, id);
+        if (await exists(target))
+            throw new SnapshotError(`${target} already exists`);
+        await mkdir(target);
+        for (const f of folders)
+            await rename(join(areaRoot, f), join(target, f));
+        const manifest = { snapshot_id: id, observed_at: id, implementation: inputs.implementation, prior_snapshot: null, members };
+        await writeFile(manifestPath(areaRoot, id), "# Implementation-set snapshot (baseline) -- written by `sdd-cli snapshot fold`.\n" + stringify(manifest, { lineWidth: 0 }));
+        write(`folded ${folders.length} member(s) into ${target}\n`);
+        if (inputs.sddPath) {
+            let repointed = 0;
+            for (const f of folders) {
+                const pin = pins.get(f);
+                if (!pin) {
+                    write(`  no reverse-metadata.yaml in ${inputs.sddPath}/repos names ${f} — its evidence pin is not re-pointed\n`);
+                    continue;
+                }
+                const sp = String(pin.meta.source_path ?? "");
+                const parts = sp.split("/");
+                if (parts.some((p) => isIsoDate(p)))
+                    continue;
+                const next = [...parts.slice(0, -1), id, parts[parts.length - 1]].join("/");
+                const fields = { source_path: next };
+                if (!pin.meta.exported_folder_name)
+                    fields.exported_folder_name = f;
+                await writeFile(pin.file, setTopLevelScalars(pin.text, fields));
+                repointed++;
+            }
+            write(`re-pointed ${repointed} evidence pin(s) in ${inputs.sddPath} into ${id}/\n`);
+            // A pin that names a folder this area does NOT hold — under the same area prefix
+            // as the pins that matched — was stale BEFORE the fold (its export moved or was
+            // never here). Inserting a date would not make it true, so it is listed, not touched.
+            const prefixes = new Set(folders.flatMap((f) => {
+                const sp = String(pins.get(f)?.meta.source_path ?? "");
+                return sp ? [sp.split("/").slice(0, -1).filter((p) => !isIsoDate(p)).join("/")] : [];
+            }));
+            const stale = [...pins.entries()].filter(([folder, pin]) => {
+                if (folders.includes(folder))
+                    return false;
+                const parts = String(pin.meta.source_path ?? "").split("/");
+                return !parts.some((p) => isIsoDate(p)) && prefixes.has(parts.slice(0, -1).join("/"));
+            });
+            for (const [folder, pin] of stale) {
+                write(`  STALE PIN (not re-pointed): ${relative(inputs.sddPath, pin.file)} names ${folder}, which this area does not hold\n`);
+            }
+        }
+        const roots = inputs.scanRoots ?? [];
+        if (roots.length === 0) {
+            write("WARNING: no --scan roots given, so no references were listed. Every citation of the old paths is now stale.\n");
+            return { exitCode: 0 };
+        }
+        let n = 0;
+        for (const r of roots) {
+            for (const hit of await references(r, folders, id)) {
+                write(`  ${r}/${hit}\n`);
+                n++;
+            }
+        }
+        write(`${n} line(s) still cite a pre-fold path. This list is a print, not a control: nothing fails if one is left — ` +
+            "re-point each (reverse-metadata source_path first) and check it resolves on disk.\n");
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED: ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=fold.js.map

package/dist/lib/snapshot/land.js

@@ -0,0 +1,178 @@
+// `sdd-cli snapshot land` — write T1's set manifest (delta-reverse.md §2).
+//
+// Refusals, each a failure a hand run actually made:
+//   - no --id, or an id in the future: the baseline id is the OBSERVATION date and
+//     has no default, so the processing date cannot slip in unasked;
+//   - a member observed after the set date;
+//   - a prior member absent from the export and not declared carried (with a
+//     reason) or removed (with a reason) — never left to be inferred;
+//   - a member re-exported at the same revision whose bytes differ;
+//   - no recorded credential scan, or one with findings but no disposition —
+//     a snapshot owner often cannot remediate upstream code, so findings land
+//     with the disposition on the record, never as a false `clean`;
+//   - an existing snapshot.yaml (no overwrite).
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { SnapshotError, baselineIds, deriveKey, diffTrees, exists, hashTree, isIsoDate, knownRepositoryIds, manifestPath, memberBytesDir, memberFolders, readManifest, splitFolder, } from "./manifest.js";
+export async function runSnapshotLand(inputs, write) {
+    try {
+        const m = await land(inputs, write);
+        write(`landed ${m.snapshot_id}: ${m.members.length} member(s), ${m.members_removed?.length ?? 0} removed\n`);
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED: ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+export async function land(inputs, write) {
+    const { areaRoot } = inputs;
+    const today = inputs.today ?? new Date().toISOString().slice(0, 10);
+    const id = inputs.id;
+    if (id === undefined) {
+        throw new SnapshotError("--id is required: the date the snapshot was OBSERVED. It has no default, so the date it was processed cannot stand in for it.");
+    }
+    if (!isIsoDate(id))
+        throw new SnapshotError(`--id '${id}' is not a YYYY-MM-DD date`);
+    if (id > today)
+        throw new SnapshotError(`--id ${id} is in the future (today is ${today})`);
+    const dir = join(areaRoot, id);
+    if (!(await exists(dir)))
+        throw new SnapshotError(`no baseline folder ${dir} — export the members into it first`);
+    if (await exists(manifestPath(areaRoot, id))) {
+        throw new SnapshotError(`${manifestPath(areaRoot, id)} already exists — land does not overwrite a manifest`);
+    }
+    const priorId = inputs.prior ?? (await baselineIds(areaRoot)).filter((b) => b < id).pop();
+    const prior = priorId === undefined ? null : await readManifest(areaRoot, priorId);
+    const implementation = inputs.implementation ?? prior?.implementation;
+    if (!implementation)
+        throw new SnapshotError("--implementation is required when there is no prior baseline");
+    const scan = inputs.credentialScan;
+    if (!scan || !scan.tool || !scan.version || !scan.date || !scan.result) {
+        throw new SnapshotError("a credential scan must be recorded before anything reads the tree: --credential-scan tool=…,version=…,date=YYYY-MM-DD,result=clean");
+    }
+    if (!isIsoDate(scan.date))
+        throw new SnapshotError(`credential scan date '${scan.date}' is not YYYY-MM-DD`);
+    if (scan.result !== "clean" && !scan.disposition) {
+        throw new SnapshotError(`credential scan result is '${scan.result}': record a disposition=… (what was found, and why it stands — e.g. present at the prior baseline, upstream's to rotate). ` +
+            "Never record `clean` for a scan that found something.");
+    }
+    if (scan.result !== "clean")
+        write(`CREDENTIAL FINDINGS landing on the record: ${scan.result} — ${scan.disposition}\n`);
+    const priorByKey = new Map((prior?.members ?? []).map((m) => [m.canonical_repo_key, m]));
+    const priorByStem = new Map((prior?.members ?? []).flatMap((m) => {
+        const s = splitFolder(m.exported_folder_name);
+        return s ? [[s.stem, m.canonical_repo_key]] : [];
+    }));
+    const known = inputs.sddPath ? await knownRepositoryIds(inputs.sddPath) : new Set();
+    const keyProblems = [];
+    const members = [];
+    const seen = new Set();
+    for (const folder of await memberFolders(dir)) {
+        const { stem, revision } = splitFolder(folder);
+        let key = inputs.keys?.get(folder) ?? priorByStem.get(stem);
+        if (key === undefined) {
+            const d = deriveKey(folder, stem, known);
+            key = d.key;
+            if (d.problem) {
+                keyProblems.push(d.problem);
+                continue;
+            }
+            write(`note: ${folder} is new; canonical_repo_key derived as '${key}'${d.unverified ? " — UNVERIFIED (no --sdd-path)" : ""} (override with --key ${folder}=<key>)\n`);
+        }
+        if (seen.has(key))
+            throw new SnapshotError(`two member folders resolve to canonical_repo_key '${key}'`);
+        seen.add(key);
+        const entry = { canonical_repo_key: key, exported_folder_name: folder, source_revision: revision };
+        const role = inputs.roleHints?.get(key) ?? priorByKey.get(key)?.role_hint;
+        if (role)
+            entry.role_hint = role;
+        const md = inputs.memberDates?.get(key);
+        if (md !== undefined) {
+            if (!isIsoDate(md))
+                throw new SnapshotError(`--member-date ${key}=${md} is not YYYY-MM-DD`);
+            if (md > id)
+                throw new SnapshotError(`member ${key} observed ${md}, after the set date ${id}`);
+            if (md !== id)
+                entry.observed_at = md;
+        }
+        const p = priorByKey.get(key);
+        if (prior && p && p.source_revision === revision) {
+            const before = await hashTree(memberBytesDir(areaRoot, prior, p));
+            const after = await hashTree(join(dir, folder));
+            const d = diffTrees(before, after);
+            const changed = d.added.length + d.removed.length + d.modified.length;
+            if (changed > 0) {
+                throw new SnapshotError(`${key} was re-exported at the same revision ${revision} as ${prior.snapshot_id}, but ${changed} file(s) differ — one of the two exports is not what its name says`);
+            }
+            entry.reverified_at = md ?? id;
+            entry.reverification = `re-exported at the same revision as ${prior.snapshot_id}; ${after.size} file(s) byte-identical`;
+        }
+        members.push(entry);
+    }
+    if (keyProblems.length > 0) {
+        throw new SnapshotError(`${keyProblems.length} derived key(s) are not repository ids:\n  - ${keyProblems.join("\n  - ")}`);
+    }
+    const removed = [];
+    const unaccounted = [];
+    for (const p of prior?.members ?? []) {
+        if (seen.has(p.canonical_repo_key))
+            continue;
+        const reasonCarried = inputs.carried?.get(p.canonical_repo_key);
+        const reasonRemoved = inputs.removed?.get(p.canonical_repo_key);
+        if (reasonCarried && reasonRemoved) {
+            throw new SnapshotError(`${p.canonical_repo_key} is declared both carried and removed`);
+        }
+        if (reasonCarried) {
+            members.push({
+                canonical_repo_key: p.canonical_repo_key,
+                exported_folder_name: p.exported_folder_name,
+                source_revision: p.source_revision,
+                carried_from: p.carried_from ?? prior.snapshot_id,
+                carried_reason: reasonCarried,
+                ...(p.role_hint ? { role_hint: p.role_hint } : {}),
+            });
+        }
+        else if (reasonRemoved) {
+            removed.push({
+                canonical_repo_key: p.canonical_repo_key,
+                last_revision: p.source_revision,
+                last_observed: p.carried_from ?? prior.snapshot_id,
+                reason: reasonRemoved,
+            });
+        }
+        else {
+            unaccounted.push(p.canonical_repo_key);
+        }
+    }
+    if (unaccounted.length > 0) {
+        throw new SnapshotError(`${unaccounted.length} member(s) of ${priorId} are absent from this export and not accounted for: ${unaccounted.join(", ")}.\n` +
+            "  Declare each --carried <key>=<why it was not re-observed> or --removed <key>=<why it left>. " +
+            "An absence nobody can explain yet is an open question: carry it with that as its reason, and never let it be inferred.");
+    }
+    for (const [flag, map] of [["--carried", inputs.carried], ["--removed", inputs.removed]]) {
+        for (const k of map?.keys() ?? []) {
+            if (!priorByKey.has(k) || seen.has(k))
+                throw new SnapshotError(`${flag} ${k}: not a member of ${priorId ?? "the prior baseline"} that is absent from this export`);
+        }
+    }
+    const manifest = {
+        snapshot_id: id,
+        observed_at: id,
+        implementation,
+        prior_snapshot: priorId ?? null,
+        members,
+        ...(removed.length > 0 ? { members_removed: removed } : {}),
+        credential_scan: scan,
+        ...(inputs.notes ? { notes: inputs.notes } : {}),
+    };
+    const header = "# Implementation-set snapshot (baseline) -- reverse/artifact-conventions.md \"Implementation-Set Snapshots\".\n" +
+        "# Written by `sdd-cli snapshot land`.\n";
+    await writeFile(manifestPath(areaRoot, id), header + stringify(manifest, { lineWidth: 0 }));
+    return manifest;
+}
+//# sourceMappingURL=land.js.map

package/dist/lib/snapshot/manifest.js

@@ -0,0 +1,206 @@
+// Implementation-set snapshot manifests (`<area>/<baseline-id>/snapshot.yaml`)
+// and the file-level primitives the `snapshot` verbs share.
+//
+// The shape is the method's, not this module's: reverse/artifact-conventions.md
+// "Implementation-Set Snapshots". Where the conventions REQUIRE a companion
+// field (`carried_reason` beside `carried_from`, `reverification` beside
+// `reverified_at`), readManifest refuses a manifest without it — a carried member
+// with no reason cannot be told apart from an unrecorded removal.
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { parse } from "yaml";
+/** The line every later verb prints while a baseline carries unresolved credential findings. */
+export function credentialNotice(m) {
+    const s = m.credential_scan;
+    if (!s || s.result === "clean")
+        return null;
+    return `CREDENTIAL FINDINGS on record for ${m.snapshot_id}: ${s.result} — ${s.disposition ?? "NO DISPOSITION"}`;
+}
+export class SnapshotError extends Error {
+}
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export function isIsoDate(s) {
+    if (typeof s !== "string" || !DATE.test(s))
+        return false;
+    const d = new Date(`${s}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
+}
+/** `name-branch@rev` → { stem: "name-branch", revision: "rev" }. */
+export function splitFolder(folder) {
+    const at = folder.lastIndexOf("@");
+    if (at <= 0 || at === folder.length - 1)
+        return null;
+    return { stem: folder.slice(0, at), revision: folder.slice(at + 1) };
+}
+/** Member folders (`*@*` directories) directly under a baseline directory. */
+export async function memberFolders(baselineDir) {
+    const out = [];
+    for (const e of await readdir(baselineDir, { withFileTypes: true })) {
+        if (e.isDirectory() && splitFolder(e.name) !== null)
+            out.push(e.name);
+    }
+    return out.sort();
+}
+/** Dated baseline ids under an area, ascending. */
+export async function baselineIds(areaRoot) {
+    const out = [];
+    for (const e of await readdir(areaRoot, { withFileTypes: true })) {
+        if (e.isDirectory() && isIsoDate(e.name))
+            out.push(e.name);
+    }
+    return out.sort();
+}
+export async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function manifestPath(areaRoot, id) {
+    return join(areaRoot, id, "snapshot.yaml");
+}
+export async function readManifest(areaRoot, id) {
+    const p = manifestPath(areaRoot, id);
+    if (!(await exists(p)))
+        throw new SnapshotError(`no manifest at ${p}`);
+    const raw = parse(await readFile(p, "utf8"));
+    if (raw === null || typeof raw !== "object")
+        throw new SnapshotError(`${p}: not a mapping`);
+    const problems = [];
+    if (raw.snapshot_id !== id)
+        problems.push(`snapshot_id '${String(raw.snapshot_id)}' does not match its folder '${id}'`);
+    if (!isIsoDate(raw.observed_at))
+        problems.push("observed_at must be YYYY-MM-DD");
+    if (typeof raw.implementation !== "string" || raw.implementation === "")
+        problems.push("implementation missing");
+    if (raw.prior_snapshot !== null && raw.prior_snapshot !== undefined && !isIsoDate(raw.prior_snapshot)) {
+        problems.push("prior_snapshot must be a baseline id or null");
+    }
+    if (!Array.isArray(raw.members))
+        problems.push("members must be a list");
+    // A hand-written revision of digits only (`50834756022`) parses as a NUMBER, and
+    // a strict comparison with the folder's string suffix then calls an unchanged
+    // member changed. Identity fields are strings, whatever YAML made of them.
+    for (const m of raw.members ?? []) {
+        if (m && typeof m === "object") {
+            for (const f of ["canonical_repo_key", "exported_folder_name", "source_revision"]) {
+                if (typeof m[f] === "number")
+                    m[f] = String(m[f]);
+            }
+        }
+    }
+    for (const r of raw.members_removed ?? []) {
+        if (r && typeof r.last_revision === "number")
+            r.last_revision = String(r.last_revision);
+    }
+    for (const [i, m] of (raw.members ?? []).entries()) {
+        const at = `members[${i}] (${m?.canonical_repo_key ?? "?"})`;
+        if (!m?.canonical_repo_key || !m.exported_folder_name || !m.source_revision) {
+            problems.push(`${at}: canonical_repo_key, exported_folder_name and source_revision are required`);
+        }
+        if (m?.carried_from !== undefined && !m.carried_reason)
+            problems.push(`${at}: carried_from requires carried_reason`);
+        if (m?.reverified_at !== undefined && !m.reverification)
+            problems.push(`${at}: reverified_at requires reverification`);
+    }
+    for (const [i, r] of (raw.members_removed ?? []).entries()) {
+        if (!r?.canonical_repo_key || !r.last_revision || !r.reason) {
+            problems.push(`members_removed[${i}]: canonical_repo_key, last_revision and reason are required`);
+        }
+    }
+    if (problems.length > 0)
+        throw new SnapshotError(`${p}:\n  - ${problems.join("\n  - ")}`);
+    return raw;
+}
+/** Where a member's bytes live: its own baseline, or the one it was carried from. */
+export function memberBytesDir(areaRoot, manifest, m) {
+    return join(areaRoot, m.carried_from ?? manifest.snapshot_id, m.exported_folder_name);
+}
+/** relative path → sha256 for every file under a directory. */
+export async function hashTree(root) {
+    const out = new Map();
+    async function walk(dir) {
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === ".git")
+                    continue;
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                const h = createHash("sha256").update(await readFile(full)).digest("hex");
+                out.set(relative(root, full).split(sep).join("/"), h);
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+export function diffTrees(before, after) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    for (const [p, h] of after) {
+        const b = before.get(p);
+        if (b === undefined)
+            added.push(p);
+        else if (b !== h)
+            modified.push(p);
+    }
+    for (const p of before.keys())
+        if (!after.has(p))
+            removed.push(p);
+    return { added: added.sort(), removed: removed.sort(), modified: modified.sort() };
+}
+const BRANCH_SUFFIX = /-(master|main|develop|trunk)$/;
+/**
+ * The repository ids an SDD declares: every `orchestration/repo-config/**\/<id>.yaml` file
+ * name and every id in its built `catalogues/repositories.csv`. Empty when neither exists.
+ */
+export async function knownRepositoryIds(sddPath) {
+    const out = new Set();
+    const walk = async (dir) => {
+        if (!(await exists(dir)))
+            return;
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            if (e.isDirectory())
+                await walk(join(dir, e.name));
+            else if (/\.ya?ml$/.test(e.name))
+                out.add(e.name.replace(/\.ya?ml$/, ""));
+        }
+    };
+    await walk(join(sddPath, "orchestration", "repo-config"));
+    const csv = join(sddPath, "catalogues", "repositories.csv");
+    if (await exists(csv)) {
+        for (const line of (await readFile(csv, "utf8")).split("\n").slice(1)) {
+            const id = line.split(",")[0]?.trim();
+            if (id)
+                out.add(id);
+        }
+    }
+    return out;
+}
+/**
+ * A canonical_repo_key derived from a folder's stem, checked. Stripping a branch
+ * suffix only works for the four names it knows: a `-_dev` or `-release-1.X` branch
+ * leaves a key that is no repository id, and nothing downstream says so until a
+ * catalogue build cannot resolve it. With the SDD's ids known, such a key is a
+ * PROBLEM naming the nearest id; without them it is marked unverified.
+ */
+export function deriveKey(folder, stem, known) {
+    const key = stem.replace(BRANCH_SUFFIX, "");
+    if (known.size === 0)
+        return { key, unverified: true };
+    if (known.has(key))
+        return { key };
+    const nearest = [...known].filter((id) => stem.startsWith(`${id}-`)).sort((a, b) => b.length - a.length)[0];
+    return {
+        key,
+        problem: `${folder}: derived canonical_repo_key '${key}' is not a repository id of this SDD — ${nearest ? `nearest is '${nearest}' (a branch suffix?): pass --key ${folder}=${nearest}` : `pass --key ${folder}=<repository id>`}`,
+    };
+}
+//# sourceMappingURL=manifest.js.map