@getmonoceros/workbench 1.29.2 → 1.31.0

package/dist/bin.js

@@ -665,7 +665,16 @@ var init_feature_doc = __esm({
 
 // src/catalog/descriptor.ts
 import { z as z2 } from "zod";
-var DESCRIPTOR_ID_RE, CategorySchema, OptionTypeSchema, SurfaceSchema, OptionValueSchema, OptionSpecSchema, BriefingLineSchema, HealthcheckSchema, LanguageBlockSchema, ServiceBlockSchema, PersistentHomeFileSchema, FeatureBlockSchema, DescriptorSchema;
+function workspaceEnvTokens(vars) {
+  const tokens = [];
+  for (const template of Object.values(vars)) {
+    for (const m of template.matchAll(/\$\{([A-Za-z0-9_]+)\}/g)) {
+      tokens.push(m[1]);
+    }
+  }
+  return tokens;
+}
+var DESCRIPTOR_ID_RE, CategorySchema, OptionTypeSchema, SurfaceSchema, OptionValueSchema, OptionSpecSchema, BriefingLineSchema, HealthcheckSchema, LanguageBlockSchema, ServiceBlockSchema, PersistentHomeFileSchema, WorkspaceEnvBlockSchema, FeatureBlockSchema, DescriptorSchema;
 var init_descriptor = __esm({
   "src/catalog/descriptor.ts"() {
     "use strict";
@@ -718,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
@@ -760,18 +786,55 @@ 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),
       initialContent: z2.string().optional()
     });
+    WorkspaceEnvBlockSchema = z2.object({
+      whenOption: z2.string().optional(),
+      vars: z2.record(z2.string(), z2.string())
+    });
     FeatureBlockSchema = z2.object({
       /** Publishable feature version (devcontainer-feature.json `version`). */
       version: z2.string().min(1),
       persistentHomePaths: z2.array(z2.string().min(1)).optional(),
       persistentHomeFiles: z2.array(PersistentHomeFileSchema).optional(),
-      vscodeExtensions: z2.array(z2.string()).optional()
+      vscodeExtensions: z2.array(z2.string()).optional(),
+      /**
+       * Named runtime env injected into the workspace container (compose
+       * `environment:` / image-mode `containerEnv`). Catalog/CLI-side only — not
+       * emitted into the published devcontainer-feature.json (like `presets`),
+       * because it drives how the workbench wires the container, not the feature
+       * install. See `featureWorkspaceEnv` in create/scaffold.ts.
+       */
+      workspaceEnv: z2.array(WorkspaceEnvBlockSchema).optional()
     });
     DescriptorSchema = z2.object({
       id: z2.string().regex(DESCRIPTOR_ID_RE, "id must be lowercase letters/digits/hyphens"),
@@ -833,6 +896,24 @@ var init_descriptor = __esm({
           });
         }
       });
+      data.feature?.workspaceEnv?.forEach((block, i) => {
+        if (block.whenOption !== void 0 && !optionKeys.has(block.whenOption)) {
+          ctx.addIssue({
+            code: z2.ZodIssueCode.custom,
+            path: ["feature", "workspaceEnv", i, "whenOption"],
+            message: `whenOption '${block.whenOption}' is not a declared option`
+          });
+        }
+        for (const token of workspaceEnvTokens(block.vars)) {
+          if (!optionKeys.has(token)) {
+            ctx.addIssue({
+              code: z2.ZodIssueCode.custom,
+              path: ["feature", "workspaceEnv", i, "vars"],
+              message: `workspaceEnv template references '\${${token}}', which is not a declared option`
+            });
+          }
+        }
+      });
       if (data.presets) {
         if (data.category !== "feature") {
           ctx.addIssue({
@@ -2180,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,
@@ -2215,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,
@@ -2269,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";
@@ -2299,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];
       })
@@ -2325,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";
   }
 });
 
@@ -2389,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.`;
 }
@@ -2845,7 +2945,8 @@ function resolveFeatures(opts) {
       devcontainerKey: entry2.feature,
       options,
       persistentHomePaths: [],
-      persistentHomeFiles: []
+      persistentHomeFiles: [],
+      workspaceEnv: []
     });
   }
   const aptPackages = [
@@ -2859,7 +2960,8 @@ function resolveFeatures(opts) {
       devcontainerKey: "ghcr.io/devcontainers-contrib/features/apt-packages:1",
       options: { packages: aptPackages.join(",") },
       persistentHomePaths: [],
-      persistentHomeFiles: []
+      persistentHomeFiles: [],
+      workspaceEnv: []
     });
   }
   if (opts.features) {
@@ -2869,6 +2971,7 @@ function resolveFeatures(opts) {
         const name = match.name;
         const descriptor = featureDescriptor(name);
         const { paths, files } = descriptorPersistentHome(descriptor);
+        const workspaceEnv = descriptor?.feature?.workspaceEnv ?? [];
         const sourceRoot = featuresSourceRoot();
         const localSourceDir = sourceRoot ? path10.join(sourceRoot, name) : null;
         if (descriptor && localSourceDir && existsSync7(localSourceDir)) {
@@ -2879,7 +2982,8 @@ function resolveFeatures(opts) {
             localName: name,
             generatedManifest: descriptorToFeatureManifest(descriptor),
             persistentHomePaths: paths,
-            persistentHomeFiles: files
+            persistentHomeFiles: files,
+            workspaceEnv
           });
           continue;
         }
@@ -2887,7 +2991,8 @@ function resolveFeatures(opts) {
           devcontainerKey: rawRef,
           options,
           persistentHomePaths: paths,
-          persistentHomeFiles: files
+          persistentHomeFiles: files,
+          workspaceEnv
         });
         continue;
       }
@@ -2895,7 +3000,8 @@ function resolveFeatures(opts) {
         devcontainerKey: rawRef,
         options,
         persistentHomePaths: [],
-        persistentHomeFiles: []
+        persistentHomeFiles: [],
+        workspaceEnv: []
       });
     }
   }
@@ -2915,6 +3021,33 @@ function descriptorPersistentHome(descriptor) {
     files: filterFileEntries(descriptor?.feature?.persistentHomeFiles)
   };
 }
+function isOptionEnabled(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value !== "" && value !== "false";
+  return false;
+}
+function featureWorkspaceEnv(features) {
+  const env = {};
+  for (const f of features) {
+    for (const block of f.workspaceEnv) {
+      if (block.whenOption !== void 0 && !isOptionEnabled(f.options[block.whenOption])) {
+        continue;
+      }
+      for (const [name, template] of Object.entries(block.vars)) {
+        const value = template.replace(
+          /\$\{([A-Za-z0-9_]+)\}/g,
+          (_, token) => {
+            const v = f.options[token];
+            return v === void 0 || v === null ? "" : String(v);
+          }
+        );
+        if (value !== "") env[name] = value;
+      }
+    }
+  }
+  return env;
+}
 function filterSubpaths(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.filter(
@@ -3034,12 +3167,15 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
     }
   } : void 0;
   const sshPostStart = runtimeSupportsSshAttach(opts.runtimeVersion) ? { postStartCommand: "sudo /usr/local/bin/monoceros-sshd-up.sh" } : {};
+  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,
@@ -3074,6 +3210,7 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
     forwardPorts: ports,
     postCreateCommand: ".devcontainer/post-create.sh",
     ...sshPostStart,
+    ...containerEnvField ?? {},
     ...featuresField ?? {},
     ...customizationsField ?? {}
   };
@@ -3123,7 +3260,10 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
   for (const v of ideVolumes) {
     lines.push(`      - ${v.volume}:${v.target}`);
   }
-  const wsEnv = serviceConnectionEnv(opts.services);
+  const wsEnv = {
+    ...serviceConnectionEnv(opts.services),
+    ...featureWorkspaceEnv(resolvedFeatures)
+  };
   const wsEnvKeys = Object.keys(wsEnv);
   if (wsEnvKeys.length > 0) {
     lines.push("    environment:");
@@ -3134,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)}`);
     }
@@ -3195,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);
     }
   }
@@ -3812,26 +3969,39 @@ function addInstallUrlToDoc(doc, url) {
   seq.add(url);
   return true;
 }
-function addFeatureToDoc(doc, ref, options = {}, displayName) {
+function addFeatureToDoc(doc, ref, options = {}, opts = {}) {
   const seq = ensureSeq(doc, "features");
-  const label = displayName ?? ref;
+  const label = opts.displayName ?? ref;
   const summary = loadFeatureManifestSummary(ref);
-  const hints = featureOptionHints(summary, ref, Object.keys(options));
-  const mergedOptions = { ...options };
-  for (const h of hints) mergedOptions[h.key] = h.placeholder;
+  const withHints = (o) => {
+    const out = { ...o };
+    for (const h of featureOptionHints(summary, ref, Object.keys(out))) {
+      out[h.key] = h.placeholder;
+    }
+    return out;
+  };
   for (const item of seq.items) {
     if (!isMap2(item)) continue;
     const itemRef = item.get("ref");
     if (itemRef !== ref) continue;
     const itemJs = item.toJS(doc);
     const existingJs = itemJs.options ?? {};
-    if (JSON.stringify(existingJs) === JSON.stringify(mergedOptions)) {
+    if (opts.isPreset) {
+      const merged = withHints(mergeFeatureOptions(existingJs, options));
+      if (JSON.stringify(existingJs) === JSON.stringify(merged)) {
+        return false;
+      }
+      item.set("options", merged);
+      return true;
+    }
+    if (JSON.stringify(existingJs) === JSON.stringify(withHints(options))) {
       return false;
     }
     throw new Error(
       `Feature ${label} is already configured with different options. Remove it first (\`monoceros remove-feature ${label}\`) before re-adding.`
     );
   }
+  const mergedOptions = withHints(options);
   const entry2 = new YAMLMap2();
   entry2.set("ref", ref);
   if (Object.keys(mergedOptions).length > 0) {
@@ -3993,6 +4163,7 @@ var init_yml = __esm({
     "use strict";
     init_scaffold();
     init_manifest();
+    init_components();
     init_feature_doc();
     init_env_file();
     GIT_USER_HEADER_COMMENT = [
@@ -4038,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,
@@ -4340,7 +4511,10 @@ async function runAddFeature(input) {
   };
   const result = await mutate(
     input,
-    (doc) => addFeatureToDoc(doc, resolved.ref, merged, raw)
+    (doc) => addFeatureToDoc(doc, resolved.ref, merged, {
+      isPreset: resolved.isPreset,
+      displayName: raw
+    })
   );
   if (result.status === "updated") {
     const summary = loadFeatureManifestSummary(resolved.ref);
@@ -4368,7 +4542,7 @@ async function runAddFeature(input) {
 }
 async function resolveFeatureRefOrShortname(input) {
   if (REGEX.featureRef.test(input)) {
-    return { ref: input, defaultOptions: {} };
+    return { ref: input, defaultOptions: {}, isPreset: false };
   }
   const catalog = await loadComponentCatalog();
   const component = catalog.get(input);
@@ -4400,7 +4574,8 @@ async function resolveFeatureRefOrShortname(input) {
   const [first] = features;
   return {
     ref: first.ref,
-    defaultOptions: { ...first.options ?? {} }
+    defaultOptions: { ...first.options ?? {} },
+    isPreset: input.includes("/")
   };
 }
 function runRemoveLanguage(input) {
@@ -4683,7 +4858,7 @@ var init_add_feature = __esm({
       meta: {
         name: "add-feature",
         group: "edit",
-        description: "Add a devcontainer feature by ref to the container config. Options follow `--` as `key=value` pairs. Idempotent (same ref + same options is a no-op). Adding the same ref with different options is an error."
+        description: "Add a devcontainer feature by ref to the container config. Options follow `--` as `key=value` pairs. Adding a sub-tool selector (e.g. `atlassian/forge`) to an already-present feature merges it in additively, keeping the other sub-tools on. A plain feature already present with different options is an error (remove + re-add to change it)."
       },
       args: {
         name: {
@@ -4846,7 +5021,7 @@ var init_add_repo = __esm({
         },
         provider: {
           type: "string",
-          description: "Git provider for credential-helper guidance: github | gitlab | bitbucket. Required when the URL host is not github.com, gitlab.com, or bitbucket.org \u2014 Monoceros uses this to suggest the right CLI (gh / glab / Atlassian token) on missing credentials."
+          description: "Git provider for credential-helper guidance: github | gitlab | bitbucket | gitea. Required when the URL host is not github.com, gitlab.com, or bitbucket.org \u2014 Monoceros uses this to suggest the right auth (gh / glab / a provider token) on missing credentials."
         },
         yes: {
           type: "boolean",
@@ -6642,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) {
@@ -6717,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) };
@@ -6944,6 +7164,7 @@ var init_compose = __esm({
     "use strict";
     init_proxy();
     init_mask_secrets();
+    init_catalog();
     init_cli();
     init_proxy();
     spawnDockerCompose = (args, cwd) => {
@@ -7020,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");
@@ -7036,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),
@@ -7051,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;
@@ -7590,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();
@@ -7784,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) {
@@ -7887,7 +8150,7 @@ exit 0
     if (!existsSync11(urlFile)) return;
     let content = "";
     try {
-      content = readFileSync6(urlFile, "utf8");
+      content = readFileSync7(urlFile, "utf8");
     } catch {
       return;
     }
@@ -8084,7 +8347,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.29.2" : "dev";
+    CLI_VERSION = true ? "1.31.0" : "dev";
   }
 });
 
@@ -8729,6 +8992,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 = [];
@@ -8894,6 +9291,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("");
@@ -9013,6 +9416,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(
@@ -9302,19 +9711,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;
@@ -9370,7 +9779,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}=`;
@@ -9436,7 +9845,7 @@ var init_init2 = __esm({
   "src/commands/init.ts"() {
     "use strict";
     init_init();
-    initCommand = defineCommand11({
+    initCommand = defineCommand12({
       meta: {
         name: "init",
         group: "lifecycle",
@@ -9544,8 +9953,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({
@@ -9553,6 +10030,8 @@ var init_list_components = __esm({
     "use strict";
     init_load();
     init_expand();
+    init_catalog_json();
+    init_version();
     init_format();
     CATEGORY_LABELS = {
       language: "Languages",
@@ -9564,16 +10043,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."
@@ -9635,14 +10126,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));
   });
@@ -9654,7 +10145,7 @@ var init_logs = __esm({
     init_paths();
     init_compose();
     init_dispatch();
-    logsCommand = defineCommand13({
+    logsCommand = defineCommand14({
       meta: {
         name: "logs",
         group: "run",
@@ -9698,14 +10189,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",
@@ -9731,7 +10222,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;
@@ -9793,7 +10284,7 @@ var init_port = __esm({
     init_schema();
     init_dynamic();
     init_format();
-    portCommand = defineCommand15({
+    portCommand = defineCommand16({
       meta: {
         name: "port",
         group: "discovery",
@@ -9820,7 +10311,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({
@@ -9828,7 +10319,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",
@@ -9872,14 +10363,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",
@@ -10075,7 +10566,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;
@@ -10083,7 +10574,7 @@ var init_remove2 = __esm({
   "src/commands/remove.ts"() {
     "use strict";
     init_remove();
-    removeCommand = defineCommand18({
+    removeCommand = defineCommand19({
       meta: {
         name: "remove",
         group: "lifecycle",
@@ -10219,14 +10710,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",
@@ -10252,14 +10743,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",
@@ -10301,14 +10792,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",
@@ -10350,7 +10841,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);
@@ -10362,7 +10853,7 @@ var init_remove_port = __esm({
     "use strict";
     init_inner_args();
     init_modify();
-    removePortCommand = defineCommand22({
+    removePortCommand = defineCommand23({
       meta: {
         name: "remove-port",
         group: "edit",
@@ -10406,14 +10897,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",
@@ -10455,14 +10946,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",
@@ -10604,7 +11095,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({
@@ -10613,7 +11104,7 @@ var init_run2 = __esm({
     init_paths();
     init_run();
     init_inner_args();
-    runCommand = defineCommand25({
+    runCommand = defineCommand26({
       meta: {
         name: "run",
         group: "run",
@@ -10656,7 +11147,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({
@@ -10664,7 +11155,7 @@ var init_shell2 = __esm({
     "use strict";
     init_paths();
     init_shell();
-    shellCommand = defineCommand26({
+    shellCommand = defineCommand27({
       meta: {
         name: "shell",
         group: "run",
@@ -10694,7 +11185,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({
@@ -10704,11 +11195,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",
@@ -10729,6 +11221,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) {
@@ -10736,6 +11229,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.`
@@ -10746,6 +11240,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 });
@@ -10761,7 +11273,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"() {
@@ -10769,7 +11281,7 @@ var init_status = __esm({
     init_paths();
     init_compose();
     init_dispatch();
-    statusCommand = defineCommand28({
+    statusCommand = defineCommand29({
       meta: {
         name: "status",
         group: "run",
@@ -10799,7 +11311,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({
@@ -10809,7 +11321,7 @@ var init_stop = __esm({
     init_compose();
     init_proxy();
     init_dispatch();
-    stopCommand = defineCommand29({
+    stopCommand = defineCommand30({
       meta: {
         name: "stop",
         group: "run",
@@ -11102,7 +11614,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) {
@@ -11192,7 +11704,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) => {
@@ -11223,7 +11735,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;
@@ -11240,7 +11752,7 @@ var init_tunnel = __esm({
   "src/commands/tunnel.ts"() {
     "use strict";
     init_run3();
-    tunnelCommand = defineCommand30({
+    tunnelCommand = defineCommand31({
       meta: {
         name: "tunnel",
         group: "discovery",
@@ -11532,7 +12044,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"() {
@@ -11540,7 +12052,7 @@ var init_upgrade2 = __esm({
     init_upgrade();
     init_version();
     init_dispatch();
-    upgradeCommand = defineCommand31({
+    upgradeCommand = defineCommand32({
       meta: {
         name: "upgrade",
         group: "lifecycle",
@@ -11582,7 +12094,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"() {
@@ -11597,6 +12109,7 @@ var init_main = __esm({
     init_apply2();
     init_completion();
     init_complete();
+    init_update_check();
     init_init2();
     init_list_components();
     init_logs();
@@ -11619,7 +12132,7 @@ var init_main = __esm({
     init_tunnel();
     init_upgrade2();
     init_version();
-    main = defineCommand32({
+    main = defineCommand33({
       meta: {
         name: "monoceros",
         version: CLI_VERSION,
@@ -11656,7 +12169,8 @@ var init_main = __esm({
         port: portCommand,
         tunnel: tunnelCommand,
         completion: completionCommand,
-        __complete: __completeCommand
+        __complete: __completeCommand,
+        "__update-check": __updateCheckCommand
       }
     });
   }
@@ -11946,9 +12460,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;
   }