@getmonoceros/workbench 1.15.0 → 1.16.0

package/dist/bin.js

@@ -74,12 +74,13 @@ ${issues}`);
   }
   return result.data;
 }
-var SOLUTION_NAME_RE, APT_PACKAGE_NAME_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, SolutionConfigSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
     SOLUTION_NAME_RE = /^[A-Za-z0-9._-]+$/;
     APT_PACKAGE_NAME_RE = /^[a-z0-9][a-z0-9.+-]*$/;
+    RUNTIME_VERSION_RE = /^\d+\.\d+\.\d+$/;
     FEATURE_REF_RE = /^[a-z0-9.-]+(\/[a-z0-9._-]+)+:[a-z0-9._-]+$/;
     INSTALL_URL_RE = /^https:\/\/[A-Za-z0-9.\-_~/:?#[\]@!&'()*+,;=%]+$/;
     REPO_URL_RE = /^https:\/\/[A-Za-z0-9@:/+_~.#=&?-]+$/;
@@ -216,6 +217,15 @@ var init_schema = __esm({
         SOLUTION_NAME_RE,
         "Invalid solution name. Use letters, digits, '.', '_' or '-'."
       ),
+      // Pinned runtime-image version (ADR 0017). Written by `init`, reused
+      // verbatim by every subsequent `apply` (never auto-bumped), changed
+      // only by `monoceros upgrade`. Optional in the schema so a
+      // pre-pinning yml still parses — `apply` is what enforces its
+      // presence with an actionable hint.
+      runtimeVersion: z.string().regex(
+        RUNTIME_VERSION_RE,
+        "Invalid runtimeVersion. Expected an exact version like '1.1.0'."
+      ).optional(),
       languages: z.array(z.string().min(1)).default([]),
       aptPackages: z.array(
         z.string().regex(
@@ -1821,6 +1831,25 @@ var init_port_check = __esm({
 });
 
 // src/create/catalog.ts
+function resolveRuntimeImage(version) {
+  const ov = process.env.MONOCEROS_BASE_IMAGE_OVERRIDE?.trim();
+  if (ov && ov.length > 0) return ov;
+  if (!version) return `${RUNTIME_IMAGE_REPO}:1`;
+  return `${RUNTIME_IMAGE_REPO}:${version}`;
+}
+function compareRuntimeVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function runtimeSupportsIdeVolumes(version) {
+  if (!version) return false;
+  return compareRuntimeVersions(version, MIN_RUNTIME_FOR_IDE_VOLUMES) >= 0;
+}
 function parseLanguageSpec(spec) {
   const m = LANGUAGE_SPEC_RE.exec(spec);
   if (!m) return null;
@@ -1877,13 +1906,16 @@ 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, 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, BUILTIN_LANGUAGES, LANGUAGE_CATALOG, LANGUAGE_SPEC_RE, SERVICE_CATALOG;
 var init_catalog = __esm({
   "src/create/catalog.ts"() {
     "use strict";
     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;
+    RUNTIME_IMAGE_REPO = "ghcr.io/getmonoceros/monoceros-runtime";
+    DEFAULT_RUNTIME_VERSION = "1.1.0";
+    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" },
@@ -1921,7 +1953,8 @@ var init_catalog = __esm({
         // /var/lib/postgresql/data directly. See
         // https://github.com/docker-library/postgres/pull/1259.
         dataMount: "/var/lib/postgresql",
-        defaultPort: 5432
+        defaultPort: 5432,
+        vscodeExtensions: ["cweijan.vscode-database-client2"]
       },
       mysql: {
         id: "mysql",
@@ -1946,7 +1979,8 @@ var init_catalog = __esm({
           retries: 5
         },
         dataMount: "/var/lib/mysql",
-        defaultPort: 3306
+        defaultPort: 3306,
+        vscodeExtensions: ["cweijan.vscode-database-client2"]
       },
       redis: {
         id: "redis",
@@ -1958,7 +1992,8 @@ var init_catalog = __esm({
           retries: 5
         },
         dataMount: "/data",
-        defaultPort: 6379
+        defaultPort: 6379,
+        vscodeExtensions: ["cweijan.vscode-database-client2"]
       }
     };
   }
@@ -2134,6 +2169,7 @@ function normalizeOptions(opts) {
   const ports = opts.ports ? [...new Set(opts.ports)] : void 0;
   return {
     name: opts.name,
+    ...opts.runtimeVersion !== void 0 ? { runtimeVersion: opts.runtimeVersion } : {},
     languages,
     services,
     postgresUrl: opts.postgresUrl,
@@ -2246,6 +2282,18 @@ function filterFileEntries(raw) {
 function isValidHomeSubpath(p) {
   return p.length > 0 && !p.startsWith("/") && !p.includes("..") && HOME_SUBPATH_RE.test(p);
 }
+function ideStateVolumes(name) {
+  return [
+    {
+      volume: `monoceros-${name}-vscode-extensions`,
+      target: "/home/node/.vscode-server/extensions"
+    },
+    {
+      volume: `monoceros-${name}-vscode-userdata`,
+      target: "/home/node/.vscode-server/data/User"
+    }
+  ];
+}
 function buildDevcontainerJson(opts, dockerMode = "rootful") {
   const resolvedFeatures = resolveFeatures(opts);
   const features = {};
@@ -2291,7 +2339,10 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
       ...customizationsField ?? {}
     };
   }
-  const mounts = [...homeMounts];
+  const ideMounts = runtimeSupportsIdeVolumes(opts.runtimeVersion) ? ideStateVolumes(opts.name).map(
+    (v) => `source=${v.volume},target=${v.target},type=volume`
+  ) : [];
+  const mounts = [...homeMounts, ...ideMounts];
   const mountsField = mounts.length > 0 ? { mounts } : {};
   const workspaceMountField = {
     workspaceMount: `source=\${localWorkspaceFolder},target=/workspaces/${opts.name},type=bind,consistency=cached`,
@@ -2304,7 +2355,7 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
   }
   return {
     name: opts.name,
-    image: BASE_IMAGE,
+    image: resolveRuntimeImage(opts.runtimeVersion),
     remoteUser: "node",
     ...workspaceMountField,
     ...mountsField,
@@ -2331,8 +2382,9 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
   void dockerMode;
   const hasPorts = (opts.ports?.length ?? 0) > 0;
   const lines = ["services:"];
+  const ideVolumes = runtimeSupportsIdeVolumes(opts.runtimeVersion) ? ideStateVolumes(opts.name) : [];
   lines.push("  workspace:");
-  lines.push(`    image: ${BASE_IMAGE}`);
+  lines.push(`    image: ${resolveRuntimeImage(opts.runtimeVersion)}`);
   lines.push("    command: 'sleep infinity'");
   lines.push("    cap_add:");
   lines.push("      - NET_ADMIN");
@@ -2355,6 +2407,9 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
       lines.push(`      - ../home/${sub}:/home/node/${sub}`);
     }
   }
+  for (const v of ideVolumes) {
+    lines.push(`      - ${v.volume}:${v.target}`);
+  }
   for (const svc of opts.services) {
     lines.push(`  ${svc.name}:`);
     lines.push(`    image: ${svc.image}`);
@@ -2393,6 +2448,13 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
       }
     }
   }
+  if (ideVolumes.length > 0) {
+    lines.push("volumes:");
+    for (const v of ideVolumes) {
+      lines.push(`  ${v.volume}:`);
+      lines.push(`    name: ${v.volume}`);
+    }
+  }
   if (hasPorts) {
     lines.push("networks:");
     lines.push("  monoceros-proxy:");
@@ -2400,8 +2462,34 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
   }
   return lines.join("\n") + "\n";
 }
+function extractRepoHost(url) {
+  const schemeMatch = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)/i.exec(url);
+  if (schemeMatch) return schemeMatch[1].toLowerCase();
+  const scpMatch = /^(?:[^@/]+@)?([^/:]+):/.exec(url);
+  if (scpMatch) return scpMatch[1].toLowerCase();
+  return null;
+}
+function computeExtensionRecommendations(opts) {
+  const recs = /* @__PURE__ */ new Set();
+  for (const svc of opts.services) {
+    const catalogEntry = SERVICE_CATALOG[svc.name];
+    for (const ext of catalogEntry?.vscodeExtensions ?? []) {
+      recs.add(ext);
+    }
+  }
+  for (const repo of opts.repos ?? []) {
+    const host = extractRepoHost(repo.url);
+    if (!host) continue;
+    for (const ext of REPO_HOST_EXTENSIONS[host] ?? []) {
+      recs.add(ext);
+    }
+  }
+  return [...recs].sort((a, b) => a.localeCompare(b));
+}
 function buildCodeWorkspaceJson(opts) {
-  const folders = [{ path: "." }];
+  const folders = [
+    { path: ".", name: WORKSPACE_ROOT_LABEL }
+  ];
   const sortedRepos = [...opts.repos ?? []].sort(
     (a, b) => a.path.localeCompare(b.path)
   );
@@ -2409,7 +2497,11 @@ function buildCodeWorkspaceJson(opts) {
     const label = repo.path.split("/").pop() ?? repo.path;
     folders.push({ path: `projects/${repo.path}`, name: label });
   }
-  return { folders };
+  const recommendations = computeExtensionRecommendations(opts);
+  return {
+    folders,
+    ...recommendations.length > 0 ? { extensions: { recommendations } } : {}
+  };
 }
 function mergeCodeWorkspace(existing, generated) {
   if (!existing || typeof existing !== "object" || Array.isArray(existing) || !Array.isArray(existing.folders)) {
@@ -2424,10 +2516,41 @@ function mergeCodeWorkspace(existing, generated) {
   for (const g of generated.folders) {
     if (!existingPaths.has(g.path)) merged.push(g);
   }
+  const generatedRootName = generated.folders.find((f) => f.path === ".")?.name;
+  if (generatedRootName) {
+    const idx = merged.findIndex(
+      (f) => f && typeof f === "object" && f.path === "."
+    );
+    if (idx >= 0 && !merged[idx].name) {
+      merged[idx] = { ...merged[idx], name: generatedRootName };
+    }
+  }
   const out = { ...existingObj };
   out.folders = merged;
+  const generatedRecs = generated.extensions?.recommendations ?? [];
+  if (generatedRecs.length > 0) {
+    const existingExtRaw = existingObj.extensions;
+    const existingExt = existingExtRaw && typeof existingExtRaw === "object" && !Array.isArray(existingExtRaw) ? existingExtRaw : {};
+    const existingRecs = Array.isArray(existingExt.recommendations) ? existingExt.recommendations.filter(
+      (r) => typeof r === "string"
+    ) : [];
+    const existingRecSet = new Set(existingRecs);
+    const mergedRecs = [...existingRecs];
+    for (const r of generatedRecs) {
+      if (!existingRecSet.has(r)) mergedRecs.push(r);
+    }
+    out.extensions = { ...existingExt, recommendations: mergedRecs };
+  }
   return out;
 }
+function mergeVscodeSettings(existing) {
+  const base = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+  const existingExclude = base["files.exclude"] && typeof base["files.exclude"] === "object" && !Array.isArray(base["files.exclude"]) ? base["files.exclude"] : {};
+  return {
+    ...base,
+    "files.exclude": { ...existingExclude, ...ROOT_DENOISE_EXCLUDES }
+  };
+}
 function buildPostCreateScript(opts) {
   const lines = [
     "#!/usr/bin/env bash",
@@ -2528,6 +2651,14 @@ async function writePostCreateScript(devcontainerDir, opts) {
   await fs7.writeFile(dest, buildPostCreateScript(opts));
   await fs7.chmod(dest, 493);
 }
+async function writeIfChanged(filePath, content) {
+  try {
+    if (await fs7.readFile(filePath, "utf8") === content) return false;
+  } catch {
+  }
+  await fs7.writeFile(filePath, content);
+  return true;
+}
 async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
   const devcontainerDir = path8.join(targetDir, ".devcontainer");
@@ -2562,7 +2693,7 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
     "git-credentials*\ngitconfig\n"
   );
   const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
-  await fs7.writeFile(
+  await writeIfChanged(
     path8.join(devcontainerDir, "devcontainer.json"),
     JSON.stringify(devcontainerJson, null, 2) + "\n"
   );
@@ -2592,7 +2723,7 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   await writePostCreateScript(devcontainerDir, opts);
   const composePath = path8.join(devcontainerDir, "compose.yaml");
   if (needsCompose(opts)) {
-    await fs7.writeFile(composePath, buildComposeYaml(opts, dockerMode));
+    await writeIfChanged(composePath, buildComposeYaml(opts, dockerMode));
   } else if (existsSync5(composePath)) {
     await fs7.rm(composePath);
   }
@@ -2607,8 +2738,21 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const generated = buildCodeWorkspaceJson(opts);
   const merged = mergeCodeWorkspace(existingWorkspace, generated);
   await fs7.writeFile(workspacePath, JSON.stringify(merged, null, 2) + "\n");
+  const vscodeDir = path8.join(targetDir, ".vscode");
+  const settingsPath = path8.join(vscodeDir, "settings.json");
+  let existingSettings;
+  try {
+    existingSettings = JSON.parse(await fs7.readFile(settingsPath, "utf8"));
+  } catch {
+    existingSettings = void 0;
+  }
+  await fs7.mkdir(vscodeDir, { recursive: true });
+  await fs7.writeFile(
+    settingsPath,
+    JSON.stringify(mergeVscodeSettings(existingSettings), null, 2) + "\n"
+  );
 }
-var APT_PACKAGE_NAME_RE2, FEATURE_REF_RE2, INSTALL_URL_RE2, REPO_URL_RE2, REPO_PATH_RE2, HOME_SUBPATH_RE;
+var APT_PACKAGE_NAME_RE2, FEATURE_REF_RE2, INSTALL_URL_RE2, REPO_URL_RE2, REPO_PATH_RE2, HOME_SUBPATH_RE, WORKSPACE_ROOT_LABEL, REPO_HOST_EXTENSIONS, ROOT_DENOISE_EXCLUDES;
 var init_scaffold = __esm({
   "src/create/scaffold.ts"() {
     "use strict";
@@ -2621,6 +2765,23 @@ var init_scaffold = __esm({
     REPO_URL_RE2 = /^[A-Za-z0-9@:/+_~.#=&?-]+$/;
     REPO_PATH_RE2 = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
     HOME_SUBPATH_RE = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+    WORKSPACE_ROOT_LABEL = "\u{1F984} Monoceros";
+    REPO_HOST_EXTENSIONS = {
+      "github.com": [
+        "github.vscode-pull-request-github",
+        "GitHub.vscode-github-actions"
+      ],
+      "gitlab.com": ["GitLab.gitlab-workflow"]
+    };
+    ROOT_DENOISE_EXCLUDES = {
+      ".devcontainer": true,
+      ".monoceros": true,
+      ".vscode": true,
+      ".gitignore": true,
+      data: true,
+      projects: true,
+      "*.code-workspace": true
+    };
   }
 });
 
@@ -4097,7 +4258,8 @@ function buildStateFile(opts) {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     origin: opts.origin,
     monocerosCliVersion: opts.cliVersion,
-    materializedAt: (opts.now ?? /* @__PURE__ */ new Date()).toISOString()
+    materializedAt: (opts.now ?? /* @__PURE__ */ new Date()).toISOString(),
+    ...opts.runtimeImage ? { runtimeImage: opts.runtimeImage } : {}
   };
 }
 function stateFilePath(targetDir) {
@@ -4138,6 +4300,7 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
   }
   const result = {
     name: config.name,
+    ...config.runtimeVersion !== void 0 ? { runtimeVersion: config.runtimeVersion } : {},
     languages: [...config.languages],
     // Normalize every services[] entry (curated string or explicit
     // object) to the canonical ResolvedService shape. `${VAR}` values
@@ -5726,6 +5889,11 @@ ${sectionLine(label)}
   await assertSafeTargetDir(targetDir, opts.name);
   section("Configuration");
   const parsed = await readConfig(ymlPath);
+  if (!parsed.config.runtimeVersion) {
+    throw new Error(
+      `No runtime pinned for '${opts.name}': the yml has no 'runtimeVersion'. Pin it with \`monoceros upgrade ${opts.name} <version>\` (or add \`runtimeVersion: <version>\` to the yml), then re-apply.`
+    );
+  }
   const globalConfig = await readMonocerosConfig({ monocerosHome: home });
   warnOnDeprecatedFeatureRefs(parsed.config.features, globalConfig, logger);
   const envPath = containerEnvPath(opts.name, home);
@@ -5837,6 +6005,7 @@ Fix the value in the env file (or the yml).`
     buildStateFile({
       origin: opts.name,
       cliVersion: opts.cliVersion,
+      runtimeImage: resolveRuntimeImage(createOpts.runtimeVersion),
       ...opts.now ? { now: opts.now } : {}
     })
   );
@@ -6059,6 +6228,7 @@ var init_apply = __esm({
     init_schema();
     init_state();
     init_transform();
+    init_catalog();
     init_scaffold();
     init_format();
     init_ref();
@@ -6085,7 +6255,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.15.0" : "dev";
+    CLI_VERSION = true ? "1.16.0" : "dev";
   }
 });
 
@@ -6510,6 +6680,7 @@ var init_resolve = __esm({
       "stop",
       "status",
       "apply",
+      "upgrade",
       "remove",
       "restore",
       "add-service",
@@ -6554,6 +6725,12 @@ var init_resolve = __esm({
         positionals: [containerName],
         flags: { "--yes": { type: "boolean", aliases: ["-y"] } }
       },
+      upgrade: {
+        // First positional is a container name; the second is a version
+        // string (no suggestions — versions live in the registry).
+        positionals: [containerName, () => []],
+        flags: { "--list": { type: "boolean" } }
+      },
       remove: {
         positionals: [containerName],
         flags: {
@@ -6704,6 +6881,11 @@ function generateComposedYml(name, composed, lookupManifest, repoUrls = [], port
   lines.push("");
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
+  lines.push(
+    "# Pinned runtime image version. Reused on every apply; change it with"
+  );
+  lines.push("# `monoceros upgrade <name> [version]`.");
+  lines.push(`runtimeVersion: ${DEFAULT_RUNTIME_VERSION}`);
   lines.push("");
   if (composed.languages.length > 0) {
     pushSectionHeader(
@@ -6802,6 +6984,11 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
   lines.push("");
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
+  lines.push(
+    "# Pinned runtime image version. Reused on every apply; change it with"
+  );
+  lines.push("# `monoceros upgrade <name> [version]`.");
+  lines.push(`runtimeVersion: ${DEFAULT_RUNTIME_VERSION}`);
   lines.push("");
   if (byCategory.language.length > 0) {
     pushSectionHeader(
@@ -7802,6 +7989,8 @@ async function runRemove(opts) {
     logger,
     exec: dockerExec
   });
+  const ideVolumes = ideStateVolumes(opts.name).map((v) => v.volume);
+  await dockerExec(["volume", "rm", "-f", ...ideVolumes]);
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
@@ -7896,6 +8085,7 @@ var init_remove = __esm({
     init_paths();
     init_schema();
     init_compose();
+    init_scaffold();
     init_proxy();
     init_dynamic();
   }
@@ -9063,12 +9253,165 @@ var init_tunnel = __esm({
   }
 });
 
+// src/upgrade/index.ts
+import { existsSync as existsSync14, promises as fs17 } from "fs";
+import { consola as consola34 } from "consola";
+async function fetchRuntimeVersions() {
+  const tokenUrl = `https://ghcr.io/token?service=ghcr.io&scope=repository:${RUNTIME_REPO}:pull`;
+  const tokenRes = await fetch(tokenUrl);
+  if (!tokenRes.ok) {
+    throw new Error(
+      `Could not get a GHCR token (HTTP ${tokenRes.status}). Pass an explicit version to skip the lookup: \`monoceros upgrade <name> <version>\`.`
+    );
+  }
+  const { token } = await tokenRes.json();
+  if (!token) throw new Error("GHCR token response contained no token.");
+  const tagsRes = await fetch(`https://ghcr.io/v2/${RUNTIME_REPO}/tags/list`, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!tagsRes.ok) {
+    throw new Error(
+      `Could not list runtime versions (HTTP ${tagsRes.status}). Pass an explicit version: \`monoceros upgrade <name> <version>\`.`
+    );
+  }
+  const { tags } = await tagsRes.json();
+  return (tags ?? []).filter((t) => VERSION_RE.test(t)).sort(compareRuntimeVersions);
+}
+function setRuntimeVersion(yml, version) {
+  if (/^runtimeVersion:.*$/m.test(yml)) {
+    return yml.replace(/^runtimeVersion:.*$/m, `runtimeVersion: ${version}`);
+  }
+  if (/^schemaVersion:.*$/m.test(yml)) {
+    return yml.replace(
+      /^(schemaVersion:.*)$/m,
+      `$1
+runtimeVersion: ${version}`
+    );
+  }
+  return `runtimeVersion: ${version}
+${yml}`;
+}
+async function runUpgrade(opts) {
+  const home = opts.monocerosHome ?? monocerosHome();
+  const logger = opts.logger ?? consola34;
+  const fetchVersions = opts.fetchVersions ?? fetchRuntimeVersions;
+  if (opts.list) {
+    const versions = await fetchVersions();
+    if (versions.length === 0) {
+      logger.info("No published runtime versions found.");
+      return 0;
+    }
+    logger.info(
+      `Available runtime versions (latest last):
+  ${versions.join("\n  ")}`
+    );
+    return 0;
+  }
+  if (!opts.name) {
+    throw new Error(
+      "Usage: `monoceros upgrade <name> [version]` (or `monoceros upgrade --list`)."
+    );
+  }
+  const ymlPath = containerConfigPath(opts.name, home);
+  if (!existsSync14(ymlPath)) {
+    throw new Error(
+      `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
+    );
+  }
+  let target = opts.version;
+  if (target !== void 0 && !VERSION_RE.test(target)) {
+    throw new Error(
+      `Invalid version ${JSON.stringify(target)}. Expected an exact version like '1.1.0'.`
+    );
+  }
+  if (target === void 0) {
+    const versions = await fetchVersions();
+    target = versions[versions.length - 1];
+    if (!target) {
+      throw new Error("Could not determine the latest runtime version.");
+    }
+    logger.info(`Latest published runtime version: ${target}`);
+  }
+  const raw = await fs17.readFile(ymlPath, "utf8");
+  const updated = setRuntimeVersion(raw, target);
+  if (updated === raw) {
+    logger.info(`'${opts.name}' is already pinned to runtime ${target}.`);
+  } else {
+    await fs17.writeFile(ymlPath, updated);
+    logger.success(`Pinned '${opts.name}' to runtime ${target}. Re-applying\u2026`);
+  }
+  const apply = opts.applyRunner ?? runApply;
+  const result = await apply({
+    name: opts.name,
+    cliVersion: opts.cliVersion,
+    monocerosHome: home
+  });
+  return result.containerExitCode;
+}
+var RUNTIME_REPO, VERSION_RE;
+var init_upgrade = __esm({
+  "src/upgrade/index.ts"() {
+    "use strict";
+    init_paths();
+    init_catalog();
+    init_apply();
+    RUNTIME_REPO = "getmonoceros/monoceros-runtime";
+    VERSION_RE = /^\d+\.\d+\.\d+$/;
+  }
+});
+
+// src/commands/upgrade.ts
+import { defineCommand as defineCommand30 } from "citty";
+var upgradeCommand;
+var init_upgrade2 = __esm({
+  "src/commands/upgrade.ts"() {
+    "use strict";
+    init_upgrade();
+    init_version();
+    init_dispatch();
+    upgradeCommand = defineCommand30({
+      meta: {
+        name: "upgrade",
+        group: "lifecycle",
+        description: "Pin a container to a newer runtime image version and re-apply. `monoceros upgrade <name>` pins to the latest published version; `monoceros upgrade <name> <version>` pins to an exact one; `monoceros upgrade --list` lists available versions."
+      },
+      args: {
+        name: {
+          type: "positional",
+          description: "Config name. Resolves to $MONOCEROS_HOME/container-configs/<name>.yml.",
+          required: false
+        },
+        version: {
+          type: "positional",
+          description: "Exact runtime version to pin (e.g. 1.1.0). Omit to use the latest published version.",
+          required: false
+        },
+        list: {
+          type: "boolean",
+          description: "List available runtime versions and exit, changing nothing.",
+          default: false
+        }
+      },
+      run({ args }) {
+        return dispatch(
+          () => runUpgrade({
+            ...args.name ? { name: args.name } : {},
+            ...args.version ? { version: args.version } : {},
+            list: args.list,
+            cliVersion: CLI_VERSION
+          })
+        );
+      }
+    });
+  }
+});
+
 // src/main.ts
 var main_exports = {};
 __export(main_exports, {
   main: () => main
 });
-import { defineCommand as defineCommand30 } from "citty";
+import { defineCommand as defineCommand31 } from "citty";
 var main;
 var init_main = __esm({
   "src/main.ts"() {
@@ -9102,8 +9445,9 @@ var init_main = __esm({
     init_status();
     init_stop();
     init_tunnel();
+    init_upgrade2();
     init_version();
-    main = defineCommand30({
+    main = defineCommand31({
       meta: {
         name: "monoceros",
         version: CLI_VERSION,
@@ -9119,6 +9463,7 @@ var init_main = __esm({
         stop: stopCommand,
         status: statusCommand,
         apply: applyCommand,
+        upgrade: upgradeCommand,
         remove: removeCommand,
         restore: restoreCommand,
         "add-service": addServiceCommand,