@devrouter/cli 0.0.50 → 0.0.51

package/README.md

@@ -88,6 +88,24 @@ The report contains the canonical selection and exact apps, dependencies,
 readiness checks, managed services, and process markers. Invalid configuration
 or profile input fails before any runtime operation.
 
+Repository automation can bind those app identities to build arguments,
+readiness URLs, or other literal values through a separate repository-owned
+contract:
+
+```bash
+devrouter profile plan \
+  --repo . \
+  --profile manage,pwa \
+  --contract ci/profile-plan.yml \
+  --output /tmp/profile-plan.json \
+  --json
+```
+
+Devrouter validates the selected resources and emits deterministic arrays. It
+does not interpret binding names, expand strings, execute commands, or start a
+runtime. See [Repository onboarding](./docs/REPO_ONBOARDING.md#bind-profiles-to-repository-automation)
+for the version-1 contract.
+
 Use devrouter lifecycle commands for managed environments. Raw DevPod or Devsy
 `up`/`stop`/`delete` calls bypass ownership locks and exact checkout validation.
 Devrouter auto-detects the installed workspace runtime CLI (DevPod or Devsy) and

package/dist/devrouter.js

@@ -50,6 +50,7 @@ function buildDevrouterSection() {
     "- `devrouter app ls --repo .`",
     "- Primary or linked devcontainer checkout: `devrouter ensure . --json`",
     "- Managed selective profile: `devrouter ensure . --profile <name> --json`",
+    "- Side-effect-free automation: `devrouter profile resolve --repo . --profile <name> --json`; add `profile plan --contract <repo-relative-yaml>` when the repository needs literal bindings.",
     "- Host/docker runtime app only: `devrouter app run <host-app> --repo . --yes`",
     "- `devrouter ls`",
     "- Managed devcontainer source configs with `postCreateCommand` and a managed post-start adapter must set `waitFor` exactly to `postCreateCommand` or `postStartCommand`; generated managed configs preserve lifecycle fields and change only `runServices`.",
@@ -300,6 +301,27 @@ profiles:
   selective configuration preserves lifecycle fields and changes only
   \`runServices\`.
 
+## Automation profile plans
+
+Use \`devrouter profile resolve --json\` when automation only needs exact selected
+resources. Use \`devrouter profile plan\` when a repository-owned contract must
+bind selected app names to build arguments, readiness URLs, or other literals:
+
+\`\`\`bash
+devrouter profile plan --repo . --profile <selection> \\
+  --contract <repo-relative-yaml> --output <plan.json> --json
+\`\`\`
+
+The version-1 contract is separate from \`.devrouter.yml\`. It maps every allowed
+app to named non-empty string arrays, constrains dependencies and managed
+services to allowed sets, and requires an exact managed-process set. All
+resource names must exist in \`.devrouter.yml\`. The path must be a regular,
+non-symlink file inside the repository. Devrouter emits canonical, deduplicated
+literal arrays and atomically writes mode \`0600\`; it never interprets binding
+names, expands values, or runs a shell or runtime. Consumers validate expected
+keys and pass values as literal data. Keep separate contracts for workloads
+with different exact process policies.
+
 ## Env var injection
 
 When a host app depends on a TCP Docker service, \`devrouter app run\` and \`devrouter app exec\` inject per-dep deterministic vars (where \`{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")\`):
@@ -380,6 +402,7 @@ Run several worktrees of one repo in parallel without host/route collisions. A *
 - \`devrouter setup --yes [--repo .] [--json] [--workspace-runtime <devpod|devsy>]\`: first-run machine setup plus structured diagnostics; explicit Devsy selection acquires its verified agent
 - \`devrouter ensure [path] [--profile <name>] [--open] [--json]\`: canonical startup/reconciliation for primary and linked checkouts; a managed profile selects its independent resource dimensions
 - \`devrouter profile resolve --repo <path> [--profile <selection>] [--json]\`: resolve exact profile resources for automation without starting or inspecting a runtime
+- \`devrouter profile plan --repo <path> [--profile <selection>] --contract <repo-relative-yaml> [--output <path>] [--json]\`: validate repository-owned resource policy and emit literal bindings without runtime access
 - \`devrouter stop [path] [--delete] [--json]\`: stop the exact workspace runtime and remove exact routes; \`--delete\` explicitly deletes its ownership-proven data without removing the checkout
 - \`devrouter exec [path] -- <command...>\`: literal one-shot command inside the exact running workspace runtime
 - \`devrouter up\` / \`devrouter down\`: start/stop shared Traefik router
@@ -2668,7 +2691,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.50" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.51" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -3153,6 +3176,8 @@ function buildOnboardingPrompt(options = {}) {
     "- managedRuntime (optional) registers devcontainer baseServices, profileServices, and managed process markers",
     "- managed profiles may add devcontainerServices and processes independently; with managedRuntime, apps may be omitted for a route-free capability profile",
     "- an omitted optional managed dimension selects nothing; use `*` or a full profile to select every registered service/process; baseServices and the primary service are always retained",
+    "- automation may use a separate strict version-1 contract with `devrouter profile plan`; the contract maps apps to named literal arrays, constrains dependencies and services to allowed registries, requires an exact managed-process set, and remains repository-owned",
+    "- profile plan values are data: Devrouter never interprets binding names, expands values, runs a shell, or starts/inspects a runtime; consumers validate expected keys and pass values literally",
     "- native Dev Container clients continue to use the source configuration's full service set; managed ensure derives an ignored sibling and changes only runServices",
     "",
     "Validation rules to enforce:",
@@ -3373,6 +3398,10 @@ var init_ai_prompt = __esm({
         command: "devrouter profile resolve --repo <path> [--profile <selection>] [--json]",
         purpose: "Resolve exact profile resources without starting or inspecting a runtime; fail closed on invalid selections or unknown report schemas."
       },
+      {
+        command: "devrouter profile plan --repo <path> [--profile <selection>] --contract <repo-relative-yaml> [--output <path>] [--json]",
+        purpose: "Validate exact profile resources against a repository-owned contract and emit named literal arrays without interpreting them or touching a runtime."
+      },
       {
         command: "devrouter stop [path] [--delete] [--json]",
         purpose: "Stop the exact checkout workspace runtime and routes; --delete explicitly deletes the ownership-proven runtime without removing the checkout."
@@ -8986,7 +9015,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.50" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.51" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -13235,9 +13264,294 @@ var init_profile_resolution = __esm({
   }
 });
 
+// src/core/profile-plan.ts
+function fail(message) {
+  throw new Error(message);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, label) {
+  if (!isRecord2(value)) fail(`${label} must be a mapping.`);
+  return value;
+}
+function requireExactKeys(value, allowed, label) {
+  const allowedSet = new Set(allowed);
+  const unknown = Object.keys(value).filter((key) => !allowedSet.has(key));
+  if (unknown.length > 0) fail(`${label} has unsupported keys: ${unknown.sort().join(", ")}.`);
+  const missing = allowed.filter((key) => !Object.hasOwn(value, key));
+  if (missing.length > 0) fail(`${label} is missing keys: ${missing.join(", ")}.`);
+}
+function requireBoolean(value, label) {
+  if (typeof value !== "boolean") fail(`${label} must be a boolean.`);
+  return value;
+}
+function requireStringList(value, label, options = {}) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    fail(`${label} must be an array of strings.`);
+  }
+  if (options.allowEmpty === false && value.length === 0) fail(`${label} must not be empty.`);
+  for (const entry of value) {
+    if (entry.length === 0) fail(`${label} must not contain empty strings.`);
+    if (entry.length > MAX_LITERAL_LENGTH) {
+      fail(`${label} contains a value longer than ${MAX_LITERAL_LENGTH} characters.`);
+    }
+  }
+  if (new Set(value).size !== value.length) fail(`${label} must not contain duplicates.`);
+  return [...value];
+}
+function parseMappings(value) {
+  const input2 = requireRecord(value, "apps.mappings");
+  const entries = Object.entries(input2);
+  if (entries.length > MAX_APP_MAPPINGS) {
+    fail(`apps.mappings exceeds the limit of ${MAX_APP_MAPPINGS}.`);
+  }
+  const mappings = [];
+  const allBindingKeys = /* @__PURE__ */ new Set();
+  let bindingValues = 0;
+  for (const [appName, rawMapping] of entries) {
+    if (appName.length === 0) fail("apps.mappings must not contain an empty app name.");
+    const mapping = requireRecord(rawMapping, `apps.mappings.${appName}`);
+    requireExactKeys(mapping, ["bindings"], `apps.mappings.${appName}`);
+    const rawBindings = requireRecord(mapping.bindings, `apps.mappings.${appName}.bindings`);
+    if (Object.keys(rawBindings).length === 0) {
+      fail(`apps.mappings.${appName}.bindings must not be empty.`);
+    }
+    const bindings = [];
+    for (const [key, rawValues] of Object.entries(rawBindings)) {
+      if (!BINDING_KEY.test(key)) {
+        fail(`binding key '${key}' must match ${BINDING_KEY.source}.`);
+      }
+      const values = requireStringList(rawValues, `apps.mappings.${appName}.bindings.${key}`, {
+        allowEmpty: false
+      });
+      allBindingKeys.add(key);
+      bindingValues += values.length;
+      bindings.push([key, values]);
+    }
+    mappings.push([appName, { bindings: Object.fromEntries(bindings) }]);
+  }
+  if (allBindingKeys.size > MAX_BINDING_KEYS) {
+    fail(`contract exceeds the limit of ${MAX_BINDING_KEYS} binding keys.`);
+  }
+  if (bindingValues > MAX_BINDING_VALUES) {
+    fail(`contract exceeds the limit of ${MAX_BINDING_VALUES} binding values.`);
+  }
+  return Object.fromEntries(mappings);
+}
+function parseProfilePlanContract(source) {
+  const document = (0, import_yaml7.parseDocument)(source, {
+    merge: false,
+    schema: "core",
+    uniqueKeys: true
+  });
+  if (document.errors.length > 0) {
+    fail(`profile plan contract is invalid YAML: ${document.errors[0]?.message}`);
+  }
+  if (document.warnings.length > 0) {
+    fail(`profile plan contract has unsupported YAML: ${document.warnings[0]?.message}`);
+  }
+  let raw;
+  try {
+    raw = document.toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    fail(`profile plan contract could not be converted: ${error.message}`);
+  }
+  const contract = requireRecord(raw, "profile plan contract");
+  requireExactKeys(
+    contract,
+    ["version", "apps", "dependencies", "managedRuntime"],
+    "profile plan contract"
+  );
+  if (contract.version !== CONTRACT_VERSION) {
+    fail(`unsupported profile plan contract version ${String(contract.version)}.`);
+  }
+  const apps = requireRecord(contract.apps, "apps");
+  requireExactKeys(apps, ["requireNonEmpty", "mappings"], "apps");
+  const dependencies = requireRecord(contract.dependencies, "dependencies");
+  requireExactKeys(dependencies, ["allowed"], "dependencies");
+  const managedRuntime = requireRecord(contract.managedRuntime, "managedRuntime");
+  requireExactKeys(managedRuntime, ["services", "processes"], "managedRuntime");
+  const services = requireRecord(managedRuntime.services, "managedRuntime.services");
+  requireExactKeys(services, ["allowed"], "managedRuntime.services");
+  const processes = requireRecord(managedRuntime.processes, "managedRuntime.processes");
+  requireExactKeys(processes, ["exact"], "managedRuntime.processes");
+  return {
+    version: CONTRACT_VERSION,
+    apps: {
+      requireNonEmpty: requireBoolean(apps.requireNonEmpty, "apps.requireNonEmpty"),
+      mappings: parseMappings(apps.mappings)
+    },
+    dependencies: {
+      allowed: requireStringList(dependencies.allowed, "dependencies.allowed")
+    },
+    managedRuntime: {
+      services: {
+        allowed: requireStringList(services.allowed, "managedRuntime.services.allowed")
+      },
+      processes: {
+        exact: requireStringList(processes.exact, "managedRuntime.processes.exact")
+      }
+    }
+  };
+}
+function sortedUnique3(values) {
+  return Array.from(new Set(values)).sort();
+}
+function registryFor(config) {
+  const managedRuntime = config.managedRuntime;
+  return {
+    apps: sortedUnique3(
+      config.apps.filter((app) => app.kind !== "dependency").map((app) => app.name)
+    ),
+    dependencies: sortedUnique3(
+      config.apps.filter((app) => app.kind === "dependency").map((app) => app.name)
+    ),
+    managedServices: sortedUnique3([
+      ...managedRuntime?.devcontainer.baseServices ?? [],
+      ...managedRuntime?.devcontainer.profileServices ?? []
+    ]),
+    managedProcesses: sortedUnique3(managedRuntime?.processes ?? [])
+  };
+}
+function assertKnown(values, registry, label) {
+  const known = new Set(registry);
+  const unknown = values.filter((value) => !known.has(value));
+  if (unknown.length > 0) fail(`${label} contains unknown resources: ${unknown.join(", ")}.`);
+}
+function assertAllowed(selected, allowed, label) {
+  const allowedSet = new Set(allowed);
+  const unsupported = selected.filter((value) => !allowedSet.has(value));
+  if (unsupported.length > 0) {
+    fail(`${label} selects unsupported resources: ${unsupported.join(", ")}.`);
+  }
+}
+function assertExact(selected, expected, label) {
+  const left = sortedUnique3(selected);
+  const right = sortedUnique3(expected);
+  if (left.length !== right.length || left.some((value, index) => value !== right[index])) {
+    fail(`${label} must equal [${right.join(", ")}], received [${left.join(", ")}].`);
+  }
+}
+function buildProfilePlanReport(options) {
+  const { report, contract, registry, contractPath } = options;
+  assertKnown(Object.keys(contract.apps.mappings), registry.apps, "apps.mappings");
+  assertKnown(contract.dependencies.allowed, registry.dependencies, "dependencies.allowed");
+  assertKnown(
+    contract.managedRuntime.services.allowed,
+    registry.managedServices,
+    "managedRuntime.services.allowed"
+  );
+  assertKnown(
+    contract.managedRuntime.processes.exact,
+    registry.managedProcesses,
+    "managedRuntime.processes.exact"
+  );
+  if (contract.apps.requireNonEmpty && report.apps.length === 0) {
+    fail("selected profile must contain at least one app for this contract.");
+  }
+  const unmapped = report.apps.filter((app) => !Object.hasOwn(contract.apps.mappings, app));
+  if (unmapped.length > 0) fail(`selected apps have no contract mapping: ${unmapped.join(", ")}.`);
+  assertAllowed(report.dependencies, contract.dependencies.allowed, "dependencies");
+  assertAllowed(
+    report.managedRuntime.services,
+    contract.managedRuntime.services.allowed,
+    "managedRuntime.services"
+  );
+  assertExact(
+    report.managedRuntime.processes,
+    contract.managedRuntime.processes.exact,
+    "managedRuntime.processes"
+  );
+  const bindingValues = /* @__PURE__ */ new Map();
+  const bindingSeen = /* @__PURE__ */ new Map();
+  for (const app of report.apps) {
+    if (!Object.hasOwn(contract.apps.mappings, app)) {
+      fail(`selected app '${app}' has no contract mapping.`);
+    }
+    const mapping = contract.apps.mappings[app];
+    if (!mapping) fail(`selected app '${app}' has no contract mapping.`);
+    for (const key of Object.keys(mapping.bindings).sort()) {
+      const values = bindingValues.get(key) ?? [];
+      const seen = bindingSeen.get(key) ?? /* @__PURE__ */ new Set();
+      for (const value of mapping.bindings[key] ?? []) {
+        if (seen.has(value)) continue;
+        values.push(value);
+        seen.add(value);
+      }
+      bindingValues.set(key, values);
+      bindingSeen.set(key, seen);
+    }
+  }
+  const bindings = Object.fromEntries(
+    Array.from(bindingValues.keys()).sort().map((key) => [key, bindingValues.get(key) ?? []])
+  );
+  return { ...report, contractPath, bindings };
+}
+function loadContract(repoPath, contractPath) {
+  if (import_node_path31.default.isAbsolute(contractPath)) {
+    fail("profile plan contract path must be relative to the repository.");
+  }
+  const absolutePath = assertPathWithinRepo(contractPath, repoPath, "Profile plan contract");
+  let metadata;
+  try {
+    metadata = import_node_fs30.default.lstatSync(absolutePath);
+  } catch (error) {
+    fail(`could not inspect profile plan contract '${contractPath}': ${error.message}`);
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    fail(`profile plan contract '${contractPath}' must be a regular file, not a symlink.`);
+  }
+  if (metadata.size > MAX_CONTRACT_BYTES) {
+    fail(`profile plan contract exceeds the ${MAX_CONTRACT_BYTES}-byte limit.`);
+  }
+  const realRepo = import_node_fs30.default.realpathSync(repoPath);
+  const realContract = import_node_fs30.default.realpathSync(absolutePath);
+  assertPathWithinRepo(realContract, realRepo, "Profile plan contract");
+  const source = import_node_fs30.default.readFileSync(absolutePath, "utf-8");
+  if (Buffer.byteLength(source, "utf-8") > MAX_CONTRACT_BYTES) {
+    fail(`profile plan contract exceeds the ${MAX_CONTRACT_BYTES}-byte limit.`);
+  }
+  return {
+    contract: parseProfilePlanContract(source),
+    contractPath: import_node_path31.default.relative(repoPath, absolutePath).split(import_node_path31.default.sep).join("/")
+  };
+}
+function resolveProfilePlan(options) {
+  const repoPath = resolveRepoPath(options.repo);
+  const config = loadRepoConfig(repoPath);
+  const loaded = loadContract(repoPath, options.contract);
+  return buildProfilePlanReport({
+    report: buildProfileResolutionReport(config, repoPath, options.profile),
+    contract: loaded.contract,
+    registry: registryFor(config),
+    contractPath: loaded.contractPath
+  });
+}
+var import_node_fs30, import_node_path31, import_yaml7, CONTRACT_VERSION, MAX_CONTRACT_BYTES, MAX_APP_MAPPINGS, MAX_BINDING_KEYS, MAX_BINDING_VALUES, MAX_LITERAL_LENGTH, BINDING_KEY;
+var init_profile_plan = __esm({
+  "src/core/profile-plan.ts"() {
+    "use strict";
+    import_node_fs30 = __toESM(require("fs"));
+    import_node_path31 = __toESM(require("path"));
+    import_yaml7 = require("yaml");
+    init_paths();
+    init_profile_resolution();
+    init_repo_config();
+    CONTRACT_VERSION = 1;
+    MAX_CONTRACT_BYTES = 1024 * 1024;
+    MAX_APP_MAPPINGS = 256;
+    MAX_BINDING_KEYS = 64;
+    MAX_BINDING_VALUES = 4096;
+    MAX_LITERAL_LENGTH = 4096;
+    BINDING_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+  }
+});
+
 // src/commands/profile.ts
 var profile_exports = {};
 __export(profile_exports, {
+  runProfilePlanCommand: () => runProfilePlanCommand,
   runProfileResolveCommand: () => runProfileResolveCommand
 });
 async function runProfileResolveCommand(options) {
@@ -13248,6 +13562,18 @@ async function runProfileResolveCommand(options) {
   }
   printProfileResolutionSummary(report);
 }
+async function runProfilePlanCommand(options) {
+  const report = resolveProfilePlan(options);
+  if (options.output) {
+    writeFileAtomically(import_node_path32.default.resolve(options.output), `${JSON.stringify(report, null, 2)}
+`);
+  }
+  if (options.json) {
+    printJSON(report);
+    return;
+  }
+  printProfilePlanSummary(report, options.output);
+}
 function renderValues(values) {
   return values.join(", ") || "-";
 }
@@ -13267,10 +13593,25 @@ function printProfileResolutionSummary(report) {
   process.stdout.write(`Managed processes: ${renderValues(report.managedRuntime.processes)}
 `);
 }
+function printProfilePlanSummary(report, output2) {
+  printProfileResolutionSummary(report);
+  process.stdout.write(`Contract: ${report.contractPath}
+`);
+  for (const key of Object.keys(report.bindings).sort()) {
+    process.stdout.write(`Binding ${key}: ${renderValues(report.bindings[key] ?? [])}
+`);
+  }
+  if (output2) process.stdout.write(`Output: ${import_node_path32.default.resolve(output2)}
+`);
+}
+var import_node_path32;
 var init_profile = __esm({
   "src/commands/profile.ts"() {
     "use strict";
+    import_node_path32 = __toESM(require("path"));
+    init_atomic_file();
     init_output();
+    init_profile_plan();
     init_profile_resolution();
   }
 });
@@ -13557,7 +13898,7 @@ function sanitizeRouterId(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function repoHash(repoPath) {
-  return (0, import_node_crypto10.createHash)("sha1").update(import_node_path31.default.resolve(repoPath)).digest("hex").slice(0, 12);
+  return (0, import_node_crypto10.createHash)("sha1").update(import_node_path33.default.resolve(repoPath)).digest("hex").slice(0, 12);
 }
 function asDockerApp(app) {
   return app.runtime === "docker";
@@ -13636,11 +13977,11 @@ function prepareDockerOverlay(repoPath, appName, apps, publishTcpPorts = false)
   if (dockerApps.length === 0) {
     throw new Error("No docker apps selected to prepare compose overlay.");
   }
-  const cachePath = import_node_path31.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
-  import_node_fs30.default.mkdirSync(cachePath, { recursive: true });
-  const overlayPath = import_node_path31.default.join(cachePath, "compose.devrouter.yml");
+  const cachePath = import_node_path33.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
+  import_node_fs31.default.mkdirSync(cachePath, { recursive: true });
+  const overlayPath = import_node_path33.default.join(cachePath, "compose.devrouter.yml");
   const overlayDocument = buildOverlayDocument(dockerApps, publishTcpPorts);
-  import_node_fs30.default.writeFileSync(overlayPath, import_yaml7.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
+  import_node_fs31.default.writeFileSync(overlayPath, import_yaml8.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
   return {
     overlayPath,
     composeFiles: ensureComposeFiles(dockerApps),
@@ -13760,15 +14101,15 @@ function queryMappedPort(repoPath, composeFiles2, overlayPath, service, internal
   const port = Number(match[1]);
   return Number.isInteger(port) && port > 0 ? port : void 0;
 }
-var import_node_child_process27, import_node_crypto10, import_node_fs30, import_node_path31, import_yaml7;
+var import_node_child_process27, import_node_crypto10, import_node_fs31, import_node_path33, import_yaml8;
 var init_docker_run = __esm({
   "src/core/docker-run.ts"() {
     "use strict";
     import_node_child_process27 = require("child_process");
     import_node_crypto10 = require("crypto");
-    import_node_fs30 = __toESM(require("fs"));
-    import_node_path31 = __toESM(require("path"));
-    import_yaml7 = __toESM(require("yaml"));
+    import_node_fs31 = __toESM(require("fs"));
+    import_node_path33 = __toESM(require("path"));
+    import_yaml8 = __toESM(require("yaml"));
     init_docker_error_guidance();
     init_paths();
     init_router();
@@ -14589,13 +14930,13 @@ function measureWorktreeConsumption(worktreePath, options) {
   const startedAt = Date.now();
   let rootStat;
   try {
-    rootStat = import_node_fs31.default.lstatSync(worktreePath);
+    rootStat = import_node_fs32.default.lstatSync(worktreePath);
   } catch (error) {
     return { status: "unknown", reason: describeError(error, worktreePath) };
   }
   let rootEntries;
   try {
-    rootEntries = import_node_fs31.default.readdirSync(worktreePath, { withFileTypes: true });
+    rootEntries = import_node_fs32.default.readdirSync(worktreePath, { withFileTypes: true });
   } catch (error) {
     return { status: "unknown", reason: describeError(error, worktreePath) };
   }
@@ -14621,10 +14962,10 @@ function measureWorktreeConsumption(worktreePath, options) {
         timedOut = true;
         break;
       }
-      const entryPath = import_node_path32.default.join(dirPath, entry.name);
+      const entryPath = import_node_path34.default.join(dirPath, entry.name);
       let entryStat;
       try {
-        entryStat = import_node_fs31.default.lstatSync(entryPath);
+        entryStat = import_node_fs32.default.lstatSync(entryPath);
       } catch (error) {
         if (error?.code === "ENOENT") continue;
         unreadableReason = describeIncompleteWalk(error);
@@ -14634,7 +14975,7 @@ function measureWorktreeConsumption(worktreePath, options) {
       if (!entryStat.isDirectory()) continue;
       let childEntries;
       try {
-        childEntries = import_node_fs31.default.readdirSync(entryPath, { withFileTypes: true });
+        childEntries = import_node_fs32.default.readdirSync(entryPath, { withFileTypes: true });
       } catch (error) {
         unreadableReason = describeIncompleteWalk(error);
         break;
@@ -14698,12 +15039,12 @@ function describeError(error, worktreePath) {
   }
   return `could not stat worktree path '${worktreePath}': ${error?.message ?? String(error)}`;
 }
-var import_node_fs31, import_node_path32, DEFAULT_DEADLINE_MS, BLOCK_SIZE_BYTES;
+var import_node_fs32, import_node_path34, DEFAULT_DEADLINE_MS, BLOCK_SIZE_BYTES;
 var init_workspace_consumption = __esm({
   "src/core/workspace-consumption.ts"() {
     "use strict";
-    import_node_fs31 = __toESM(require("fs"));
-    import_node_path32 = __toESM(require("path"));
+    import_node_fs32 = __toESM(require("fs"));
+    import_node_path34 = __toESM(require("path"));
     init_devpod_environment();
     DEFAULT_DEADLINE_MS = 1e4;
     BLOCK_SIZE_BYTES = 512;
@@ -14711,7 +15052,7 @@ var init_workspace_consumption = __esm({
 });
 
 // src/core/workspace-cleanup.ts
-function isRecord2(value) {
+function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isSha(value) {
@@ -14804,7 +15145,7 @@ function evaluateWorkspaceActivity(evidence, cutoff) {
 }
 function readGitSnapshot(worktree, commandRunner) {
   const comparablePath = comparableWorkspacePath(worktree.path);
-  if (worktree.prunable || !import_node_fs32.default.existsSync(comparablePath)) {
+  if (worktree.prunable || !import_node_fs33.default.existsSync(comparablePath)) {
     return { worktree, checkout: "missing", head: null, committerDate: null };
   }
   const head = gitOutput(comparablePath, ["rev-parse", "--verify", "HEAD"], commandRunner);
@@ -14855,14 +15196,14 @@ function parseGitHubChanges(value, project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord2(item)) return void 0;
-    const repository = isRecord2(item.repository) ? item.repository.nameWithOwner : void 0;
-    const headRepository = isRecord2(item.headRepository) ? item.headRepository.nameWithOwner : void 0;
+    if (!isRecord3(item)) return void 0;
+    const repository = isRecord3(item.repository) ? item.repository.nameWithOwner : void 0;
+    const headRepository = isRecord3(item.headRepository) ? item.headRepository.nameWithOwner : void 0;
     if (repository !== project || headRepository !== project || item.headRefName !== branch || !isSha(item.headRefOid) || typeof item.baseRefName !== "string") {
       continue;
     }
     const merged = item.state === "MERGED" && validTimestamp(item.mergedAt);
-    const mergeCommit = isRecord2(item.mergeCommit) && isSha(item.mergeCommit.oid) ? item.mergeCommit.oid : void 0;
+    const mergeCommit = isRecord3(item.mergeCommit) && isSha(item.mergeCommit.oid) ? item.mergeCommit.oid : void 0;
     const baseSha = isSha(item.baseRefOid) ? item.baseRefOid : void 0;
     changes.push({
       sourceBranch: branch,
@@ -14879,14 +15220,14 @@ function parseGitLabChanges(value, _project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord2(item)) return void 0;
+    if (!isRecord3(item)) return void 0;
     const sourceProjectId = item.source_project_id;
     const targetProjectId = item.target_project_id;
     const sameProject = typeof sourceProjectId === "number" && typeof targetProjectId === "number" && sourceProjectId === targetProjectId;
     if (!sameProject || item.source_branch !== branch || !isSha(item.sha) || typeof item.target_branch !== "string") {
       continue;
     }
-    const diffRefs = isRecord2(item.diff_refs) ? item.diff_refs : void 0;
+    const diffRefs = isRecord3(item.diff_refs) ? item.diff_refs : void 0;
     const mergeCommitSha = isSha(item.merge_commit_sha) ? item.merge_commit_sha : void 0;
     const baseSha = diffRefs && isSha(diffRefs.base_sha) ? diffRefs.base_sha : void 0;
     changes.push({
@@ -15329,7 +15670,7 @@ function buildWorkspaceCleanupReport(options = {}, dependencies = {}) {
       containers = measureContainersFn(worktreePaths);
     } catch (error) {
       const reason = `container measurement failed: ${describeCause(error)}`;
-      containers = new Map(worktreePaths.map((path32) => [path32, unknownContainers(reason)]));
+      containers = new Map(worktreePaths.map((path34) => [path34, unknownContainers(reason)]));
     }
   }
   const rows = records.map((record) => {
@@ -15378,12 +15719,12 @@ function buildWorkspaceCleanupReport(options = {}, dependencies = {}) {
     workspaces: rows
   };
 }
-var import_node_child_process29, import_node_fs32, DEFAULT_INACTIVE_FOR, READ_ONLY_GIT_ENV2, ACTIVITY_SOURCES, defaultCommandRunner;
+var import_node_child_process29, import_node_fs33, DEFAULT_INACTIVE_FOR, READ_ONLY_GIT_ENV2, ACTIVITY_SOURCES, defaultCommandRunner;
 var init_workspace_cleanup = __esm({
   "src/core/workspace-cleanup.ts"() {
     "use strict";
     import_node_child_process29 = require("child_process");
-    import_node_fs32 = __toESM(require("fs"));
+    import_node_fs33 = __toESM(require("fs"));
     init_devpod_workspaces();
     init_host_routes();
     init_repo_config();
@@ -15560,7 +15901,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.50" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.51" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {
@@ -15728,6 +16069,17 @@ profileCommand.command("resolve").description("Print the exact apps, dependencie
     await runProfileResolveCommand2(options);
   })
 );
+profileCommand.command("plan").description("Validate a profile against a repository contract and emit literal bindings").option("--repo <path>", "Repository path (defaults to current directory)").option(
+  "--profile <name>",
+  "Profile name or comma-separated selection (defaults to configured profile)"
+).requiredOption("--contract <path>", "Repository-relative profile plan contract").option("--output <path>", "Atomically write the JSON plan with mode 0600").option("--json", "Output stable JSON").action(
+  withErrorHandling(
+    async (options) => {
+      const { runProfilePlanCommand: runProfilePlanCommand2 } = await Promise.resolve().then(() => (init_profile(), profile_exports));
+      await runProfilePlanCommand2(options);
+    }
+  )
+);
 var appCommand = program.command("app").description("Manage app entries and runtime actions from `.devrouter.yml`");
 appCommand.command("add").description("Add or update one app definition in `.devrouter.yml`").requiredOption("--name <name>", "App name").option("--kind <kind>", "app or dependency", "app").option("--host <host>", "Hostname ending with .localhost (required for --kind app)").option("--protocol <protocol>", "http or tcp (required for --kind app)").option(
   "--runtime <runtime>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "description": "Local dev routing CLI with shared Traefik reverse proxy",
   "author": "Roland Schlaefli",
   "homepage": "https://github.com/rschlaefli/devrouter#readme",

package/upgrade-prompts/0.0.51.md

@@ -0,0 +1,40 @@
+# Upgrade to devrouter 0.0.51
+
+Devrouter can now turn an exact profile selection into repository-owned literal
+bindings for CI or other automation without touching a runtime.
+
+1. Install `@devrouter/cli@0.0.51` on the host and bump `.devrouter.yml` to
+   `devrouter.version: 0.0.51`.
+2. Keep using `devrouter profile resolve` when automation only needs exact
+   selected resources. No consumer change is required for that command.
+3. When automation needs build arguments, readiness URLs, or other literals,
+   add a separate version-1 contract inside the repository and invoke
+   `devrouter profile plan --contract <repo-relative-yaml>`. Map every selectable
+   app, constrain dependency and service registries, and set the exact managed
+   process list for that workload.
+4. Treat bindings as data. Validate the keys expected by the consumer and pass
+   each value as a literal argument or input. Do not evaluate the values through
+   a shell or template engine.
+5. Refresh generated guidance with `devrouter repo agents` when the repository
+   stores Devrouter's generated `AGENTS.md` section or bundled skill.
+
+Verification:
+
+- Run `devrouter -V --repo <checkout>` and confirm the installed CLI and local
+  repository report `0.0.51`.
+- With no workspace running, run `devrouter profile plan --repo <checkout>
+  --profile <selection> --contract <repo-relative-yaml> --output <plan.json>
+  --json` and require exit status zero.
+- Require stdout and `<plan.json>` to contain the same schema-version-1 profile,
+  repository-relative `contractPath`, and expected literal `bindings`. Require
+  the file mode to be `0600`.
+- Reject unknown schema versions, missing mappings, unexpected binding keys, and
+  any resource selection outside the contract instead of widening the profile.
+
+Report template:
+
+- CLI/config version: `0.0.51`
+- Profile and contract: `<selection and repository-relative path>`
+- Literal binding plan: `<passed, not used, or details>`
+- Runtime side effects: `none`
+- Remaining blockers: `<none or details>`