@getmonoceros/workbench 1.21.2 → 1.22.0

package/dist/bin.js

@@ -74,7 +74,7 @@ ${issues}`);
   }
   return result.data;
 }
-var SOLUTION_NAME_RE, APT_PACKAGE_NAME_RE, RUNTIME_VERSION_RE, FEATURE_REF_RE, INSTALL_URL_RE, REPO_URL_RE, REPO_PATH_RE, POSTGRES_URL_RE, REGEX, PROVIDER_VALUES, KNOWN_PROVIDER_HOSTS, CONFIG_SCHEMA_VERSION, FeatureOptionValueSchema, FeatureEntrySchema, EMAIL_RE, GitUserSchema, RepoEntrySchema, PortEntrySchema, RoutingSchema, SERVICE_NAME_RE, ServiceEnvValueSchema, ServiceHealthcheckSchema, SERVICE_RESTART_VALUES, ServiceObjectSchema, ExternalServicesSchema, SolutionConfigSchema;
+var SOLUTION_NAME_RE, APT_PACKAGE_NAME_RE, RUNTIME_VERSION_RE, FEATURE_REF_RE, INSTALL_URL_RE, REPO_URL_RE, REPO_PATH_RE, POSTGRES_URL_RE, REGEX, PROVIDER_VALUES, KNOWN_PROVIDER_HOSTS, CONFIG_SCHEMA_VERSION, FeatureOptionValueSchema, FeatureEntrySchema, EMAIL_RE, GitUserSchema, RepoEntrySchema, PortEntrySchema, RoutingSchema, SERVICE_NAME_RE, ServiceEnvValueSchema, ServiceHealthcheckSchema, SERVICE_RESTART_VALUES, ServiceObjectSchema, ExternalServicesSchema, LanguageOptionValueSchema, LanguageEntrySchema, SolutionConfigSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
@@ -211,6 +211,20 @@ var init_schema = __esm({
         "Postgres URL must start with 'postgres://' or 'postgresql://'"
       ).optional()
     });
+    LanguageOptionValueSchema = z.union([
+      z.string(),
+      z.number(),
+      z.boolean()
+    ]);
+    LanguageEntrySchema = z.union([
+      z.string().min(1),
+      z.record(
+        z.string().min(1),
+        z.record(z.string().min(1), LanguageOptionValueSchema)
+      ).refine((obj) => Object.keys(obj).length === 1, {
+        message: "a language entry object must have exactly one language name as its key"
+      })
+    ]);
     SolutionConfigSchema = z.object({
       schemaVersion: z.literal(CONFIG_SCHEMA_VERSION),
       name: z.string().regex(
@@ -226,7 +240,7 @@ var init_schema = __esm({
         RUNTIME_VERSION_RE,
         "Invalid runtimeVersion. Expected an exact version like '1.1.0'."
       ).optional(),
-      languages: z.array(z.string().min(1)).default([]),
+      languages: z.array(LanguageEntrySchema).default([]),
       aptPackages: z.array(
         z.string().regex(
           APT_PACKAGE_NAME_RE,
@@ -336,11 +350,13 @@ function workbenchCheckoutRoot() {
     dir = parent;
   }
 }
-function componentsDir(root = workbenchRoot()) {
-  return path.join(root, "templates", "components");
-}
-function bundledFeaturesDir(root = workbenchRoot()) {
-  return path.join(root, "features");
+function componentsRootDir() {
+  const checkout = workbenchCheckoutRoot();
+  if (checkout) {
+    const inCheckout = path.join(checkout, "components");
+    if (existsSync(inCheckout)) return inCheckout;
+  }
+  return path.join(workbenchRoot(), "bundled-components");
 }
 function containerConfigsDir(home = monocerosHome()) {
   return path.join(home, "container-configs");
@@ -378,7 +394,7 @@ var init_paths = __esm({
   "src/config/paths.ts"() {
     "use strict";
     MONOCEROS_HOME_MARKER = "monoceros-config.sample.yml";
-    WORKBENCH_MARKER = path.join("templates", "components", "README.md");
+    WORKBENCH_MARKER = path.join("templates", "monoceros-config.sample.yml");
     CHECKOUT_MARKER = "pnpm-workspace.yaml";
     cachedWorkbenchRoot = null;
     cachedMonocerosHome = null;
@@ -632,6 +648,304 @@ 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;
+var init_descriptor = __esm({
+  "src/catalog/descriptor.ts"() {
+    "use strict";
+    init_schema();
+    DESCRIPTOR_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+    CategorySchema = z2.enum(["language", "service", "feature"]);
+    OptionTypeSchema = z2.enum(["string", "boolean", "number"]);
+    SurfaceSchema = z2.enum(["yml", "silent", "env"]);
+    OptionValueSchema = z2.union([z2.string(), z2.boolean(), z2.number()]);
+    OptionSpecSchema = z2.object({
+      type: OptionTypeSchema,
+      default: OptionValueSchema.optional(),
+      description: z2.string().optional(),
+      surface: SurfaceSchema.default("silent"),
+      /** Suggested values (rendered as devcontainer `proposals`). */
+      proposals: z2.array(z2.string()).optional()
+    });
+    BriefingLineSchema = z2.object({
+      text: z2.string().min(1),
+      /**
+       * Option name; the line is emitted only when that option resolves
+       * truthy (after merging defaults + user options). Must reference an
+       * option declared on the same descriptor.
+       */
+      whenOption: z2.string().optional()
+    });
+    HealthcheckSchema = z2.object({
+      test: z2.array(z2.string()).min(1),
+      interval: z2.string().optional(),
+      timeout: z2.string().optional(),
+      retries: z2.number().int().positive().optional(),
+      startPeriod: z2.string().optional()
+    });
+    LanguageBlockSchema = z2.object({
+      /** Upstream OCI feature ref, e.g. `ghcr.io/devcontainers/features/java:1`. */
+      feature: z2.string().regex(REGEX.featureRef),
+      /** True when the toolchain is already in the base runtime image (node). */
+      builtin: z2.boolean().default(false),
+      /**
+       * Version shown inline in the generated yml (`name:<defaultVersion>`), so
+       * the builder sees where to edit it. Should equal the upstream feature's
+       * real default to stay behavior-neutral. For a `builtin` language it is the
+       * base-image version; pinning that exact version stays builtin (no feature
+       * install), only a different version triggers the upstream feature.
+       * Coerced to string so bare YAML numbers (`defaultVersion: 22`) work.
+       */
+      defaultVersion: z2.coerce.string().optional(),
+      /**
+       * Versions the upstream feature accepts (docs/UX only, not enforced).
+       * Coerced to string so authors can write bare YAML numbers
+       * (`versions: [latest, 21, 17]`) without quoting.
+       */
+      versions: z2.array(z2.coerce.string()).optional()
+    });
+    ServiceBlockSchema = z2.object({
+      image: z2.string().min(1),
+      defaultPort: z2.number().int().positive().optional(),
+      dataMount: z2.string().optional(),
+      healthcheck: HealthcheckSchema.optional(),
+      /**
+       * Connection env vars injected into the WORKSPACE container so the app /
+       * agent can reach this service without hardcoding anything. Keyed by env
+       * var name → a template value. Tokens: `${host}` (the service hostname),
+       * `${port}` (the service's port, falling back to `defaultPort`), and
+       * `${<OPTION>}` (any of the service's own option values, e.g.
+       * `${POSTGRES_USER}`). Example:
+       *   DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
+       */
+      connectionEnv: z2.record(z2.string(), z2.string()).optional(),
+      vscodeExtensions: z2.array(z2.string()).optional()
+    });
+    PersistentHomeFileSchema = z2.object({
+      path: z2.string().min(1),
+      initialContent: z2.string().optional()
+    });
+    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()
+    });
+    DescriptorSchema = z2.object({
+      id: z2.string().regex(DESCRIPTOR_ID_RE, "id must be lowercase letters/digits/hyphens"),
+      /**
+       * CLI/yml selector name (catalog key). Defaults to `id`. Lets a feature
+       * keep a short selector (`claude`) while its published manifest id stays
+       * canonical (`claude-code`).
+       */
+      name: z2.string().regex(DESCRIPTOR_ID_RE, "name must be lowercase letters/digits/hyphens").optional(),
+      category: CategorySchema,
+      displayName: z2.string().min(1),
+      description: z2.string().min(1),
+      documentationURL: z2.string().url().optional(),
+      options: z2.record(z2.string(), OptionSpecSchema).default({}),
+      /** Free-text notes rendered above the component block at `init`. */
+      usageNotes: z2.array(z2.string()).default([]),
+      briefing: z2.array(BriefingLineSchema).default([]),
+      language: LanguageBlockSchema.optional(),
+      service: ServiceBlockSchema.optional(),
+      feature: FeatureBlockSchema.optional(),
+      /**
+       * Named option-override presets. Each becomes a selectable
+       * `<name>/<presetKey>` component (e.g. `atlassian/twg`); the bare
+       * component keeps the descriptor's own option defaults. Feature-only.
+       */
+      presets: z2.record(
+        z2.string().regex(DESCRIPTOR_ID_RE),
+        z2.record(z2.string(), OptionValueSchema)
+      ).optional()
+    }).superRefine((data, ctx) => {
+      const present = [
+        data.language ? "language" : null,
+        data.service ? "service" : null,
+        data.feature ? "feature" : null
+      ].filter(Boolean).sort();
+      if (present.length === 0) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `missing the '${data.category}' block required by category '${data.category}'`
+        });
+      } else if (present.length > 1) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `exactly one of language/service/feature is allowed, got: ${present.join(", ")}`
+        });
+      } else if (present[0] !== data.category) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `category '${data.category}' requires a '${data.category}' block, found '${present[0]}'`
+        });
+      }
+      const optionKeys = new Set(Object.keys(data.options));
+      data.briefing.forEach((line, i) => {
+        if (line.whenOption !== void 0 && !optionKeys.has(line.whenOption)) {
+          ctx.addIssue({
+            code: z2.ZodIssueCode.custom,
+            path: ["briefing", i, "whenOption"],
+            message: `whenOption '${line.whenOption}' is not a declared option`
+          });
+        }
+      });
+      if (data.presets) {
+        if (data.category !== "feature") {
+          ctx.addIssue({
+            code: z2.ZodIssueCode.custom,
+            path: ["presets"],
+            message: `presets are only allowed on features, not '${data.category}'`
+          });
+        }
+        for (const [presetKey, overrides] of Object.entries(data.presets)) {
+          for (const optKey of Object.keys(overrides)) {
+            if (!optionKeys.has(optKey)) {
+              ctx.addIssue({
+                code: z2.ZodIssueCode.custom,
+                path: ["presets", presetKey, optKey],
+                message: `preset '${presetKey}' overrides '${optKey}', which is not a declared option`
+              });
+            }
+          }
+        }
+      }
+    });
+  }
+});
+
+// src/catalog/load.ts
+import { existsSync as existsSync3, promises as fs2 } from "fs";
+import path3 from "path";
+import { parse as parseYaml } from "yaml";
+async function loadDescriptorCatalog(rootDir = componentsRootDir()) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync3(rootDir)) {
+    return out;
+  }
+  for (const [dirName, category] of Object.entries(CATEGORY_DIRS)) {
+    const categoryDir = path3.join(rootDir, dirName);
+    if (!existsSync3(categoryDir)) continue;
+    const entries = await fs2.readdir(categoryDir, { withFileTypes: true });
+    for (const entry2 of entries) {
+      if (!entry2.isDirectory()) continue;
+      const id = entry2.name;
+      const sourcePath = path3.join(categoryDir, id, "component.yml");
+      if (!existsSync3(sourcePath)) continue;
+      const component = await loadOne(sourcePath, id, category);
+      if (out.has(component.id)) {
+        const first = out.get(component.id);
+        throw new Error(
+          `Duplicate component id '${component.id}': ${first.sourcePath} and ${sourcePath}.`
+        );
+      }
+      out.set(component.id, component);
+    }
+  }
+  return out;
+}
+async function loadOne(sourcePath, folderId, expectedCategory) {
+  const text = await fs2.readFile(sourcePath, "utf8");
+  return parseDescriptorFile(text, sourcePath, folderId, expectedCategory);
+}
+function parseDescriptorFile(text, sourcePath, folderId, expectedCategory) {
+  let raw;
+  try {
+    raw = parseYaml(text);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse descriptor (${sourcePath}): ${err.message}`
+    );
+  }
+  const parsed = DescriptorSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => {
+      const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `  - ${where}: ${issue.message}`;
+    }).join("\n");
+    throw new Error(`Invalid descriptor (${sourcePath}):
+${issues}`);
+  }
+  const descriptor = parsed.data;
+  if (descriptor.id !== folderId) {
+    throw new Error(
+      `Descriptor id '${descriptor.id}' must match its folder name '${folderId}' (${sourcePath}).`
+    );
+  }
+  if (descriptor.category !== expectedCategory) {
+    throw new Error(
+      `Descriptor '${descriptor.id}' has category '${descriptor.category}' but sits under '${expectedCategory}s/' (${sourcePath}).`
+    );
+  }
+  return {
+    id: descriptor.id,
+    category: descriptor.category,
+    sourcePath,
+    descriptor
+  };
+}
+var CATEGORY_DIRS;
+var init_load = __esm({
+  "src/catalog/load.ts"() {
+    "use strict";
+    init_paths();
+    init_descriptor();
+    CATEGORY_DIRS = {
+      languages: "language",
+      services: "service",
+      features: "feature"
+    };
+  }
+});
+
+// src/catalog/load-sync.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync } from "fs";
+import path4 from "path";
+function loadDescriptorCatalogSync(rootDir = componentsRootDir()) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync4(rootDir)) return out;
+  for (const [dirName, category] of Object.entries(CATEGORY_DIRS2)) {
+    const categoryDir = path4.join(rootDir, dirName);
+    if (!existsSync4(categoryDir)) continue;
+    for (const entry2 of readdirSync(categoryDir, { withFileTypes: true })) {
+      if (!entry2.isDirectory()) continue;
+      const id = entry2.name;
+      const sourcePath = path4.join(categoryDir, id, "component.yml");
+      if (!existsSync4(sourcePath)) continue;
+      const component = parseDescriptorFile(
+        readFileSync2(sourcePath, "utf8"),
+        sourcePath,
+        id,
+        category
+      );
+      if (out.has(component.id)) {
+        const first = out.get(component.id);
+        throw new Error(
+          `Duplicate component id '${component.id}': ${first.sourcePath} and ${sourcePath}.`
+        );
+      }
+      out.set(component.id, component);
+    }
+  }
+  return out;
+}
+var CATEGORY_DIRS2;
+var init_load_sync = __esm({
+  "src/catalog/load-sync.ts"() {
+    "use strict";
+    init_paths();
+    init_load();
+    CATEGORY_DIRS2 = {
+      languages: "language",
+      services: "service",
+      features: "feature"
+    };
+  }
+});
+
 // src/util/ref.ts
 function matchMonocerosFeature(ref) {
   const match = MONOCEROS_FEATURE_RE.exec(ref);
@@ -661,108 +975,59 @@ var init_ref = __esm({
 });
 
 // src/init/manifest.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
-import path3 from "path";
-function resolveManifestPath(name, checkoutRoot) {
-  if (checkoutRoot) {
-    const checkoutPath = path3.join(
-      checkoutRoot,
-      "images",
-      "features",
-      name,
-      "devcontainer-feature.json"
-    );
-    if (existsSync3(checkoutPath)) return checkoutPath;
-  }
-  const bundlePath = path3.join(
-    bundledFeaturesDir(),
-    name,
-    "devcontainer-feature.json"
-  );
-  if (existsSync3(bundlePath)) return bundlePath;
-  return null;
-}
-function loadFeatureManifestSummary(ref, checkoutRoot = workbenchCheckoutRoot()) {
+function loadFeatureManifestSummary(ref, componentsRoot) {
   const match = matchMonocerosFeature(ref);
   if (!match) return void 0;
-  const manifestPath = resolveManifestPath(match.name, checkoutRoot);
-  if (!manifestPath) return void 0;
+  let descriptor;
   try {
-    const text = readFileSync2(manifestPath, "utf8");
-    const parsed = JSON.parse(text);
-    const rawHints = parsed["x-monoceros"]?.optionHints;
-    const optionHints = Array.isArray(rawHints) ? rawHints.filter(
-      (x) => typeof x === "string" && x.length > 0
-    ) : [];
-    const rawNotes = parsed["x-monoceros"]?.usageNotes;
-    const usageNotes = Array.isArray(rawNotes) ? rawNotes.filter(
-      (x) => typeof x === "string" && x.length > 0
-    ) : [];
-    const optionDescriptions = {};
-    const optionTypes = {};
-    const optionDefaults = {};
-    const optionNames = [];
-    if (parsed.options) {
-      for (const [key, opt] of Object.entries(parsed.options)) {
-        if (!opt || typeof opt !== "object") continue;
-        optionNames.push(key);
-        if (typeof opt.description === "string" && opt.description.length > 0) {
-          optionDescriptions[key] = opt.description;
-        }
-        if (opt.type === "boolean") {
-          optionTypes[key] = "boolean";
-        } else if (opt.type === "string") {
-          optionTypes[key] = "string";
-        }
-        if (typeof opt.default === "string" || typeof opt.default === "boolean") {
-          optionDefaults[key] = opt.default;
-        }
-      }
-    }
-    const briefing = parseBriefing(parsed["x-monoceros"]?.briefing);
-    const name = typeof parsed.name === "string" ? parsed.name : "";
-    const description = typeof parsed.description === "string" ? parsed.description : "";
-    const rawUrl = typeof parsed.documentationURL === "string" ? parsed.documentationURL.trim() : "";
-    const documentationURL = rawUrl.length > 0 && rawUrl.toLowerCase() !== "tbd" ? rawUrl : void 0;
-    return {
-      name,
-      description,
-      documentationURL,
-      optionHints,
-      optionDescriptions,
-      optionNames,
-      optionTypes,
-      optionDefaults,
-      usageNotes,
-      ...briefing ? { briefing } : {}
-    };
+    descriptor = loadDescriptorCatalogSync(componentsRoot).get(
+      match.name
+    )?.descriptor;
   } catch {
     return void 0;
   }
-}
-function parseBriefing(raw) {
-  if (!raw || typeof raw !== "object") return void 0;
-  const rawLines = raw.lines;
-  if (!Array.isArray(rawLines)) return void 0;
-  const lines = [];
-  for (const entry2 of rawLines) {
-    if (!entry2 || typeof entry2 !== "object") continue;
-    const text = entry2.text;
-    if (typeof text !== "string" || text.length === 0) continue;
-    const whenOption = entry2.whenOption;
-    const line = { text };
-    if (typeof whenOption === "string" && whenOption.length > 0) {
-      line.whenOption = whenOption;
-    }
-    lines.push(line);
-  }
-  if (lines.length === 0) return void 0;
-  return { lines };
+  if (!descriptor || descriptor.category !== "feature") return void 0;
+  const optionHints = [];
+  const optionDescriptions = {};
+  const optionTypes = {};
+  const optionDefaults = {};
+  const optionNames = [];
+  for (const [key, spec] of Object.entries(descriptor.options)) {
+    optionNames.push(key);
+    if (spec.surface === "env") optionHints.push(key);
+    if (spec.description !== void 0 && spec.description.length > 0) {
+      optionDescriptions[key] = spec.description;
+    }
+    optionTypes[key] = spec.type === "boolean" ? "boolean" : "string";
+    if (typeof spec.default === "string" || typeof spec.default === "boolean") {
+      optionDefaults[key] = spec.default;
+    }
+  }
+  const rawUrl = descriptor.documentationURL?.trim() ?? "";
+  const documentationURL = rawUrl.length > 0 && rawUrl.toLowerCase() !== "tbd" ? rawUrl : void 0;
+  const briefing = descriptor.briefing.length > 0 ? {
+    lines: descriptor.briefing.map((l) => ({
+      text: l.text,
+      ...l.whenOption !== void 0 ? { whenOption: l.whenOption } : {}
+    }))
+  } : void 0;
+  return {
+    name: descriptor.displayName,
+    description: descriptor.description,
+    documentationURL,
+    optionHints,
+    optionDescriptions,
+    optionNames,
+    optionTypes,
+    optionDefaults,
+    usageNotes: descriptor.usageNotes,
+    ...briefing ? { briefing } : {}
+  };
 }
 var init_manifest = __esm({
   "src/init/manifest.ts"() {
     "use strict";
-    init_paths();
+    init_load_sync();
     init_ref();
   }
 });
@@ -809,8 +1074,8 @@ var init_format = __esm({
 
 // src/devcontainer/credentials.ts
 import { spawn } from "child_process";
-import { promises as fs2 } from "fs";
-import path4 from "path";
+import { promises as fs3 } from "fs";
+import path5 from "path";
 function resolveProvider(host, explicit) {
   const canonical = KNOWN_PROVIDER_HOSTS[host.toLowerCase()];
   if (canonical) return canonical;
@@ -959,8 +1224,8 @@ function formatCredentialLine(host, username, password) {
   return `https://${encUser}:${encPass}@${host}`;
 }
 async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
-  const credsDir = path4.join(devContainerRoot, ".monoceros");
-  const credentialsPath = path4.join(credsDir, "git-credentials");
+  const credsDir = path5.join(devContainerRoot, ".monoceros");
+  const credentialsPath = path5.join(credsDir, "git-credentials");
   const spawnFn = options.spawn ?? realGitCredentialFill;
   const approveFn = options.approve ?? realGitCredentialApprove;
   const logger = options.logger ?? { info: () => {
@@ -1024,8 +1289,8 @@ password=${password}
     } catch {
     }
   }
-  await fs2.mkdir(credsDir, { recursive: true });
-  await fs2.writeFile(
+  await fs3.mkdir(credsDir, { recursive: true });
+  await fs3.writeFile(
     credentialsPath,
     lines.join("\n") + (lines.length > 0 ? "\n" : ""),
     {
@@ -1180,15 +1445,15 @@ var init_locate_running = __esm({
 });
 
 // src/config/global.ts
-import { promises as fs3 } from "fs";
-import { z as z2 } from "zod";
+import { promises as fs4 } from "fs";
+import { z as z3 } from "zod";
 import { isMap, Pair, parseDocument as parseDocument2, Scalar, YAMLMap } from "yaml";
 async function readMonocerosConfig(opts = {}) {
   const home = opts.monocerosHome ?? monocerosHome();
   const filePath = monocerosConfigPath(home);
   let text;
   try {
-    text = await fs3.readFile(filePath, "utf8");
+    text = await fs4.readFile(filePath, "utf8");
   } catch {
     return void 0;
   }
@@ -1224,7 +1489,7 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
   const filePath = monocerosConfigPath(home);
   let text;
   try {
-    text = await fs3.readFile(filePath, "utf8");
+    text = await fs4.readFile(filePath, "utf8");
   } catch {
     text = void 0;
   }
@@ -1241,8 +1506,8 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
       `      email: ${user.email}`,
       ""
     ].join("\n");
-    await fs3.mkdir(home, { recursive: true });
-    await fs3.writeFile(filePath, fresh, "utf8");
+    await fs4.mkdir(home, { recursive: true });
+    await fs4.writeFile(filePath, fresh, "utf8");
     return { filePath, created: true, alreadySet: false };
   }
   const doc = parseDocument2(text, { prettyErrors: true });
@@ -1263,7 +1528,7 @@ async function writeGlobalDefaultGitUser(user, opts = {}) {
   userMap.set("name", user.name);
   userMap.set("email", user.email);
   const newText = String(doc);
-  await fs3.writeFile(filePath, newText, "utf8");
+  await fs4.writeFile(filePath, newText, "utf8");
   return { filePath, created: false, alreadySet: false };
 }
 function ensureMap(doc, key) {
@@ -1375,19 +1640,19 @@ var init_global = __esm({
     init_schema();
     init_paths();
     SCHEMA_VERSION = 1;
-    MonocerosConfigSchema = z2.object({
-      schemaVersion: z2.literal(SCHEMA_VERSION),
+    MonocerosConfigSchema = z3.object({
+      schemaVersion: z3.literal(SCHEMA_VERSION),
       // .nullish() (= .optional().nullable()) on defaults so the shipped
       // sample yml — where `defaults:` is uncommented but every sub-block
       // is commented out — parses cleanly. YAML produces `defaults: null`
       // in that case; without .nullish() the schema would reject it and
       // we'd be back to forcing builders to comment-juggle three lines.
-      defaults: z2.object({
+      defaults: z3.object({
         // .nullish() (not just .optional()) so the sample yml can leave
         // `git:` uncommented as a category marker — YAML produces
         // `git: null` for an empty mapping, which zod's plain
         // `.optional()` would reject.
-        git: z2.object({
+        git: z3.object({
           // Strict email here: monoceros-config defaults are not tied to
           // any container `<name>.env`, so `${VAR}` placeholders make no
           // sense and the format can (and should) be validated at load
@@ -1400,25 +1665,25 @@ var init_global = __esm({
         }).nullish(),
         // .nullish() for the same reason as `git` — the sample keeps
         // `features:` uncommented as a category marker.
-        features: z2.record(
-          z2.string().regex(
+        features: z3.record(
+          z3.string().regex(
             REGEX.featureRef,
             "Invalid feature ref. Expected an OCI-image-style ref like 'ghcr.io/getmonoceros/monoceros-features/<name>:<tag>'."
           ),
-          z2.record(z2.string(), FeatureOptionValueSchema)
+          z3.record(z3.string(), FeatureOptionValueSchema)
         ).nullish()
       }).nullish(),
       // Machine-global routing settings — one Traefik per builder, so
       // host-port and similar live here rather than in any container yml.
       // See ADR 0007.
-      routing: z2.object({
-        hostPort: z2.number().int().min(1).max(65535).optional().describe(
+      routing: z3.object({
+        hostPort: z3.number().int().min(1).max(65535).optional().describe(
           "Host port the Traefik singleton binds. Default 80. Set this when 80 is held by another service on your machine \u2014 URLs then become http://<name>.localhost:<port>/."
         )
       }).nullish(),
       // Tool-freshness settings (ADR 0018). One machine-global knob.
-      upgrade: z2.object({
-        staleDays: z2.number().int().min(1).optional().describe(
+      upgrade: z3.object({
+        staleDays: z3.number().int().min(1).optional().describe(
           "Days after the last `monoceros upgrade` before `apply` nudges you to refresh tooling. Default 30."
         )
       }).nullish()
@@ -1428,49 +1693,81 @@ var init_global = __esm({
 });
 
 // src/init/components.ts
-import { existsSync as existsSync4, promises as fs4 } from "fs";
-import path5 from "path";
-import { z as z3 } from "zod";
-import { parse as parseYaml } from "yaml";
-async function loadComponentCatalog(rootDir = componentsDir()) {
-  if (!existsSync4(rootDir)) {
-    return /* @__PURE__ */ new Map();
+function featureRef(d) {
+  const major = (d.feature?.version ?? "1").split(".")[0];
+  return `ghcr.io/getmonoceros/monoceros-features/${d.id}:${major}`;
+}
+function surfaceYmlDefaults(d) {
+  const out = {};
+  for (const [key, spec] of Object.entries(d.options)) {
+    if (spec.surface === "yml" && spec.default !== void 0) {
+      out[key] = spec.default;
+    }
   }
-  const out = /* @__PURE__ */ new Map();
-  await walk(rootDir, rootDir, out);
   return out;
 }
-async function walk(baseDir, currentDir, out) {
-  const entries = await fs4.readdir(currentDir, { withFileTypes: true });
-  for (const entry2 of entries) {
-    const full = path5.join(currentDir, entry2.name);
-    if (entry2.isDirectory()) {
-      await walk(baseDir, full, out);
-      continue;
+function baseComponentFile(d) {
+  const selector = d.name ?? d.id;
+  if (d.category === "language") {
+    return {
+      displayName: d.displayName,
+      description: d.description,
+      category: "language",
+      contributes: { languages: [selector] }
+    };
+  }
+  if (d.category === "service") {
+    return {
+      displayName: d.displayName,
+      description: d.description,
+      category: "service",
+      contributes: { services: [selector] }
+    };
+  }
+  return {
+    displayName: d.displayName,
+    description: d.description,
+    category: "feature",
+    contributes: {
+      features: [{ ref: featureRef(d), options: surfaceYmlDefaults(d) }]
     }
-    if (!entry2.isFile() || !entry2.name.endsWith(".yml")) continue;
-    const relative = path5.relative(baseDir, full);
-    const name = relative.replace(/\.yml$/, "").split(path5.sep).join("/");
-    const text = await fs4.readFile(full, "utf8");
-    let raw;
-    try {
-      raw = parseYaml(text);
-    } catch (err) {
-      throw new Error(
-        `Failed to parse component ${name} (${full}): ${err.message}`
-      );
+  };
+}
+async function loadComponentCatalog(rootDir) {
+  return buildComponentCatalog(await loadDescriptorCatalog(rootDir));
+}
+function buildComponentCatalog(descriptors) {
+  const out = /* @__PURE__ */ new Map();
+  const add = (name, file, sourcePath) => {
+    if (out.has(name)) {
+      throw new Error(`Duplicate component name '${name}' (${sourcePath}).`);
     }
-    const parsed = ComponentFileSchema.safeParse(raw);
-    if (!parsed.success) {
-      const issues = parsed.error.issues.map((issue) => {
-        const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-        return `  - ${where}: ${issue.message}`;
-      }).join("\n");
-      throw new Error(`Invalid component ${name} (${full}):
-${issues}`);
+    out.set(name, { name, sourcePath, file });
+  };
+  for (const { descriptor: d, sourcePath } of descriptors.values()) {
+    const selector = d.name ?? d.id;
+    add(selector, baseComponentFile(d), sourcePath);
+    for (const [presetKey, overrides] of Object.entries(d.presets ?? {})) {
+      add(
+        `${selector}/${presetKey}`,
+        {
+          displayName: `${d.displayName} (${presetKey})`,
+          description: d.description,
+          category: "feature",
+          contributes: {
+            features: [
+              {
+                ref: featureRef(d),
+                options: { ...surfaceYmlDefaults(d), ...overrides }
+              }
+            ]
+          }
+        },
+        sourcePath
+      );
     }
-    out.set(name, { name, sourcePath: full, file: parsed.data });
   }
+  return out;
 }
 function mergeFeatureOptions(a, b) {
   const result = { ...a };
@@ -1484,55 +1781,10 @@ function mergeFeatureOptions(a, b) {
   }
   return result;
 }
-var CategorySchema, FeatureContributionSchema, ComponentFileSchema;
 var init_components = __esm({
   "src/init/components.ts"() {
     "use strict";
-    init_paths();
-    init_schema();
-    CategorySchema = z3.enum(["language", "service", "feature"]);
-    FeatureContributionSchema = z3.object({
-      ref: z3.string().regex(REGEX.featureRef),
-      options: z3.record(z3.string(), FeatureOptionValueSchema).optional()
-    });
-    ComponentFileSchema = z3.object({
-      displayName: z3.string().min(1),
-      description: z3.string().min(1),
-      category: CategorySchema,
-      contributes: z3.object({
-        languages: z3.array(z3.string().min(1)).optional(),
-        services: z3.array(z3.string().min(1)).optional(),
-        features: z3.array(FeatureContributionSchema).optional()
-      })
-    }).superRefine((data, ctx) => {
-      const c = data.contributes;
-      const filled = [
-        c.languages && c.languages.length > 0 ? "languages" : null,
-        c.services && c.services.length > 0 ? "services" : null,
-        c.features && c.features.length > 0 ? "features" : null
-      ].filter((x) => x !== null);
-      if (filled.length === 0) {
-        ctx.addIssue({
-          code: z3.ZodIssueCode.custom,
-          message: "contributes must set at least one of languages/services/features"
-        });
-        return;
-      }
-      if (filled.length > 1) {
-        ctx.addIssue({
-          code: z3.ZodIssueCode.custom,
-          message: `contributes must set exactly one of languages/services/features, got: ${filled.join(", ")}`
-        });
-        return;
-      }
-      const expected = data.category === "language" ? "languages" : data.category === "service" ? "services" : "features";
-      if (filled[0] !== expected) {
-        ctx.addIssue({
-          code: z3.ZodIssueCode.custom,
-          message: `category '${data.category}' requires contributes.${expected}, got contributes.${filled[0]}`
-        });
-      }
-    });
+    init_load();
   }
 });
 
@@ -1858,6 +2110,25 @@ function runtimeSupportsIdeVolumes(version) {
   if (!version) return false;
   return compareRuntimeVersions(version, MIN_RUNTIME_FOR_IDE_VOLUMES) >= 0;
 }
+function descriptorOptionDefaults(options) {
+  const out = {};
+  for (const [key, spec] of Object.entries(options)) {
+    if (spec.default !== void 0) out[key] = spec.default;
+  }
+  return out;
+}
+function descriptorYmlOptionDefaults(options) {
+  const out = {};
+  for (const [key, spec] of Object.entries(options)) {
+    if (spec.surface === "yml" && spec.default !== void 0) {
+      out[key] = spec.default;
+    }
+  }
+  return out;
+}
+function descriptorSelector(c) {
+  return c.descriptor.name ?? c.descriptor.id;
+}
 function parseLanguageSpec(spec) {
   const m = LANGUAGE_SPEC_RE.exec(spec);
   if (!m) return null;
@@ -1912,34 +2183,17 @@ function curatedServiceEnvDefaults(name) {
 function serviceConnectionEnv(services) {
   const env = {};
   for (const svc of services) {
-    if (!isCuratedService(svc.name)) continue;
+    const def = SERVICE_CATALOG[svc.name];
+    if (!def?.connectionEnv) continue;
     const host = svc.name;
-    if (svc.name === "postgres") {
-      const user = svc.env.POSTGRES_USER ?? "postgres";
-      const pass = svc.env.POSTGRES_PASSWORD ?? "";
-      const db = svc.env.POSTGRES_DB ?? user;
-      const port = svc.port ?? 5432;
-      env.PGHOST = host;
-      env.PGPORT = String(port);
-      env.PGUSER = user;
-      env.PGPASSWORD = pass;
-      env.PGDATABASE = db;
-      env.DATABASE_URL = `postgresql://${user}:${pass}@${host}:${port}/${db}`;
-    } else if (svc.name === "mysql") {
-      const pass = svc.env.MYSQL_ROOT_PASSWORD ?? "";
-      const db = svc.env.MYSQL_DATABASE ?? "";
-      const port = svc.port ?? 3306;
-      env.MYSQL_HOST = host;
-      env.MYSQL_PORT = String(port);
-      env.MYSQL_USER = "root";
-      env.MYSQL_PASSWORD = pass;
-      env.MYSQL_DATABASE = db;
-      if (env.DATABASE_URL === void 0) {
-        env.DATABASE_URL = `mysql://root:${pass}@${host}:${port}/${db}`;
-      }
-    } else if (svc.name === "redis") {
-      const port = svc.port ?? 6379;
-      env.REDIS_URL = `redis://${host}:${port}`;
+    const port = String(svc.port ?? def.defaultPort);
+    const fill = (template) => template.replace(/\$\{([A-Za-z0-9_]+)\}/g, (_, token) => {
+      if (token === "host") return host;
+      if (token === "port") return port;
+      return svc.env[token] ?? "";
+    });
+    for (const [key, template] of Object.entries(def.connectionEnv)) {
+      env[key] = fill(template);
     }
   }
   return env;
@@ -1949,10 +2203,11 @@ 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_IDE_VOLUMES, 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_IDE_VOLUMES, DESCRIPTORS, BUILTIN_LANGUAGES, LANGUAGE_CATALOG, LANGUAGE_SPEC_RE, SERVICE_CATALOG;
 var init_catalog = __esm({
   "src/create/catalog.ts"() {
     "use strict";
+    init_load_sync();
     DEFAULT_BASE_IMAGE = "ghcr.io/getmonoceros/monoceros-runtime:1";
     override = process.env.MONOCEROS_BASE_IMAGE_OVERRIDE?.trim();
     BASE_IMAGE = override && override.length > 0 ? override : DEFAULT_BASE_IMAGE;
@@ -1964,86 +2219,49 @@ var init_catalog = __esm({
       "utf8"
     ).trim();
     MIN_RUNTIME_FOR_IDE_VOLUMES = "1.1.0";
-    BUILTIN_LANGUAGES = /* @__PURE__ */ new Set(["node"]);
-    LANGUAGE_CATALOG = {
-      node: { id: "node", feature: "ghcr.io/devcontainers/features/node:1" },
-      python: { id: "python", feature: "ghcr.io/devcontainers/features/python:1" },
-      java: { id: "java", feature: "ghcr.io/devcontainers/features/java:1" },
-      go: { id: "go", feature: "ghcr.io/devcontainers/features/go:1" },
-      rust: { id: "rust", feature: "ghcr.io/devcontainers/features/rust:1" },
-      dotnet: { id: "dotnet", feature: "ghcr.io/devcontainers/features/dotnet:2" }
-    };
+    DESCRIPTORS = loadDescriptorCatalogSync();
+    BUILTIN_LANGUAGES = new Set(
+      [...DESCRIPTORS.values()].filter((c) => c.category === "language" && c.descriptor.language?.builtin).map(descriptorSelector)
+    );
+    LANGUAGE_CATALOG = Object.fromEntries(
+      [...DESCRIPTORS.values()].filter((c) => c.category === "language").map((c) => {
+        const key = descriptorSelector(c);
+        const defaults = descriptorOptionDefaults(c.descriptor.options);
+        const ymlOptions = descriptorYmlOptionDefaults(c.descriptor.options);
+        const entry2 = {
+          id: key,
+          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 } : {}
+        };
+        return [key, entry2];
+      })
+    );
     LANGUAGE_SPEC_RE = /^([a-z][a-z0-9-]*)(?::([A-Za-z0-9._-]+))?$/;
-    SERVICE_CATALOG = {
-      postgres: {
-        id: "postgres",
-        image: "postgres:18",
-        env: {
-          POSTGRES_USER: "monoceros",
-          POSTGRES_PASSWORD: "monoceros",
-          POSTGRES_DB: "monoceros"
-        },
-        healthcheck: {
-          test: [
-            "CMD",
-            "pg_isready",
-            "-U",
-            "${POSTGRES_USER}",
-            "-d",
-            "${POSTGRES_DB}"
-          ],
-          interval: "10s",
-          timeout: "5s",
-          retries: 5
-        },
-        // Postgres 18+ stores data under /var/lib/postgresql/<major>/, so
-        // the recommended mount is the parent directory; pre-18 used
-        // /var/lib/postgresql/data directly. See
-        // https://github.com/docker-library/postgres/pull/1259.
-        dataMount: "/var/lib/postgresql",
-        defaultPort: 5432,
-        vscodeExtensions: ["cweijan.vscode-database-client2"]
-      },
-      mysql: {
-        id: "mysql",
-        image: "mysql:8",
-        env: {
-          MYSQL_ROOT_PASSWORD: "monoceros",
-          MYSQL_DATABASE: "monoceros"
-        },
-        healthcheck: {
-          test: [
-            "CMD",
-            "mysqladmin",
-            "ping",
-            "-h",
-            "127.0.0.1",
-            "-u",
-            "root",
-            "-p${MYSQL_ROOT_PASSWORD}"
-          ],
-          interval: "10s",
-          timeout: "5s",
-          retries: 5
-        },
-        dataMount: "/var/lib/mysql",
-        defaultPort: 3306,
-        vscodeExtensions: ["cweijan.vscode-database-client2"]
-      },
-      redis: {
-        id: "redis",
-        image: "redis:8",
-        healthcheck: {
-          test: ["CMD", "redis-cli", "ping"],
-          interval: "10s",
-          timeout: "5s",
-          retries: 5
-        },
-        dataMount: "/data",
-        defaultPort: 6379,
-        vscodeExtensions: ["cweijan.vscode-database-client2"]
-      }
-    };
+    SERVICE_CATALOG = Object.fromEntries(
+      [...DESCRIPTORS.values()].filter((c) => c.category === "service").map((c) => {
+        const key = descriptorSelector(c);
+        const svc = c.descriptor.service;
+        if (svc.defaultPort === void 0) {
+          throw new Error(
+            `Service descriptor '${key}' is missing service.defaultPort.`
+          );
+        }
+        const env = descriptorOptionDefaults(c.descriptor.options);
+        const entry2 = {
+          id: key,
+          image: svc.image,
+          ...Object.keys(env).length > 0 ? { env } : {},
+          ...svc.healthcheck ? { healthcheck: svc.healthcheck } : {},
+          ...svc.dataMount ? { dataMount: svc.dataMount } : {},
+          defaultPort: svc.defaultPort,
+          ...svc.vscodeExtensions ? { vscodeExtensions: svc.vscodeExtensions } : {},
+          ...svc.connectionEnv ? { connectionEnv: svc.connectionEnv } : {}
+        };
+        return [key, entry2];
+      })
+    );
   }
 });
 
@@ -2104,6 +2322,66 @@ var init_service_doc = __esm({
   }
 });
 
+// src/catalog/generate-manifest.ts
+function descriptorToFeatureManifest(descriptor) {
+  if (descriptor.category !== "feature" || !descriptor.feature) {
+    throw new Error(
+      `descriptorToFeatureManifest: '${descriptor.id}' is a ${descriptor.category}, not a feature.`
+    );
+  }
+  const feat = descriptor.feature;
+  const options = {};
+  const optionHints = [];
+  for (const [key, spec] of Object.entries(descriptor.options)) {
+    const option = { type: spec.type };
+    if (spec.proposals !== void 0) option.proposals = spec.proposals;
+    if (spec.default !== void 0) option.default = spec.default;
+    if (spec.description !== void 0) option.description = spec.description;
+    options[key] = option;
+    if (spec.surface === "env") optionHints.push(key);
+  }
+  const xMonoceros = {};
+  if (feat.persistentHomePaths && feat.persistentHomePaths.length > 0) {
+    xMonoceros.persistentHomePaths = feat.persistentHomePaths;
+  }
+  if (feat.persistentHomeFiles && feat.persistentHomeFiles.length > 0) {
+    xMonoceros.persistentHomeFiles = feat.persistentHomeFiles;
+  }
+  xMonoceros.optionHints = optionHints;
+  xMonoceros.usageNotes = descriptor.usageNotes;
+  xMonoceros.briefing = {
+    lines: descriptor.briefing.map((line) => ({
+      ...line.whenOption !== void 0 ? { whenOption: line.whenOption } : {},
+      text: line.text
+    }))
+  };
+  const manifest = {
+    $schema: DEVCONTAINER_FEATURE_SCHEMA,
+    id: descriptor.id,
+    name: descriptor.displayName,
+    version: feat.version,
+    description: descriptor.description
+  };
+  if (descriptor.documentationURL !== void 0) {
+    manifest.documentationURL = descriptor.documentationURL;
+  }
+  if (Object.keys(options).length > 0) {
+    manifest.options = options;
+  }
+  if (feat.vscodeExtensions && feat.vscodeExtensions.length > 0) {
+    manifest.customizations = { vscode: { extensions: feat.vscodeExtensions } };
+  }
+  manifest["x-monoceros"] = xMonoceros;
+  return manifest;
+}
+var DEVCONTAINER_FEATURE_SCHEMA;
+var init_generate_manifest = __esm({
+  "src/catalog/generate-manifest.ts"() {
+    "use strict";
+    DEVCONTAINER_FEATURE_SCHEMA = "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainerFeature.schema.json";
+  }
+});
+
 // src/create/claude-settings.ts
 import { existsSync as existsSync5, promises as fsp2 } from "fs";
 import path8 from "path";
@@ -2180,7 +2458,7 @@ var init_claude_settings = __esm({
 });
 
 // src/create/scaffold.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4, promises as fs7 } from "fs";
+import { existsSync as existsSync6, promises as fs7 } from "fs";
 import path9 from "path";
 function deriveRepoName(url) {
   const lastSep = Math.max(url.lastIndexOf("/"), url.lastIndexOf(":"));
@@ -2294,6 +2572,7 @@ function normalizeOptions(opts) {
     name: opts.name,
     ...opts.runtimeVersion !== void 0 ? { runtimeVersion: opts.runtimeVersion } : {},
     languages,
+    ...opts.languageOptions && Object.keys(opts.languageOptions).length > 0 ? { languageOptions: opts.languageOptions } : {},
     services,
     postgresUrl: opts.postgresUrl,
     ...aptPackages.length > 0 ? { aptPackages } : {},
@@ -2311,19 +2590,22 @@ function featuresSourceRoot() {
   const override2 = process.env.MONOCEROS_FEATURES_DIR_OVERRIDE?.trim();
   if (override2 && override2.length > 0) return override2;
   const checkout = workbenchCheckoutRoot();
-  return checkout ? path9.join(checkout, "images", "features") : null;
+  return checkout ? path9.join(checkout, "components", "features") : null;
 }
 function resolveFeatures(opts) {
   const resolved = [];
   for (const langSpec of opts.languages) {
     const parsed = parseLanguageSpec(langSpec);
     if (!parsed) continue;
-    if (BUILTIN_LANGUAGES.has(parsed.name) && parsed.version === void 0) {
-      continue;
-    }
     const entry2 = LANGUAGE_CATALOG[parsed.name];
     if (!entry2) continue;
-    const options = {};
+    if (BUILTIN_LANGUAGES.has(parsed.name) && (parsed.version === void 0 || parsed.version === entry2.defaultVersion)) {
+      continue;
+    }
+    const options = {
+      ...entry2.defaultOptions ?? {},
+      ...opts.languageOptions?.[parsed.name] ?? {}
+    };
     if (parsed.version !== void 0) options.version = parsed.version;
     resolved.push({
       devcontainerKey: entry2.feature,
@@ -2345,21 +2627,22 @@ function resolveFeatures(opts) {
       const match = matchMonocerosFeature(rawRef);
       if (match) {
         const name = match.name;
+        const descriptor = featureDescriptor(name);
+        const { paths, files } = descriptorPersistentHome(descriptor);
         const sourceRoot = featuresSourceRoot();
         const localSourceDir = sourceRoot ? path9.join(sourceRoot, name) : null;
-        if (localSourceDir && existsSync6(localSourceDir)) {
-          const { paths: paths2, files: files2 } = readPersistentHomeEntries(localSourceDir);
+        if (descriptor && localSourceDir && existsSync6(localSourceDir)) {
           resolved.push({
             devcontainerKey: `./features/${name}`,
             options,
             localSourceDir,
             localName: name,
-            persistentHomePaths: paths2,
-            persistentHomeFiles: files2
+            generatedManifest: descriptorToFeatureManifest(descriptor),
+            persistentHomePaths: paths,
+            persistentHomeFiles: files
           });
           continue;
         }
-        const { paths, files } = readBundledPersistentHomeEntries(name);
         resolved.push({
           devcontainerKey: rawRef,
           options,
@@ -2378,25 +2661,19 @@ function resolveFeatures(opts) {
   }
   return resolved;
 }
-function readPersistentHomeEntries(localSourceDir) {
-  const manifestPath = path9.join(localSourceDir, "devcontainer-feature.json");
+function featureDescriptor(name) {
   try {
-    const text = readFileSync4(manifestPath, "utf8");
-    const parsed = JSON.parse(text);
-    return {
-      paths: filterSubpaths(parsed["x-monoceros"]?.persistentHomePaths),
-      files: filterFileEntries(parsed["x-monoceros"]?.persistentHomeFiles)
-    };
+    const c = loadDescriptorCatalogSync().get(name);
+    return c?.category === "feature" ? c.descriptor : void 0;
   } catch {
-    return { paths: [], files: [] };
+    return void 0;
   }
 }
-function readBundledPersistentHomeEntries(name) {
-  try {
-    return readPersistentHomeEntries(path9.join(bundledFeaturesDir(), name));
-  } catch {
-    return { paths: [], files: [] };
-  }
+function descriptorPersistentHome(descriptor) {
+  return {
+    paths: filterSubpaths(descriptor?.feature?.persistentHomePaths),
+    files: filterFileEntries(descriptor?.feature?.persistentHomeFiles)
+  };
 }
 function filterSubpaths(raw) {
   if (!Array.isArray(raw)) return [];
@@ -2858,7 +3135,23 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
     if (!f.localSourceDir || !f.localName) continue;
     const dest = path9.join(featuresDir, f.localName);
     await fs7.mkdir(dest, { recursive: true });
-    await fs7.cp(f.localSourceDir, dest, { recursive: true });
+    const entries = await fs7.readdir(f.localSourceDir, { withFileTypes: true });
+    for (const entry2 of entries) {
+      if (!entry2.isFile()) continue;
+      if (entry2.name === "component.yml" || entry2.name === "devcontainer-feature.json") {
+        continue;
+      }
+      await fs7.cp(
+        path9.join(f.localSourceDir, entry2.name),
+        path9.join(dest, entry2.name)
+      );
+    }
+    if (f.generatedManifest) {
+      await fs7.writeFile(
+        path9.join(dest, "devcontainer-feature.json"),
+        JSON.stringify(f.generatedManifest, null, 2) + "\n"
+      );
+    }
   }
   for (const f of resolvedFeatures) {
     for (const sub of f.persistentHomePaths) {
@@ -2911,6 +3204,8 @@ var init_scaffold = __esm({
     "use strict";
     init_paths();
     init_ref();
+    init_load_sync();
+    init_generate_manifest();
     init_claude_settings();
     init_catalog();
     APT_PACKAGE_NAME_RE2 = /^[a-z0-9][a-z0-9.+-]*$/;
@@ -2966,10 +3261,33 @@ function pruneEmptySeq(doc, key) {
 function scalarValue(item) {
   return isScalar(item) ? item.value : item;
 }
-function addLanguageToDoc(doc, lang) {
+function languageEntryName(item) {
+  const v = scalarValue(item);
+  if (typeof v === "string") {
+    const colon = v.indexOf(":");
+    return colon === -1 ? v : v.slice(0, colon);
+  }
+  if (isMap2(item)) {
+    const firstKey = item.items[0]?.key;
+    const k = isScalar(firstKey) ? firstKey.value : firstKey;
+    return typeof k === "string" ? k : void 0;
+  }
+  return void 0;
+}
+function addLanguageToDoc(doc, name, opts = {}) {
   const seq = ensureSeq(doc, "languages");
-  if (seq.items.some((i) => scalarValue(i) === lang)) return false;
-  seq.add(lang);
+  if (seq.items.some((i) => languageEntryName(i) === name)) return false;
+  const { version, options } = opts;
+  if (options && Object.keys(options).length > 0) {
+    const inner = new YAMLMap2();
+    if (version !== void 0) inner.set("version", version);
+    for (const [key, value] of Object.entries(options)) inner.set(key, value);
+    const outer = new YAMLMap2();
+    outer.set(name, inner);
+    seq.add(outer);
+  } else {
+    seq.add(version !== void 0 ? `${name}:${version}` : name);
+  }
   return true;
 }
 function findServiceItem(seq, name) {
@@ -3382,12 +3700,22 @@ import { consola } from "consola";
 import { createPatch } from "diff";
 import path10 from "path";
 function runAddLanguage(input) {
-  if (!BUILTIN_LANGUAGES.has(input.language) && !LANGUAGE_CATALOG[input.language]) {
+  const spec = parseLanguageSpec(input.language);
+  if (!spec || !BUILTIN_LANGUAGES.has(spec.name) && !LANGUAGE_CATALOG[spec.name]) {
     throw new Error(
       `Unknown language: ${input.language}. Known: ${knownLanguages().join(", ")}.`
     );
   }
-  return mutate(input, (doc) => addLanguageToDoc(doc, input.language));
+  const entry2 = LANGUAGE_CATALOG[spec.name];
+  const version = spec.version ?? entry2?.defaultVersion;
+  const options = entry2?.ymlOptions;
+  return mutate(
+    input,
+    (doc) => addLanguageToDoc(doc, spec.name, {
+      ...version !== void 0 ? { version } : {},
+      ...options && Object.keys(options).length > 0 ? { options } : {}
+    })
+  );
 }
 async function runAddService(input) {
   const arg = input.service;
@@ -4443,6 +4771,23 @@ var init_state = __esm({
 });
 
 // src/config/transform.ts
+function normalizeLanguages(entries) {
+  const languages = [];
+  const languageOptions = {};
+  for (const entry2 of entries) {
+    if (typeof entry2 === "string") {
+      languages.push(entry2);
+      continue;
+    }
+    const name = Object.keys(entry2)[0];
+    const opts = { ...entry2[name] };
+    const version = opts.version;
+    delete opts.version;
+    languages.push(version !== void 0 ? `${name}:${String(version)}` : name);
+    if (Object.keys(opts).length > 0) languageOptions[name] = opts;
+  }
+  return { languages, languageOptions };
+}
 function solutionConfigToCreateOptions(config, featureDefaults = {}) {
   const featureRecord = {};
   for (const entry2 of config.features) {
@@ -4452,16 +4797,20 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
     );
     featureRecord[entry2.ref] = { ...defaults, ...containerOpts };
   }
+  const { languages, languageOptions } = normalizeLanguages(config.languages);
   const result = {
     name: config.name,
     ...config.runtimeVersion !== void 0 ? { runtimeVersion: config.runtimeVersion } : {},
-    languages: [...config.languages],
+    languages,
     // Normalize every services[] entry (curated string or explicit
     // object) to the canonical ResolvedService shape. `${VAR}` values
     // survive untouched here — apply interpolates them against
     // <name>.env afterwards.
     services: config.services.map(resolveService)
   };
+  if (Object.keys(languageOptions).length > 0) {
+    result.languageOptions = languageOptions;
+  }
   if (config.externalServices.postgres !== void 0) {
     result.postgresUrl = config.externalServices.postgres;
   }
@@ -4967,6 +5316,13 @@ function generateAgentsMd(input) {
       }
     }
     lines.push("");
+    lines.push(
+      "To show the user a running app, open it in their host browser with",
+      `\`xdg-open http://${input.containerName}.localhost\` \u2014 Monoceros relays`,
+      "browser-opens from the container to the host machine. Also tell the user",
+      "the URL, so they can open it themselves if no bridge is active."
+    );
+    lines.push("");
   }
   lines.push("## How to extend this container");
   lines.push("");
@@ -5548,13 +5904,13 @@ var init_runtime_pull_hint = __esm({
 
 // src/devcontainer/cli.ts
 import { spawn as spawn4 } from "child_process";
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { createRequire } from "module";
 import path14 from "path";
 function devcontainerCliPath() {
   if (cachedBinaryPath) return cachedBinaryPath;
   const pkgJsonPath = require_.resolve("@devcontainers/cli/package.json");
-  const pkg = JSON.parse(readFileSync5(pkgJsonPath, "utf8"));
+  const pkg = JSON.parse(readFileSync4(pkgJsonPath, "utf8"));
   const binEntry = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.devcontainer ?? "";
   if (!binEntry) {
     throw new Error("Could not resolve @devcontainers/cli bin entry.");
@@ -6699,7 +7055,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.21.2" : "dev";
+    CLI_VERSION = true ? "1.22.0" : "dev";
   }
 });
 
@@ -7346,7 +7702,21 @@ function generateComposedYml(name, composed, lookupManifest, repoUrls = [], port
       false
     );
     lines.push("languages:");
-    for (const lang of composed.languages) lines.push(`  - ${lang}`);
+    for (const lang of composed.languages) {
+      const opts = lang.options ?? {};
+      if (Object.keys(opts).length === 0) {
+        lines.push(`  - ${lang.spec}`);
+        continue;
+      }
+      const colon = lang.spec.indexOf(":");
+      const langName = colon === -1 ? lang.spec : lang.spec.slice(0, colon);
+      const version = colon === -1 ? void 0 : lang.spec.slice(colon + 1);
+      lines.push(`  - ${langName}:`);
+      if (version !== void 0) lines.push(`      version: ${version}`);
+      for (const [key, value] of Object.entries(opts)) {
+        lines.push(`      ${key}: ${String(value)}`);
+      }
+    }
     lines.push("");
   }
   if (composed.aptPackages.length > 0) {
@@ -7454,7 +7824,8 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
     lines.push("# languages:");
     for (const c of byCategory.language) {
       for (const lang of c.file.contributes.languages ?? []) {
-        lines.push(`#   - ${lang}`);
+        const ver = LANGUAGE_CATALOG[lang]?.defaultVersion;
+        lines.push(`#   - ${ver ? `${lang}:${ver}` : lang}`);
       }
     }
     lines.push("");
@@ -7697,7 +8068,6 @@ import { existsSync as existsSync10, promises as fs14 } from "fs";
 import path19 from "path";
 import { consola as consola13 } from "consola";
 async function runInit(opts) {
-  const workbench = opts.workbenchRoot ?? workbenchRoot();
   const home = opts.monocerosHome ?? monocerosHome();
   const logger = opts.logger ?? {
     success: (msg) => consola13.success(msg),
@@ -7714,14 +8084,14 @@ async function runInit(opts) {
       `Config already exists: ${dest}. Delete it manually before re-running \`monoceros init\` \u2014 this protects any hand-edits.`
     );
   }
-  const catalog = await loadComponentCatalog(componentsDir(workbench));
+  const componentsRoot = opts.workbenchRoot ? path19.join(opts.workbenchRoot, "components") : componentsRootDir();
+  const catalog = await loadComponentCatalog(componentsRoot);
   if (catalog.size === 0) {
     throw new Error(
-      `No components found under ${componentsDir(workbench)}. The workbench checkout is incomplete.`
+      `No components found under ${componentsRoot}. The workbench checkout is incomplete.`
     );
   }
-  const checkoutRoot = opts.workbenchRoot ?? workbenchCheckoutRoot();
-  const lookup = (ref) => loadFeatureManifestSummary(ref, checkoutRoot);
+  const lookup = (ref) => loadFeatureManifestSummary(ref, componentsRoot);
   const reposRaw = (opts.withRepo ?? []).map((u) => u.trim()).filter((u) => u.length > 0);
   const repos = [];
   const seenRepoUrls = /* @__PURE__ */ new Set();
@@ -7842,7 +8212,14 @@ function resolveInitLanguages(entries) {
       continue;
     }
     seen.add(e);
-    out.push(e);
+    const entry2 = LANGUAGE_CATALOG[spec.name];
+    const renderedSpec = spec.version === void 0 && entry2?.defaultVersion ? `${spec.name}:${entry2.defaultVersion}` : e;
+    if (out.some((o) => o.spec === renderedSpec)) continue;
+    const ymlOptions = entry2?.ymlOptions;
+    out.push({
+      spec: renderedSpec,
+      ...ymlOptions && Object.keys(ymlOptions).length > 0 ? { options: ymlOptions } : {}
+    });
   }
   if (unknown.length > 0) {
     throw new Error(
@@ -8077,6 +8454,45 @@ var init_init2 = __esm({
   }
 });
 
+// src/catalog/expand.ts
+function expandSelectable(catalog) {
+  const out = /* @__PURE__ */ new Map();
+  const add = (entry2) => {
+    if (out.has(entry2.name)) {
+      throw new Error(
+        `Duplicate selectable component name '${entry2.name}' (from descriptor '${entry2.componentId}').`
+      );
+    }
+    out.set(entry2.name, entry2);
+  };
+  for (const { descriptor: d } of catalog.values()) {
+    const selector = d.name ?? d.id;
+    add({
+      name: selector,
+      category: d.category,
+      displayName: d.displayName,
+      description: d.description,
+      componentId: d.id
+    });
+    for (const [presetKey, overrides] of Object.entries(d.presets ?? {})) {
+      add({
+        name: `${selector}/${presetKey}`,
+        category: d.category,
+        displayName: `${d.displayName} (${presetKey})`,
+        description: d.description,
+        componentId: d.id,
+        presetOptions: overrides
+      });
+    }
+  }
+  return out;
+}
+var init_expand = __esm({
+  "src/catalog/expand.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/list-components.ts
 import { defineCommand as defineCommand12 } from "citty";
 import { consola as consola15 } from "consola";
@@ -8084,7 +8500,8 @@ var CATEGORY_LABELS, CATEGORY_ORDER, listComponentsCommand;
 var init_list_components = __esm({
   "src/commands/list-components.ts"() {
     "use strict";
-    init_components();
+    init_load();
+    init_expand();
     init_format();
     CATEGORY_LABELS = {
       language: "Languages",
@@ -8105,7 +8522,7 @@ var init_list_components = __esm({
       args: {},
       async run() {
         try {
-          const catalog = await loadComponentCatalog();
+          const catalog = expandSelectable(await loadDescriptorCatalog());
           if (catalog.size === 0) {
             consola15.warn(
               "No components found. The workbench checkout looks incomplete."
@@ -8116,9 +8533,9 @@ var init_list_components = __esm({
           const isTty2 = process.stdout.isTTY ?? false;
           const byCategory = /* @__PURE__ */ new Map();
           for (const c of catalog.values()) {
-            const list = byCategory.get(c.file.category) ?? [];
-            list.push({ name: c.name, desc: c.file.displayName });
-            byCategory.set(c.file.category, list);
+            const list = byCategory.get(c.category) ?? [];
+            list.push({ name: c.name, desc: c.displayName });
+            byCategory.set(c.category, list);
           }
           for (const list of byCategory.values()) {
             list.sort((a, b) => a.name.localeCompare(b.name));
@@ -8994,7 +9411,7 @@ var init_remove_service = __esm({
 
 // src/devcontainer/browser-bridge.ts
 import { spawn as spawn9 } from "child_process";
-import { existsSync as existsSync14, promises as fsp4, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync14, promises as fsp4, readFileSync as readFileSync5 } from "fs";
 import http from "http";
 import path23 from "path";
 function parseCallbackTarget(authUrl) {
@@ -9011,6 +9428,10 @@ function parseCallbackTarget(authUrl) {
     return null;
   }
 }
+function nextRelayUrl(content, lastOpened) {
+  const url = content.trim();
+  return url && url !== lastOpened ? url : null;
+}
 function openInBrowser(url) {
   const platform = process.platform;
   const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
@@ -9041,7 +9462,7 @@ exit 0
   );
   await fsp4.chmod(relayScript, 493);
   const servers = [];
-  let handled = false;
+  let lastOpened = null;
   const onUrl = (url) => {
     openInBrowser(url);
     const target = parseCallbackTarget(url);
@@ -9072,16 +9493,17 @@ exit 0
     servers.push(server);
   };
   const poll = setInterval(() => {
-    if (handled || !existsSync14(urlFile)) return;
+    if (!existsSync14(urlFile)) return;
     let content = "";
     try {
-      content = readFileSync6(urlFile, "utf8");
+      content = readFileSync5(urlFile, "utf8");
     } catch {
       return;
     }
-    if (!content.trim()) return;
-    handled = true;
-    onUrl(content.trim());
+    const url = nextRelayUrl(content, lastOpened);
+    if (!url) return;
+    lastOpened = url;
+    onUrl(url);
   }, 250);
   return {
     relayDirInContainer: `/workspaces/${opts.name}/${RELAY_DIRNAME}`,