@sdd-method/verify-cli 0.1.0

package/dist/lib/pack/seed.js

@@ -0,0 +1,182 @@
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Adopter pack seed file. Per ADR 0151 + context-pack-seed-schema.yaml.
+ *
+ * Loaded by `sdd-cli pack build` and `sdd-cli pack validate` from
+ * `orchestration/distribution/{pack-name}-seed.yaml` in adopter repos.
+ *
+ * Includes are resolved before validation: the merged seed presents
+ * all `include`'d managed_paths + forbidden_paths concatenated with
+ * the host seed's own.
+ */
+/**
+ * Authored seed keys, snake_case → the camelCase field they map to.
+ *
+ * THE SINGLE SOURCE OF TRUTH for "what may appear in a seed file". It lived only
+ * inside the canonical-conformance test, which meant the loader had no idea what a
+ * valid key set was — so an unrecognised key was dropped by the hand-mapping below
+ * without a word. An adopter following a schema that documents a field their sdd-cli
+ * predates got a clean validation and a silent no-op: the same failure M-ADR 0175's
+ * history records for `packaging`, and the same one fixed for `.sdd/sdd-manifest.yaml`
+ * in 0.110.1 — but by a different mechanism, which is why that fix did not cover this.
+ *
+ * The conformance test now imports this rather than declaring its own copy. Two
+ * hand-maintained lists of the same facts is how the lifecycle expectation drifted.
+ */
+export const SEED_KEY_TO_FIELD = {
+    version: "version",
+    scope: "scope",
+    forward_base: "forwardBase",
+    vendor_base: "vendorBase",
+    minimum_sdd_cli_version: "minimumSddCliVersion",
+    description: "description",
+    include: "include",
+    managed_paths: "managedPaths",
+    forbidden_paths: "forbiddenPaths",
+    scaffold_source_paths: "scaffoldSourcePaths",
+    requires_pack: "requiresPack",
+};
+/**
+ * Top-level keys in a seed file that this build does not recognise.
+ *
+ * Deliberately TOP-LEVEL only, stated as a limit rather than left implied: nested
+ * blocks (`forward_base`, `vendor_base`, `requires_pack`) are hand-mapped field by
+ * field too, so an unknown key inside one is still dropped silently today.
+ */
+export function unknownSeedKeys(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return [];
+    return Object.keys(raw)
+        .filter((k) => !(k in SEED_KEY_TO_FIELD))
+        .sort();
+}
+/**
+ * Load a seed file from disk, resolve its `include:` directives,
+ * and return a merged PackSeed. Throws if any include cannot be read
+ * or if circular includes are detected.
+ *
+ * NOTE: This does not validate the seed structure — only parses YAML
+ * and assembles the typed shape. Use `validateSeed` (separate module)
+ * for schema enforcement.
+ */
+export async function loadSeed(seedPath) {
+    const absPath = isAbsolute(seedPath) ? seedPath : resolve(seedPath);
+    const visited = new Set();
+    return loadSeedRecursive(absPath, visited);
+}
+async function loadSeedRecursive(absPath, visited) {
+    if (visited.has(absPath)) {
+        throw new Error(`Circular include detected at ${absPath}`);
+    }
+    visited.add(absPath);
+    let raw;
+    try {
+        raw = await readFile(absPath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`Cannot read seed file ${absPath}: ${err.message}`);
+    }
+    const parsed = parseYaml(raw);
+    if (parsed === null || typeof parsed !== "object") {
+        throw new Error(`Seed file ${absPath} is not a YAML object`);
+    }
+    const baseDir = dirname(absPath);
+    const includes = Array.isArray(parsed.include) ? parsed.include : [];
+    const includedManaged = [];
+    const includedForbidden = [];
+    const includedUnknown = [];
+    for (const inc of includes) {
+        if (typeof inc !== "string") {
+            throw new Error(`Non-string include entry in ${absPath}: ${String(inc)}`);
+        }
+        const incPath = isAbsolute(inc) ? inc : resolve(baseDir, inc);
+        const includedSeed = await loadSeedRecursive(incPath, visited);
+        includedManaged.push(...includedSeed.managedPaths);
+        if (includedSeed.forbiddenPaths) {
+            includedForbidden.push(...includedSeed.forbiddenPaths);
+        }
+        if (includedSeed.unknownKeys)
+            includedUnknown.push(...includedSeed.unknownKeys);
+    }
+    // Unknown keys from this file, plus everything its includes reported. An included
+    // seed's stray key is as silently dropped as the root's, so the queue is unioned.
+    const ownUnknown = unknownSeedKeys(parsed);
+    const own = parsed;
+    const managedPaths = [
+        ...includedManaged,
+        ...asStringArray(own.managed_paths, "managed_paths", absPath),
+    ];
+    const forbiddenPaths = includedForbidden.length > 0 || Array.isArray(own.forbidden_paths)
+        ? [
+            ...includedForbidden,
+            ...asStringArray(own.forbidden_paths, "forbidden_paths", absPath, true),
+        ]
+        : undefined;
+    const scaffoldSourcePaths = Array.isArray(own.scaffold_source_paths)
+        ? asStringArray(own.scaffold_source_paths, "scaffold_source_paths", absPath, true)
+        : undefined;
+    const seed = {
+        version: asString(own.version, "version", absPath),
+        scope: asString(own.scope, "scope", absPath),
+        // forward_base optional per ADR 0176 §4.6 (profile-agnostic packs omit it)
+        ...(own.forward_base && {
+            forwardBase: {
+                bundle: asString(own.forward_base.bundle, "forward_base.bundle", absPath),
+                minimumVersion: asString(own.forward_base.minimum_version, "forward_base.minimum_version", absPath),
+                sourceRepo: own.forward_base.source_repo
+                    ? asString(own.forward_base.source_repo, "forward_base.source_repo", absPath)
+                    : "sdd-method",
+            },
+        }),
+        // vendor_base present only on a vendor-base pack (M-ADR 0175); the
+        // profile-agnostic/forward_base contradiction is caught in validateSeed.
+        ...(own.vendor_base && {
+            vendorBase: {
+                vendor: asString(own.vendor_base.vendor, "vendor_base.vendor", absPath),
+                vendorVersion: asString(own.vendor_base.vendor_version, "vendor_base.vendor_version", absPath),
+            },
+        }),
+        minimumSddCliVersion: asString(own.minimum_sdd_cli_version, "minimum_sdd_cli_version", absPath),
+        description: asString(own.description, "description", absPath),
+        managedPaths,
+        sourcePath: absPath,
+        ...(ownUnknown.length + includedUnknown.length > 0
+            ? { unknownKeys: [...new Set([...includedUnknown, ...ownUnknown])].sort() }
+            : {}),
+        ...(includes.length > 0 && { include: includes }),
+        ...(forbiddenPaths && { forbiddenPaths }),
+        ...(scaffoldSourcePaths && scaffoldSourcePaths.length > 0 && { scaffoldSourcePaths }),
+        ...(own.requires_pack && {
+            requiresPack: {
+                name: asString(own.requires_pack.name, "requires_pack.name", absPath),
+                version: asString(own.requires_pack.version, "requires_pack.version", absPath),
+            },
+        }),
+    };
+    return seed;
+}
+function asString(value, field, file) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Seed field "${field}" must be a non-empty string in ${file}`);
+    }
+    return value;
+}
+function asStringArray(value, field, file, allowEmpty = false) {
+    if (value === undefined || value === null) {
+        if (allowEmpty)
+            return [];
+        throw new Error(`Seed field "${field}" is required in ${file}`);
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Seed field "${field}" must be a list in ${file}`);
+    }
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            throw new Error(`Seed field "${field}" entries must be strings in ${file}`);
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=seed.js.map

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 { getPackageVersion } 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 ${getPackageVersion()} ` +
+            `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,25 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } 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;
+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;
+}
+//# 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/validate/aggregate.js

@@ -0,0 +1,35 @@
+const WARN_MARKER = "[WARN]";
+export function aggregateResults(results, opts) {
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    let warned = 0;
+    for (const r of results) {
+        if (r.status === "skip") {
+            skipped++;
+            continue;
+        }
+        const hasWarn = r.stdout.includes(WARN_MARKER);
+        if (r.exitCode !== 0) {
+            failed++;
+        }
+        else if (hasWarn) {
+            warned++;
+            if (opts.strict)
+                failed++;
+            else
+                passed++;
+        }
+        else {
+            passed++;
+        }
+    }
+    return {
+        exitCode: failed > 0 ? 1 : 0,
+        passed,
+        failed,
+        skipped,
+        warned,
+    };
+}
+//# sourceMappingURL=aggregate.js.map

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

@@ -0,0 +1,69 @@
+// 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 { getPackageVersion } 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: getPackageVersion(),
+        });
+        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) {
+        lines.push(`[PASS] bundle-coherence: profile '${profile}' declares no forward-base expectation\n`);
+        return { exitCode: 0, stdout: lines.join("") };
+    }
+    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