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

package/dist/verbs/sync.js

@@ -0,0 +1,98 @@
+import { AGENT_HARNESSES, resolveAgentHarness, } from "../lib/agent-harness.js";
+import { loadSyncConfig } from "../lib/sync/config.js";
+import { materialiseBundle } from "../lib/sync/bundle-source.js";
+import { runSync } from "../lib/sync/index.js";
+import { CI_BINDINGS, isCiBinding } from "../lib/ci-binding/index.js";
+import { resolvePathOption } from "./path-option.js";
+export function registerSync(program) {
+    program
+        .command("sync")
+        .description("Pull upstream method baselines + adopter packs into this SDD repository")
+        .option("--bundle <path>", "path to a single bundle tarball (mutually exclusive with --config)")
+        .option("--config <path>", "path to a multi-bundle sync config (iterates bundles in declared order; runs each through the single-bundle sync engine)")
+        .option("--target-repo <dir>", "target SDD repo", resolvePathOption, process.cwd())
+        .option("--dry-run", "report planned actions without writing")
+        .option("--replace-bundle <name>", "migrate: drop the named bundle's lock block and release its paths to the incoming bundle (single --bundle mode only; prints the shared/arriving/orphaned split; requires --yes outside --dry-run)")
+        .option("--yes", "confirm a --replace-bundle migration outside --dry-run")
+        .option("--allow-overwrite", "accept overwrites of locally-modified method content")
+        .option("--no-delete", "preserve files removed upstream")
+        .option("--agent-harness <name>", `target agent harness for hooks + briefing. Default: claude-code. Supported: ${AGENT_HARNESSES.join(", ")}`)
+        .option("--ci-binding <host>", `CI host whose wrapper calls the Method Validation module (M-ADR 0219): ${CI_BINDINGS.join(", ")}. Default: the binding the lock records, else github; a new choice is recorded in the lock`)
+        .action(async (opts) => {
+        if (opts.ciBinding !== undefined && !isCiBinding(opts.ciBinding)) {
+            process.stderr.write(`[FAIL] --ci-binding must be one of ${CI_BINDINGS.join(", ")}; got '${opts.ciBinding}'\n`);
+            process.exit(1);
+        }
+        const ciBinding = opts.ciBinding;
+        let agentHarness;
+        try {
+            agentHarness = resolveAgentHarness(opts.agentHarness);
+        }
+        catch (err) {
+            process.stderr.write(`[FAIL] ${err.message}\n`);
+            process.exit(1);
+        }
+        if (opts.bundle && opts.config) {
+            process.stderr.write("[FAIL] --bundle and --config are mutually exclusive\n");
+            process.exit(1);
+        }
+        if (opts.replaceBundle && !opts.bundle) {
+            process.stderr.write("[FAIL] --replace-bundle requires single-bundle mode (--bundle <tarball>) — a migration is one deliberate act, not a config iteration\n");
+            process.exit(1);
+        }
+        // Single-bundle path (legacy and explicit).
+        if (opts.bundle) {
+            const { exitCode } = await runSync({
+                bundle: opts.bundle,
+                targetRepo: opts.targetRepo,
+                dryRun: opts.dryRun === true,
+                allowOverwrite: opts.allowOverwrite === true,
+                delete: opts.delete,
+                agentHarness,
+                ...(ciBinding ? { ciBinding } : {}),
+                ...(opts.replaceBundle ? { replaceBundle: opts.replaceBundle } : {}),
+                ...(opts.yes === true ? { yes: true } : {}),
+            });
+            if (exitCode !== 0)
+                process.exit(exitCode);
+            return;
+        }
+        // Multi-bundle path via --config.
+        if (!opts.config) {
+            process.stderr.write("[FAIL] one of --bundle or --config is required\n");
+            process.exit(1);
+        }
+        try {
+            const config = await loadSyncConfig(opts.config);
+            for (const entry of config.bundles) {
+                // Resolve the entry to a verified local tarball (local path used
+                // in place; an internal-HTTPS source fetched to a temp file; the
+                // sha256 pin checked when present), then apply + release.
+                const resolved = await materialiseBundle(entry);
+                try {
+                    const { exitCode } = await runSync({
+                        bundle: resolved.localPath,
+                        targetRepo: opts.targetRepo,
+                        dryRun: opts.dryRun === true,
+                        allowOverwrite: opts.allowOverwrite === true,
+                        delete: opts.delete,
+                        agentHarness,
+                        ...(ciBinding ? { ciBinding } : {}),
+                    });
+                    if (exitCode !== 0) {
+                        await resolved.cleanup();
+                        process.exit(exitCode);
+                    }
+                }
+                finally {
+                    await resolved.cleanup();
+                }
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[FAIL] ${err.message}\n`);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=sync.js.map

package/dist/verbs/validate.js

@@ -0,0 +1,48 @@
+import { runValidate } from "../lib/validate/index.js";
+import { methodValidationPlan } from "../lib/validate/plan.js";
+import { profileFromRepoKind, readRepoKind } from "../lib/repo-kind.js";
+const LISTABLE = ["platform", "application", "integration"];
+const isListable = (p) => LISTABLE.includes(p);
+import { resolvePathOption } from "./path-option.js";
+export function registerValidate(program) {
+    program
+        .command("validate")
+        .description("Run the method-level validation suite for this SDD repository")
+        .option("--target-repo <dir>", "target SDD repo", resolvePathOption, process.cwd())
+        .option("--platform-root <dir>", "path to the sdd-method (or platform) repo, required for app-dependencies", resolvePathOption)
+        .option("--validator <name>", "run only the named validator")
+        .option("--strict", "treat warnings as failures")
+        .option("--list", "print the method-managed validation job for this repo's profile as JSON (the plan every CI executor runs, the Dagger module included) and run nothing")
+        .option("--profile <profile>", "with --list: the profile to list, instead of reading .sdd-repo-kind (platform | application | integration)")
+        .action(async (opts) => {
+        if (opts.list === true) {
+            let profile;
+            if (opts.profile !== undefined) {
+                if (!isListable(opts.profile)) {
+                    process.stderr.write(`--profile must be platform, application or integration (got: ${opts.profile})\n`);
+                    process.exit(2);
+                }
+                profile = opts.profile;
+            }
+            else {
+                const kind = await readRepoKind(opts.targetRepo);
+                if (kind === null) {
+                    process.stderr.write(`Not an SDD repo (no .sdd-repo-kind in ${opts.targetRepo}); pass --profile\n`);
+                    process.exit(1);
+                }
+                profile = profileFromRepoKind(kind);
+            }
+            process.stdout.write(JSON.stringify({ profile, steps: methodValidationPlan(profile) }, null, 2) + "\n");
+            return;
+        }
+        const { exitCode } = await runValidate({
+            targetRepo: opts.targetRepo,
+            ...(opts.platformRoot ? { platformRoot: opts.platformRoot } : {}),
+            ...(opts.validator ? { validator: opts.validator } : {}),
+            strict: opts.strict === true,
+        });
+        if (exitCode !== 0)
+            process.exit(exitCode);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/verify-program.js

@@ -0,0 +1,122 @@
+// Third entrypoint: the VERIFY surface — M-ADR 0212 §4.3b.
+//
+// A binary that CANNOT WRITE to the repository it is pointed at. That is the
+// whole property, and it is the one a pipeline can rely on: whatever runs
+// `sdd-verify` in CI can judge a repository and cannot change it.
+//
+// Two criteria admit a verb here, and both are required:
+//   1. it does not write to the target repository — TESTED, not read from a
+//      description: the package acceptance check runs every verb in every mode
+//      against a clean checkout and requires `git status --porcelain` to be
+//      empty. Reading help text misfiled four verbs before that test existed
+//      (`sync`, `render`, `catalogue graph`, `metamodel roundtrip`).
+//   2. it has something to act on in an adopter repository today. A read-only
+//      verb can fail this and pass (1): `metamodel roundtrip` is producer-only,
+//      `catalogue migration-map` serves a finished migration. Neither is here.
+//
+// ⚠ The boundary is ABSENCE, not a menu. The package ships only the import
+// closure of this file, so an excluded verb's code is not present to be reached
+// by any path — including `mcp serve`, which exposes the SDD as tools and would
+// hand authoring back through a second door. That is why registration imports
+// per-subcommand registrars (`catalogue-verify.ts`, `pack-validate.ts`) and never
+// a barrel that re-exports a build path.
+//
+// Verbs are the SAME registrars the full CLI uses: one implementation, two
+// surfaces, so behaviour cannot drift between them.
+import { Command, CommanderError } from "commander";
+import { getPackageVersion } from "./lib/package-version.js";
+import { registerCatalogueBaselineCheck, registerCatalogueImpact, registerCatalogueValidate, registerCatalogueVersion, } from "./verbs/catalogue-verify.js";
+import { registerList } from "./verbs/list.js";
+import { registerPackValidate } from "./verbs/pack-validate.js";
+import { registerValidate } from "./verbs/validate.js";
+const SPEC_URL = "https://github.com/tomfosteruk/sdd-method/blob/main/docs/method/cli/sdd-cli-specification.md";
+/** The full surface, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
+export const VERIFY_SURFACE = [
+    "validate",
+    "list",
+    "pack validate",
+    "catalogue validate",
+    "catalogue impact",
+    "catalogue baseline-check",
+    "catalogue version",
+];
+const OUTSIDE = "is not part of sdd-verify, which cannot write to the repository it is pointed at. " +
+    "Authoring and maintenance verbs are in @sdd-method/sdd-cli.";
+/**
+ * Refuse anything outside the surface BEFORE commander parses it. Left to
+ * commander, `sdd-verify sync --help` prints top-level usage and exits 0 — in a
+ * pipeline that is a step that runs nothing and passes, which is the failure
+ * this binary exists to prevent. So an excluded verb fails, loudly, whatever
+ * flags accompany it.
+ */
+export function rejectOutsideSurface(program, argv, outside = OUTSIDE) {
+    const words = argv.filter((a) => !a.startsWith("-"));
+    if (words.length === 0)
+        return;
+    const [verb, sub] = words;
+    if (verb === "help")
+        return;
+    const cmd = program.commands.find((c) => c.name() === verb);
+    if (!cmd)
+        throw new Error(`'${verb}' ${outside}`);
+    const subs = cmd.commands.map((c) => c.name()).filter((n) => n !== "help");
+    if (subs.length > 0 && sub !== undefined && sub !== "help" && !subs.includes(sub)) {
+        throw new Error(`'${verb} ${sub}' ${outside}`);
+    }
+}
+export async function runVerify(argv) {
+    const program = buildVerifyProgram();
+    if (argv.length === 0) {
+        program.outputHelp();
+        return;
+    }
+    rejectOutsideSurface(program, argv);
+    try {
+        await program.parseAsync([...argv], { from: "user" });
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            if (err.code === "commander.help" ||
+                err.code === "commander.helpDisplayed" ||
+                err.code === "commander.version") {
+                return;
+            }
+        }
+        throw err;
+    }
+}
+export function buildVerifyProgram() {
+    const program = new Command();
+    program
+        .name("sdd-verify")
+        .description("Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Cannot write to the repository it is pointed at.")
+        .version(getPackageVersion(), "-v, --version")
+        .addHelpText("after", `\nSpec: ${SPEC_URL}\nAuthoring and maintenance verbs (sync, catalogue build, init, scaffold, mcp, …) are in @sdd-method/sdd-cli.`)
+        .exitOverride()
+        .configureOutput({
+        writeOut: (str) => process.stdout.write(str),
+        writeErr: (str) => process.stderr.write(str),
+    });
+    registerVerifySurface(program);
+    return program;
+}
+/**
+ * The verify verbs, registered onto any program. sdd-verify calls it; sdd-maintain calls it too,
+ * which is what makes the personas nest structurally: whatever verify ships, maintain ships.
+ */
+export function registerVerifySurface(program) {
+    registerValidate(program);
+    registerList(program);
+    const pack = program
+        .command("pack")
+        .description("Validate adopter-shipped context-pack seeds (ADR 0151) — read-only");
+    registerPackValidate(pack);
+    const catalogue = program
+        .command("catalogue")
+        .description("Validate and query per-SDD catalogues (ADR 0134) — read-only, never rebuilds");
+    registerCatalogueValidate(catalogue);
+    registerCatalogueImpact(catalogue);
+    registerCatalogueBaselineCheck(catalogue);
+    registerCatalogueVersion(catalogue);
+}
+//# sourceMappingURL=verify-program.js.map

package/dist/verify-version.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.1.0-rc.0",
+  "built_against_sdd_cli": "1.42.0"
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.0",
+  "sddCliVersion": "1.42.0",
+  "description": "Bring an SDD repository current and rebuild its derived model \u2014 sync, briefing, catalogue build and aggregate, pack build, context pull \u2014 plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "sdd-maintain": "dist/maintain-bin.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.0",
+    "zod": "^4.3.6",
+    "@duckdb/node-api": "^1.5.5-r.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomfosteruk/sdd-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}