@motherbase/cli 0.2.4 → 0.2.6

package/src/commands/inspect.js

@@ -1,41 +1,178 @@
-'use strict';
-
-const api = require('../api');
-const { output } = require('./_util');
-
-function simple(apiPath, summary, render) {
-  return {
-    summary,
-    usage: `motherbase inspect ${summary.split(' ')[0].toLowerCase()}`,
-    async run(ctx) {
-      const data = await api.adminRequest(ctx, 'GET', apiPath);
-      output(ctx, data, render || ((d, ui) => ui.json(d)));
-    },
-  };
-}
-
-const subcommands = {
-  logs: {
-    summary: 'Recent server logs',
-    usage: 'motherbase inspect logs [--limit n]',
-    async run(ctx, args, flags) {
-      const query = flags.limit ? { limit: flags.limit } : undefined;
-      const data = await api.adminRequest(ctx, 'GET', '/logs', { query });
-      const logs = (data && data.logs) || [];
-      output(ctx, data, (_d, ui) =>
-        logs.forEach(l => ui.print(typeof l === 'string' ? l : `${l.level || ''} ${l.source || ''} ${l.message || JSON.stringify(l)}`)),
-      );
-    },
-  },
-  stats: simple('/stats', 'Stats overview'),
-  performance: simple('/performance', 'Performance metrics'),
-  requests: simple('/metrics/requests', 'Request metrics'),
-  advisor: simple('/advisor', 'Advisor findings'),
-  shield: simple('/shield', 'Security shield report'),
-};
-
-module.exports = {
-  summary: 'Diagnostics: logs, stats, performance, advisor, shield',
-  usage: 'motherbase inspect <logs|stats|performance|requests|advisor|shield>',
-  subcommands,
-};
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const api = require('../api');
+const { output } = require('./_util');
+const { CliError } = require('../context');
+const { QUERIES, DEPRECATED, REPORT, resolveQuery } = require('../inspect/queries');
+const { toCsv } = require('../inspect/csv');
+
+function simple(apiPath, summary, render) {
+  return {
+    summary,
+    // usage is filled in from the subcommand key below: deriving it from the
+    // summary printed `inspect security` for `shield` and `inspect request` for
+    // `requests`, neither of which is a command.
+    usage: '',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', apiPath);
+      output(ctx, data, render || ((d, ui) => ui.json(d)));
+    },
+  };
+}
+
+// Postgres' two ways of saying pg_stat_statements is not usable here: the
+// extension was never created in this database, or the library is not preloaded.
+const STAT_STATEMENTS_MISSING = /pg_stat_statements.*(does not exist|must be loaded)/i;
+
+class StatStatementsMissing extends CliError {
+  constructor() {
+    super(
+      'pg_stat_statements is not enabled in this database. Enable it from Studio (Database > Extensions) '
+        + 'or run: motherbase db sql -e "create extension pg_stat_statements"',
+    );
+  }
+}
+
+/** Rows of one inspect query, run on the read-only SQL endpoint. */
+async function runQuery(ctx, query) {
+  try {
+    const data = await api.adminRequest(ctx, 'POST', '/sql/readonly', { body: { sql: query.sql } });
+    return (data && data.rows) || [];
+  } catch (err) {
+    if (query.needsStatStatements && STAT_STATEMENTS_MISSING.test(err.message)) {
+      throw new StatStatementsMissing();
+    }
+    throw err;
+  }
+}
+
+// Statements span lines and `to_char` pads numbers; a table cell wants neither.
+// A statement is also cut short, or one query pushes every other column off
+// screen; -o json keeps it whole.
+const CELL_WIDTH = 60;
+function cell(value) {
+  if (typeof value !== 'string') return value;
+  const text = value.replace(/\s+/g, ' ').trim();
+  return text.length > CELL_WIDTH ? `${text.slice(0, CELL_WIDTH - 1)}…` : text;
+}
+
+function dbCommand(name) {
+  const { name: canonical, query } = resolveQuery(name);
+  const replaced = canonical !== name;
+  return {
+    summary: replaced ? `Deprecated: use "${canonical}" instead` : query.summary,
+    usage: `motherbase inspect db ${name}`,
+    async run(ctx) {
+      const rows = await runQuery(ctx, query);
+      output(ctx, { query: canonical, rows }, (_d, ui) => {
+        if (replaced) ui.warn(`"inspect db ${name}" is deprecated: showing "${canonical}".`);
+        const display = rows.map(row => Object.fromEntries(Object.entries(row).map(([k, v]) => [k, cell(v)])));
+        ui.table(display, query.columns);
+      });
+    },
+  };
+}
+
+const db = {
+  summary: 'Inspect the database: bloat, locks, slow queries, index and table stats',
+  usage: `motherbase inspect db <${Object.keys(QUERIES).join('|')}>`,
+  subcommands: Object.fromEntries(
+    [...Object.keys(QUERIES), ...Object.keys(DEPRECATED)].map(name => [name, dbCommand(name)]),
+  ),
+};
+
+// Local-time YYYY-MM-DD: the report's folder, one per day as upstream does.
+function dateFolder(now = new Date()) {
+  const pad = n => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+const report = {
+  summary: 'Write every inspect query to a CSV in a dated folder',
+  usage: 'motherbase inspect report [--output-dir <dir>]',
+  async run(ctx, _args, flags) {
+    const dir = path.resolve(ctx.cwd, String(flags['output-dir'] || '.'), dateFolder());
+    fs.mkdirSync(dir, { recursive: true });
+
+    const files = [];
+    const skipped = [];
+    // One at a time: fourteen catalog scans at once is a load spike on the
+    // database being diagnosed.
+    for (const { file, name, query } of REPORT) {
+      let rows;
+      try {
+        rows = await runQuery(ctx, query);
+      } catch (err) {
+        // A missing pg_stat_statements costs two files, not the whole report.
+        if (!(err instanceof StatStatementsMissing)) throw err;
+        skipped.push(name);
+        continue;
+      }
+      const target = path.join(dir, `${file}.csv`);
+      fs.writeFileSync(target, toCsv(query.columns, rows));
+      files.push(target);
+    }
+
+    output(ctx, { outputDir: dir, files, skipped }, (d, ui) => {
+      if (d.skipped.length) ui.warn(`Skipped ${d.skipped.join(', ')}: ${new StatStatementsMissing().message}`);
+      ui.success(`Saved ${d.files.length} CSV files to ${path.relative(ctx.cwd, d.outputDir) || '.'}`);
+    });
+  },
+};
+
+const subcommands = {
+  db,
+  report,
+  logs: {
+    summary: 'Recent server logs',
+    usage: 'motherbase inspect logs [--limit n] [--source api|rest|postgres|pooler|auth|storage|realtime|edge-function|cron|platform]',
+    async run(ctx, args, flags) {
+      // A Logs Explorer "source" is the server's `service` filter.
+      const query = flags.limit || flags.source ? { limit: flags.limit, service: flags.source } : undefined;
+      const data = await api.adminRequest(ctx, 'GET', '/logs', { query });
+      const logs = (data && data.logs) || [];
+      output(ctx, data, (_d, ui) =>
+        logs.forEach(l => ui.print(typeof l === 'string' ? l : `${l.level || ''} ${l.source || ''} ${l.message || JSON.stringify(l)}`)),
+      );
+    },
+  },
+  'index-advisor': {
+    summary: 'Suggest indexes for a statement (hypopg + index_advisor)',
+    usage: 'motherbase inspect index-advisor --sql "<select ...>" | motherbase inspect index-advisor --enable',
+    async run(ctx, args, flags) {
+      if (flags.enable) {
+        const status = await api.adminRequest(ctx, 'POST', '/performance/index-advisor/enable');
+        output(ctx, status, (_d, ui) => ui.success('Index advisor enabled'));
+        return;
+      }
+      const query = flags.sql || flags.e;
+      if (typeof query !== 'string') throw new CliError('Provide the statement with --sql "..." (or --enable to install the advisor).');
+      const data = await api.adminRequest(ctx, 'POST', '/performance/index-advisor', { body: { query } });
+      output(ctx, data, (d, ui) => {
+        const statements = (d && d.indexStatements) || [];
+        if (!statements.length) ui.print('No index would help this statement.');
+        statements.forEach(s => ui.print(s));
+        if (d && d.improvementPct != null) ui.print(`Estimated cost drop: ${d.improvementPct}%`);
+      });
+    },
+  },
+  stats: simple('/stats', 'Stats overview'),
+  performance: simple('/performance', 'Performance metrics'),
+  requests: simple('/metrics/requests', 'Request metrics'),
+  advisor: simple('/advisor', 'Advisor findings'),
+  shield: simple('/shield', 'Security shield report'),
+};
+
+for (const [name, def] of Object.entries(subcommands)) {
+  if (!def.usage) def.usage = `motherbase inspect ${name}`;
+}
+
+module.exports = {
+  summary: 'Diagnostics: database inspection, report, logs, stats, index-advisor, advisor, shield',
+  usage: 'motherbase inspect <db|report|logs|stats|performance|index-advisor|requests|advisor|shield>',
+  subcommands,
+  dateFolder,
+  cell,
+};

package/src/commands/link.js

@@ -1,35 +1,35 @@
-'use strict';
-
-const api = require('../api');
-const config = require('../config');
-const prompt = require('../prompt');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-module.exports = {
-  summary: 'Link the current directory to a project (writes ./.motherbase/config.json)',
-  usage: 'motherbase link [projectNameOrId]',
-  async run(ctx, args, flags) {
-    const { consoleUrl } = ctx.requireConsole();
-    const projects = await api.consoleRequest(ctx, 'GET', '/projects');
-    const list = Array.isArray(projects) ? projects : [];
-    if (list.length === 0) throw new CliError('No projects available on this console.');
-
-    let picked = args[0];
-    if (!picked) {
-      if (flags.yes) throw new CliError('Specify a project name/id when using --yes.');
-      ui.print(ui.color.bold('Available projects:'));
-      list.forEach((p, i) => ui.print(`  ${i + 1}. ${p.name || p.id}`));
-      const answer = await prompt.question('Pick a project (number or name): ');
-      const asNum = Number(answer);
-      picked = Number.isInteger(asNum) && list[asNum - 1] ? (list[asNum - 1].name || list[asNum - 1].id) : answer;
-    }
-
-    const match = list.find(p => p.name === picked || p.id === picked);
-    if (!match) throw new CliError(`Project "${picked}" not found on ${consoleUrl}.`);
-
-    const projectId = match.name || match.id;
-    config.writeLink(ctx.cwd, { consoleUrl, projectId, projectName: match.name || projectId });
-    ui.success(`Linked ${ctx.cwd} → ${projectId} (${consoleUrl})`);
-  },
-};
+'use strict';
+
+const api = require('../api');
+const config = require('../config');
+const prompt = require('../prompt');
+const ui = require('../ui');
+const { CliError } = require('../context');
+
+module.exports = {
+  summary: 'Link the current directory to a project (writes ./.motherbase/config.json)',
+  usage: 'motherbase link [projectNameOrId]',
+  async run(ctx, args, flags) {
+    const { consoleUrl } = ctx.requireConsole();
+    const projects = await api.consoleRequest(ctx, 'GET', '/projects');
+    const list = Array.isArray(projects) ? projects : [];
+    if (list.length === 0) throw new CliError('No projects available on this console.');
+
+    let picked = args[0];
+    if (!picked) {
+      if (flags.yes) throw new CliError('Specify a project name/id when using --yes.');
+      ui.print(ui.color.bold('Available projects:'));
+      list.forEach((p, i) => ui.print(`  ${i + 1}. ${p.name || p.id}`));
+      const answer = await prompt.question('Pick a project (number or name): ');
+      const asNum = Number(answer);
+      picked = Number.isInteger(asNum) && list[asNum - 1] ? (list[asNum - 1].name || list[asNum - 1].id) : answer;
+    }
+
+    const match = list.find(p => p.name === picked || p.id === picked);
+    if (!match) throw new CliError(`Project "${picked}" not found on ${consoleUrl}.`);
+
+    const projectId = match.name || match.id;
+    config.writeLink(ctx.cwd, { consoleUrl, projectId, projectName: match.name || projectId });
+    ui.success(`Linked ${ctx.cwd} → ${projectId} (${consoleUrl})`);
+  },
+};

package/src/commands/local.js

@@ -138,7 +138,7 @@ services:
 
   # One-shot: a private bucket and a separate anonymously-downloadable one.
   createbuckets:
-    image: minio/mc:RELEASE.2025-08-13T08-35-41Z
+    image: quay.io/minio/mc:RELEASE.2025-08-13T08-35-41Z
     depends_on:
       minio:
         condition: service_healthy
@@ -183,10 +183,31 @@ volumes:
 `;
 }
 
+// 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"'`$#\\]+$/,
+  repo: /^[\w.:/@~+-]+$/,
+  ref: /^[\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] [--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 });
@@ -270,4 +291,4 @@ const logs = {
   },
 };
 
-module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose };
+module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose, validateInitFlags };

package/src/commands/login.js

@@ -1,39 +1,39 @@
-'use strict';
-
-const api = require('../api');
-const config = require('../config');
-const prompt = require('../prompt');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-module.exports = {
-  summary: 'Log in to a Motherbase Console (email/password → session token)',
-  usage: 'motherbase login [--url <consoleUrl>] [--email <email>]',
-  async run(ctx, args, flags) {
-    const consoleUrl = config.normalizeUrl(
-      flags.url || ctx.env.MOTHERBASE_CONSOLE_URL || ctx.consoleUrl || '',
-    );
-    if (!consoleUrl) {
-      throw new CliError('Console URL required. Use --url <consoleUrl> or set MOTHERBASE_CONSOLE_URL.');
-    }
-
-    // Non-interactive: accept a token directly (CI).
-    if (flags.token) {
-      const email = flags.email || 'token';
-      config.saveConsoleToken(consoleUrl, flags.token, email);
-      ui.success(`Stored token for ${consoleUrl}`);
-      return;
-    }
-
-    const email = flags.email || (await prompt.question('Email: '));
-    if (!email) throw new CliError('email is required');
-    const password = flags.password || (await prompt.password('Password: '));
-    if (!password) throw new CliError('password is required');
-
-    const data = await api.loginRequest(consoleUrl, email, password);
-    const token = data && data.token;
-    if (!token) throw new CliError('login succeeded but no token was returned');
-    config.saveConsoleToken(consoleUrl, token, email);
-    ui.success(`Logged in to ${consoleUrl} as ${email}`);
-  },
-};
+'use strict';
+
+const api = require('../api');
+const config = require('../config');
+const prompt = require('../prompt');
+const ui = require('../ui');
+const { CliError } = require('../context');
+
+module.exports = {
+  summary: 'Log in to a Motherbase Console (email/password → session token)',
+  usage: 'motherbase login [--url <consoleUrl>] [--email <email>]',
+  async run(ctx, args, flags) {
+    const consoleUrl = config.normalizeUrl(
+      flags.url || ctx.env.MOTHERBASE_CONSOLE_URL || ctx.consoleUrl || '',
+    );
+    if (!consoleUrl) {
+      throw new CliError('Console URL required. Use --url <consoleUrl> or set MOTHERBASE_CONSOLE_URL.');
+    }
+
+    // Non-interactive: accept a token directly (CI).
+    if (flags.token) {
+      const email = flags.email || 'token';
+      config.saveConsoleToken(consoleUrl, flags.token, email);
+      ui.success(`Stored token for ${consoleUrl}`);
+      return;
+    }
+
+    const email = flags.email || (await prompt.question('Email: '));
+    if (!email) throw new CliError('email is required');
+    const password = (typeof flags.password === 'string' && flags.password) || (await prompt.password('Password: '));
+    if (!password) throw new CliError('password is required');
+
+    const data = await api.loginRequest(consoleUrl, email, password);
+    const token = data && data.token;
+    if (!token) throw new CliError('login succeeded but no token was returned');
+    config.saveConsoleToken(consoleUrl, token, email);
+    ui.success(`Logged in to ${consoleUrl} as ${email}`);
+  },
+};

package/src/commands/logout.js

@@ -1,16 +1,16 @@
-'use strict';
-
-const config = require('../config');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-module.exports = {
-  summary: 'Remove the stored token for the current (or --url) console',
-  usage: 'motherbase logout [--url <consoleUrl>]',
-  async run(ctx) {
-    const url = config.normalizeUrl(ctx.flags.url || ctx.consoleUrl || '');
-    if (!url) throw new CliError('No console to log out of.');
-    config.clearConsoleToken(url);
-    ui.success(`Logged out of ${url}`);
-  },
-};
+'use strict';
+
+const config = require('../config');
+const ui = require('../ui');
+const { CliError } = require('../context');
+
+module.exports = {
+  summary: 'Remove the stored token for the current (or --url) console',
+  usage: 'motherbase logout [--url <consoleUrl>]',
+  async run(ctx) {
+    const url = config.normalizeUrl(ctx.flags.url || ctx.consoleUrl || '');
+    if (!url) throw new CliError('No console to log out of.');
+    config.clearConsoleToken(url);
+    ui.success(`Logged out of ${url}`);
+  },
+};

package/src/commands/mcp.js

@@ -1,7 +1,7 @@
 'use strict';
 
-// `motherbase mcp` — expose the linked project to an AI agent over the Model
-// Context Protocol.
+// `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
@@ -9,26 +9,44 @@
 
 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 to an AI agent over MCP (stdio)',
+  summary: 'Serve the linked project and console 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();
+    // 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 });
+    const tools = buildTools(ctx, { write, ...scope });
 
     process.stderr.write(
       `motherbase mcp: ${tools.length} tools, ${write ? 'read and write' : 'read only'}. `
-        + `Project: ${ctx.projectName || ctx.projectId || 'direct'}\n`,
+        + `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 and raw SQL writes.\n');
+      process.stderr.write('  Pass --write to expose apply_migration, raw SQL writes, function deploys and project lifecycle.\n');
     }
 
     await serve({