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

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

@@ -18,6 +18,16 @@ import { DAGGER_VERSION, MODULE_CALL, MODULE_DIR, moduleSha256, renderModuleFile
 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);
 }
@@ -42,13 +52,14 @@ function header(comment, profile) {
 // 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) {
+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:",
@@ -70,13 +81,13 @@ function gitlabBlock(profile) {
 // 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) {
+function jenkinsBlock(profile, runner) {
     return [
         SLASH.begin,
         ...header("//", profile),
         "",
         "pipeline {",
-        "  agent any",
+        runner !== undefined && runner.length > 0 ? `  agent { label '${runner.join(" && ")}' }` : "  agent any",
         "  stages {",
         "    stage('Method Validation') {",
         "      steps {",
@@ -100,13 +111,13 @@ export const HOST_WRAPPERS = {
         relPath: ".gitlab-ci.yml",
         markers: HASH,
         block: gitlabBlock,
-        file: (p) => gitlabBlock(p) + "\n\n# Adopter-specific jobs go below, outside the method-managed markers.\n",
+        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) => jenkinsBlock(p) + "\n",
+        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. */
@@ -128,7 +139,7 @@ export async function syncCiBinding(o) {
     // 1. The host wrapper.
     const wrapperAbs = join(o.targetRepo, host.relPath);
     const existing = await tryRead(wrapperAbs);
-    const block = host.block(o.profile);
+    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;
@@ -159,7 +170,7 @@ export async function syncCiBinding(o) {
     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) : block, host.markers, o.allowOverwrite);
+    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) {

package/dist/lib/init/ci-workflow.js

@@ -16,8 +16,8 @@ export const BLOCK_END = "# method-managed: end";
  * Full file content (block + adopter-extension footer). Used by
  * `sdd-cli init` to write a fresh workflow.
  */
-export function renderMethodValidationWorkflow(profile) {
-    const methodBlock = buildMethodManagedBlock(profile);
+export function renderMethodValidationWorkflow(profile, runner) {
+    const methodBlock = buildMethodManagedBlock(profile, runner);
     return methodBlock + "\n\n# Adopter-specific jobs go in a separate workflow file\n# (e.g. .github/workflows/adopter-validation.yml) — see\n# docs/method/methods/ci-baseline-guide.md.\n";
 }
 /**
@@ -26,10 +26,19 @@ export function renderMethodValidationWorkflow(profile) {
  * `writeMarkedBlockFile` so adopter content outside the markers is
  * preserved verbatim.
  */
-export function renderMethodManagedWorkflowBlock(profile) {
-    return buildMethodManagedBlock(profile);
+export function renderMethodManagedWorkflowBlock(profile, runner) {
+    return buildMethodManagedBlock(profile, runner);
 }
-function buildMethodManagedBlock(profile) {
+/**
+ * `runs-on`: GitHub's hosted runner unless the SDD chose labels (sync --ci-runner), e.g. a
+ * self-hosted runner, where the Dagger engine and its cache persist between runs.
+ */
+function runsOn(runner) {
+    if (runner === undefined || runner.length === 0)
+        return "ubuntu-latest";
+    return runner.length === 1 ? runner[0] : `[${runner.join(", ")}]`;
+}
+function buildMethodManagedBlock(profile, runner) {
     return [
         BLOCK_BEGIN,
         "# Method Validation per M-ADR 0129, run by the method's Dagger module (M-ADR 0219).",
@@ -63,7 +72,7 @@ function buildMethodManagedBlock(profile) {
         // ONE job: GitHub bills each job rounded UP to a whole minute (adopter measurement, 2026-10-12).
         "  method-validation:",
         "    name: Method Validation",
-        "    runs-on: ubuntu-latest",
+        `    runs-on: ${runsOn(runner)}`,
         "    steps:",
         "      - uses: actions/checkout@v4",
         "      - name: Install Dagger",

package/dist/lib/lock-file.js

@@ -63,6 +63,7 @@ export function serialiseLockFile(lock) {
         `method_repo: ${lock.methodRepo}`,
         `lock_version: ${lock.lockVersion}`,
         ...(lock.ciBinding !== undefined ? [`ci_binding: ${lock.ciBinding}`] : []),
+        ...(lock.ciRunner !== undefined ? [`ci_runner: "${lock.ciRunner}"`] : []),
         ...(lock.ciWorkflowBlockSha256 !== undefined ? [`ci_workflow_block_sha256: "${lock.ciWorkflowBlockSha256}"`] : []),
         ...(lock.ciModuleSha256 !== undefined ? [`ci_module_sha256: "${lock.ciModuleSha256}"`] : []),
         "bundles:",
@@ -114,6 +115,7 @@ function parseVersioned(raw) {
     let lockVersion;
     let ciWorkflowBlockSha256;
     let ciBinding;
+    let ciRunner;
     let ciModuleSha256;
     const bundles = [];
     let inBundles = false;
@@ -180,6 +182,8 @@ function parseVersioned(raw) {
                     ciWorkflowBlockSha256 = stripQuotes(value);
                 else if (key === "ci_binding")
                     ciBinding = stripQuotes(value);
+                else if (key === "ci_runner")
+                    ciRunner = stripQuotes(value);
                 else if (key === "ci_module_sha256")
                     ciModuleSha256 = stripQuotes(value);
             }
@@ -306,6 +310,7 @@ function parseVersioned(raw) {
         lockVersion: LOCK_VERSION,
         bundles,
         ...(ciBinding !== undefined ? { ciBinding } : {}),
+        ...(ciRunner !== undefined ? { ciRunner } : {}),
         ...(ciWorkflowBlockSha256 !== undefined ? { ciWorkflowBlockSha256 } : {}),
         ...(ciModuleSha256 !== undefined ? { ciModuleSha256 } : {}),
     };

package/dist/lib/sync/index.js

@@ -15,7 +15,7 @@ import { syncMethodManagedCopilotHooks } from "./copilot-hooks-merge.js";
 import { syncBriefingFiles } from "./briefing-merge.js";
 import { DEFAULT_AGENT_HARNESS } from "../agent-harness.js";
 import { BLOCK_BEGIN, BLOCK_END } from "../init/ci-workflow.js";
-import { blockSha256, CI_BINDINGS, DEFAULT_CI_BINDING, isCiBinding, syncCiBinding, } from "../ci-binding/index.js";
+import { blockSha256, CI_BINDINGS, DEFAULT_CI_BINDING, isCiBinding, parseCiRunner, syncCiBinding, } from "../ci-binding/index.js";
 import { BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, harnessWrapperOutputPath, } from "../briefing/index.js";
 const SECTION_RULE = "═".repeat(59);
 /**
@@ -97,6 +97,12 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             return { exitCode: 1 };
         }
         const ciBinding = opts.ciBinding ?? lockBinding ?? DEFAULT_CI_BINDING;
+        const lockRunner = prevLock?.ciRunner === undefined ? undefined : parseCiRunner(prevLock.ciRunner);
+        if (lockRunner === null) {
+            stdout(fail(`method-baseline.lock names ci_runner '${prevLock.ciRunner}', which is not a list of runner labels. Re-run with --ci-runner <label[,label]> or --ci-runner default.`));
+            return { exitCode: 1 };
+        }
+        const ciRunner = opts.ciRunner ?? lockRunner;
         const classification = await classifyConflicts(conflicts, opts.targetRepo, prevEntry?.pathDigests);
         if (conflicts.length > 0) {
             reportClassification(stdout, conflicts.length, classification, prevEntry?.bundleVersion);
@@ -360,6 +366,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
                         targetRepo: opts.targetRepo,
                         profile: preflightProfile,
                         binding: ciBinding,
+                        ...(ciRunner !== undefined ? { runner: ciRunner } : {}),
                         prevLock,
                         allowDrift: false,
                         allowOverwrite: false,
@@ -564,6 +571,7 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
             targetRepo: opts.targetRepo,
             profile,
             binding: ciBinding,
+            ...(ciRunner !== undefined ? { runner: ciRunner } : {}),
             prevLock,
             allowDrift: opts.allowOverwrite || migrateFrom !== null,
             allowOverwrite: opts.allowOverwrite,
@@ -596,10 +604,11 @@ export async function runSync(opts, stdout = (line) => process.stdout.write(line
         // Record the wrapper block and the module exactly as they now stand on disk, so the next sync
         // can tell them untouched from edited (M-ADR 0218 §4.7), and the binding when it is not the default.
         const nextLock = upsertBundle(migrateFrom ? removeBundle(prevLock, migrateFrom.name) : prevLock, newEntry);
-        const { ciBinding: _previousBinding, ciWorkflowBlockSha256: _previousSha, ...lockBase } = nextLock;
+        const { ciBinding: _previousBinding, ciRunner: _previousRunner, ciWorkflowBlockSha256: _previousSha, ...lockBase } = nextLock;
         await writeLockFile(opts.targetRepo, {
             ...lockBase,
             ...(ciBinding !== DEFAULT_CI_BINDING ? { ciBinding } : {}),
+            ...(ciRunner !== undefined && ciRunner.length > 0 ? { ciRunner: ciRunner.join(",") } : {}),
             ...(ci.wrapperSha !== null ? { ciWorkflowBlockSha256: ci.wrapperSha } : {}),
             ciModuleSha256: ci.moduleSha,
         });

package/dist/maintain-version.json

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

package/dist/verbs/sync.js

@@ -2,7 +2,7 @@ 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 { CI_BINDINGS, CI_RUNNER_DEFAULT, isCiBinding, parseCiRunner } from "../lib/ci-binding/index.js";
 import { resolvePathOption } from "./path-option.js";
 export function registerSync(program) {
     program
@@ -18,12 +18,22 @@ export function registerSync(program) {
         .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`)
+        .option("--ci-runner <labels>", `runner label(s) the CI wrapper targets, comma-separated (GitHub runs-on, GitLab tags, Jenkins agent label), e.g. a self-hosted runner. '${CI_RUNNER_DEFAULT}' returns to the host's default runner. Default: what the lock records; a new choice is recorded`)
         .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 ciRunner;
+        if (opts.ciRunner !== undefined) {
+            const parsed = opts.ciRunner === CI_RUNNER_DEFAULT ? [] : parseCiRunner(opts.ciRunner);
+            if (parsed === null) {
+                process.stderr.write(`[FAIL] --ci-runner takes comma-separated labels of letters, digits, '.', '_' or '-', or '${CI_RUNNER_DEFAULT}'; got '${opts.ciRunner}'\n`);
+                process.exit(1);
+            }
+            ciRunner = parsed;
+        }
         let agentHarness;
         try {
             agentHarness = resolveAgentHarness(opts.agentHarness);
@@ -50,6 +60,7 @@ export function registerSync(program) {
                 delete: opts.delete,
                 agentHarness,
                 ...(ciBinding ? { ciBinding } : {}),
+                ...(ciRunner ? { ciRunner } : {}),
                 ...(opts.replaceBundle ? { replaceBundle: opts.replaceBundle } : {}),
                 ...(opts.yes === true ? { yes: true } : {}),
             });
@@ -78,6 +89,7 @@ export function registerSync(program) {
                         delete: opts.delete,
                         agentHarness,
                         ...(ciBinding ? { ciBinding } : {}),
+                        ...(ciRunner ? { ciRunner } : {}),
                     });
                     if (exitCode !== 0) {
                         await resolved.cleanup();

package/dist/verify-version.json

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.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.",
+  "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — 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": {