@motherbase/cli 0.2.3 → 0.2.5

package/src/commands/keys.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// Project API keys. `secrets` next door is a different thing: those are values
+// an edge function reads, these are what a client presents to reach the project.
+
+const api = require('../api');
+const { output, requireArg } = require('./_util');
+
+const TYPES = ['publishable', 'secret'];
+
+const subcommands = {
+  list: {
+    summary: 'List project API keys',
+    usage: 'motherbase keys list',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/api-keys');
+      const keys = (data && data.keys) || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(
+          keys.map(k => ({
+            name: k.name,
+            type: k.type,
+            // A secret key has no stored clear value; the prefix is all there is.
+            key: k.token || `${k.prefix}…`,
+            status: k.revokedAt ? 'revoked' : 'active',
+          })),
+          [
+            { key: 'name', label: 'NAME' },
+            { key: 'type', label: 'TYPE' },
+            { key: 'key', label: 'KEY' },
+            { key: 'status', label: 'STATUS' },
+          ],
+        ),
+      );
+    },
+  },
+  create: {
+    summary: 'Create a key. A secret key is printed once and never again',
+    usage: 'motherbase keys create <NAME> [--type publishable|secret]',
+    async run(ctx, args, flags) {
+      const name = requireArg(args[0], 'NAME');
+      const type = flags.type || 'secret';
+      if (!TYPES.includes(type)) {
+        throw new Error(`--type must be one of: ${TYPES.join(', ')}`);
+      }
+      const data = await api.adminRequest(ctx, 'POST', '/api-keys', { body: { name, type } });
+      output(ctx, data, (d, ui) => {
+        ui.success(`Created ${type} key "${name}"`);
+        ui.print(d.clearToken);
+        if (type === 'secret') {
+          ui.warn('Copy it now. It is stored hashed and cannot be shown again.');
+          ui.warn('It bypasses row level security: keep it server side.');
+        }
+      });
+    },
+  },
+  revoke: {
+    summary: 'Revoke a key by id',
+    usage: 'motherbase keys revoke <ID>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'ID');
+      const data = await api.adminRequest(ctx, 'DELETE', `/api-keys/${encodeURIComponent(id)}`);
+      output(ctx, data, (d, ui) => ui.success(`Revoked key ${d.name || id}`));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Project API keys (publishable and secret)',
+  usage: 'motherbase keys <list|create|revoke> ...',
+  subcommands,
+};

package/src/commands/local.js

@@ -1,15 +1,30 @@
 'use strict';
 
 // Local self-host workflow: thin wrappers over `docker compose`, plus `init`
-// scaffolding. No HTTP, no context resolution required. Ported and extended from
-// the original single-file CLI.
+// 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 });
@@ -18,47 +33,241 @@ function dockerCompose(composeArgs) {
   });
 }
 
+/**
+ * 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 local project directory with a .env',
-  usage: 'motherbase init [dir]',
-  async run(ctx, args) {
+  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 envPath = path.join(target, '.env');
-    if (!fs.existsSync(envPath)) {
-      const example = path.join(ctx.cwd, '.env.example');
-      const template = fs.existsSync(example)
-        ? fs.readFileSync(example, 'utf8')
-        : 'PORT=5001\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/app?schema=public\nJWT_SECRET=change-me\n';
-      fs.writeFileSync(envPath, template);
+
+    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() { await dockerCompose(['up', '-d']); },
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['up', '-d']);
+  },
 };
 
 const stop = {
   summary: 'Stop the local docker compose stack',
   usage: 'motherbase stop',
-  async run() { await dockerCompose(['down']); },
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['down']);
+  },
 };
 
 const deploy = {
   summary: 'Rebuild and start the local docker compose stack',
   usage: 'motherbase deploy',
-  async run() { await dockerCompose(['up', '-d', '--build']); },
+  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) { await dockerCompose(['logs', '-f', ...args]); },
+  async run(ctx, args) {
+    assertStack(ctx);
+    await dockerCompose(['logs', '-f', ...args]);
+  },
 };
 
-module.exports = { init, start, stop, deploy, logs };
+module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose };

package/src/commands/mcp.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// `motherbase mcp`: expose the linked project, and the console's organizations
+// and projects, to an AI agent over the Model Context Protocol.
+//
+// The transport is stdio, which is how an MCP client launches a server: it spawns
+// this process and talks JSON-RPC over its stdin/stdout. Nothing is printed to
+// stdout except protocol messages, so diagnostics go to stderr.
+
+const { serve, toolServer } = require('../mcp/protocol');
+const { buildTools } = require('../mcp/tools');
+const { CliError } = require('../context');
+
+const pkg = require('../../package.json');
+
+/** Whether a `require*()` resolves, without surfacing its error. */
+function reaches(resolve) {
+  try {
+    resolve();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const mcp = {
+  summary: 'Serve the linked project and console to an AI agent over MCP (stdio)',
+  usage: 'motherbase mcp [--write]',
+  async run(ctx, _args, flags = {}) {
+    // Resolve what this session reaches up front. Failing here is a clear CLI
+    // error; failing on the first tool call is an opaque one inside someone's agent.
+    const scope = { project: reaches(() => ctx.requireProject()), console: reaches(() => ctx.requireConsole()) };
+    if (!scope.project && !scope.console) {
+      throw new CliError(
+        'Nothing to serve. Run `motherbase login` for the organization and project tools, and `motherbase link` '
+          + '(or set MOTHERBASE_URL + MOTHERBASE_ADMIN_TOKEN) for the database tools.',
+      );
+    }
+
+    const write = Boolean(flags.write);
+    const tools = buildTools(ctx, { write, ...scope });
+
+    process.stderr.write(
+      `motherbase mcp: ${tools.length} tools, ${write ? 'read and write' : 'read only'}. `
+        + `Project: ${scope.project ? ctx.projectName || ctx.projectId || 'direct' : 'none linked'}. `
+        + `Console: ${scope.console ? ctx.consoleUrl : 'not logged in'}\n`,
+    );
+    if (!write) {
+      process.stderr.write('  Pass --write to expose apply_migration, raw SQL writes, function deploys and project lifecycle.\n');
+    }
+
+    await serve({
+      input: process.stdin,
+      output: process.stdout,
+      handlers: toolServer({ name: 'motherbase', version: pkg.version, tools }),
+      onError: err => process.stderr.write(`motherbase mcp: ${err && err.message ? err.message : err}\n`),
+    });
+  },
+};
+
+module.exports = mcp;

package/src/commands/migrate.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// `motherbase migrate codemod <dir>`: port a Supabase codebase's imports, and
+// report what this SDK does not implement.
+//
+// The rewrite is trivial and the report is the point. `@motherbase/client` is
+// supabase-js shaped, so most files need one import line changed; what breaks a
+// port is the handful of calls that do not exist here, and finding those at
+// build time beats finding them when a user hits that screen.
+//
+// Deliberately a text pass, not an AST pass. A codemod that needs a TypeScript
+// parser needs typescript as a CLI dependency, and the patterns below are
+// import specifiers and method names, which do not need one. The cost is that a
+// match inside a comment or a string is still reported: over-reporting in a
+// list a human reads is the acceptable direction to be wrong in.
+
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./_util');
+const { CliError } = require('../context');
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const SKIP_DIRECTORIES = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.turbo']);
+
+/** Import specifiers that map one to one. */
+const IMPORT_REWRITES = [
+  { from: '@supabase/supabase-js', to: '@motherbase/client' },
+  { from: '@supabase/ssr', to: '@motherbase/ssr' },
+];
+
+/**
+ * Calls this SDK does not implement, and what to do instead.
+ *
+ * Kept short and kept true: every entry here is a row marked `Not supported` in
+ * packages/client/COMPATIBILITY.md. An entry that becomes supported and is left
+ * behind sends people to rewrite working code, so this list is part of the same
+ * change as implementing the feature.
+ */
+const UNSUPPORTED = [
+  {
+    pattern: /\.schema\(\s*['"`](?!public['"`])/g,
+    what: 'schema() on a schema other than public',
+    advice: 'The REST API exposes public only. Move the tables, or expose them through a view or an RPC.',
+  },
+  {
+    pattern: /exchangeCodeForSession\s*\(/g,
+    what: 'auth.exchangeCodeForSession()',
+    advice: 'This install runs the implicit flow. Read the session client side with auth.getSessionFromUrl().',
+  },
+  {
+    pattern: /signInAnonymously\s*\(/g,
+    what: 'auth.signInAnonymously()',
+    advice: 'Not implemented. Create a real user, or gate the feature behind sign-in.',
+  },
+  {
+    pattern: /transform\s*:\s*\{/g,
+    what: 'storage image transform options',
+    advice: 'No image pipeline yet. Store the sizes you need at upload time.',
+  },
+  {
+    pattern: /\.delete\(\s*\)\s*(?![\s\S]{0,200}?\.(eq|neq|in|gt|gte|lt|lte|like|ilike|is|filter|match|or|not)\()/g,
+    what: 'delete() with no filter',
+    advice: 'Refused with 400 on purpose, so a missing filter cannot empty a table. Add a filter.',
+  },
+];
+
+function walk(dir, files = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') && entry.name !== '.') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      walk(full, files);
+    } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/** Line number of an offset, 1-based, for a report a human can act on. */
+function lineAt(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === '\n') line++;
+  return line;
+}
+
+function rewriteImports(text) {
+  let out = text;
+  let changed = 0;
+  for (const { from, to } of IMPORT_REWRITES) {
+    // Only inside a quoted specifier, so a mention in prose is left alone.
+    const pattern = new RegExp(`(['"\`])${from.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\1`, 'g');
+    out = out.replace(pattern, match => {
+      changed++;
+      return match.replace(from, to);
+    });
+  }
+  return { text: out, changed };
+}
+
+function scanUnsupported(text, file) {
+  const findings = [];
+  for (const rule of UNSUPPORTED) {
+    rule.pattern.lastIndex = 0;
+    let match;
+    while ((match = rule.pattern.exec(text)) !== null) {
+      findings.push({ file, line: lineAt(text, match.index), what: rule.what, advice: rule.advice });
+      if (match.index === rule.pattern.lastIndex) rule.pattern.lastIndex++;
+    }
+  }
+  return findings;
+}
+
+const codemod = {
+  summary: 'Rewrite Supabase imports and report what this SDK does not support',
+  usage: 'motherbase migrate codemod <dir> [--write]',
+  async run(ctx, args, flags) {
+    const target = path.resolve(ctx.cwd, args[0] || '.');
+    if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+      throw new CliError(`${target} is not a directory.`);
+    }
+
+    const files = walk(target);
+    const rewritten = [];
+    const findings = [];
+
+    for (const file of files) {
+      const original = fs.readFileSync(file, 'utf8');
+      const { text, changed } = rewriteImports(original);
+      if (changed) {
+        rewritten.push({ file: path.relative(ctx.cwd, file), imports: changed });
+        // Scan the rewritten text so a line number matches what the file will
+        // hold after --write, not what it held before.
+        if (flags.write) fs.writeFileSync(file, text, 'utf8');
+      }
+      findings.push(...scanUnsupported(text, path.relative(ctx.cwd, file)));
+    }
+
+    const result = {
+      root: target,
+      scanned: files.length,
+      rewritten,
+      written: Boolean(flags.write),
+      findings,
+    };
+
+    output(ctx, result, (data, ui) => {
+      const verb = data.written ? 'Rewrote' : 'Would rewrite';
+      ui.info(`Scanned ${data.scanned} files under ${data.root}`);
+      if (data.rewritten.length) {
+        ui.info(`${verb} imports in ${data.rewritten.length} file(s):`);
+        for (const entry of data.rewritten) ui.info(`  ${entry.file} (${entry.imports})`);
+      } else {
+        ui.info('No Supabase imports found.');
+      }
+      if (!data.written && data.rewritten.length) ui.info('Re-run with --write to apply.');
+
+      if (!data.findings.length) {
+        ui.success('No unsupported calls found.');
+        return;
+      }
+      ui.info('');
+      ui.info(`${data.findings.length} call(s) this SDK does not support:`);
+      for (const finding of data.findings) {
+        ui.info(`  ${finding.file}:${finding.line}  ${finding.what}`);
+        ui.info(`      ${finding.advice}`);
+      }
+    });
+  },
+};
+
+module.exports = {
+  summary: 'Port an application from Supabase',
+  usage: 'motherbase migrate codemod <dir> [--write]',
+  subcommands: { codemod },
+  // Exported for the unit test: the scanner is the part worth pinning.
+  _internals: { rewriteImports, scanUnsupported },
+};