@devrouter/cli 0.0.37 → 0.0.38

package/dist/devrouter.js

@@ -221,6 +221,31 @@ healthcheck:
   retries: 20
 \`\`\`
 
+## Profiles
+
+Optional named subsets of routed apps in \`.devrouter.yml\` so \`ensure\` can start only what a task needs:
+
+\`\`\`yaml
+profiles:
+  manage:
+    apps: [manage, api, auth]
+    readiness: [manage, api]
+  pwa:
+    apps: [pwa, api, auth]
+    readiness: [pwa, api]
+  full:
+    apps: ['*']
+    default: true
+\`\`\`
+
+- \`apps\` (required): routed app names (\`kind=app\`) or \`['*']\` for everything.
+- \`dependencies\` (optional): \`kind=dependency\` services this profile needs; omitted = every dependency a kept app requires transitively.
+- \`readiness\` (optional): subset of the profile's apps that \`ensure\` HTTP-probes; omitted = all profile apps with an http route.
+- \`default\` (optional): at most one; used when \`--profile\` is omitted. No \`profiles\` key at all = implicit full behavior.
+- Validation is strict at config load: unknown keys, non-routed \`apps\`, non-dependency \`dependencies\`, \`readiness\` outside the profile's apps, and multiple defaults are rejected.
+- Selection: \`devrouter ensure <path> --profile <name>\`. Comma-separated selections (\`--profile manage,pwa\`) merge with deduplication; the canonical name is sorted-unique so order never affects identity or fingerprints. A wildcard member collapses to everything.
+- Managed adapters receive \`DEVROUTER_PROFILE\` (canonical resolved name) in the post-start env; profile switches replace the owned process group via the fingerprint.
+
 ## 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, "_")\`):
@@ -1926,7 +1951,11 @@ function parseApp(value, index) {
 }
 function parseConfig(raw, configPath) {
   const root = ensureObject(raw, configPath);
-  ensureAllowedKeys(root, ["version", "devrouter", "project", "secretManager", "apps"], configPath);
+  ensureAllowedKeys(
+    root,
+    ["version", "devrouter", "project", "secretManager", "profiles", "apps"],
+    configPath
+  );
   const version = toIntegerOrThrow(root.version, `${configPath}.version`);
   if (version !== 1) {
     throw new Error(`${configPath}.version must be 1.`);
@@ -1994,14 +2023,202 @@ function parseConfig(raw, configPath) {
     }
     seenNames.add(app.name);
   }
+  const profiles = parseProfiles(root.profiles, configPath, apps);
   return {
     version: 1,
     ...devrouter ? { devrouter } : {},
     project: root.project && typeof root.project === "object" ? { name: root.project.name } : void 0,
     ...secretManager ? { secretManager } : {},
+    ...profiles ? { profiles } : {},
     apps
   };
 }
+function parseProfiles(value, configPath, apps) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const raw = ensureObject(value, `${configPath}.profiles`);
+  if (Object.keys(raw).length === 0) {
+    throw new Error(`${configPath}.profiles must define at least one profile.`);
+  }
+  if (Object.keys(raw).length > MAX_PROFILES) {
+    throw new Error(`${configPath}.profiles exceeds the maximum of ${MAX_PROFILES} profiles.`);
+  }
+  const routedNames = new Set(
+    apps.filter((app) => app.kind !== "dependency").map((app) => app.name)
+  );
+  const result = {};
+  let defaultCount = 0;
+  for (const [name, profileValue] of Object.entries(raw)) {
+    if (!PROFILE_NAME_RE.test(name)) {
+      throw new Error(
+        `${configPath}.profiles.${name} is not a valid profile name (lowercase alphanumerics and hyphens).`
+      );
+    }
+    const profile = ensureObject(profileValue, `${configPath}.profiles.${name}`);
+    ensureAllowedKeys(
+      profile,
+      ["apps", "dependencies", "readiness", "default"],
+      `${configPath}.profiles.${name}`
+    );
+    const profileApps = toStringArray(profile.apps, `${configPath}.profiles.${name}.apps`);
+    if (profileApps.length === 0) {
+      throw new Error(`${configPath}.profiles.${name}.apps must not be empty.`);
+    }
+    const isWildcard = profileApps.length === 1 && profileApps[0] === "*";
+    if (!isWildcard) {
+      for (const appName of profileApps) {
+        if (!routedNames.has(appName)) {
+          throw new Error(
+            `${configPath}.profiles.${name}.apps references '${appName}', which is not a routed app (kind=app).`
+          );
+        }
+      }
+    }
+    let dependencies;
+    if (profile.dependencies !== void 0) {
+      dependencies = toStringArray(
+        profile.dependencies,
+        `${configPath}.profiles.${name}.dependencies`
+      );
+      for (const depName of dependencies) {
+        const dependency = apps.find((candidate) => candidate.name === depName);
+        if (!dependency) {
+          throw new Error(
+            `${configPath}.profiles.${name}.dependencies references '${depName}', which does not exist in apps.`
+          );
+        }
+        if (dependency.kind !== "dependency") {
+          throw new Error(
+            `${configPath}.profiles.${name}.dependencies references '${depName}', which is not kind=dependency.`
+          );
+        }
+      }
+    }
+    let readiness;
+    if (profile.readiness !== void 0) {
+      readiness = toStringArray(profile.readiness, `${configPath}.profiles.${name}.readiness`);
+      const appSet = new Set(isWildcard ? Array.from(routedNames) : profileApps);
+      for (const readyName of readiness) {
+        if (!appSet.has(readyName)) {
+          throw new Error(
+            `${configPath}.profiles.${name}.readiness references '${readyName}', which is not in the profile's apps.`
+          );
+        }
+      }
+    }
+    let isDefault = false;
+    if (profile.default !== void 0) {
+      if (typeof profile.default !== "boolean") {
+        throw new Error(`${configPath}.profiles.${name}.default must be a boolean.`);
+      }
+      isDefault = profile.default;
+    }
+    if (isDefault) {
+      defaultCount += 1;
+    }
+    result[name] = {
+      apps: profileApps,
+      ...dependencies ? { dependencies } : {},
+      ...readiness ? { readiness } : {},
+      ...isDefault ? { default: true } : {}
+    };
+  }
+  if (defaultCount > 1) {
+    throw new Error(`${configPath}.profiles must have at most one default profile.`);
+  }
+  return result;
+}
+function resolveProfile(config, profileOverride) {
+  const profiles = config.profiles;
+  const mergeSelection = (selection) => {
+    const names = Array.from(
+      new Set(
+        selection.split(",").map((name) => name.trim()).filter(Boolean)
+      )
+    );
+    if (names.length === 0) {
+      throw new Error("Profile selection is empty.");
+    }
+    const missing = names.filter((name) => !profiles?.[name]);
+    if (missing.length > 0) {
+      const available = profiles ? Object.keys(profiles).join(", ") : "(none defined)";
+      throw new Error(
+        `Profile '${missing[0]}' is not defined in .devrouter.yml. Available: ${available}`
+      );
+    }
+    if (names.length === 1) {
+      return { name: names[0], profile: profiles?.[names[0]] };
+    }
+    const canonicalName = [...names].sort().join(",");
+    const apps = /* @__PURE__ */ new Set();
+    const dependencies = /* @__PURE__ */ new Set();
+    const readiness = /* @__PURE__ */ new Set();
+    let hasWildcard = false;
+    for (const name of names) {
+      const profile = profiles?.[name];
+      if (!profile) continue;
+      if (profile.apps.length === 1 && profile.apps[0] === "*") {
+        hasWildcard = true;
+        continue;
+      }
+      for (const appName of profile.apps) apps.add(appName);
+      for (const depName of profile.dependencies ?? []) dependencies.add(depName);
+      for (const readyName of profile.readiness ?? []) readiness.add(readyName);
+    }
+    if (hasWildcard) {
+      return { name: canonicalName, profile: { apps: ["*"] } };
+    }
+    const merged = {
+      apps: Array.from(apps),
+      ...dependencies.size > 0 ? { dependencies: Array.from(dependencies) } : {},
+      ...readiness.size > 0 ? { readiness: Array.from(readiness) } : {}
+    };
+    return { name: canonicalName, profile: merged };
+  };
+  if (profileOverride !== void 0) {
+    return mergeSelection(profileOverride);
+  }
+  if (profiles) {
+    const defaultName = Object.keys(profiles).find((name) => profiles[name].default);
+    if (defaultName) {
+      return { name: defaultName, profile: profiles[defaultName] };
+    }
+    return { name: "full", profile: void 0 };
+  }
+  return { name: "full", profile: void 0 };
+}
+function applyProfile(config, profile) {
+  if (!profile || profile.apps.length === 1 && profile.apps[0] === "*") {
+    return config;
+  }
+  const appSet = new Set(profile.apps);
+  const next = structuredClone(config);
+  const kept = [];
+  const keptDependencies = /* @__PURE__ */ new Set();
+  for (const app of next.apps) {
+    if (app.kind === "dependency") {
+      continue;
+    }
+    if (!appSet.has(app.name)) {
+      continue;
+    }
+    for (const dependency of resolveAppDependencies(config, app)) {
+      keptDependencies.add(dependency.name);
+    }
+    kept.push(app);
+  }
+  for (const dependencyName of profile.dependencies ?? []) {
+    keptDependencies.add(dependencyName);
+  }
+  for (const app of next.apps) {
+    if (app.kind === "dependency" && keptDependencies.has(app.name)) {
+      kept.push(app);
+    }
+  }
+  next.apps = kept;
+  return next;
+}
 function renderConfig(config) {
   return import_yaml2.default.stringify(config, { lineWidth: 0 });
 }
@@ -2049,7 +2266,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.37" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.38" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -2340,11 +2557,13 @@ function applyWorkspace(config, workspace, repoPath) {
   }
   return next;
 }
-function loadRuntimeConfig(repoPath, workspaceOverride) {
+function loadRuntimeConfig(repoPath, workspaceOverride, profileOverride) {
   const resolved = resolveRepoPath(repoPath);
   const raw = loadRepoConfig(resolved);
+  const resolvedProfile = resolveProfile(raw, profileOverride);
   const workspace = resolveWorkspace(resolved, workspaceOverride);
-  return { config: applyWorkspace(raw, workspace, resolved), workspace };
+  const config = applyProfile(applyWorkspace(raw, workspace, resolved), resolvedProfile.profile);
+  return { config, workspace, profile: resolvedProfile.name };
 }
 function resolveAppByName(repoPath, name, workspaceOverride) {
   const { config, workspace } = loadRuntimeConfig(repoPath, workspaceOverride);
@@ -2386,7 +2605,7 @@ function resolveAppDependencies(config, app) {
   }
   return results;
 }
-var import_node_fs7, import_node_path6, import_yaml2, hasWarnedVersionMismatch, CONFIG_FILE_NAME, DEFAULT_TCP_PROTOCOL, VALID_HOSTNAME_RE, DEVROUTER_VERSION_RE, VALID_ENV_NAME_RE, VALID_ENV_VAR_RE, UPSTREAM_TEMPLATE_RE, MAX_COMMAND_LENGTH, DEFAULT_HOST_STRATEGY;
+var import_node_fs7, import_node_path6, import_yaml2, hasWarnedVersionMismatch, CONFIG_FILE_NAME, DEFAULT_TCP_PROTOCOL, VALID_HOSTNAME_RE, DEVROUTER_VERSION_RE, VALID_ENV_NAME_RE, VALID_ENV_VAR_RE, UPSTREAM_TEMPLATE_RE, MAX_COMMAND_LENGTH, DEFAULT_HOST_STRATEGY, PROFILE_NAME_RE, MAX_PROFILES;
 var init_repo_config = __esm({
   "src/core/repo-config.ts"() {
     "use strict";
@@ -2410,6 +2629,8 @@ var init_repo_config = __esm({
       denyPorts: [80, 443, 5432],
       allowPortRange: "1024-65535"
     };
+    PROFILE_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    MAX_PROFILES = 32;
   }
 });
 
@@ -2470,6 +2691,7 @@ function buildOnboardingPrompt(options = {}) {
     "- project.name: string (optional)",
     `- secretManager.command: string (optional; SM command including trailing \`--\` boundary; supports \`${SECRET_MANAGER_ENV_PLACEHOLDER}\` template placeholder)`,
     `- secretManager.defaultEnv: string (optional; fallback env for \`${SECRET_MANAGER_ENV_PLACEHOLDER}\` template; required when command contains \`${SECRET_MANAGER_ENV_PLACEHOLDER}\`)`,
+    "- profiles: map (optional; named subsets of routed apps; see Profile schema below)",
     "- apps: array (required)",
     "",
     "Canonical valid skeleton:",
@@ -2514,6 +2736,14 @@ function buildOnboardingPrompt(options = {}) {
     "  - docker.composeFiles: string[]",
     "  - do not set host/protocol/tcpProtocol/hostRun/docker.internalPort/docker.router",
     "",
+    "Profile schema (each value in the optional top-level profiles map):",
+    '- apps: array (required; routed app names, or ["*"] for every routed app)',
+    "- dependencies: array (optional; kind=dependency names this profile needs; omitted = every dependency a kept app requires transitively)",
+    "- readiness: array (optional; subset of the profile's apps that `devrouter ensure` HTTP-probes before readiness; omitted = all profile apps with an http route)",
+    "- default: boolean (optional; at most one profile may set true)",
+    "- validation: unknown profile keys are rejected; apps must reference routed apps (kind=app); dependencies must reference kind=dependency apps; readiness entries must be in the profile's apps; at most one default",
+    "- selection: `devrouter ensure <path> --profile <name>` scopes routes/readiness to the profile; comma-separated selections (e.g. --profile a,b) merge with deduplication and a canonical sorted name; managed adapters receive DEVROUTER_PROFILE in the post-start env",
+    "",
     "Validation rules to enforce:",
     "- kind=app host must end with .localhost",
     `- kind=app runtime=host supports protocol=${formatProtocolRule("host")} only`,
@@ -3619,6 +3849,7 @@ function runManagedPostStart(options) {
       `DEVROUTER_PROCESS_HELPER=${RUNTIME_HELPER_PATH}`,
       "--env",
       `DEVROUTER_PROCESS_ADAPTER_SHA256=${options.plan.adapterSha256}`,
+      ...options.profile ? ["--env", `DEVROUTER_PROFILE=${options.profile}`] : [],
       options.container.id,
       "bash",
       "-c",
@@ -3630,7 +3861,7 @@ function runManagedPostStart(options) {
   );
   if (started.status !== 0) {
     const details = commandFailure(started);
-    throw new Error(`Managed post-start failed${details ? `: ${details}` : "."}`);
+    throw new Error(`Managed post-start failed${details ? `: ${details}.` : "."}`);
   }
 }
 var import_node_child_process5, import_node_crypto3, import_node_fs9, import_node_path8, MANAGED_MARKER, MANAGED_ADAPTER_PATH, RUNTIME_HELPER_PATH, ADAPTER_WRAPPER;
@@ -5794,7 +6025,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.37" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.38" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -6782,7 +7013,8 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       const managedPostStart = resolveManagedPostStartPlan(repoPath);
       const runtime = loadRuntimeConfig(
         repoPath,
-        target.kind === "primary" ? "" : target.workspace
+        target.kind === "primary" ? "" : target.workspace,
+        options.profile
       );
       const apps = proxyAppsFromConfig(runtime.config);
       const parsedUpstreams = apps.map((app) => parseUpstream(app.upstream));
@@ -6860,7 +7092,8 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       runManagedPostStart({
         plan: managedPostStart,
         container,
-        quiet: options.quiet
+        quiet: options.quiet,
+        profile: runtime.profile
       });
       const publication = await replacePublishedProxyRoutes(
         repoPath,
@@ -6882,7 +7115,8 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         runManagedPostStart({
           plan: managedPostStart,
           container: recoveredContainer,
-          quiet: options.quiet
+          quiet: options.quiet,
+          profile: runtime.profile
         });
         recreated = true;
         replaceHostRoutesForRepo(repoPath, publication.routes);
@@ -6907,6 +7141,7 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         kind: target.kind,
         repoPath,
         workspace: target.workspace,
+        profile: runtime.profile,
         devpodId,
         urls,
         recreated,
@@ -6978,14 +7213,15 @@ async function runEnsureCommand(options) {
   const repoPath = resolveGitCheckoutPath(options.path);
   const result = await workspaceEnsure(repoPath, {
     open: options.open,
-    quiet: Boolean(options.json)
+    quiet: Boolean(options.json),
+    profile: options.profile
   });
   if (options.json) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
     return;
   }
-  const label = result.kind === "primary" ? "Primary checkout" : `Workspace '${result.workspace}'`;
+  const label = result.kind === "primary" ? `Primary checkout [profile: ${result.profile}]` : `Workspace '${result.workspace}' [profile: ${result.profile}]`;
   const routes = result.urls.map((url) => `  ${url}`).join("\n");
   process.stdout.write(`${label} is ready (${result.devpodId}).
 ${routes}${routes ? "\n" : ""}`);
@@ -11425,7 +11661,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.37" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.38" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {
@@ -11475,12 +11711,13 @@ program.command("up").description("Ensure devnet and start shared Traefik (reser
     await runUpCommand2();
   })
 );
-program.command("ensure").description("Start and prove a primary or linked checkout's environment and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
+program.command("ensure").description("Start and prove a primary or linked checkout's environment and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
   withErrorHandling(async (repoPath, _options, command) => {
     const options = command.opts();
     const { runEnsureCommand: runEnsureCommand2 } = await Promise.resolve().then(() => (init_ensure(), ensure_exports));
     await runEnsureCommand2({
       path: repoPath,
+      profile: options.profile,
       open: Boolean(options.open),
       json: Boolean(options.json)
     });
@@ -11679,13 +11916,14 @@ workspaceCommand2.command("up").description(
     });
   })
 );
-workspaceCommand2.command("ensure").description("Start and prove a primary or linked checkout's DevPod, upstreams, and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
+workspaceCommand2.command("ensure").description("Start and prove a primary or linked checkout's DevPod, upstreams, and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
   withErrorHandling(
     async (worktreePath, _options, command) => {
       const options = command.opts();
       const { runEnsureCommand: runEnsureCommand2 } = await Promise.resolve().then(() => (init_ensure(), ensure_exports));
       await runEnsureCommand2({
         path: worktreePath,
+        profile: options.profile,
         open: Boolean(options.open),
         json: Boolean(options.json)
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "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.38.md

@@ -0,0 +1,45 @@
+# Upgrade to devrouter 0.0.38
+
+Devrouter now supports profile-scoped environments: a `profiles` map in
+`.devrouter.yml` plus `devrouter ensure --profile <name>` starts, routes, and
+readiness-probes only the apps a task needs. Comma-separated selections
+(`--profile manage,pwa`) merge profiles with deduplication, and managed
+adapters receive `DEVROUTER_PROFILE` so they can scope their dev process tree
+to the same selection.
+
+1. Install `@devrouter/cli@0.0.38` on the host and bump `.devrouter.yml` to
+   `devrouter.version: 0.0.38`.
+2. No schema or data migration is required. Repositories without a `profiles`
+   key keep the implicit full behavior; adding `profiles` is optional.
+   Validation is strict: unknown keys, references to apps that are not routed
+   (`kind=app`), references to apps that are not `kind=dependency` in
+   `dependencies`, `readiness` entries outside the profile's apps, and more
+   than one `default: true` are rejected at config-load time.
+3. Optional: declare profiles and select one per task, e.g.
+   `devrouter ensure <checkout> --profile <name>` or
+   `devrouter ensure <checkout> --profile <name-a>,<name-b>`. The merged name
+   is canonicalized (sorted unique), so order does not affect identity.
+   Repository post-start adapters can read `DEVROUTER_PROFILE` and must treat
+   an empty/unset value as the default profile.
+4. Consumers that parse `ensure --json` output must accept the new `profile`
+   field in the result object.
+
+Verification:
+
+- Run `devrouter -V --repo <checkout>` and confirm both the installed CLI and
+  the local repository report `0.0.38`.
+- Run `devrouter doctor --repo <checkout> --json` and confirm the config still
+  validates.
+- With profiles declared, run `devrouter ensure <checkout> --profile <name>
+  --json` and confirm the result reports `"profile": "<name>"` and that only
+  the profile's routes are published (`devrouter ls`).
+- Re-run `devrouter ensure <checkout> --json` without `--profile` and confirm
+  the default/full route set is restored.
+
+Report template:
+
+- CLI/config version: `0.0.38`
+- Config validation: `<passed or details>`
+- Profile-scoped ensure: `<passed or details>`
+- Default (full) ensure after profile use: `<passed or details>`
+- Remaining blockers: `<none or details>`