@getmonoceros/workbench 1.30.0 → 1.31.1

package/dist/bin.js

@@ -727,11 +727,28 @@ var init_descriptor = __esm({
        * Coerced to string so authors can write bare YAML numbers
        * (`versions: [latest, 21, 17]`) without quoting.
        */
-      versions: z2.array(z2.coerce.string()).optional()
+      versions: z2.array(z2.coerce.string()).optional(),
+      /**
+       * VS Code extensions to *recommend* (not auto-install) when this language
+       * is present, written to the `.code-workspace` `extensions.recommendations`
+       * (ADR 0016). List every editor variant where editors diverge: VS Code and
+       * VSCodium each resolve recommendation IDs against their own registry (MS
+       * Marketplace / Open VSX) and silently skip what they can't find, so an
+       * ID that only exists for one editor is simply ignored by the other. E.g.
+       * `[ms-python.python, ms-python.vscode-pylance]` — Codium drops Pylance.
+       */
+      vscodeExtensions: z2.array(z2.string()).optional()
     });
     ServiceBlockSchema = z2.object({
       image: z2.string().min(1),
       defaultPort: z2.number().int().positive().optional(),
+      /**
+       * Compose `command:` for the service container — the process to run
+       * instead of the image's default CMD. Baked into the expanded yml
+       * (visible + editable, unlike `deferStart`). E.g. Keycloak needs
+       * `start-dev --import-realm` because its image has no auto-start default.
+       */
+      command: z2.string().optional(),
       dataMount: z2.string().optional(),
       /**
        * Compose `user:` for the service container (e.g. `"0:0"`). Needed for
@@ -769,7 +786,32 @@ var init_descriptor = __esm({
         apt: z2.array(z2.string()).optional(),
         npm: z2.array(z2.string()).optional()
       }).optional(),
-      vscodeExtensions: z2.array(z2.string()).optional()
+      vscodeExtensions: z2.array(z2.string()).optional(),
+      /**
+       * Example bind-mounts rendered as a COMMENTED `volumes:` scaffold in the
+       * generated yml (init / add-service), for the builder to uncomment and
+       * edit. NOT active volumes — the catalog can't know the builder's repo
+       * path. Used by services that need a project file but can't auto-wire it
+       * (e.g. Keycloak's realm.json / theme). Each entry is a compose volume
+       * spec, e.g. `projects/<app>/keycloak/realm.json:/opt/keycloak/data/import/<app>.json:ro`.
+       */
+      exampleVolumes: z2.array(z2.string()).optional(),
+      /**
+       * Start this service in a SECOND WAVE, host-side, *after* `devcontainer
+       * up` (and thus the in-container repo clone in post-create) has
+       * finished — instead of together with the workspace at `compose up`.
+       * For a service that bind-mounts a file from a cloned repo (e.g.
+       * Keycloak's `realm.json`, a Postgres `init.sql`): the file does not
+       * exist at the normal parallel start, but is on disk by the time the
+       * second wave runs. See ADR 0025.
+       *
+       * Deliberately a HIDDEN, descriptor-only field: it is NOT exposed in the
+       * user-facing yml schema and not baked into the expanded service object.
+       * The start paths resolve it by catalog lookup on the service name
+       * (`serviceDefersStart`). Caveat: a deferred service is NOT reachable
+       * during the workspace's post-create.
+       */
+      deferStart: z2.boolean().optional()
     });
     PersistentHomeFileSchema = z2.object({
       path: z2.string().min(1),
@@ -2219,6 +2261,12 @@ function knownLanguages() {
 function knownServices() {
   return Object.keys(SERVICE_CATALOG).sort();
 }
+function serviceDefersStart(name) {
+  return SERVICE_CATALOG[name]?.deferStart === true;
+}
+function curatedServiceExampleVolumes(name) {
+  return SERVICE_CATALOG[name]?.exampleVolumes ?? [];
+}
 function resolveService(entry2) {
   return {
     name: entry2.name,
@@ -2254,6 +2302,7 @@ function expandCuratedService(name) {
     } : {},
     ...def.dataMount ? { volumes: [`data:${def.dataMount}`] } : {},
     ...def.user ? { user: def.user } : {},
+    ...def.command ? { command: def.command } : {},
     ...def.healthcheck ? { healthcheck: def.healthcheck } : {},
     // Bake the connection-env templates into the yml (suffix → template) so
     // they travel with the service: a renamed/duplicated instance keeps them,
@@ -2308,7 +2357,7 @@ function deriveServiceName(image) {
   const noTag = lastSegment.split("@")[0].split(":")[0];
   return noTag.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
 }
-var DEFAULT_BASE_IMAGE, override, BASE_IMAGE, RUNTIME_IMAGE_REPO, DEFAULT_RUNTIME_VERSION, MIN_RUNTIME_FOR_SSH_ATTACH, DESCRIPTORS, BUILTIN_LANGUAGES, LANGUAGE_CATALOG, LANGUAGE_SPEC_RE, SERVICE_CATALOG;
+var DEFAULT_BASE_IMAGE, override, BASE_IMAGE, RUNTIME_IMAGE_REPO, DEFAULT_RUNTIME_VERSION, MIN_RUNTIME_FOR_SSH_ATTACH, DESCRIPTORS, BUILTIN_LANGUAGES, LANGUAGE_CATALOG, LANGUAGE_SPEC_RE, SERVICE_CATALOG, DEFERRED_SERVICE_PROFILE;
 var init_catalog = __esm({
   "src/create/catalog.ts"() {
     "use strict";
@@ -2338,7 +2387,8 @@ var init_catalog = __esm({
           feature: c.descriptor.language.feature,
           ...Object.keys(defaults).length > 0 ? { defaultOptions: defaults } : {},
           ...Object.keys(ymlOptions).length > 0 ? { ymlOptions } : {},
-          ...c.descriptor.language.defaultVersion !== void 0 ? { defaultVersion: c.descriptor.language.defaultVersion } : {}
+          ...c.descriptor.language.defaultVersion !== void 0 ? { defaultVersion: c.descriptor.language.defaultVersion } : {},
+          ...c.descriptor.language.vscodeExtensions ? { vscodeExtensions: c.descriptor.language.vscodeExtensions } : {}
         };
         return [key, entry2];
       })
@@ -2364,11 +2414,15 @@ var init_catalog = __esm({
           defaultPort: svc.defaultPort,
           ...svc.vscodeExtensions ? { vscodeExtensions: svc.vscodeExtensions } : {},
           ...svc.connectionEnv ? { connectionEnv: svc.connectionEnv } : {},
-          ...svc.client ? { client: svc.client } : {}
+          ...svc.client ? { client: svc.client } : {},
+          ...svc.command ? { command: svc.command } : {},
+          ...svc.exampleVolumes ? { exampleVolumes: svc.exampleVolumes } : {},
+          ...svc.deferStart ? { deferStart: true } : {}
         };
         return [key, entry2];
       })
     );
+    DEFERRED_SERVICE_PROFILE = "monoceros-deferred";
   }
 });
 
@@ -2428,6 +2482,13 @@ function renderCustomService(name, image) {
   ].join("\n");
   return { bodyLines, comment };
 }
+function exampleVolumesComment(exampleVolumes) {
+  if (exampleVolumes.length === 0) return void 0;
+  return [
+    " volumes:                   # uncomment + edit to mount your realm/theme",
+    ...exampleVolumes.map((v) => `   - ${v}`)
+  ].join("\n");
+}
 function customServiceHint(name) {
   return `'${name}' is a custom image \u2014 Monoceros doesn't know its env, ports or volumes. Review the commented block under services[].${name} in the yml and fill in what the image needs.`;
 }
@@ -3109,11 +3170,12 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
   const workspaceEnv = featureWorkspaceEnv(resolvedFeatures);
   const containerEnvField = Object.keys(workspaceEnv).length > 0 ? { containerEnv: workspaceEnv } : void 0;
   if (needsCompose(opts)) {
+    const eagerServices = opts.services.filter((s) => !serviceDefersStart(s.name)).map((s) => s.name);
     return {
       name: opts.name,
       dockerComposeFile: "compose.yaml",
       service: "workspace",
-      ...opts.services.length > 0 ? { runServices: opts.services.map((s) => s.name) } : {},
+      ...eagerServices.length > 0 ? { runServices: eagerServices } : {},
       workspaceFolder: `/workspaces/${opts.name}`,
       remoteUser: "node",
       forwardPorts: ports,
@@ -3212,6 +3274,10 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
   for (const svc of opts.services) {
     lines.push(`  ${svc.name}:`);
     lines.push(`    image: ${svc.image}`);
+    if (serviceDefersStart(svc.name)) {
+      lines.push("    profiles:");
+      lines.push(`      - ${DEFERRED_SERVICE_PROFILE}`);
+    }
     if (svc.user !== void 0) {
       lines.push(`    user: ${composeScalar(svc.user)}`);
     }
@@ -3273,9 +3339,22 @@ function extractRepoHost(url) {
 }
 function computeExtensionRecommendations(opts) {
   const recs = /* @__PURE__ */ new Set();
+  for (const langSpec of opts.languages) {
+    const parsed = parseLanguageSpec(langSpec);
+    if (!parsed) continue;
+    for (const ext of LANGUAGE_CATALOG[parsed.name]?.vscodeExtensions ?? []) {
+      recs.add(ext);
+    }
+  }
   for (const svc of opts.services) {
-    const catalogEntry = SERVICE_CATALOG[svc.name];
-    for (const ext of catalogEntry?.vscodeExtensions ?? []) {
+    for (const ext of SERVICE_CATALOG[svc.name]?.vscodeExtensions ?? []) {
+      recs.add(ext);
+    }
+  }
+  for (const rawRef of Object.keys(opts.features ?? {})) {
+    const match = matchMonocerosFeature(rawRef);
+    const descriptor = match ? featureDescriptor(match.name) : void 0;
+    for (const ext of descriptor?.feature?.vscodeExtensions ?? []) {
       recs.add(ext);
     }
   }
@@ -4130,7 +4209,7 @@ async function runAddService(input) {
   const image = curated ? expandCuratedService(arg).image : arg;
   const custom = curated ? null : renderCustomService(name, arg);
   const bodyLines = curated ? renderServiceObjectBody({ ...expandCuratedService(arg), name }) : custom.bodyLines;
-  const scaffoldComment = curated ? void 0 : custom.comment;
+  const scaffoldComment = curated ? exampleVolumesComment(curatedServiceExampleVolumes(arg)) : custom.comment;
   const result = await mutate(input, (doc) => {
     const r = addServiceEntryToDoc(
       doc,
@@ -6738,6 +6817,25 @@ import { existsSync as existsSync9 } from "fs";
 import path17 from "path";
 import { Writable as Writable3 } from "stream";
 import { consola as consola10 } from "consola";
+function spawnDockerComposeTo(opts) {
+  return (args, cwd) => new Promise((resolve, reject) => {
+    const child = spawn6("docker", ["compose", ...args], {
+      cwd,
+      stdio: ["inherit", "pipe", "pipe"]
+    });
+    const route = (src, screen) => {
+      if (!src) return;
+      src.pipe(createSecretMaskStream()).on("data", (chunk) => {
+        opts.logSink?.write(chunk);
+        if (!opts.silent) screen.write(chunk);
+      });
+    };
+    route(child.stdout, process.stdout);
+    route(child.stderr, process.stderr);
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+}
 async function findContainerIds(filters, exec = spawnDocker) {
   const ids = /* @__PURE__ */ new Set();
   for (const filter of filters) {
@@ -6813,6 +6911,32 @@ async function runComposeAction(buildSubArgs, opts) {
   const subArgs = buildSubArgs(opts.service);
   return spawnFn(["-f", composeFile, "-p", projectName, ...subArgs], opts.root);
 }
+async function startDeferredServices(opts) {
+  if (opts.services.length === 0) return 0;
+  const { composeFile, projectName } = resolveCompose(opts.root);
+  const spawnFn = opts.spawn ?? spawnDockerComposeTo({
+    ...opts.logSink ? { logSink: opts.logSink } : {},
+    ...opts.silent ? { silent: true } : {}
+  });
+  opts.logger?.info(
+    `Starting deferred service(s): ${opts.services.join(", ")}\u2026`
+  );
+  return spawnFn(
+    [
+      "-f",
+      composeFile,
+      "-p",
+      projectName,
+      "--profile",
+      DEFERRED_SERVICE_PROFILE,
+      "up",
+      "-d",
+      "--quiet-pull",
+      ...opts.services
+    ],
+    opts.root
+  );
+}
 async function runStart(opts) {
   assertDevcontainer(opts.root);
   const logger = opts.logger ?? { info: (msg) => consola10.info(msg) };
@@ -7040,6 +7164,7 @@ var init_compose = __esm({
     "use strict";
     init_proxy();
     init_mask_secrets();
+    init_catalog();
     init_cli();
     init_proxy();
     spawnDockerCompose = (args, cwd) => {
@@ -7116,7 +7241,7 @@ var init_images = __esm({
 });
 
 // src/config/machine-state.ts
-import { promises as fsp4 } from "fs";
+import { promises as fsp4, readFileSync as readFileSync6 } from "fs";
 import path18 from "path";
 function machineStatePath(home = monocerosHome()) {
   return path18.join(home, ".machine-state.json");
@@ -7132,6 +7257,18 @@ async function readMachineState(home = monocerosHome()) {
   }
   return {};
 }
+function readMachineStateSync(home = monocerosHome()) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync6(machineStatePath(home), "utf8")
+    );
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed;
+    }
+  } catch {
+  }
+  return {};
+}
 async function writeMachineState(state, home = monocerosHome()) {
   await fsp4.writeFile(
     machineStatePath(home),
@@ -7147,6 +7284,12 @@ async function recordBuiltImage(record, home = monocerosHome()) {
   state.builtImages = [...rest, record];
   await writeMachineState(state, home);
 }
+async function recordVersionCheck(opts, home = monocerosHome()) {
+  const state = await readMachineState(home);
+  state.lastVersionCheckAt = opts.nowIso;
+  if (opts.latestVersion) state.latestVersion = opts.latestVersion;
+  await writeMachineState(state, home);
+}
 async function markUpgraded(nowIso, home = monocerosHome()) {
   const state = await readMachineState(home);
   state.lastUpgradeAt = nowIso;
@@ -7686,6 +7829,30 @@ Fix the value in the env file (or the yml).`
       ...progress ? { progressSink: progress.streamSink, silent: true } : {},
       logger: internalLogger
     });
+    if (exitCode === 0) {
+      const deferred = createOpts.services.filter((s) => serviceDefersStart(s.name)).map((s) => s.name);
+      if (deferred.length > 0) {
+        if (progress) progress.setPhase("starting services\u2026");
+        try {
+          const deferExit = await startDeferredServices({
+            root: targetDir,
+            services: deferred,
+            logSink: applyLog.sink,
+            silent: progress !== null,
+            logger: internalLogger
+          });
+          if (deferExit !== 0) {
+            containerLogger.warn?.(
+              `Deferred service(s) ${deferred.join(", ")} did not start cleanly (exit ${deferExit}). The workspace is up; bring them up with \`monoceros start ${opts.name}\`.`
+            );
+          }
+        } catch (err) {
+          containerLogger.warn?.(
+            `Could not start deferred service(s) ${deferred.join(", ")}: ${err instanceof Error ? err.message : String(err)}. The workspace is up.`
+          );
+        }
+      }
+    }
     if (progress) {
       if (exitCode === 0) {
         progress.succeed();
@@ -7880,7 +8047,7 @@ var init_apply = __esm({
 
 // src/devcontainer/browser-bridge.ts
 import { spawn as spawn9 } from "child_process";
-import { existsSync as existsSync11, promises as fsp5, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync11, promises as fsp5, readFileSync as readFileSync7 } from "fs";
 import http from "http";
 import path20 from "path";
 function parseCallbackTarget(authUrl) {
@@ -7983,7 +8150,7 @@ exit 0
     if (!existsSync11(urlFile)) return;
     let content = "";
     try {
-      content = readFileSync6(urlFile, "utf8");
+      content = readFileSync7(urlFile, "utf8");
     } catch {
       return;
     }
@@ -8180,7 +8347,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.30.0" : "dev";
+    CLI_VERSION = true ? "1.31.1" : "dev";
   }
 });
 
@@ -8538,6 +8705,50 @@ async function listContainerNames(ctx) {
   const entries = await fs14.readdir(dir);
   return entries.filter((e) => e.endsWith(".yml")).map((e) => e.slice(0, -".yml".length)).sort();
 }
+function containerNameFromCtx(ctx) {
+  for (let i = 2; i < ctx.prev.length; i++) {
+    const t = ctx.prev[i];
+    if (t === "--") break;
+    if (t.startsWith("-")) continue;
+    return t;
+  }
+  return void 0;
+}
+async function collectDirs(dir, maxDepth) {
+  const out = [];
+  async function walk(at, rel, depth) {
+    let entries;
+    try {
+      entries = await fs14.readdir(at, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith(".")) continue;
+      if (WORKSPACE_DIR_SKIP.has(e.name)) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      out.push(childRel);
+      if (depth + 1 < maxDepth) {
+        await walk(path23.join(at, e.name), childRel, depth + 1);
+      }
+    }
+  }
+  await walk(dir, "", 0);
+  return out;
+}
+async function listContainerWorkspaceDirs(home, name) {
+  const root = path23.join(home, "container", name);
+  const top = await collectDirs(root, 1);
+  const projects = (await collectDirs(path23.join(root, "projects"), PROJECTS_DIR_MAX_DEPTH)).map((p) => `projects/${p}`);
+  return [.../* @__PURE__ */ new Set([...top, ...projects])].sort();
+}
+async function listRunInDirs(ctx) {
+  const name = containerNameFromCtx(ctx);
+  if (!name) return [];
+  const home = ctx.opts.monocerosHome ?? monocerosHome();
+  return listContainerWorkspaceDirs(home, name);
+}
 async function listFeatureComponents() {
   const catalog = await loadComponentCatalog();
   return [...catalog.values()].filter((c) => c.file.category === "feature").map((c) => c.name).sort();
@@ -8600,7 +8811,7 @@ async function resolveFeatureRefForCompletion(token) {
   const f = c.file.contributes.features?.[0];
   return f?.ref;
 }
-var ALL_COMMANDS, containerName, COMMAND_SPECS, COMPLETION_COMMAND_SPEC_KEYS;
+var WORKSPACE_DIR_SKIP, PROJECTS_DIR_MAX_DEPTH, ALL_COMMANDS, containerName, COMMAND_SPECS, COMPLETION_COMMAND_SPEC_KEYS;
 var init_resolve = __esm({
   "src/completion/resolve.ts"() {
     "use strict";
@@ -8610,6 +8821,8 @@ var init_resolve = __esm({
     init_catalog();
     init_schema();
     init_open();
+    WORKSPACE_DIR_SKIP = /* @__PURE__ */ new Set(["node_modules"]);
+    PROJECTS_DIR_MAX_DEPTH = 4;
     ALL_COMMANDS = [
       "init",
       "list-components",
@@ -8686,7 +8899,7 @@ var init_resolve = __esm({
       open: { positionals: [containerName, () => [...OPEN_TOOLS]] },
       run: {
         positionals: [containerName],
-        flags: { "--in": { type: "value" } }
+        flags: { "--in": { type: "value", values: (ctx) => listRunInDirs(ctx) } }
       },
       logs: { positionals: [containerName] },
       start: {
@@ -8825,6 +9038,140 @@ var init_complete = __esm({
   }
 });
 
+// src/update/notifier.ts
+import { spawn as spawn11 } from "child_process";
+function isNewerVersion(latest, current) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+function formatUpdateNotice(latest, current) {
+  return `
+\u2B06 Monoceros ${latest} is available (you have ${current}).
+  Update:  ${INSTALL_COMMAND}
+`;
+}
+function decideUpdateAction(state, currentVersion, now, intervalMs = CHECK_INTERVAL_MS) {
+  const notice = state.latestVersion && isNewerVersion(state.latestVersion, currentVersion) ? formatUpdateNotice(state.latestVersion, currentVersion) : null;
+  const last = state.lastVersionCheckAt ? new Date(state.lastVersionCheckAt).getTime() : NaN;
+  const refresh = !Number.isFinite(last) || now.getTime() - last > intervalMs;
+  return { notice, refresh };
+}
+function scheduleUpdateNotice(opts) {
+  try {
+    if (process.env[OPT_OUT_ENV]) return;
+    if (opts.currentVersion === "dev") return;
+    if (!process.stdout.isTTY) return;
+    if (opts.commandName === void 0) return;
+    if (SKIP_COMMANDS.has(opts.commandName)) return;
+    const argv = opts.argv ?? process.argv.slice(2);
+    if (argv.some((a) => ["-h", "--help", "-v", "--version"].includes(a))) {
+      return;
+    }
+    const state = readMachineStateSync();
+    const { notice, refresh } = decideUpdateAction(
+      state,
+      opts.currentVersion,
+      opts.now ?? /* @__PURE__ */ new Date()
+    );
+    if (notice) {
+      process.on("exit", () => {
+        try {
+          process.stderr.write(notice);
+        } catch {
+        }
+      });
+    }
+    if (refresh) spawnBackgroundCheck();
+  } catch {
+  }
+}
+function spawnBackgroundCheck() {
+  const self = process.argv[1];
+  if (!self) return;
+  try {
+    const child = spawn11(process.execPath, [self, "__update-check"], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+  } catch {
+  }
+}
+async function runUpdateCheck(now = /* @__PURE__ */ new Date(), home) {
+  let latestVersion;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+      if (res.ok) {
+        const json = await res.json();
+        if (typeof json.version === "string") latestVersion = json.version;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+  }
+  try {
+    await recordVersionCheck(
+      {
+        ...latestVersion ? { latestVersion } : {},
+        nowIso: now.toISOString()
+      },
+      home
+    );
+  } catch {
+  }
+}
+var PACKAGE, REGISTRY_URL, INSTALL_COMMAND, CHECK_INTERVAL_MS, OPT_OUT_ENV, FETCH_TIMEOUT_MS, SKIP_COMMANDS;
+var init_notifier = __esm({
+  "src/update/notifier.ts"() {
+    "use strict";
+    init_machine_state();
+    PACKAGE = "@getmonoceros/workbench";
+    REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
+    INSTALL_COMMAND = "curl -fsSL https://raw.githubusercontent.com/getmonoceros/workbench/main/install.sh | bash";
+    CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+    OPT_OUT_ENV = "MONOCEROS_NO_UPDATE_NOTIFIER";
+    FETCH_TIMEOUT_MS = 5e3;
+    SKIP_COMMANDS = /* @__PURE__ */ new Set(["__complete", "__update-check", "completion"]);
+  }
+});
+
+// src/commands/__update-check.ts
+import { defineCommand as defineCommand11 } from "citty";
+var __updateCheckCommand;
+var init_update_check = __esm({
+  "src/commands/__update-check.ts"() {
+    "use strict";
+    init_notifier();
+    __updateCheckCommand = defineCommand11({
+      meta: {
+        name: "__update-check",
+        group: "internal",
+        hidden: true,
+        description: "Internal: refresh the cached latest-version (background)."
+      },
+      async run() {
+        try {
+          await runUpdateCheck();
+        } catch {
+        }
+      }
+    });
+  }
+});
+
 // src/init/generator.ts
 function generateComposedYml(name, composed, lookupManifest, repoUrls = [], ports = []) {
   const lines = [];
@@ -8990,6 +9337,12 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
         const body = renderServiceObjectBody(expandCuratedService(svc));
         lines.push(`#   - ${body[0]}`);
         for (const line of body.slice(1)) lines.push(`#     ${line}`);
+        const exComment = exampleVolumesComment(
+          curatedServiceExampleVolumes(svc)
+        );
+        if (exComment) {
+          for (const cl of exComment.split("\n")) lines.push(`#    ${cl}`);
+        }
       }
     }
     lines.push("");
@@ -9109,6 +9462,12 @@ function pushServiceEntry(out, svc) {
   const body = renderServiceObjectBody(expandCuratedService(svc.name));
   out.push(`  - ${body[0]}`);
   for (const line of body.slice(1)) out.push(`    ${line}`);
+  const exComment = exampleVolumesComment(
+    curatedServiceExampleVolumes(svc.name)
+  );
+  if (exComment) {
+    for (const cl of exComment.split("\n")) out.push(`    #${cl}`);
+  }
 }
 function pushGitIdentityBlock(lines) {
   pushSectionHeader(
@@ -9398,19 +9757,19 @@ function resolveInitAptPackages(entries) {
 }
 function resolveInitServices(entries) {
   const out = [];
-  const byName = /* @__PURE__ */ new Map();
+  const byName2 = /* @__PURE__ */ new Map();
   for (const raw of entries) {
     const e = raw.trim();
     if (!e) continue;
     const svc = isCuratedService(e) ? { kind: "curated", name: e } : { kind: "custom", name: deriveServiceName(e), image: e };
-    const existing = byName.get(svc.name);
+    const existing = byName2.get(svc.name);
     if (existing) {
       if (existing.kind === svc.kind && existing.image === svc.image) continue;
       throw new Error(
         `Two --with-services entries resolve to the service name '${svc.name}'. Add one after init with \`monoceros add-service ${"<name>"} <image> --as=<other>\`.`
       );
     }
-    byName.set(svc.name, svc);
+    byName2.set(svc.name, svc);
     out.push(svc);
   }
   return out;
@@ -9466,7 +9825,7 @@ var init_init = __esm({
 });
 
 // src/commands/init.ts
-import { defineCommand as defineCommand11 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
 import { consola as consola17 } from "consola";
 function collectListFlag(flag, rawArgs) {
   const eq = `${flag}=`;
@@ -9532,7 +9891,7 @@ var init_init2 = __esm({
   "src/commands/init.ts"() {
     "use strict";
     init_init();
-    initCommand = defineCommand11({
+    initCommand = defineCommand12({
       meta: {
         name: "init",
         group: "lifecycle",
@@ -9640,8 +9999,76 @@ var init_expand = __esm({
   }
 });
 
+// src/catalog/catalog-json.ts
+function projectOption(key, spec) {
+  if (spec.surface === "silent") return null;
+  const out = {
+    key,
+    type: spec.type,
+    surface: spec.surface
+  };
+  if (spec.default !== void 0) out.default = spec.default;
+  if (spec.description !== void 0) out.description = spec.description;
+  if (spec.proposals !== void 0) out.proposals = spec.proposals;
+  return out;
+}
+function projectOptions(options) {
+  return Object.entries(options).map(([key, spec]) => projectOption(key, spec)).filter((o) => o !== null).sort((a, b) => a.key.localeCompare(b.key));
+}
+function byName(a, b) {
+  return a.name.localeCompare(b.name);
+}
+function buildCatalogJson(catalog, cliVersion) {
+  const languages = [];
+  const services = [];
+  const features = [];
+  for (const { descriptor: d } of catalog.values()) {
+    const base = {
+      name: d.name ?? d.id,
+      displayName: d.displayName,
+      description: d.description,
+      options: projectOptions(d.options)
+    };
+    if (d.documentationURL !== void 0) {
+      base.documentationURL = d.documentationURL;
+    }
+    if (d.category === "language" && d.language) {
+      const lang = { ...base };
+      if (d.language.defaultVersion !== void 0) {
+        lang.defaultVersion = d.language.defaultVersion;
+      }
+      if (d.language.versions !== void 0) {
+        lang.versions = d.language.versions;
+      }
+      languages.push(lang);
+    } else if (d.category === "service" && d.service) {
+      const svc = { ...base };
+      if (d.service.defaultPort !== void 0) {
+        svc.defaultPort = d.service.defaultPort;
+      }
+      services.push(svc);
+    } else if (d.category === "feature") {
+      features.push({ ...base, presets: Object.keys(d.presets ?? {}).sort() });
+    }
+  }
+  return {
+    schemaVersion: CATALOG_JSON_SCHEMA_VERSION,
+    cliVersion,
+    languages: languages.sort(byName),
+    services: services.sort(byName),
+    features: features.sort(byName)
+  };
+}
+var CATALOG_JSON_SCHEMA_VERSION;
+var init_catalog_json = __esm({
+  "src/catalog/catalog-json.ts"() {
+    "use strict";
+    CATALOG_JSON_SCHEMA_VERSION = 1;
+  }
+});
+
 // src/commands/list-components.ts
-import { defineCommand as defineCommand12 } from "citty";
+import { defineCommand as defineCommand13 } from "citty";
 import { consola as consola18 } from "consola";
 var CATEGORY_LABELS, CATEGORY_ORDER, listComponentsCommand;
 var init_list_components = __esm({
@@ -9649,6 +10076,8 @@ var init_list_components = __esm({
     "use strict";
     init_load();
     init_expand();
+    init_catalog_json();
+    init_version();
     init_format();
     CATEGORY_LABELS = {
       language: "Languages",
@@ -9660,16 +10089,28 @@ var init_list_components = __esm({
       "service",
       "feature"
     ];
-    listComponentsCommand = defineCommand12({
+    listComponentsCommand = defineCommand13({
       meta: {
         name: "list-components",
         group: "discovery",
-        description: "Print the components catalog used by `monoceros init --with-languages=\u2026 / --with-services=\u2026 / --with-features=\u2026`, grouped by category (Languages, Services, Features). Component names render in cyan, descriptions in default colour; when piped, the formatting drops out and lines become `name<TAB>description` for grep/awk-friendly consumption."
+        description: "Print the components catalog used by `monoceros init --with-languages=\u2026 / --with-services=\u2026 / --with-features=\u2026`, grouped by category (Languages, Services, Features). Component names render in cyan, descriptions in default colour; when piped, the formatting drops out and lines become `name<TAB>description` for grep/awk-friendly consumption. `--json` emits the full catalog (options, versions, presets) as a machine-readable document \u2014 the same shape published at getmonoceros.build/catalog.json."
       },
-      args: {},
-      async run() {
+      args: {
+        json: {
+          type: "boolean",
+          description: "Emit the catalog as a JSON document (name, options, versions, presets per component) instead of the human-readable listing."
+        }
+      },
+      async run({ args }) {
         try {
-          const catalog = expandSelectable(await loadDescriptorCatalog());
+          const descriptors = await loadDescriptorCatalog();
+          if (args.json) {
+            const doc = buildCatalogJson(descriptors, CLI_VERSION);
+            process.stdout.write(`${JSON.stringify(doc, null, 2)}
+`);
+            process.exit(0);
+          }
+          const catalog = expandSelectable(descriptors);
           if (catalog.size === 0) {
             consola18.warn(
               "No components found. The workbench checkout looks incomplete."
@@ -9731,14 +10172,14 @@ var init_list_components = __esm({
 });
 
 // src/commands/logs.ts
-import { spawn as spawn11 } from "child_process";
+import { spawn as spawn12 } from "child_process";
 import { existsSync as existsSync16 } from "fs";
 import path25 from "path";
-import { defineCommand as defineCommand13 } from "citty";
+import { defineCommand as defineCommand14 } from "citty";
 function tailLogFile(file, follow) {
   const [cmd, args] = follow ? ["tail", ["-F", file]] : ["cat", [file]];
   return new Promise((resolve, reject) => {
-    const child = spawn11(cmd, args, { stdio: "inherit" });
+    const child = spawn12(cmd, args, { stdio: "inherit" });
     child.on("error", reject);
     child.on("exit", (code) => resolve(code ?? 0));
   });
@@ -9750,7 +10191,7 @@ var init_logs = __esm({
     init_paths();
     init_compose();
     init_dispatch();
-    logsCommand = defineCommand13({
+    logsCommand = defineCommand14({
       meta: {
         name: "logs",
         group: "run",
@@ -9794,14 +10235,14 @@ var init_logs = __esm({
 });
 
 // src/commands/open.ts
-import { defineCommand as defineCommand14 } from "citty";
+import { defineCommand as defineCommand15 } from "citty";
 var openCommand;
 var init_open2 = __esm({
   "src/commands/open.ts"() {
     "use strict";
     init_open();
     init_dispatch();
-    openCommand = defineCommand14({
+    openCommand = defineCommand15({
       meta: {
         name: "open",
         group: "run",
@@ -9827,7 +10268,7 @@ var init_open2 = __esm({
 });
 
 // src/commands/port.ts
-import { defineCommand as defineCommand15 } from "citty";
+import { defineCommand as defineCommand16 } from "citty";
 import { consola as consola19 } from "consola";
 async function runPortListing(opts) {
   const out = opts.out ?? process.stdout;
@@ -9889,7 +10330,7 @@ var init_port = __esm({
     init_schema();
     init_dynamic();
     init_format();
-    portCommand = defineCommand15({
+    portCommand = defineCommand16({
       meta: {
         name: "port",
         group: "discovery",
@@ -9916,7 +10357,7 @@ var init_port = __esm({
 });
 
 // src/commands/remove-apt-packages.ts
-import { defineCommand as defineCommand16 } from "citty";
+import { defineCommand as defineCommand17 } from "citty";
 import { consola as consola20 } from "consola";
 var removeAptPackagesCommand;
 var init_remove_apt_packages = __esm({
@@ -9924,7 +10365,7 @@ var init_remove_apt_packages = __esm({
     "use strict";
     init_inner_args();
     init_modify();
-    removeAptPackagesCommand = defineCommand16({
+    removeAptPackagesCommand = defineCommand17({
       meta: {
         name: "remove-apt-packages",
         group: "edit",
@@ -9968,14 +10409,14 @@ var init_remove_apt_packages = __esm({
 });
 
 // src/commands/remove-feature.ts
-import { defineCommand as defineCommand17 } from "citty";
+import { defineCommand as defineCommand18 } from "citty";
 import { consola as consola21 } from "consola";
 var removeFeatureCommand;
 var init_remove_feature = __esm({
   "src/commands/remove-feature.ts"() {
     "use strict";
     init_modify();
-    removeFeatureCommand = defineCommand17({
+    removeFeatureCommand = defineCommand18({
       meta: {
         name: "remove-feature",
         group: "edit",
@@ -10171,7 +10612,7 @@ var init_remove = __esm({
 });
 
 // src/commands/remove.ts
-import { defineCommand as defineCommand18 } from "citty";
+import { defineCommand as defineCommand19 } from "citty";
 import { consola as consola23 } from "consola";
 import { createInterface } from "readline/promises";
 var removeCommand;
@@ -10179,7 +10620,7 @@ var init_remove2 = __esm({
   "src/commands/remove.ts"() {
     "use strict";
     init_remove();
-    removeCommand = defineCommand18({
+    removeCommand = defineCommand19({
       meta: {
         name: "remove",
         group: "lifecycle",
@@ -10315,14 +10756,14 @@ var init_restore = __esm({
 });
 
 // src/commands/restore.ts
-import { defineCommand as defineCommand19 } from "citty";
+import { defineCommand as defineCommand20 } from "citty";
 import { consola as consola25 } from "consola";
 var restoreCommand;
 var init_restore2 = __esm({
   "src/commands/restore.ts"() {
     "use strict";
     init_restore();
-    restoreCommand = defineCommand19({
+    restoreCommand = defineCommand20({
       meta: {
         name: "restore",
         group: "lifecycle",
@@ -10348,14 +10789,14 @@ var init_restore2 = __esm({
 });
 
 // src/commands/remove-from-url.ts
-import { defineCommand as defineCommand20 } from "citty";
+import { defineCommand as defineCommand21 } from "citty";
 import { consola as consola26 } from "consola";
 var removeFromUrlCommand;
 var init_remove_from_url = __esm({
   "src/commands/remove-from-url.ts"() {
     "use strict";
     init_modify();
-    removeFromUrlCommand = defineCommand20({
+    removeFromUrlCommand = defineCommand21({
       meta: {
         name: "remove-from-url",
         group: "edit",
@@ -10397,14 +10838,14 @@ var init_remove_from_url = __esm({
 });
 
 // src/commands/remove-language.ts
-import { defineCommand as defineCommand21 } from "citty";
+import { defineCommand as defineCommand22 } from "citty";
 import { consola as consola27 } from "consola";
 var removeLanguageCommand;
 var init_remove_language = __esm({
   "src/commands/remove-language.ts"() {
     "use strict";
     init_modify();
-    removeLanguageCommand = defineCommand21({
+    removeLanguageCommand = defineCommand22({
       meta: {
         name: "remove-language",
         group: "edit",
@@ -10446,7 +10887,7 @@ var init_remove_language = __esm({
 });
 
 // src/commands/remove-port.ts
-import { defineCommand as defineCommand22 } from "citty";
+import { defineCommand as defineCommand23 } from "citty";
 import { consola as consola28 } from "consola";
 function coerceToken2(raw) {
   const n = Number(raw);
@@ -10458,7 +10899,7 @@ var init_remove_port = __esm({
     "use strict";
     init_inner_args();
     init_modify();
-    removePortCommand = defineCommand22({
+    removePortCommand = defineCommand23({
       meta: {
         name: "remove-port",
         group: "edit",
@@ -10502,14 +10943,14 @@ var init_remove_port = __esm({
 });
 
 // src/commands/remove-repo.ts
-import { defineCommand as defineCommand23 } from "citty";
+import { defineCommand as defineCommand24 } from "citty";
 import { consola as consola29 } from "consola";
 var removeRepoCommand;
 var init_remove_repo = __esm({
   "src/commands/remove-repo.ts"() {
     "use strict";
     init_modify();
-    removeRepoCommand = defineCommand23({
+    removeRepoCommand = defineCommand24({
       meta: {
         name: "remove-repo",
         group: "edit",
@@ -10551,14 +10992,14 @@ var init_remove_repo = __esm({
 });
 
 // src/commands/remove-service.ts
-import { defineCommand as defineCommand24 } from "citty";
+import { defineCommand as defineCommand25 } from "citty";
 import { consola as consola30 } from "consola";
 var removeServiceCommand;
 var init_remove_service = __esm({
   "src/commands/remove-service.ts"() {
     "use strict";
     init_modify();
-    removeServiceCommand = defineCommand24({
+    removeServiceCommand = defineCommand25({
       meta: {
         name: "remove-service",
         group: "edit",
@@ -10700,7 +11141,7 @@ var init_run = __esm({
 });
 
 // src/commands/run.ts
-import { defineCommand as defineCommand25 } from "citty";
+import { defineCommand as defineCommand26 } from "citty";
 import { consola as consola31 } from "consola";
 var runCommand;
 var init_run2 = __esm({
@@ -10709,7 +11150,7 @@ var init_run2 = __esm({
     init_paths();
     init_run();
     init_inner_args();
-    runCommand = defineCommand25({
+    runCommand = defineCommand26({
       meta: {
         name: "run",
         group: "run",
@@ -10752,7 +11193,7 @@ var init_run2 = __esm({
 });
 
 // src/commands/shell.ts
-import { defineCommand as defineCommand26 } from "citty";
+import { defineCommand as defineCommand27 } from "citty";
 import { consola as consola32 } from "consola";
 var shellCommand;
 var init_shell2 = __esm({
@@ -10760,7 +11201,7 @@ var init_shell2 = __esm({
     "use strict";
     init_paths();
     init_shell();
-    shellCommand = defineCommand26({
+    shellCommand = defineCommand27({
       meta: {
         name: "shell",
         group: "run",
@@ -10790,7 +11231,7 @@ var init_shell2 = __esm({
 });
 
 // src/commands/start.ts
-import { defineCommand as defineCommand27 } from "citty";
+import { defineCommand as defineCommand28 } from "citty";
 import { consola as consola33 } from "consola";
 var startCommand;
 var init_start = __esm({
@@ -10800,11 +11241,12 @@ var init_start = __esm({
     init_io();
     init_paths();
     init_compose();
+    init_catalog();
     init_open();
     init_proxy();
     init_port_check();
     init_dispatch();
-    startCommand = defineCommand27({
+    startCommand = defineCommand28({
       meta: {
         name: "start",
         group: "run",
@@ -10825,6 +11267,7 @@ var init_start = __esm({
         return dispatch(async () => {
           let needsProxy = false;
           let hostPort = 80;
+          let deferred = [];
           try {
             const parsed = await readConfig(containerConfigPath(args.name));
             if ((parsed.config.routing?.ports ?? []).length > 0) {
@@ -10832,6 +11275,7 @@ var init_start = __esm({
               const global = await readMonocerosConfig();
               hostPort = proxyHostPort(global);
             }
+            deferred = (parsed.config.services ?? []).filter((s) => serviceDefersStart(s.name)).map((s) => s.name);
           } catch (err) {
             consola33.warn(
               `Could not read container yml ahead of start: ${err instanceof Error ? err.message : String(err)}. Skipping Traefik pre-flight.`
@@ -10842,6 +11286,24 @@ var init_start = __esm({
             await ensureProxy({ hostPort });
           }
           const exitCode = await runStart({ root: containerDir(args.name) });
+          if (exitCode === 0 && deferred.length > 0) {
+            try {
+              const deferExit = await startDeferredServices({
+                root: containerDir(args.name),
+                services: deferred,
+                logger: consola33
+              });
+              if (deferExit !== 0) {
+                consola33.warn(
+                  `Deferred service(s) ${deferred.join(", ")} did not start cleanly (exit ${deferExit}).`
+                );
+              }
+            } catch (err) {
+              consola33.warn(
+                `Could not start deferred service(s) ${deferred.join(", ")}: ${err instanceof Error ? err.message : String(err)}`
+              );
+            }
+          }
           if (args.open && exitCode === 0) {
             try {
               await runOpen({ name: args.name, tool: args.open });
@@ -10857,7 +11319,7 @@ var init_start = __esm({
 });
 
 // src/commands/status.ts
-import { defineCommand as defineCommand28 } from "citty";
+import { defineCommand as defineCommand29 } from "citty";
 var statusCommand;
 var init_status = __esm({
   "src/commands/status.ts"() {
@@ -10865,7 +11327,7 @@ var init_status = __esm({
     init_paths();
     init_compose();
     init_dispatch();
-    statusCommand = defineCommand28({
+    statusCommand = defineCommand29({
       meta: {
         name: "status",
         group: "run",
@@ -10895,7 +11357,7 @@ var init_status = __esm({
 });
 
 // src/commands/stop.ts
-import { defineCommand as defineCommand29 } from "citty";
+import { defineCommand as defineCommand30 } from "citty";
 import { consola as consola34 } from "consola";
 var stopCommand;
 var init_stop = __esm({
@@ -10905,7 +11367,7 @@ var init_stop = __esm({
     init_compose();
     init_proxy();
     init_dispatch();
-    stopCommand = defineCommand29({
+    stopCommand = defineCommand30({
       meta: {
         name: "stop",
         group: "run",
@@ -11198,7 +11660,7 @@ var init_port_check2 = __esm({
 });
 
 // src/tunnel/run.ts
-import { spawn as spawn12 } from "child_process";
+import { spawn as spawn13 } from "child_process";
 import { consola as consola35 } from "consola";
 function signalNumber(signal) {
   switch (signal) {
@@ -11288,7 +11750,7 @@ var init_run3 = __esm({
     init_port_check2();
     SOCAT_IMAGE = "alpine/socat:1.8.0.3";
     defaultDockerSpawn = (args) => {
-      const child = spawn12("docker", args, {
+      const child = spawn13("docker", args, {
         stdio: "inherit"
       });
       const exited = new Promise((resolve, reject) => {
@@ -11319,7 +11781,7 @@ var init_run3 = __esm({
 });
 
 // src/commands/tunnel.ts
-import { defineCommand as defineCommand30 } from "citty";
+import { defineCommand as defineCommand31 } from "citty";
 import { consola as consola36 } from "consola";
 function parseLocalPort(raw) {
   if (raw === void 0) return void 0;
@@ -11336,7 +11798,7 @@ var init_tunnel = __esm({
   "src/commands/tunnel.ts"() {
     "use strict";
     init_run3();
-    tunnelCommand = defineCommand30({
+    tunnelCommand = defineCommand31({
       meta: {
         name: "tunnel",
         group: "discovery",
@@ -11628,7 +12090,7 @@ var init_upgrade = __esm({
 });
 
 // src/commands/upgrade.ts
-import { defineCommand as defineCommand31 } from "citty";
+import { defineCommand as defineCommand32 } from "citty";
 var upgradeCommand;
 var init_upgrade2 = __esm({
   "src/commands/upgrade.ts"() {
@@ -11636,7 +12098,7 @@ var init_upgrade2 = __esm({
     init_upgrade();
     init_version();
     init_dispatch();
-    upgradeCommand = defineCommand31({
+    upgradeCommand = defineCommand32({
       meta: {
         name: "upgrade",
         group: "lifecycle",
@@ -11678,7 +12140,7 @@ var main_exports = {};
 __export(main_exports, {
   main: () => main
 });
-import { defineCommand as defineCommand32 } from "citty";
+import { defineCommand as defineCommand33 } from "citty";
 var main;
 var init_main = __esm({
   "src/main.ts"() {
@@ -11693,6 +12155,7 @@ var init_main = __esm({
     init_apply2();
     init_completion();
     init_complete();
+    init_update_check();
     init_init2();
     init_list_components();
     init_logs();
@@ -11715,7 +12178,7 @@ var init_main = __esm({
     init_tunnel();
     init_upgrade2();
     init_version();
-    main = defineCommand32({
+    main = defineCommand33({
       meta: {
         name: "monoceros",
         version: CLI_VERSION,
@@ -11752,7 +12215,8 @@ var init_main = __esm({
         port: portCommand,
         tunnel: tunnelCommand,
         completion: completionCommand,
-        __complete: __completeCommand
+        __complete: __completeCommand,
+        "__update-check": __updateCheckCommand
       }
     });
   }
@@ -12042,9 +12506,15 @@ async function maybeRenderHelp(argv, main2) {
 // src/bin.ts
 init_inner_args();
 init_main();
+init_notifier();
+init_version();
 bootstrapDockerGroup();
 consumeInnerArgsFromProcessArgv();
 async function entry() {
+  scheduleUpdateNotice({
+    currentVersion: CLI_VERSION,
+    commandName: process.argv.slice(2).find((a) => !a.startsWith("-"))
+  });
   if (await maybeRenderHelp(process.argv.slice(2), main)) {
     return;
   }