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

package/dist/lib/ci-binding/index.js

@@ -0,0 +1,220 @@
+/**
+ * CI host bindings (M-ADR 0219 §4.4): `sync --ci-binding github | gitlab | jenkins` renders ONE host
+ * wrapper, which installs the pinned Dagger CLI and calls the Method Validation module, and writes
+ * the module itself at MODULE_DIR (§4.3). The wrapper is a method-managed block inside the host's
+ * file, so adopter content outside the markers survives; the module is wholly method-managed.
+ *
+ * Both are digest-tracked in the lock (M-ADR 0218 §4.7): content that still hashes to what sync last
+ * wrote is pristine and re-renders with no override, and only an edited copy needs --allow-overwrite.
+ * The binding is remembered in the lock too (`ci_binding:`, absent meaning github), so an estate
+ * chooses it once.
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { BLOCK_BEGIN, BLOCK_END, WORKFLOW_REL_PATH, renderMethodManagedWorkflowBlock, renderMethodValidationWorkflow, } from "../init/ci-workflow.js";
+import { detectBlockDrift, writeMarkedBlockFile } from "../sync/yaml-block-merge.js";
+import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, moduleSha256, renderModuleFiles } from "./module.js";
+export const CI_BINDINGS = ["github", "gitlab", "jenkins"];
+/** M-ADR 0219 §8.2 (ruled 2026-10-16): what every SDD has before it chooses. */
+export const DEFAULT_CI_BINDING = "github";
+/**
+ * Runner labels (sync --ci-runner): where the host runs the job. One label is a word of letters,
+ * digits, '.', '_' or '-', so a label can never inject YAML or Groovy into a wrapper.
+ */
+export const CI_RUNNER_DEFAULT = "default";
+const RUNNER_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function parseCiRunner(s) {
+    const labels = s.split(",").map((l) => l.trim());
+    return labels.length > 0 && labels.every((l) => RUNNER_LABEL.test(l)) ? labels : null;
+}
+export function isCiBinding(s) {
+    return CI_BINDINGS.includes(s);
+}
+const HASH = { begin: BLOCK_BEGIN, end: BLOCK_END };
+// Groovy has no '#' comments.
+const SLASH = { begin: "// method-managed: begin", end: "// method-managed: end" };
+function header(comment, profile) {
+    return [
+        `${comment} Method Validation per M-ADR 0129, run by the method's Dagger module (M-ADR 0219).`,
+        `${comment} Refreshed by \`sdd-cli sync\`; content inside the method-managed`,
+        `${comment} markers must not be hand-edited (sync refuses without --allow-overwrite).`,
+        `${comment} Profile: ${profile}`,
+        comment,
+        `${comment} The job is defined once, in ${MODULE_DIR}/, and this file only calls it,`,
+        `${comment} so CI on any host and a local run cannot disagree. The runner must`,
+        `${comment} provide a container engine Dagger can drive (M-ADR 0219 §4.5).`,
+        comment,
+        `${comment} Run it locally:`,
+        `${comment}   ${MODULE_CALL}`,
+    ];
+}
+// GitLab: a Docker-in-Docker service, the shape GitLab documents for Dagger. The runner must allow
+// privileged containers; that is the adopter's infrastructure (M-ADR 0219 §4.5). No `stage:`, so
+// the job lands in the default `test` stage whatever stages the adopter declares around it.
+function gitlabBlock(profile, runner) {
+    return [
+        HASH.begin,
+        ...header("#", profile),
+        "",
+        "method-validation:",
+        "  image: docker:27.3.1",
+        ...(runner !== undefined && runner.length > 0 ? [`  tags: [${runner.join(", ")}]`] : []),
+        "  services:",
+        "    - docker:27.3.1-dind",
+        "  variables:",
+        "    DOCKER_HOST: tcp://docker:2376",
+        '    DOCKER_TLS_CERTDIR: "/certs"',
+        '    DOCKER_TLS_VERIFY: "1"',
+        '    DOCKER_CERT_PATH: "/certs/client"',
+        "  rules:",
+        '    - if: $CI_PIPELINE_SOURCE == "merge_request_event"',
+        "    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH",
+        "  before_script:",
+        "    - apk add --no-cache curl",
+        `    - curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=/usr/local/bin DAGGER_VERSION=${DAGGER_VERSION} sh`,
+        "  script:",
+        `    - ${MODULE_CALL}`,
+        HASH.end,
+    ].join("\n");
+}
+// Jenkins: a declarative pipeline at its own path, so it never collides with an adopter's
+// Jenkinsfile; the job's Script Path points at it. The agent must reach a Docker daemon. Dagger is
+// installed outside the workspace, so the binary is not uploaded with --source.
+function jenkinsBlock(profile, runner) {
+    return [
+        SLASH.begin,
+        ...header("//", profile),
+        "",
+        "pipeline {",
+        runner !== undefined && runner.length > 0 ? `  agent { label '${runner.join(" && ")}' }` : "  agent any",
+        "  stages {",
+        "    stage('Method Validation') {",
+        "      steps {",
+        `        sh 'curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR="$WORKSPACE@tmp/dagger" DAGGER_VERSION=${DAGGER_VERSION} sh'`,
+        `        sh 'PATH="$WORKSPACE@tmp/dagger:$PATH" ${MODULE_CALL}'`,
+        "      }",
+        "    }",
+        "  }",
+        "}",
+        SLASH.end,
+    ].join("\n");
+}
+export const HOST_WRAPPERS = {
+    github: {
+        relPath: WORKFLOW_REL_PATH,
+        markers: HASH,
+        block: renderMethodManagedWorkflowBlock,
+        file: renderMethodValidationWorkflow,
+    },
+    gitlab: {
+        relPath: ".gitlab-ci.yml",
+        markers: HASH,
+        block: gitlabBlock,
+        file: (p, r) => gitlabBlock(p, r) + "\n\n# Adopter-specific jobs go below, outside the method-managed markers.\n",
+    },
+    jenkins: {
+        relPath: ".jenkins/method-validation.Jenkinsfile",
+        markers: SLASH,
+        block: jenkinsBlock,
+        file: (p, r) => jenkinsBlock(p, r) + "\n",
+    },
+};
+/** sha256 of a host file's method-managed block (begin marker through end marker), or null without one. */
+export function blockSha256(text, markers) {
+    if (text === null)
+        return null;
+    const b = text.indexOf(markers.begin);
+    const e = b === -1 ? -1 : text.indexOf(markers.end, b);
+    if (b === -1 || e === -1)
+        return null;
+    return createHash("sha256").update(text.slice(b, e + markers.end.length)).digest("hex");
+}
+/** Bring the host wrapper and the module up to this sdd-cli's render, or say why not. */
+export async function syncCiBinding(o) {
+    const failures = [];
+    const log = [];
+    const host = HOST_WRAPPERS[o.binding];
+    const sameBinding = (o.prevLock?.ciBinding ?? DEFAULT_CI_BINDING) === o.binding;
+    // 1. The host wrapper.
+    const wrapperAbs = join(o.targetRepo, host.relPath);
+    const existing = await tryRead(wrapperAbs);
+    const block = host.block(o.profile, o.runner);
+    const drifted = existing !== null && detectBlockDrift(existing, block, host.markers);
+    const recorded = sameBinding ? o.prevLock?.ciWorkflowBlockSha256 : undefined;
+    const pristine = existing !== null && recorded !== undefined && blockSha256(existing, host.markers) === recorded;
+    const markerless = existing !== null && existing !== "" && !(existing.includes(host.markers.begin) && existing.includes(host.markers.end));
+    if (drifted && pristine) {
+        log.push(`${host.relPath}: method-managed block unmodified since the last sync (digest matches the lock); re-rendering it for this sdd-cli.`);
+    }
+    if (drifted && !pristine && !o.allowDrift) {
+        failures.push(`${host.relPath}: the method-managed block differs from what this sdd-cli renders. Either the generator changed since the last sync (expected after a CLI upgrade) or the block was hand-edited. Re-run with --allow-overwrite to re-render it; adopter content outside the markers is preserved either way.`);
+    }
+    else if (markerless && !o.allowOverwrite) {
+        failures.push(`${host.relPath} exists without method-managed markers — refusing to overwrite adopter content. Re-run with --allow-overwrite to replace the file.`);
+    }
+    // 2. The module: every file it renders, compared as one set.
+    const rendered = renderModuleFiles();
+    const onDisk = [];
+    for (const [rel] of rendered)
+        onDisk.push([rel, await tryRead(join(o.targetRepo, MODULE_DIR, rel))]);
+    const present = onDisk.some(([, c]) => c !== null);
+    const matches = rendered.every(([rel, c], i) => onDisk[i][0] === rel && onDisk[i][1] === c);
+    const modulePristine = o.prevLock?.ciModuleSha256 !== undefined && moduleSha256(onDisk) === o.prevLock.ciModuleSha256;
+    if (present && !matches && modulePristine) {
+        log.push(`${MODULE_DIR}/: unmodified since the last sync (digest matches the lock); re-rendering it for this sdd-cli.`);
+    }
+    if (present && !matches && !modulePristine && !o.allowDrift) {
+        failures.push(`${MODULE_DIR}/: the method-managed module differs from what this sdd-cli renders. Either the generator changed since the last sync (expected after a CLI upgrade) or a file was hand-edited. Re-run with --allow-overwrite to re-render it.`);
+    }
+    if (o.checkOnly || failures.length > 0) {
+        return { failures, log, wrapperSha: null, moduleSha: moduleSha256(onDisk) };
+    }
+    const written = await writeMarkedBlockFile(wrapperAbs, existing === null ? host.file(o.profile, o.runner) : block, host.markers, o.allowOverwrite);
+    if (written.changed)
+        log.push(`${existing === null ? "Wrote" : "Refreshed"} ${host.relPath}.`);
+    if (!matches) {
+        for (const [rel, content] of rendered) {
+            const abs = join(o.targetRepo, MODULE_DIR, rel);
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, content, "utf8");
+        }
+        log.push(`${present ? "Refreshed" : "Wrote"} ${MODULE_DIR}/ (the Method Validation module, M-ADR 0219).`);
+    }
+    // A binding switch leaves the previous host's file alone: it is the adopter's to delete once the
+    // new host runs, and deleting it here would remove a job some branch protection may still require.
+    if (!sameBinding) {
+        const was = o.prevLock?.ciBinding;
+        const previous = HOST_WRAPPERS[was !== undefined && isCiBinding(was) ? was : DEFAULT_CI_BINDING];
+        if ((await tryRead(join(o.targetRepo, previous.relPath))) !== null) {
+            log.push(`CI binding is now ${o.binding}; ${previous.relPath} (the previous binding) is left in place. Delete it once ${host.relPath} runs.`);
+        }
+    }
+    return {
+        failures,
+        log,
+        wrapperSha: blockSha256(await tryRead(wrapperAbs), host.markers),
+        moduleSha: moduleSha256(rendered),
+    };
+}
+async function tryRead(path) {
+    try {
+        await access(path);
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the module into a new SDD (init); returns the paths written, relative to the SDD root. */
+export async function writeMethodValidationModule(targetRepo) {
+    const written = [];
+    for (const [rel, content] of renderModuleFiles()) {
+        const abs = join(targetRepo, MODULE_DIR, rel);
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, "utf8");
+        written.push(`${MODULE_DIR}/${rel}`);
+    }
+    return written;
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/ci-binding/module.js

@@ -0,0 +1,204 @@
+/**
+ * The Method Validation Dagger module (M-ADR 0219 §4.1–§4.3): the ONLY definition of the
+ * method-managed validation job. `sync` writes these files into every SDD at MODULE_DIR, with the
+ * exact verify-cli and maintain-cli versions released alongside this sdd-cli substituted in, and
+ * every CI host's wrapper (./index.ts) just calls the module.
+ *
+ * The module's source lives here, as text, rather than as files beside the package: sync runs from
+ * three packages (sdd-cli, maintain-cli, and the persona builds' import closure), and a string
+ * travels with whichever one imports it, where an asset directory would have to be copied into each.
+ * `scripts/dagger-parity.sh` renders it from the built package, so the parity harness runs exactly
+ * what sync writes.
+ */
+import { createHash } from "node:crypto";
+import { getMaintainCliVersion, getVerifyCliVersion } from "../package-version.js";
+/** Where the module lives in an SDD (M-ADR 0219 §4.3, ruled 2026-10-16). */
+export const MODULE_DIR = ".dagger/method-validation";
+/**
+ * The Dagger engine the module declares and every wrapper installs, pinned to one value so the CLI a
+ * wrapper installs and the engine the module asks for can never disagree (M-ADR 0219 §6). An engine
+ * upgrade is a release concern: change it here, run scripts/dagger-parity.sh, release.
+ */
+export const DAGGER_VERSION = "0.21.10";
+/** The command every host wrapper runs. */
+export const MODULE_CALL = `dagger call -m ${MODULE_DIR} method-validation --source .`;
+const VERIFY_PIN = "@@VERIFY_CLI_VERSION@@";
+// The module's SDK import, substituted at render: written literally, the persona builds' import-closure
+// scan would read this text as an import of the CLI's own and refuse a dependency it does not declare.
+const DAGGER_SDK = "@@DAGGER_SDK@@";
+const MAINTAIN_PIN = "@@MAINTAIN_CLI_VERSION@@";
+// The module's own source. String.raw keeps it byte-for-byte, so it holds no backtick; its only
+// substitutions are the three markers above, which renderModuleFiles replaces.
+const INDEX_TS = String.raw `/**
+ * Method Validation (M-ADR 0219): the method-managed validation job, as one Dagger module. Every CI
+ * host calls it, and none keeps a step list of its own. Written by sdd-cli sync and method-managed:
+ * sync refuses to overwrite an edited copy without --allow-overwrite.
+ *
+ * Run it anywhere a container engine runs:
+ *   dagger call -m .dagger/method-validation method-validation --source .
+ *
+ * The steps are the method's job plan, read at run time from "sdd-verify validate --list". Every
+ * step runs even after an earlier one fails, so one red step never hides the verdicts after it. The
+ * job fails only when a non-advisory step fails; the catalogue freshness step is advisory.
+ */
+import { dag, Container, Directory, File, object, func, ReturnType } from ${DAGGER_SDK}
+
+// Pinned, so a run is reproducible and every tool the validators shell out to is named here.
+const NODE_IMAGE = "node:20-bookworm"
+const YQ_VERSION = "v4.44.3"
+
+interface PlanStep {
+  id: string
+  title: string
+  tool: "sdd-verify" | "sdd-maintain" | "bash"
+  args: string[]
+  advisory: boolean
+}
+
+@object()
+export class MethodValidation {
+  /**
+   * The toolchain: Node, git, bash, python3, ripgrep, a pinned yq, and the exact-pinned verify and
+   * maintain CLIs. A tarball, when given, replaces the published package (a release candidate).
+   */
+  @func()
+  toolchain(
+    verifyVersion: string = "${VERIFY_PIN}",
+    maintainVersion: string = "${MAINTAIN_PIN}",
+    verifyTarball?: File,
+    maintainTarball?: File,
+  ): Container {
+    let c = dag
+      .container()
+      .from(NODE_IMAGE)
+      .withExec(["sh", "-c", "apt-get update -qq && apt-get install -y -qq ripgrep python3 >/dev/null"])
+      .withExec([
+        "sh",
+        "-c",
+        "curl -fsSL -o /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/" +
+          YQ_VERSION +
+          "/yq_linux_$(dpkg --print-architecture) && chmod +x /usr/local/bin/yq",
+      ])
+    const pkgs: string[] = []
+    if (verifyTarball) {
+      c = c.withFile("/pkgs/verify-cli.tgz", verifyTarball)
+      pkgs.push("/pkgs/verify-cli.tgz")
+    } else pkgs.push("@sdd-method/verify-cli@" + verifyVersion)
+    if (maintainTarball) {
+      c = c.withFile("/pkgs/maintain-cli.tgz", maintainTarball)
+      pkgs.push("/pkgs/maintain-cli.tgz")
+    } else pkgs.push("@sdd-method/maintain-cli@" + maintainVersion)
+    return c.withExec(["npm", "install", "-g", "--silent", ...pkgs])
+  }
+
+  /**
+   * Run Method Validation on an SDD repository. Returns a step-by-step report, and throws (so the
+   * CI host's job fails) when any non-advisory step failed.
+   */
+  @func()
+  async methodValidation(
+    source: Directory,
+    verifyVersion: string = "${VERIFY_PIN}",
+    maintainVersion: string = "${MAINTAIN_PIN}",
+    verifyTarball?: File,
+    maintainTarball?: File,
+  ): Promise<string> {
+    const base = this.toolchain(verifyVersion, maintainVersion, verifyTarball, maintainTarball)
+      .withMountedDirectory("/src", source)
+      .withWorkdir("/src")
+    const versions = (await base.withExec(["sh", "-c", "sdd-verify --version; sdd-maintain --version"]).stdout()).split("\n")
+    const plan = JSON.parse(await base.withExec(["sdd-verify", "validate", "--list"]).stdout()) as {
+      profile: string
+      steps: PlanStep[]
+    }
+
+    const lines = ["Method Validation: profile " + plan.profile + "; sdd-verify " + versions[0] + ", sdd-maintain " + versions[1]]
+    let failed = 0
+    for (const step of plan.steps) {
+      const ran = base.withExec([step.tool, ...step.args], { expect: ReturnType.Any })
+      const code = await ran.exitCode()
+      const verdict = code === 0 ? "PASS" : step.advisory ? "ADVISORY" : "FAIL"
+      if (code !== 0 && !step.advisory) failed++
+      lines.push(verdict.padEnd(8) + " exit " + code + "  " + step.id + "  (" + step.title + ")")
+      if (code !== 0) {
+        const out = (await ran.stdout()) + (await ran.stderr())
+        lines.push(...out.trim().split("\n").slice(-6).map((l) => "           " + l))
+      }
+    }
+    lines.push(failed === 0 ? "RESULT: PASS" : "RESULT: FAIL (" + failed + " failing step(s))")
+    const report = lines.join("\n")
+    if (failed > 0) throw new Error(report)
+    return report
+  }
+}
+`;
+const DAGGER_JSON = `{
+  "name": "method-validation",
+  "engineVersion": "v${DAGGER_VERSION}",
+  "sdk": {
+    "source": "typescript"
+  }
+}
+`;
+const PACKAGE_JSON = `{
+  "type": "module",
+  "dependencies": {
+    "typescript": "5.9.3"
+  }
+}
+`;
+const TSCONFIG_JSON = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "moduleResolution": "Node",
+    "experimentalDecorators": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@dagger.io/dagger": ["./sdk/index.ts"],
+      "@dagger.io/dagger/telemetry": ["./sdk/telemetry.ts"]
+    }
+  }
+}
+`;
+const YARN_LOCK = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+typescript@5.9.3:
+  version "5.9.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
+  integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==
+`;
+// The SDK Dagger generates at run time stays out of the SDD's history.
+const GITIGNORE = `/sdk
+/**/node_modules/**
+/**/.pnpm-store/**
+/.env
+`;
+/**
+ * The module's files, relative to MODULE_DIR, in a fixed order. Pins default to the versions released
+ * with this sdd-cli (M-ADR 0218 §4.6); the parity harness passes candidate versions.
+ */
+export function renderModuleFiles(pins = { verify: getVerifyCliVersion(), maintain: getMaintainCliVersion() }) {
+    return [
+        [".gitignore", GITIGNORE],
+        ["dagger.json", DAGGER_JSON],
+        ["package.json", PACKAGE_JSON],
+        ["src/index.ts", INDEX_TS.split(VERIFY_PIN).join(pins.verify).split(MAINTAIN_PIN).join(pins.maintain).split(DAGGER_SDK).join('"@dagger.io' + '/dagger"')],
+        ["tsconfig.json", TSCONFIG_JSON],
+        ["yarn.lock", YARN_LOCK],
+    ];
+}
+/**
+ * sha256 over the module's files as they stand (null content = absent), in the render's order, so
+ * sync can tell a module nobody touched from an edited one (M-ADR 0218 §4.7, as for the wrapper).
+ */
+export function moduleSha256(files) {
+    const h = createHash("sha256");
+    for (const [rel, content] of files) {
+        h.update(rel).update("\0").update(content === null ? "\u0001absent" : content).update("\0");
+    }
+    return h.digest("hex");
+}
+//# sourceMappingURL=module.js.map

package/dist/lib/conformance/binding.js

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const BINDING_FILENAME = ".sdd/implementation-binding.yaml";
+/** One binding per implementation, for an SDD that specifies several (M-ADR 0214 §4.9). */
+export const BINDINGS_DIRNAME = ".sdd/implementation-bindings";
+export function bindingPath(targetRepo) {
+    return resolve(targetRepo, BINDING_FILENAME);
+}
+/**
+ * Every binding file of the SDD, relative to its root: the single-implementation file
+ * when present, then each `<implementation>.yaml` in the bindings directory, sorted.
+ */
+export function bindingFiles(targetRepo) {
+    const out = [];
+    if (existsSync(bindingPath(targetRepo)))
+        out.push(BINDING_FILENAME);
+    const dir = resolve(targetRepo, BINDINGS_DIRNAME);
+    if (existsSync(dir)) {
+        for (const f of readdirSync(dir).sort()) {
+            if (f.endsWith(".yaml") || f.endsWith(".yml"))
+                out.push(`${BINDINGS_DIRNAME}/${f}`);
+        }
+    }
+    return out;
+}
+export function hasBinding(targetRepo) {
+    return bindingFiles(targetRepo).length > 0;
+}
+/**
+ * Flatten the binding's implementation members into derived checks. Each member's `checks[]` become
+ * Check objects (run as-is by the extractor core); the member's repo/role/lifecycle ride alongside so
+ * the emitted finding records *which implementation* drifted. A member with no checks contributes none
+ * (e.g. a decommissioned as-is member you no longer validate).
+ */
+export async function deriveChecksFromBinding(targetRepo) {
+    const derived = [];
+    // A check id is the conformance_finding primary key within the SDD, so one declared by two
+    // bindings would collide there: refused here, where both files can be named.
+    const declaredIn = new Map();
+    for (const file of bindingFiles(targetRepo)) {
+        for (const d of await deriveFromFile(resolve(targetRepo, file))) {
+            const prior = declaredIn.get(d.check.id);
+            if (prior !== undefined) {
+                throw new Error(`conformance check id '${d.check.id}' is declared by both ${prior} and ${file} — check ids are unique within the SDD (M-ADR 0214 §4.9)`);
+            }
+            declaredIn.set(d.check.id, file);
+            derived.push(d);
+        }
+    }
+    return derived;
+}
+async function deriveFromFile(path) {
+    const raw = parseYaml(await readFile(path, "utf-8"));
+    const derived = [];
+    for (const impl of raw?.implementations ?? []) {
+        const member = {
+            repo: impl.repo,
+            ...(impl.role ? { role: impl.role } : {}),
+            ...(impl.lifecycle ? { lifecycle: impl.lifecycle } : {}),
+            ...(impl.stack ? { stack: impl.stack } : {}),
+        };
+        for (const check of impl.checks ?? []) {
+            derived.push({ check, member });
+        }
+    }
+    return derived;
+}
+//# sourceMappingURL=binding.js.map

package/dist/lib/context-pull/index.js

@@ -0,0 +1,151 @@
+/**
+ * `sdd-cli context pull` — write the code-repo briefing and MCP_SETUP.md into a
+ * code repository from its upstream SDD (M-ADR 0128 §1; M-ADR 0150 §4.3–4.4).
+ *
+ * The successor to the code-repo half of `generate-claude-md.sh`, scoped by
+ * M-ADR 0150 Phase D: no dynamic content is baked in; that is the SDD's MCP
+ * server's job. A sibling verb to `generate-briefing`, not an extension of it:
+ * `generate-briefing` needs the target to be an SDD (marker, lock, synced
+ * templates), and a code repository is none of those. They share the
+ * placeholder substitution and the wrapper's marker-block merge.
+ *
+ * What it writes, and nothing else (M-ADR 0218 §4.3 item 9, a MAINTAIN verb):
+ *   agent-instructions.md   whole file, method-managed
+ *   CLAUDE.md / AGENTS.md   the method-managed block only; adopter content survives
+ *   MCP_SETUP.md            whole file, method-managed
+ * Templates are read from the SDD, which carries them via its baseline bundle.
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { AGENT_INSTRUCTIONS_REL_PATH, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, findUnresolvedPlaceholders, harnessWrapperOutputPath, resolveBriefingVariables, splitWrapperTemplate, } from "../briefing/index.js";
+import { readLockFile } from "../lock-file.js";
+import { readRepoKind } from "../repo-kind.js";
+import { writeMarkedBlockFile } from "../sync/yaml-block-merge.js";
+import { defaultSearchRoots, resolveCodeRepoName, resolveSdd } from "./resolve.js";
+export const CODE_REPO_BRIEFING_ROOT = "orchestration/templates/briefing/code-repo";
+export const MCP_SETUP_TEMPLATE = "orchestration/templates/mcp/code-repo/MCP_SETUP.md.hbs";
+export const MCP_SETUP_REL_PATH = "MCP_SETUP.md";
+const WRAPPER_TEMPLATE = {
+    "claude-code": "claude-code/CLAUDE.md.hbs",
+    "github-copilot-cli": "github-copilot-cli/AGENTS.md.hbs",
+};
+export async function runContextPull(opts, out = (line) => process.stdout.write(line)) {
+    const codeRepo = resolve(opts.codeRepo);
+    if ((await readRepoKind(codeRepo)) !== null) {
+        out(fail(`${codeRepo} is an SDD repository (it has .sdd-repo-kind). context pull writes into a code repository; for an SDD use sdd-cli generate-briefing.`));
+        return { exitCode: 1 };
+    }
+    const repoName = resolveCodeRepoName(codeRepo, opts.repoName);
+    const outcome = await resolveSdd({
+        repoName,
+        sddPath: opts.sddPath,
+        searchRoots: opts.searchRoots ?? defaultSearchRoots(codeRepo),
+        codeRepo,
+    });
+    if (outcome.kind === "not-an-sdd") {
+        out(fail(`--sdd ${outcome.path} is not an SDD repository (no .sdd-repo-kind).`));
+        return { exitCode: 1 };
+    }
+    if (outcome.kind === "not-found") {
+        out(fail(`No SDD lists repository "${repoName}" in its catalogues/repositories.csv (searched ${outcome.searched.length} SDD(s) under ${(opts.searchRoots ?? defaultSearchRoots(codeRepo)).join(", ")}). Pass --sdd <path>, or --repo <id> if this repository is catalogued under another id.`));
+        return { exitCode: 1 };
+    }
+    if (outcome.kind === "ambiguous") {
+        out(fail(`Repository "${repoName}" is listed by ${outcome.candidates.length} SDDs: ${outcome.candidates.join(", ")}. Pass --sdd <path> to choose.`));
+        return { exitCode: 1 };
+    }
+    const sddRoot = outcome.sddRoot;
+    if (!outcome.catalogued) {
+        out(warn(`${basename(sddRoot)}'s catalogues/repositories.csv does not list "${repoName}"; continuing because --sdd was given.`));
+    }
+    // The SDD's own identity, profile and baseline, exactly as its own briefing renders them.
+    const lock = await readLockFile(sddRoot);
+    const forwardBase = lock?.bundles.find((b) => b.isForwardBase);
+    if (!forwardBase) {
+        out(fail(`${sddRoot} has no forward-base bundle in method-baseline.lock; sync it first.`));
+        return { exitCode: 1 };
+    }
+    const sdd = await resolveBriefingVariables({ targetRepo: sddRoot, baselineVersionOverride: forwardBase.bundleVersion });
+    const vars = {
+        repo_name: repoName,
+        sdd_name: sdd.sdd_name,
+        sdd_root: sddRoot,
+        repo_kind: sdd.repo_kind,
+        baseline_version: sdd.baseline_version,
+        pull_date: opts.pullDate ?? new Date().toISOString().slice(0, 10),
+        // MCP_SETUP.md's own names, kept so the template the bash generator rendered still renders.
+        upstream_sdd_name: basename(sddRoot),
+        sdd_method_baseline_version: sdd.baseline_version,
+    };
+    const aiTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, "agent-instructions.md.hbs");
+    const wrapperTemplate = join(sddRoot, CODE_REPO_BRIEFING_ROOT, WRAPPER_TEMPLATE[opts.agentHarness]);
+    const mcpTemplate = join(sddRoot, MCP_SETUP_TEMPLATE);
+    for (const t of [aiTemplate, wrapperTemplate, mcpTemplate]) {
+        if (!(await exists(t))) {
+            out(fail(`${sddRoot} does not carry ${t.slice(sddRoot.length + 1)}: its method baseline predates context pull. Sync the SDD to a baseline that ships the code-repo templates.`));
+            return { exitCode: 1 };
+        }
+    }
+    const rendered = {};
+    for (const [rel, path] of [[AGENT_INSTRUCTIONS_REL_PATH, aiTemplate], [harnessWrapperOutputPath(opts.agentHarness), wrapperTemplate], [MCP_SETUP_REL_PATH, mcpTemplate]]) {
+        const content = substituteAll(await readFile(path, "utf8"), vars);
+        const unresolved = findUnresolvedPlaceholders(content);
+        if (unresolved.length > 0) {
+            out(fail(`${rel}: the SDD's template has placeholders this CLI does not know: ${unresolved.join(", ")}. Upgrade sdd-cli.`));
+            return { exitCode: 1 };
+        }
+        rendered[rel] = content;
+    }
+    // The wrapper first: it is the only write that can be refused, and a refusal must leave nothing written.
+    const wrapperRel = harnessWrapperOutputPath(opts.agentHarness);
+    const wrapperPath = join(codeRepo, wrapperRel);
+    const existing = (await exists(wrapperPath)) ? await readFile(wrapperPath, "utf8") : null;
+    const parts = splitWrapperTemplate(rendered[wrapperRel]);
+    const hasMarkers = existing !== null && existing.includes(WRAPPER_BLOCK_BEGIN) && existing.includes(WRAPPER_BLOCK_END);
+    let wrapperChanged;
+    if (existing !== null && !hasMarkers) {
+        // No markers: a pre-briefing-layer file (the bash generator wrote these whole) or adopter-authored.
+        if (!opts.allowOverwrite) {
+            out(fail(`${wrapperRel} exists without method-managed markers, so it is treated as adopter-authored. Nothing was written. Re-run with --allow-overwrite to replace it with the rendered wrapper (move anything worth keeping below its markers afterwards).`));
+            return { exitCode: 1 };
+        }
+        await writeFile(wrapperPath, rendered[wrapperRel], "utf8");
+        wrapperChanged = existing !== rendered[wrapperRel];
+    }
+    else {
+        const merge = await writeMarkedBlockFile(wrapperPath, existing === null ? rendered[wrapperRel] : parts.block, { begin: WRAPPER_BLOCK_BEGIN, end: WRAPPER_BLOCK_END }, opts.allowOverwrite, existing === null ? undefined : { pre: parts.pre, post: parts.post });
+        wrapperChanged = merge.changed;
+    }
+    const changed = [];
+    if (wrapperChanged)
+        changed.push(wrapperRel);
+    for (const rel of [AGENT_INSTRUCTIONS_REL_PATH, MCP_SETUP_REL_PATH]) {
+        const path = join(codeRepo, rel);
+        const before = (await exists(path)) ? await readFile(path, "utf8") : null;
+        if (before !== rendered[rel]) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, rendered[rel], "utf8");
+            changed.push(rel);
+        }
+    }
+    out(info(`Code repo "${repoName}" is specified by ${sdd.sdd_name} (${sdd.repo_kind}, ${sdd.baseline_version}) at ${sddRoot}.`));
+    out(info(changed.length > 0 ? `Wrote ${changed.join(", ")}.` : `Already current: ${AGENT_INSTRUCTIONS_REL_PATH}, ${wrapperRel}, ${MCP_SETUP_REL_PATH}.`));
+    return { exitCode: 0 };
+}
+/** `{{name}}` substitution over an open variable set (the briefing renderer's is closed to four). */
+export function substituteAll(template, vars) {
+    return template.replace(/\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g, (full, key) => (key in vars ? vars[key] : full));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const info = (m) => `[INFO] ${m}\n`;
+const warn = (m) => `[WARN] ${m}\n`;
+const fail = (m) => `[FAIL] ${m}\n`;
+//# sourceMappingURL=index.js.map