@motherbase/cli 0.2.5 → 0.2.8

package/src/commands/local.js

@@ -1,273 +1,371 @@
-'use strict';
-
-// Local self-host workflow: thin wrappers over `docker compose`, plus `init`
-// scaffolding.
-//
-// `init` used to write a `.env` and nothing else, which left a directory that
-// `motherbase start` could not start: `docker compose up` in a folder with no
-// compose file is a raw Docker error, and that was the first thing a new user
-// saw. It now writes a self-contained stack that runs.
-
-const crypto = require('crypto');
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-const COMPOSE_FILE = 'docker-compose.yml';
-const ENV_FILE = '.env';
-
-// Where the images are built from when the caller has no checkout. Docker
-// Compose accepts a git URL as a build context, so a scaffolded directory needs
-// nothing but Docker: no clone, no registry, no published image. The first `up`
-// pays for the build; every one after that is cached.
-const DEFAULT_REPO = 'https://github.com/JulienGuinot/BoilerPlate-Backend.git';
-const DEFAULT_REF = 'master';
-
-function dockerCompose(composeArgs) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('docker', ['compose', ...composeArgs], { stdio: 'inherit', windowsHide: true });
-    child.on('error', err => reject(new CliError(`failed to run docker: ${err.message}`)));
-    child.on('close', code => (code === 0 ? resolve() : reject(new CliError(`docker compose exited with code ${code}`))));
-  });
-}
-
-/**
- * Refuse to run compose from a directory that has no stack, and say what to do.
- * Without this the user gets Docker's own "no configuration file provided",
- * which does not mention `motherbase init`.
- */
-function assertStack(ctx) {
-  const file = path.join(ctx.cwd, COMPOSE_FILE);
-  if (!fs.existsSync(file)) {
-    throw new CliError(
-      `no ${COMPOSE_FILE} here. Run \`motherbase init\` first, or cd into a directory that has one.`,
-    );
-  }
-}
-
-const hex = n => crypto.randomBytes(n).toString('hex');
-const b64 = n => crypto.randomBytes(n).toString('base64');
-
-function renderEnv(context) {
-  return [
-    '# Generated by `motherbase init`. Secrets below are unique to this install.',
-    '# Keep this file out of version control.',
-    '',
-    `PORT=${context.port}`,
-    `BASE_HOST=localhost:${context.port}`,
-    'NODE_ENV=production',
-    '',
-    '# Secrets. Regenerating any of these invalidates what it protects:',
-    '# JWT_SECRET signs sessions, CONFIG_ENCRYPTION_KEY encrypts Studio-managed',
-    '# secrets (SMTP, OAuth credentials) at rest.',
-    `JWT_SECRET=${hex(32)}`,
-    `CONFIG_ENCRYPTION_KEY=${b64(32)}`,
-    `POSTGRES_PASSWORD=${hex(16)}`,
-    `S3_ACCESS_KEY_ID=${hex(8)}`,
-    `S3_SECRET_ACCESS_KEY=${hex(20)}`,
-    '',
-    'S3_BUCKET=uploads',
-    'S3_PUBLIC_BUCKET=public',
-    'S3_REGION=us-east-1',
-    '',
-    '# Host ports. Change these if something already listens on them.',
-    `POSTGRES_PORT=${context.postgresPort}`,
-    'MINIO_PORT=59000',
-    'MINIO_CONSOLE_PORT=59001',
-    '',
-    '# First operator account, created on first boot.',
-    `SEED_ADMIN_EMAIL=${context.adminEmail}`,
-    `SEED_ADMIN_PASSWORD=${context.adminPassword}`,
-    '',
-  ].join('\n');
-}
-
-function renderCompose(context) {
-  const buildContext = `${context.repo}#${context.ref}`;
-  return `# Generated by \`motherbase init\`.
-#
-# Images are built from the public repository, so this directory needs Docker and
-# nothing else: no checkout, no registry login. The first \`up\` builds them, which
-# takes a few minutes; after that the layers are cached.
-#
-# Working from a checkout instead? Replace both \`context:\` values with the path
-# to it and the build becomes local and incremental.
-services:
-  db:
-    build:
-      context: ${buildContext}
-      dockerfile: deploy/postgres.Dockerfile
-    command: ['postgres', '-c', 'shared_preload_libraries=pg_cron,pg_stat_statements', '-c', 'cron.database_name=app']
-    restart: unless-stopped
-    environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD}
-      POSTGRES_DB: app
-    ports:
-      # Loopback only: reachable by psql, Prisma, Drizzle or a BI client on this
-      # machine, and by nothing on the network.
-      - '127.0.0.1:\${POSTGRES_PORT:-55432}:5432'
-    volumes:
-      - db_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U postgres']
-      interval: 5s
-      timeout: 5s
-      retries: 10
-
-  minio:
-    image: alpine/minio:RELEASE.2025-10-15T17-29-55Z
-    restart: unless-stopped
-    user: "0:0"
-    command: server /data --console-address ":9001"
-    environment:
-      MINIO_ROOT_USER: \${S3_ACCESS_KEY_ID}
-      MINIO_ROOT_PASSWORD: \${S3_SECRET_ACCESS_KEY}
-    ports:
-      - '127.0.0.1:\${MINIO_PORT:-59000}:9000'
-      - '127.0.0.1:\${MINIO_CONSOLE_PORT:-59001}:9001'
-    volumes:
-      - minio_data:/data
-    healthcheck:
-      test: ['CMD-SHELL', 'wget -qO- http://localhost:9000/minio/health/live >/dev/null']
-      interval: 5s
-      timeout: 5s
-      retries: 10
-
-  # One-shot: a private bucket and a separate anonymously-downloadable one.
-  createbuckets:
-    image: quay.io/minio/mc:RELEASE.2025-08-13T08-35-41Z
-    depends_on:
-      minio:
-        condition: service_healthy
-    entrypoint: >
-      /bin/sh -c "
-      mc alias set local http://minio:9000 \${S3_ACCESS_KEY_ID} \${S3_SECRET_ACCESS_KEY};
-      mc mb --ignore-existing local/\${S3_BUCKET:-uploads};
-      mc anonymous set none local/\${S3_BUCKET:-uploads};
-      mc mb --ignore-existing local/\${S3_PUBLIC_BUCKET:-public};
-      mc anonymous set download local/\${S3_PUBLIC_BUCKET:-public};
-      echo 'buckets ready';
-      "
-
-  api:
-    build:
-      context: ${buildContext}
-    restart: unless-stopped
-    depends_on:
-      db:
-        condition: service_healthy
-      minio:
-        condition: service_healthy
-      createbuckets:
-        condition: service_completed_successfully
-    env_file:
-      - ${ENV_FILE}
-    # Container-internal wiring, overriding the localhost values in .env so the
-    # same file works for both host tooling and the containers.
-    environment:
-      NODE_ENV: production
-      PORT: 5001
-      DATABASE_URL: postgresql://postgres:\${POSTGRES_PASSWORD}@db:5432/app?schema=public
-      STORAGE_DRIVER: s3
-      S3_ENDPOINT: http://minio:9000
-      DB_PORT: \${POSTGRES_PORT:-55432}
-    ports:
-      - '\${PORT:-5001}:5001'
-
-volumes:
-  db_data:
-  minio_data:
-`;
-}
-
-const init = {
-  summary: 'Scaffold a runnable local stack (compose file, .env, generated secrets)',
-  usage: 'motherbase init [dir] [--port 5001] [--repo URL] [--ref BRANCH] [--force]',
-  async run(ctx, args, flags = {}) {
-    const dir = args[0] || '.';
-    const target = path.resolve(ctx.cwd, dir);
-    fs.mkdirSync(target, { recursive: true });
-
-    const context = {
-      port: Number(flags.port) || 5001,
-      postgresPort: Number(flags['postgres-port']) || 55432,
-      repo: flags.repo || DEFAULT_REPO,
-      ref: flags.ref || DEFAULT_REF,
-      adminEmail: flags['admin-email'] || 'admin@example.com',
-      // Generated, never a placeholder: a scaffold that ships `change-me` is a
-      // scaffold that reaches production with `change-me`.
-      adminPassword: flags['admin-password'] || crypto.randomBytes(12).toString('base64url'),
-    };
-
-    const written = [];
-    const skipped = [];
-    for (const [name, render] of [[ENV_FILE, renderEnv], [COMPOSE_FILE, renderCompose]]) {
-      const file = path.join(target, name);
-      // Never silently overwrite: .env holds the only copy of secrets that
-      // existing data was encrypted with.
-      if (fs.existsSync(file) && !flags.force) {
-        skipped.push(name);
-        continue;
-      }
-      fs.writeFileSync(file, render(context), name === ENV_FILE ? { mode: 0o600 } : undefined);
-      written.push(name);
-    }
-
-    ui.success(`Initialized Motherbase project at ${target}`);
-    if (written.length) ui.info(`wrote ${written.join(', ')}`);
-    if (skipped.length) {
-      ui.warn(`kept existing ${skipped.join(', ')} (use --force to overwrite, which discards their secrets)`);
-    }
-    if (written.includes(ENV_FILE)) {
-      ui.print('');
-      ui.print(`  Studio:   http://localhost:${context.port}`);
-      ui.print(`  Sign in:  ${context.adminEmail} / ${context.adminPassword}`);
-      ui.print('');
-      ui.print('  Next:');
-      if (dir !== '.') ui.print(`    cd ${dir}`);
-      ui.print('    motherbase start        # first run builds the images, give it a few minutes');
-      ui.print('');
-    }
-  },
-};
-
-const start = {
-  summary: 'Start the local docker compose stack',
-  usage: 'motherbase start',
-  async run(ctx) {
-    assertStack(ctx);
-    await dockerCompose(['up', '-d']);
-  },
-};
-
-const stop = {
-  summary: 'Stop the local docker compose stack',
-  usage: 'motherbase stop',
-  async run(ctx) {
-    assertStack(ctx);
-    await dockerCompose(['down']);
-  },
-};
-
-const deploy = {
-  summary: 'Rebuild and start the local docker compose stack',
-  usage: 'motherbase deploy',
-  async run(ctx) {
-    assertStack(ctx);
-    await dockerCompose(['up', '-d', '--build']);
-  },
-};
-
-const logs = {
-  summary: 'Follow logs from the local docker compose stack',
-  usage: 'motherbase logs [service...]',
-  async run(ctx, args) {
-    assertStack(ctx);
-    await dockerCompose(['logs', '-f', ...args]);
-  },
-};
-
-module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose };
+'use strict';
+
+// Local self-host workflow: thin wrappers over `docker compose`, plus `init`
+// scaffolding.
+//
+// `init` used to write a `.env` and nothing else, which left a directory that
+// `motherbase start` could not start: `docker compose up` in a folder with no
+// compose file is a raw Docker error, and that was the first thing a new user
+// saw. It now writes a self-contained stack that runs.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const ui = require('../ui');
+const { CliError } = require('../context');
+
+const COMPOSE_FILE = 'docker-compose.yml';
+const ENV_FILE = '.env';
+
+// By default the stack runs the images CI publishes after every green build of
+// the default branch, so `start` pulls instead of compiling. Building from a git
+// context used to be the default and could not work on a clean machine: the API
+// image derives from a base image (motherbase-deps) that only the repository's
+// own build script produces.
+const DEFAULT_REGISTRY = 'ghcr.io/julienguinot';
+const DEFAULT_TAG = 'latest';
+// Build-from-source mode, kept for --repo / --ref. It needs motherbase-deps:1.0.0
+// built locally first (see the compose header it writes).
+const DEFAULT_REPO = 'https://github.com/JulienGuinot/BoilerPlate-Backend.git';
+const DEFAULT_REF = 'master';
+
+function dockerCompose(composeArgs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('docker', ['compose', ...composeArgs], { stdio: 'inherit', windowsHide: true });
+    child.on('error', err => reject(new CliError(`failed to run docker: ${err.message}`)));
+    child.on('close', code => (code === 0 ? resolve() : reject(new CliError(`docker compose exited with code ${code}`))));
+  });
+}
+
+/**
+ * Refuse to run compose from a directory that has no stack, and say what to do.
+ * Without this the user gets Docker's own "no configuration file provided",
+ * which does not mention `motherbase init`.
+ */
+function assertStack(ctx) {
+  const file = path.join(ctx.cwd, COMPOSE_FILE);
+  if (!fs.existsSync(file)) {
+    throw new CliError(
+      `no ${COMPOSE_FILE} here. Run \`motherbase init\` first, or cd into a directory that has one.`,
+    );
+  }
+}
+
+const hex = n => crypto.randomBytes(n).toString('hex');
+const b64 = n => crypto.randomBytes(n).toString('base64');
+
+function renderEnv(context) {
+  return [
+    '# Generated by `motherbase init`. Secrets below are unique to this install.',
+    '# Keep this file out of version control.',
+    '',
+    `PORT=${context.port}`,
+    `BASE_HOST=localhost:${context.port}`,
+    'NODE_ENV=production',
+    '',
+    '# Origins allowed to call this API from a browser. Required: the API refuses',
+    '# to boot in production without an explicit list. Comma-separated.',
+    `CORS_ORIGINS=${context.corsOrigins}`,
+    '',
+    '# Raw SQL over the admin API (`motherbase db sql`). This stack has no Console',
+    '# in front of it, so the admin API is the only way in.',
+    'CONSOLE_SQL_ENABLED=true',
+    '',
+    '# Secrets. Regenerating any of these invalidates what it protects:',
+    '# JWT_SECRET signs sessions, CONFIG_ENCRYPTION_KEY encrypts Studio-managed',
+    '# secrets (SMTP, OAuth credentials) at rest.',
+    `JWT_SECRET=${hex(32)}`,
+    `CONFIG_ENCRYPTION_KEY=${b64(32)}`,
+    `POSTGRES_PASSWORD=${hex(16)}`,
+    `S3_ACCESS_KEY_ID=${hex(8)}`,
+    `S3_SECRET_ACCESS_KEY=${hex(20)}`,
+    `EDGE_RUNTIME_TOKEN=${hex(24)}`,
+    '',
+    'S3_BUCKET=uploads',
+    'S3_PUBLIC_BUCKET=public',
+    'S3_REGION=us-east-1',
+    '',
+    '# Host ports. Change these if something already listens on them.',
+    `POSTGRES_PORT=${context.postgresPort}`,
+    'MINIO_PORT=59000',
+    'MINIO_CONSOLE_PORT=59001',
+    '',
+    '# Operator account. Created (or reset to these values) by running the seed',
+    '# once: docker compose exec api node apps/server/dist/prisma/seed.js',
+    `SEED_ADMIN_EMAIL=${context.adminEmail}`,
+    `SEED_ADMIN_PASSWORD=${context.adminPassword}`,
+    '',
+    ...(context.mode === 'image'
+      ? [
+          '# Published images this stack runs. Pin MOTHERBASE_TAG to a sha-<commit> tag',
+          '# to stop `docker compose pull` from moving it.',
+          `MOTHERBASE_REGISTRY=${context.registry}`,
+          `MOTHERBASE_TAG=${context.tag}`,
+          '',
+        ]
+      : []),
+  ].join('\n');
+}
+
+function renderCompose(context) {
+  const buildContext = `${context.repo}#${context.ref}`;
+  const fromImages = context.mode === 'image';
+  const image = name => `\${MOTHERBASE_REGISTRY:-${DEFAULT_REGISTRY}}/motherbase-${name}:\${MOTHERBASE_TAG:-${DEFAULT_TAG}}`;
+  const source = (dockerfile, indent = '    ') => fromImages
+    ? ''
+    : `${indent}build:\n${indent}  context: ${buildContext}\n${dockerfile ? `${indent}  dockerfile: ${dockerfile}\n` : ''}`;
+  const header = fromImages
+    ? `# Runs the images published for Motherbase (MOTHERBASE_REGISTRY / MOTHERBASE_TAG
+# in .env), so this directory needs Docker and nothing else. \`docker compose pull\`
+# then \`motherbase start\` updates it.`
+    : `# Builds from ${buildContext}. The API image derives from motherbase-deps:1.0.0,
+# which Compose cannot build: in a checkout of that repository, run
+#   docker build -t motherbase-deps:1.0.0 -f deploy/deps.Dockerfile .
+# once first. Point every \`context:\` value at that checkout to build locally.`;
+  return `# Generated by \`motherbase init\`.
+#
+${header}
+services:
+  db:
+${fromImages ? `    image: ${image('postgres')}\n` : source('deploy/postgres.Dockerfile')}    command: ['postgres', '-c', 'shared_preload_libraries=pg_cron,pg_stat_statements', '-c', 'cron.database_name=app']
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD}
+      POSTGRES_DB: app
+    ports:
+      # Loopback only: reachable by psql, Prisma, Drizzle or a BI client on this
+      # machine, and by nothing on the network.
+      - '127.0.0.1:\${POSTGRES_PORT:-55432}:5432'
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  minio:
+    image: alpine/minio:RELEASE.2025-10-15T17-29-55Z
+    restart: unless-stopped
+    user: "0:0"
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: \${S3_ACCESS_KEY_ID}
+      MINIO_ROOT_PASSWORD: \${S3_SECRET_ACCESS_KEY}
+    ports:
+      - '127.0.0.1:\${MINIO_PORT:-59000}:9000'
+      - '127.0.0.1:\${MINIO_CONSOLE_PORT:-59001}:9001'
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://localhost:9000/minio/health/live >/dev/null']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # One-shot: a private bucket and a separate anonymously-downloadable one.
+  createbuckets:
+    # Not quay.io/minio/mc: that path now requires a registry login.
+    image: bitnamilegacy/minio-client:2025.5.21
+    # mc keeps its config under $HOME; the image's HOME (/) is not writable.
+    environment:
+      HOME: /tmp
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 \${S3_ACCESS_KEY_ID} \${S3_SECRET_ACCESS_KEY};
+      mc mb --ignore-existing local/\${S3_BUCKET:-uploads};
+      mc anonymous set none local/\${S3_BUCKET:-uploads};
+      mc mb --ignore-existing local/\${S3_PUBLIC_BUCKET:-public};
+      mc anonymous set download local/\${S3_PUBLIC_BUCKET:-public};
+      echo 'buckets ready';
+      "
+
+  # Runs edge functions. Only the API shares its network, so function code has
+  # no route to Postgres or MinIO.
+  edge-runtime:
+${fromImages ? `    image: ${image('edge-runtime')}\n` : source('deploy/edge-runtime.Dockerfile')}    restart: unless-stopped
+    environment:
+      EDGE_RUNTIME_PORT: 9000
+      DENO_DIR: /tmp/deno-dir
+      EDGE_RUNTIME_TOKEN: \${EDGE_RUNTIME_TOKEN:?EDGE_RUNTIME_TOKEN is required}
+      EDGE_ALLOWED_INTERNAL_ORIGINS: http://api:5001
+    networks:
+      - edge
+    read_only: true
+    tmpfs:
+      - /tmp
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+
+  api:
+${fromImages ? `    image: ${image('api')}\n` : source(null)}    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      createbuckets:
+        condition: service_completed_successfully
+      edge-runtime:
+        condition: service_started
+    env_file:
+      - ${ENV_FILE}
+    # Container-internal wiring, overriding the localhost values in .env so the
+    # same file works for both host tooling and the containers.
+    environment:
+      NODE_ENV: production
+      PORT: 5001
+      DATABASE_URL: postgresql://postgres:\${POSTGRES_PASSWORD}@db:5432/app?schema=public
+      STORAGE_DRIVER: s3
+      S3_ENDPOINT: http://minio:9000
+      # Signed URLs are fetched from this machine, where MinIO is published on
+      # MINIO_PORT, not at its container address.
+      S3_PRESIGN_ENDPOINT: http://localhost:\${MINIO_PORT:-59000}
+      DB_PORT: \${POSTGRES_PORT:-55432}
+      EDGE_RUNTIME_URL: http://edge-runtime:9000
+      EDGE_RUNTIME_CALLBACK_URL: http://api:5001
+    ports:
+      - '\${PORT:-5001}:5001'
+    networks:
+      - default
+      - edge
+
+volumes:
+  db_data:
+  minio_data:
+
+networks:
+  edge:
+`;
+}
+
+// Values that end up unquoted in `.env` and in the compose `context:` line. A
+// newline would inject a second variable or key; the character sets below are
+// what these fields legitimately contain.
+const INIT_FLAG_PATTERNS = {
+  'admin-email': /^[^\s"'`$#\\]+$/,
+  'admin-password': /^[^\s"'`$#\\]+$/,
+  'cors-origins': /^[\w.:/,*-]+$/,
+  repo: /^[\w.:/@~+-]+$/,
+  ref: /^[\w./-]+$/,
+  registry: /^[\w.:/-]+$/,
+  tag: /^[\w.-]+$/,
+};
+
+function validateInitFlags(flags) {
+  for (const [name, pattern] of Object.entries(INIT_FLAG_PATTERNS)) {
+    const value = flags[name];
+    if (value === undefined) continue;
+    if (typeof value !== 'string' || !pattern.test(value)) {
+      throw new CliError(`Invalid --${name}: contains whitespace, quotes or other unsafe characters`);
+    }
+  }
+}
+
+const init = {
+  summary: 'Scaffold a runnable local stack (compose file, .env, generated secrets)',
+  usage: 'motherbase init [dir] [--port 5001] [--cors-origins http://localhost:3000] [--tag latest] [--repo URL --ref BRANCH] [--force]',
+  async run(ctx, args, flags = {}) {
+    validateInitFlags(flags);
+    const dir = args[0] || '.';
+    const target = path.resolve(ctx.cwd, dir);
+    fs.mkdirSync(target, { recursive: true });
+
+    const context = {
+      port: Number(flags.port) || 5001,
+      postgresPort: Number(flags['postgres-port']) || 55432,
+      corsOrigins: flags['cors-origins'] || 'http://localhost:3000',
+      // --repo / --ref ask for a source build; anything else runs published images.
+      mode: flags.repo || flags.ref ? 'source' : 'image',
+      registry: flags.registry || DEFAULT_REGISTRY,
+      tag: flags.tag || DEFAULT_TAG,
+      repo: flags.repo || DEFAULT_REPO,
+      ref: flags.ref || DEFAULT_REF,
+      adminEmail: flags['admin-email'] || 'admin@example.com',
+      // Generated, never a placeholder: a scaffold that ships `change-me` is a
+      // scaffold that reaches production with `change-me`.
+      adminPassword: flags['admin-password'] || crypto.randomBytes(12).toString('base64url'),
+    };
+
+    const written = [];
+    const skipped = [];
+    for (const [name, render] of [[ENV_FILE, renderEnv], [COMPOSE_FILE, renderCompose]]) {
+      const file = path.join(target, name);
+      // Never silently overwrite: .env holds the only copy of secrets that
+      // existing data was encrypted with.
+      if (fs.existsSync(file) && !flags.force) {
+        skipped.push(name);
+        continue;
+      }
+      fs.writeFileSync(file, render(context), name === ENV_FILE ? { mode: 0o600 } : undefined);
+      written.push(name);
+    }
+
+    ui.success(`Initialized Motherbase project at ${target}`);
+    if (written.length) ui.info(`wrote ${written.join(', ')}`);
+    if (skipped.length) {
+      ui.warn(`kept existing ${skipped.join(', ')} (use --force to overwrite, which discards their secrets)`);
+    }
+    if (written.includes(ENV_FILE)) {
+      // No Studio here: Studio is served by the Platform Console, which this
+      // stack does not include. Saying otherwise sent people to a URL that
+      // answers JSON.
+      ui.print('');
+      ui.print(`  API:       http://localhost:${context.port}   (no Studio: that comes with the Platform Console)`);
+      ui.print(`  Operator:  ${context.adminEmail} / ${context.adminPassword}`);
+      ui.print('');
+      ui.print('  Next:');
+      if (dir !== '.') ui.print(`    cd ${dir}`);
+      ui.print(context.mode === 'image'
+        ? '    motherbase start        # pulls the images on first run'
+        : '    motherbase start        # builds the images on first run (see the compose header)');
+      ui.print('    docker compose exec api node apps/server/dist/prisma/seed.js   # once, creates the operator');
+      ui.print('');
+    }
+  },
+};
+
+const start = {
+  summary: 'Start the local docker compose stack',
+  usage: 'motherbase start',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['up', '-d']);
+  },
+};
+
+const stop = {
+  summary: 'Stop the local docker compose stack',
+  usage: 'motherbase stop',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['down']);
+  },
+};
+
+const deploy = {
+  summary: 'Rebuild and start the local docker compose stack',
+  usage: 'motherbase deploy',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['up', '-d', '--build']);
+  },
+};
+
+const logs = {
+  summary: 'Follow logs from the local docker compose stack',
+  usage: 'motherbase logs [service...]',
+  async run(ctx, args) {
+    assertStack(ctx);
+    await dockerCompose(['logs', '-f', ...args]);
+  },
+};
+
+module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose, validateInitFlags };