@getmonoceros/workbench 1.24.2 → 1.26.0

package/bundled-components/services/mailpit/component.yml

@@ -0,0 +1,17 @@
+id: mailpit
+category: service
+displayName: Mailpit
+description: 'SMTP catcher for local dev — apps send mail to it and nothing leaves the machine. SMTP on `mailpit:1025`; web UI + API on 8025 (reach via `monoceros tunnel <name> mailpit:8025`).'
+service:
+  image: axllent/mailpit:latest
+  defaultPort: 1025
+  healthcheck:
+    # Mailpit ships its own readiness probe in the image — no curl/wget needed.
+    test: [CMD, /mailpit, readyz]
+    interval: 15s
+    timeout: 5s
+    retries: 5
+  connectionEnv:
+    URL: smtp://${host}:${port}
+    HOST: ${host}
+    PORT: ${port}

package/bundled-components/services/mongodb/component.yml

@@ -0,0 +1,36 @@
+id: mongodb
+category: service
+displayName: MongoDB
+description: 'MongoDB with seeded dev credentials and a readiness healthcheck. Reachable in-container as host `mongodb`.'
+service:
+  image: mongo:8
+  defaultPort: 27017
+  dataMount: /data/db
+  healthcheck:
+    test: [CMD, mongosh, --quiet, --eval, 'db.adminCommand({ ping: 1 }).ok']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+  vscodeExtensions: [mongodb.mongodb-vscode]
+  client:
+    npm: [mongosh]
+  connectionEnv:
+    URL: mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@${host}:${port}/${MONGO_INITDB_DATABASE}?authSource=admin
+    HOST: ${host}
+    PORT: ${port}
+    USER: ${MONGO_INITDB_ROOT_USERNAME}
+    PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD}
+    DB: ${MONGO_INITDB_DATABASE}
+options:
+  MONGO_INITDB_ROOT_USERNAME:
+    type: string
+    default: monoceros
+    surface: env
+  MONGO_INITDB_ROOT_PASSWORD:
+    type: string
+    default: monoceros
+    surface: env
+  MONGO_INITDB_DATABASE:
+    type: string
+    default: monoceros
+    surface: env

package/bundled-components/services/mysql/component.yml

@@ -22,13 +22,15 @@ service:
     timeout: 5s
     retries: 5
   vscodeExtensions: [cweijan.vscode-database-client2]
+  client:
+    apt: [default-mysql-client]
   connectionEnv:
-    MYSQL_HOST: ${host}
-    MYSQL_PORT: ${port}
-    MYSQL_USER: root
-    MYSQL_PASSWORD: ${MYSQL_ROOT_PASSWORD}
-    MYSQL_DATABASE: ${MYSQL_DATABASE}
-    DATABASE_URL: mysql://root:${MYSQL_ROOT_PASSWORD}@${host}:${port}/${MYSQL_DATABASE}
+    URL: mysql://root:${MYSQL_ROOT_PASSWORD}@${host}:${port}/${MYSQL_DATABASE}
+    HOST: ${host}
+    PORT: ${port}
+    USER: root
+    PASSWORD: ${MYSQL_ROOT_PASSWORD}
+    DB: ${MYSQL_DATABASE}
 options:
   MYSQL_ROOT_PASSWORD:
     type: string

package/bundled-components/services/pgvector/component.yml

@@ -0,0 +1,36 @@
+id: pgvector
+category: service
+displayName: pgvector (PostgreSQL + vectors)
+description: 'PostgreSQL with the pgvector extension for embeddings / vector search — a drop-in Postgres. Reachable in-container as host `pgvector`. Enable the extension once with `CREATE EXTENSION vector;` (or in your migration).'
+service:
+  image: pgvector/pgvector:pg18
+  defaultPort: 5432
+  dataMount: /var/lib/postgresql
+  healthcheck:
+    test: [CMD, pg_isready, -U, '${POSTGRES_USER}', -d, '${POSTGRES_DB}']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+  vscodeExtensions: [cweijan.vscode-database-client2]
+  client:
+    apt: [postgresql-client]
+  connectionEnv:
+    URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
+    HOST: ${host}
+    PORT: ${port}
+    USER: ${POSTGRES_USER}
+    PASSWORD: ${POSTGRES_PASSWORD}
+    DB: ${POSTGRES_DB}
+options:
+  POSTGRES_USER:
+    type: string
+    default: monoceros
+    surface: env
+  POSTGRES_PASSWORD:
+    type: string
+    default: monoceros
+    surface: env
+  POSTGRES_DB:
+    type: string
+    default: monoceros
+    surface: env

package/bundled-components/services/postgres/component.yml

@@ -12,13 +12,15 @@ service:
     timeout: 5s
     retries: 5
   vscodeExtensions: [cweijan.vscode-database-client2]
+  client:
+    apt: [postgresql-client]
   connectionEnv:
-    PGHOST: ${host}
-    PGPORT: ${port}
-    PGUSER: ${POSTGRES_USER}
-    PGPASSWORD: ${POSTGRES_PASSWORD}
-    PGDATABASE: ${POSTGRES_DB}
-    DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
+    URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
+    HOST: ${host}
+    PORT: ${port}
+    USER: ${POSTGRES_USER}
+    PASSWORD: ${POSTGRES_PASSWORD}
+    DB: ${POSTGRES_DB}
 options:
   POSTGRES_USER:
     type: string

package/bundled-components/services/redis/component.yml

@@ -12,5 +12,9 @@ service:
     timeout: 5s
     retries: 5
   vscodeExtensions: [cweijan.vscode-database-client2]
+  client:
+    apt: [redis-tools]
   connectionEnv:
-    REDIS_URL: redis://${host}:${port}
+    URL: redis://${host}:${port}
+    HOST: ${host}
+    PORT: ${port}

package/bundled-components/services/rustfs/component.yml

@@ -0,0 +1,28 @@
+id: rustfs
+category: service
+displayName: RustFS
+description: 'S3-compatible object storage (MinIO-compatible API). S3 API on `rustfs:9000`; web console on 9001 (enable with `RUSTFS_CONSOLE_ENABLE=true`, reach via `monoceros tunnel <name> rustfs:9001`).'
+service:
+  image: rustfs/rustfs:latest
+  defaultPort: 9000
+  dataMount: /data
+  healthcheck:
+    test: [CMD, curl, -f, 'http://localhost:9000/minio/health/live']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+  connectionEnv:
+    URL: http://${host}:${port}
+    HOST: ${host}
+    PORT: ${port}
+    ACCESS_KEY: ${RUSTFS_ACCESS_KEY}
+    SECRET_KEY: ${RUSTFS_SECRET_KEY}
+options:
+  RUSTFS_ACCESS_KEY:
+    type: string
+    default: rustfsadmin
+    surface: env
+  RUSTFS_SECRET_KEY:
+    type: string
+    default: rustfsadmin
+    surface: env

package/dist/bin.js

@@ -203,7 +203,13 @@ var init_schema = __esm({
       ).optional(),
       healthcheck: ServiceHealthcheckSchema.optional(),
       restart: z.enum(SERVICE_RESTART_VALUES).optional(),
-      command: z.string().optional()
+      command: z.string().optional(),
+      // Connection-env templates keyed by logical SUFFIX (URL/HOST/PORT/USER/
+      // PASSWORD/DB). Baked in by `expandCuratedService`; emitted into the
+      // workspace as `<UPPER(name)>_<SUFFIX>` at apply (ADR 0021). `${host}`/
+      // `${port}`/`${<OPTION>}` are render tokens, NOT `.env` placeholders, and
+      // are left untouched by `interpolateServices`.
+      connectionEnv: z.record(z.string(), z.string()).optional()
     });
     ExternalServicesSchema = z.object({
       postgres: z.string().regex(
@@ -261,6 +267,18 @@ var init_schema = __esm({
       git: z.object({
         user: GitUserSchema.optional()
       }).optional()
+    }).superRefine((cfg, ctx) => {
+      const seen = /* @__PURE__ */ new Set();
+      cfg.services.forEach((svc, i) => {
+        if (seen.has(svc.name)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["services", i, "name"],
+            message: `Duplicate service name '${svc.name}'. Service names must be unique (use \`add-service \u2026 --as <name>\` to add a second instance of the same image).`
+          });
+        }
+        seen.add(svc.name);
+      });
     });
   }
 });
@@ -711,15 +729,30 @@ var init_descriptor = __esm({
       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}
+       * Connection env injected into the WORKSPACE container so the app / agent
+       * can reach this service without hardcoding anything. Keyed by logical
+       * SUFFIX → template; emitted at apply as `<UPPER(name)>_<SUFFIX>` per
+       * service instance (ADR 0021), e.g. suffix `URL` on a service named
+       * `postgres` → `POSTGRES_URL`. Tokens: `${host}` (the service's instance
+       * name), `${port}` (its port, falling back to `defaultPort`), and
+       * `${<OPTION>}` (its own option values, e.g. `${POSTGRES_USER}`). Example:
+       *   URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
+       *   HOST: ${host}
        */
       connectionEnv: z2.record(z2.string(), z2.string()).optional(),
+      /**
+       * CLI client tool(s) for this service, installed into the WORKSPACE
+       * container at apply so the dev/agent can use them (the service runs in its
+       * own container; the workspace has no client otherwise). `apt` packages are
+       * merged into the workspace's apt-packages feature (build-time, cached);
+       * `npm` packages are installed globally in post-create (guarded, so it's a
+       * no-op once present). E.g. postgres → apt `postgresql-client` (`psql`),
+       * mongodb → npm `mongosh`. See ADR 0020.
+       */
+      client: z2.object({
+        apt: z2.array(z2.string()).optional(),
+        npm: z2.array(z2.string()).optional()
+      }).optional(),
       vscodeExtensions: z2.array(z2.string()).optional()
     });
     PersistentHomeFileSchema = z2.object({
@@ -2149,7 +2182,8 @@ function resolveService(entry2) {
     volumes: entry2.volumes ? [...entry2.volumes] : [],
     ...entry2.healthcheck ? { healthcheck: entry2.healthcheck } : {},
     ...entry2.restart ? { restart: entry2.restart } : {},
-    ...entry2.command ? { command: entry2.command } : {}
+    ...entry2.command ? { command: entry2.command } : {},
+    ...entry2.connectionEnv ? { connectionEnv: { ...entry2.connectionEnv } } : {}
   };
 }
 function isCuratedService(name) {
@@ -2173,6 +2207,10 @@ function expandCuratedService(name) {
     } : {},
     ...def.dataMount ? { volumes: [`data:${def.dataMount}`] } : {},
     ...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,
+    // and `serviceConnectionEnv` prefixes by the instance's current name.
+    ...def.connectionEnv ? { connectionEnv: { ...def.connectionEnv } } : {},
     restart: "unless-stopped"
   };
 }
@@ -2183,21 +2221,40 @@ function curatedServiceEnvDefaults(name) {
 function serviceConnectionEnv(services) {
   const env = {};
   for (const svc of services) {
-    const def = SERVICE_CATALOG[svc.name];
-    if (!def?.connectionEnv) continue;
+    const conn = svc.connectionEnv ?? SERVICE_CATALOG[svc.name]?.connectionEnv;
+    if (!conn || Object.keys(conn).length === 0) continue;
+    const prefix = svc.name.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
     const host = svc.name;
-    const port = String(svc.port ?? def.defaultPort);
+    const port = svc.port !== void 0 ? String(svc.port) : "";
     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);
+    for (const [suffix, template] of Object.entries(conn)) {
+      env[`${prefix}_${suffix}`] = fill(template);
     }
   }
   return env;
 }
+function serviceClientAptPackages(services) {
+  const pkgs = /* @__PURE__ */ new Set();
+  for (const svc of services) {
+    for (const pkg of SERVICE_CATALOG[svc.name]?.client?.apt ?? []) {
+      pkgs.add(pkg);
+    }
+  }
+  return [...pkgs].sort();
+}
+function serviceClientNpmPackages(services) {
+  const pkgs = /* @__PURE__ */ new Set();
+  for (const svc of services) {
+    for (const pkg of SERVICE_CATALOG[svc.name]?.client?.npm ?? []) {
+      pkgs.add(pkg);
+    }
+  }
+  return [...pkgs].sort();
+}
 function deriveServiceName(image) {
   const lastSegment = image.split("/").pop() ?? image;
   const noTag = lastSegment.split("@")[0].split(":")[0];
@@ -2257,7 +2314,8 @@ var init_catalog = __esm({
           ...svc.dataMount ? { dataMount: svc.dataMount } : {},
           defaultPort: svc.defaultPort,
           ...svc.vscodeExtensions ? { vscodeExtensions: svc.vscodeExtensions } : {},
-          ...svc.connectionEnv ? { connectionEnv: svc.connectionEnv } : {}
+          ...svc.connectionEnv ? { connectionEnv: svc.connectionEnv } : {},
+          ...svc.client ? { client: svc.client } : {}
         };
         return [key, entry2];
       })
@@ -2774,10 +2832,16 @@ function resolveFeatures(opts) {
       persistentHomeFiles: []
     });
   }
-  if (opts.aptPackages && opts.aptPackages.length > 0) {
+  const aptPackages = [
+    .../* @__PURE__ */ new Set([
+      ...opts.aptPackages ?? [],
+      ...serviceClientAptPackages(opts.services)
+    ])
+  ].sort();
+  if (aptPackages.length > 0) {
     resolved.push({
       devcontainerKey: "ghcr.io/devcontainers-contrib/features/apt-packages:1",
-      options: { packages: opts.aptPackages.join(",") },
+      options: { packages: aptPackages.join(",") },
       persistentHomePaths: [],
       persistentHomeFiles: []
     });
@@ -3171,6 +3235,18 @@ function buildPostCreateScript(opts) {
     "  pnpm install",
     "fi"
   ];
+  const clientNpm = serviceClientNpmPackages(opts.services);
+  if (clientNpm.length > 0) {
+    lines.push(
+      "",
+      "# CLI clients for the curated services (global npm installs)."
+    );
+    for (const pkg of clientNpm) {
+      lines.push(
+        `command -v ${pkg} >/dev/null 2>&1 || npm install -g --no-audit --no-fund ${pkg}`
+      );
+    }
+  }
   if (opts.installUrls && opts.installUrls.length > 0) {
     lines.push(
       "",
@@ -5405,29 +5481,30 @@ function generateAgentsMd(input) {
     }
     lines.push("");
     const connEnv = serviceConnectionEnv(input.services);
-    if (Object.keys(connEnv).length > 0) {
+    const connUrlKeys = Object.keys(connEnv).filter((k) => k.endsWith("_URL"));
+    if (connUrlKeys.length > 0) {
       lines.push(
-        "Connection details for the curated services above are already set as",
-        "environment variables in this container. Read them from the",
-        "environment \u2014 do not ask the user for credentials, and do not",
-        "hardcode them:"
+        "Connection details for the curated services above are set as",
+        "environment variables in this container \u2014 one set per service, prefixed",
+        "with the (uppercased) service name. Read them from the environment; do",
+        "not ask the user for credentials and do not hardcode them. The URLs:"
       );
       lines.push("");
-      if (connEnv.DATABASE_URL !== void 0) {
-        lines.push(
-          "- `DATABASE_URL` \u2014 the SQL database. Engine-specific variables are",
-          "  set too (`PGHOST`/`PGPORT`/`PGUSER`/`PGPASSWORD`/`PGDATABASE` for",
-          "  Postgres, `MYSQL_*` for MySQL)."
-        );
-      }
-      if (connEnv.REDIS_URL !== void 0) {
-        lines.push("- `REDIS_URL` \u2014 Redis.");
+      for (const k of connUrlKeys) {
+        lines.push(`- \`${k}\``);
       }
       lines.push("");
       lines.push(
-        "These are dev-only defaults for the local container, fine to use",
-        "directly. Prefer reading the variable (e.g. `process.env.DATABASE_URL`)",
-        "over copying its value into code."
+        "Each service also exposes `<SERVICE>_HOST`, `<SERVICE>_PORT` and, for SQL",
+        "databases, `<SERVICE>_USER` / `<SERVICE>_PASSWORD` / `<SERVICE>_DB`. These",
+        "are dev-only defaults for the local container, fine to read directly."
+      );
+      lines.push("");
+      lines.push(
+        "There is deliberately **no** bare `DATABASE_URL` (multiple databases",
+        "would collide on it). If a framework or tool defaults to `DATABASE_URL`,",
+        "set it in the project's `.env` to the right service URL, e.g.",
+        "`DATABASE_URL=$POSTGRES_URL`."
       );
     }
     const hasCustom = input.services.some((s) => !isCuratedService(s.name));
@@ -7233,7 +7310,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.24.2" : "dev";
+    CLI_VERSION = true ? "1.26.0" : "dev";
   }
 });