@motherbase/cli 0.2.2 → 0.2.4

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,64 +1,273 @@
-'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.
-
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-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}`))));
-  });
-}
-
-const init = {
-  summary: 'Scaffold a local project directory with a .env',
-  usage: 'motherbase init [dir]',
-  async run(ctx, args) {
-    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);
-    }
-    ui.success(`Initialized Motherbase project at ${target}`);
-  },
-};
-
-const start = {
-  summary: 'Start the local docker compose stack',
-  usage: 'motherbase start',
-  async run() { await dockerCompose(['up', '-d']); },
-};
-
-const stop = {
-  summary: 'Stop the local docker compose stack',
-  usage: 'motherbase stop',
-  async run() { await dockerCompose(['down']); },
-};
-
-const deploy = {
-  summary: 'Rebuild and start the local docker compose stack',
-  usage: 'motherbase deploy',
-  async run() { 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]); },
-};
-
-module.exports = { init, start, stop, deploy, logs };
+'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: 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 };

package/src/commands/mcp.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// `motherbase mcp` — expose the linked project 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 pkg = require('../../package.json');
+
+const mcp = {
+  summary: 'Serve the linked project to an AI agent over MCP (stdio)',
+  usage: 'motherbase mcp [--write]',
+  async run(ctx, _args, flags = {}) {
+    // Resolve the project up front. Failing here is a clear CLI error; failing
+    // on the first tool call is an opaque one inside someone's agent.
+    ctx.requireProject();
+
+    const write = Boolean(flags.write);
+    const tools = buildTools(ctx, { write });
+
+    process.stderr.write(
+      `motherbase mcp: ${tools.length} tools, ${write ? 'read and write' : 'read only'}. `
+        + `Project: ${ctx.projectName || ctx.projectId || 'direct'}\n`,
+    );
+    if (!write) {
+      process.stderr.write('  Pass --write to expose apply_migration and raw SQL writes.\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/rls.js

@@ -76,10 +76,101 @@ const subcommands = {
     },
   },
   policy,
+  preset: {
+    summary: 'Apply a policy preset to a table',
+    usage:
+      'motherbase rls preset <table> <starter|public_crud|authenticated_crud|admin_only|blocked|owner_only|org_scoped|public_read_owner_write|soft_delete> [--owner-column c] [--org-column c] [--org-claim c] [--deleted-column c] [--replace]',
+    async run(ctx, args, flags) {
+      const table = requireArg(args[0], 'table');
+      const preset = requireArg(args[1], 'preset');
+      const body = { preset };
+      if (flags['owner-column']) body.ownerColumn = flags['owner-column'];
+      if (flags['org-column']) body.orgColumn = flags['org-column'];
+      if (flags['org-claim']) body.orgClaim = flags['org-claim'];
+      if (flags['deleted-column']) body.deletedColumn = flags['deleted-column'];
+      if (flags.replace) body.replace = true;
+      const data = await api.adminRequest(ctx, 'POST', `/rls/tables/${table}/preset`, { body });
+      output(ctx, data, (d, ui) =>
+        ui.success(`Applied ${preset} to ${table}: ${(d && d.policies ? d.policies : []).join(', ')}`)
+      );
+    },
+  },
+  simulate: {
+    summary: 'Run a query as a given caller and show what RLS lets through',
+    usage:
+      'motherbase rls simulate --sql "select * from t" [--as anon|authenticated|<userId>] [--claims \'{"org_id":"x"}\'] [--limit n]',
+    async run(ctx, args, flags) {
+      const sql = flags.sql || args.join(' ');
+      if (!sql) throw new CliError('--sql is required');
+
+      // `--as` takes a role or a user id. A value that is not one of the two
+      // roles is treated as a user id, which is what makes "as this person"
+      // spellable without looking their claims up by hand.
+      const as = flags.as || 'anon';
+      const body = { sql };
+      if (as === 'anon' || as === 'authenticated') body.role = as;
+      else body.userId = as;
+      if (flags.claims) {
+        try {
+          body.claims = JSON.parse(flags.claims);
+        } catch {
+          throw new CliError('--claims must be a JSON object');
+        }
+      }
+      if (flags.limit) body.limit = Number(flags.limit);
+
+      const data = await api.adminRequest(ctx, 'POST', '/rls/simulate', { body });
+      output(ctx, data, (d, ui) => {
+        if (d.denied) {
+          ui.warn(`Refused by Postgres: ${d.denied.message}`);
+        }
+        if (d.rows && d.rows.length) {
+          ui.table(d.rows, (d.columns || []).map(key => ({ key, label: key.toUpperCase() })));
+        } else {
+          ui.info('0 rows');
+        }
+        if (d.truncated) ui.info(`Truncated at ${d.rowCount} rows.`);
+        for (const t of d.tables || []) {
+          const reason =
+            t.deniedBy === 'grant'
+              ? 'no privilege for this role'
+              : t.deniedBy === 'policy'
+                ? 'RLS on, no policy grants this role read access'
+                : null;
+          ui.info(`${t.schema}.${t.table}: RLS ${t.rlsEnabled ? 'on' : 'off'}${reason ? ` (${reason})` : ''}`);
+          for (const p of t.policies || []) {
+            ui.info(`  ${p.applies ? '*' : ' '} ${p.name} ${p.command} to ${p.roles.join(',')}: ${p.using || 'true'}`);
+          }
+        }
+      });
+    },
+  },
+  lint: {
+    summary: 'Run the security and performance advisor',
+    usage: 'motherbase rls lint [--level critical|warning|info]',
+    async run(ctx, args, flags) {
+      const data = await api.adminRequest(ctx, 'GET', '/advisor');
+      const findings = (data && data.findings ? data.findings : []).filter(
+        f => !flags.level || f.level === flags.level
+      );
+      output(ctx, { ...data, findings }, (d, ui) => {
+        if (!findings.length) return ui.success('No findings.');
+        ui.table(
+          findings.map(f => ({ level: f.level, id: f.id, target: f.target, title: f.title })),
+          [
+            { key: 'level', label: 'LEVEL' },
+            { key: 'id', label: 'RULE' },
+            { key: 'target', label: 'TARGET' },
+            { key: 'title', label: 'FINDING' },
+          ]
+        );
+      });
+    },
+  },
 };
 
 module.exports = {
-  summary: 'Row-level security (tables + policies)',
-  usage: 'motherbase rls <list|enable|disable|policy> ...',
+  summary: 'Row-level security (tables, policies, presets, simulator, lint)',
+  usage: 'motherbase rls <list|enable|disable|policy|preset|simulate|lint> ...',
   subcommands,
 };

package/src/main.js

@@ -8,6 +8,11 @@ const ui = require('./ui');
 // Flags that never consume a following value.
 const PURE_BOOLEAN = new Set([
   'json', 'yes', 'help', 'version', 'force', 'preview', 'app', 'no-data', 'no-auth', 'f',
+  // Codegen: `--check` and `--local` never take a value, so a trailing
+  // `--check database.types.ts` must not silently swallow the path.
+  'check', 'local',
+  // `rls preset <table> <preset> --replace` must not swallow a following word.
+  'replace',
 ]);
 // Short flag aliases → canonical (with whether they take a value).
 const SHORT = {