@motherbase/cli 0.2.5 → 0.2.6

package/src/commands/_util.js

@@ -1,93 +1,106 @@
-'use strict';
-
-// Small shared helpers for command modules.
-
-const { CliError } = require('../context');
-const { outputFormat, toYaml, toEnv } = require('../format');
-
-// Parse `key=value` tokens into an object. Values that look like numbers/bools are
-// coerced unless `raw` is set. Supports dotted keys via `--json`-style callers.
-function parseKeyValues(tokens, { coerce = true } = {}) {
-  const out = {};
-  for (const tok of tokens) {
-    const idx = tok.indexOf('=');
-    if (idx <= 0) throw new CliError(`expected key=value, got "${tok}"`);
-    const key = tok.slice(0, idx).trim();
-    let value = tok.slice(idx + 1);
-    if (coerce) {
-      if (value === 'true') value = true;
-      else if (value === 'false') value = false;
-      else if (value !== '' && !Number.isNaN(Number(value)) && /^-?\d+(\.\d+)?$/.test(value)) value = Number(value);
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
-// Render a command's result in the selected `-o/--output` format; `pretty` is
-// the command's own human renderer.
-function output(ctx, data, humanFn) {
-  const ui = require('../ui');
-  switch (outputFormat(ctx.flags)) {
-    case 'json': ui.json(data); return;
-    case 'yaml': process.stdout.write(toYaml(data)); return;
-    case 'env': process.stdout.write(toEnv(data)); return;
-    default: humanFn(data, ui);
-  }
-}
-
-// The same command under a second (Supabase) name: one implementation, with
-// help that shows the name it was reached by.
-function alias(entry, usage, summary = entry.summary) {
-  return { ...entry, usage, summary };
-}
-
-// Parse a dotenv file: `KEY=value`, `export KEY=value`, `#` comments, and
-// single- or double-quoted values (double quotes expand \n).
-function parseDotenv(text) {
-  const out = {};
-  for (const raw of String(text).split(/\r?\n/)) {
-    const line = raw.trim().replace(/^export\s+/, '');
-    if (!line || line.startsWith('#')) continue;
-    const idx = line.indexOf('=');
-    if (idx <= 0) throw new CliError(`invalid env line: "${raw}"`);
-    const key = line.slice(0, idx).trim();
-    let value = line.slice(idx + 1).trim();
-    const quote = value[0];
-    if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
-      value = value.slice(1, -1);
-      if (quote === '"') value = value.replace(/\\n/g, '\n');
-    } else {
-      value = value.replace(/\s+#.*$/, '');
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
-function requireArg(value, name) {
-  if (value === undefined || value === null || value === '') {
-    throw new CliError(`missing required argument: <${name}>`);
-  }
-  return value;
-}
-
-// Split "bucket:path" into { bucket, rest }.
-function splitRef(ref) {
-  const idx = ref.indexOf(':');
-  if (idx < 0) return { bucket: undefined, rest: ref };
-  return { bucket: ref.slice(0, idx), rest: ref.slice(idx + 1) };
-}
-
-// `/projects/<linked project>` on the Console, for the per-project platform
-// surfaces (branches, domains) that live on the Console rather than the
-// project API. They need a Console, so direct mode cannot reach them.
-function consoleProjectPath(ctx, suffix = '') {
-  ctx.requireConsole();
-  if (!ctx.projectId) {
-    throw new CliError('No project linked. Run `motherbase link` or pass --project-ref <id>.');
-  }
-  return `/projects/${encodeURIComponent(ctx.projectId)}${suffix}`;
-}
-
-module.exports = { parseKeyValues, output, alias, parseDotenv, requireArg, splitRef, consoleProjectPath };
+'use strict';
+
+// Small shared helpers for command modules.
+
+const path = require('path');
+const { CliError } = require('../context');
+const { outputFormat, toYaml, toEnv } = require('../format');
+
+// Parse `key=value` tokens into an object. Values that look like numbers/bools are
+// coerced unless `raw` is set. Supports dotted keys via `--json`-style callers.
+function parseKeyValues(tokens, { coerce = true } = {}) {
+  const out = {};
+  for (const tok of tokens) {
+    const idx = tok.indexOf('=');
+    if (idx <= 0) throw new CliError(`expected key=value, got "${tok}"`);
+    const key = tok.slice(0, idx).trim();
+    let value = tok.slice(idx + 1);
+    if (coerce) {
+      if (value === 'true') value = true;
+      else if (value === 'false') value = false;
+      else if (value !== '' && !Number.isNaN(Number(value)) && /^-?\d+(\.\d+)?$/.test(value)) value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// Render a command's result in the selected `-o/--output` format; `pretty` is
+// the command's own human renderer.
+function output(ctx, data, humanFn) {
+  const ui = require('../ui');
+  switch (outputFormat(ctx.flags)) {
+    case 'json': ui.json(data); return;
+    case 'yaml': process.stdout.write(toYaml(data)); return;
+    case 'env': process.stdout.write(toEnv(data)); return;
+    default: humanFn(data, ui);
+  }
+}
+
+// The same command under a second (Supabase) name: one implementation, with
+// help that shows the name it was reached by.
+function alias(entry, usage, summary = entry.summary) {
+  return { ...entry, usage, summary };
+}
+
+// Parse a dotenv file: `KEY=value`, `export KEY=value`, `#` comments, and
+// single- or double-quoted values (double quotes expand \n).
+function parseDotenv(text) {
+  const out = {};
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim().replace(/^export\s+/, '');
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf('=');
+    if (idx <= 0) throw new CliError(`invalid env line: "${raw}"`);
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
+      value = value.slice(1, -1);
+      if (quote === '"') value = value.replace(/\\n/g, '\n');
+    } else {
+      value = value.replace(/\s+#.*$/, '');
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function requireArg(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new CliError(`missing required argument: <${name}>`);
+  }
+  return value;
+}
+
+// Split "bucket:path" into { bucket, rest }.
+function splitRef(ref) {
+  const idx = ref.indexOf(':');
+  if (idx < 0) return { bucket: undefined, rest: ref };
+  return { bucket: ref.slice(0, idx), rest: ref.slice(idx + 1) };
+}
+
+// `/projects/<linked project>` on the Console, for the per-project platform
+// surfaces (branches, domains) that live on the Console rather than the
+// project API. They need a Console, so direct mode cannot reach them.
+function consoleProjectPath(ctx, suffix = '') {
+  ctx.requireConsole();
+  if (!ctx.projectId) {
+    throw new CliError('No project linked. Run `motherbase link` or pass --project-ref <id>.');
+  }
+  return `/projects/${encodeURIComponent(ctx.projectId)}${suffix}`;
+}
+
+// Join `parts` under `root`, refusing a result that escapes it. Names that come
+// from the server (object keys, function routes) must not write outside the
+// directory the user picked: `../../.bashrc` is a valid object key.
+function resolveInside(root, ...parts) {
+  const target = path.resolve(root, ...parts);
+  const rel = path.relative(root, target);
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw new CliError(`Refusing to write outside ${root}: ${parts.join('/')}`);
+  }
+  return target;
+}
+
+module.exports = { parseKeyValues, output, alias, parseDotenv, requireArg, splitRef, consoleProjectPath, resolveInside };

package/src/commands/backups.js

@@ -1,16 +1,16 @@
-'use strict';
-
-// Supabase's top-level `backups`. The implementations live under `db`, which
-// keeps its own names for them.
-
-const db = require('./db');
-const { alias } = require('./_util');
-
-module.exports = {
-  summary: 'List and restore database backups',
-  usage: 'motherbase backups <list|restore> ...',
-  subcommands: {
-    list: alias(db.subcommands.backups, 'motherbase backups list', 'List database backups'),
-    restore: alias(db.subcommands.restore, 'motherbase backups restore <file> | --key <remoteKey>  --confirm'),
-  },
-};
+'use strict';
+
+// Supabase's top-level `backups`. The implementations live under `db`, which
+// keeps its own names for them.
+
+const db = require('./db');
+const { alias } = require('./_util');
+
+module.exports = {
+  summary: 'List and restore database backups',
+  usage: 'motherbase backups <list|restore> ...',
+  subcommands: {
+    list: alias(db.subcommands.backups, 'motherbase backups list', 'List database backups'),
+    restore: alias(db.subcommands.restore, 'motherbase backups restore <file> | --key <remoteKey>  --confirm'),
+  },
+};

package/src/commands/branches.js

@@ -1,113 +1,113 @@
-'use strict';
-
-// Preview branches (Supabase's `supabase branches`). A branch is a project of
-// its own on the Console, cut from the linked project; these commands address
-// it by its name (e.g. the git branch) or its project id.
-
-const api = require('../api');
-const config = require('../config');
-const { output, requireArg, consoleProjectPath } = require('./_util');
-
-const COLUMNS = [
-  { key: 'name', label: 'NAME' },
-  { key: 'project', label: 'PROJECT' },
-  { key: 'gitBranch', label: 'GIT BRANCH' },
-  { key: 'status', label: 'STATUS' },
-  { key: 'running', label: 'RUNNING' },
-  { key: 'createdAt', label: 'CREATED' },
-];
-
-const branchPath = (ctx, name, action = '') =>
-  consoleProjectPath(ctx, `/branches/${encodeURIComponent(requireArg(name, 'name'))}${action}`);
-
-function action(verb, summary, render) {
-  return {
-    summary,
-    usage: `motherbase branches ${verb} <name>`,
-    async run(ctx, args) {
-      const data = await api.consoleRequest(ctx, 'POST', branchPath(ctx, args[0], `/${verb}`));
-      output(ctx, data, (d, ui) => render(d, ui));
-    },
-  };
-}
-
-const subcommands = {
-  create: {
-    summary: 'Create a preview branch of the linked project',
-    usage: 'motherbase branches create <name> [--git-branch <ref>] [--with-data]',
-    async run(ctx, args, flags) {
-      const body = { name: requireArg(args[0], 'name'), withData: Boolean(flags['with-data']) };
-      if (flags['git-branch']) body.gitBranch = String(flags['git-branch']);
-      const data = await api.consoleRequest(ctx, 'POST', consoleProjectPath(ctx, '/branches'), { body });
-      output(ctx, data, (d, ui) => {
-        ui.success(`Creating branch ${d.name} as project ${d.project} (${d.domain})`);
-        ui.info('This takes a few minutes. Follow it with `motherbase branches get ' + d.name + '`.');
-      });
-    },
-  },
-  list: {
-    summary: 'List the branches of the linked project, main first',
-    usage: 'motherbase branches list',
-    async run(ctx) {
-      const rows = await api.consoleRequest(ctx, 'GET', consoleProjectPath(ctx, '/branches'));
-      output(ctx, { branches: rows }, (d, ui) => ui.table(d.branches, COLUMNS));
-    },
-  },
-  get: {
-    summary: 'Show one branch, with the migrations it is ahead and behind',
-    usage: 'motherbase branches get <name>',
-    async run(ctx, args) {
-      const data = await api.consoleRequest(ctx, 'GET', branchPath(ctx, args[0]));
-      output(ctx, data, (d, ui) => {
-        const { migrations, ...rest } = d;
-        ui.keyValue(rest);
-        if (migrations) ui.keyValue({ ahead: migrations.ahead.join(', ') || '-', behind: migrations.behind.join(', ') || '-' });
-      });
-    },
-  },
-  update: {
-    summary: 'Change a branch\'s git branch',
-    usage: 'motherbase branches update <name> --git-branch <ref>',
-    async run(ctx, args, flags) {
-      const body = {};
-      if (flags['git-branch'] !== undefined) body.gitBranch = String(flags['git-branch']);
-      const data = await api.consoleRequest(ctx, 'PATCH', branchPath(ctx, args[0]), { body });
-      output(ctx, data, (d, ui) => ui.success(`Updated branch ${d.name}`));
-    },
-  },
-  delete: {
-    summary: 'Delete a branch and its whole stack',
-    usage: 'motherbase branches delete <name>',
-    async run(ctx, args) {
-      const data = await api.consoleRequest(ctx, 'DELETE', branchPath(ctx, args[0]));
-      output(ctx, data, (d, ui) => ui.success(`Deleted branch ${d.name}`));
-    },
-  },
-  pause: action('pause', 'Stop a branch\'s stack, keeping its data', (d, ui) => ui.success(`Paused ${d.name}`)),
-  unpause: action('unpause', 'Start a paused branch again', (d, ui) => ui.success(`Unpaused ${d.name}`)),
-  reset: action('reset', 'Recreate a branch from the parent as it is now (its changes are lost)',
-    (d, ui) => ui.success(`Resetting ${d.name}; it is being cut again from ${d.parent}`)),
-  merge: action('merge', 'Apply the branch\'s new migrations to the parent',
-    (d, ui) => ui.success(d.applied.length ? `Merged ${d.applied.length} migration(s): ${d.applied.join(', ')}` : 'Nothing to merge')),
-  rebase: action('rebase', 'Apply the parent\'s newer migrations to the branch',
-    (d, ui) => ui.success(d.applied.length ? `Rebased ${d.applied.length} migration(s): ${d.applied.join(', ')}` : 'Already up to date')),
-  switch: {
-    summary: 'Point this directory\'s link at a branch (or back at main)',
-    usage: 'motherbase branches switch <name|main>',
-    async run(ctx, args) {
-      const name = requireArg(args[0], 'name');
-      const rows = await api.consoleRequest(ctx, 'GET', consoleProjectPath(ctx, '/branches'));
-      const match = rows.find(b => b.name === name || b.project === name || (name === 'main' && b.isDefault));
-      if (!match) throw new Error(`No branch ${name}. See \`motherbase branches list\`.`);
-      const link = config.readLink(ctx.cwd) || {};
-      config.writeLink(ctx.cwd, { ...link, consoleUrl: ctx.consoleUrl, projectId: match.project, projectName: match.project });
-      output(ctx, { project: match.project, branch: match.name }, (d, ui) => ui.success(`Linked ${ctx.cwd} → ${d.project} (${d.branch})`));
-    },
-  },
-};
-
-module.exports = {
-  summary: 'Manage preview branches of the linked project',
-  usage: 'motherbase branches <create|list|get|update|delete|pause|unpause|reset|merge|rebase|switch> ...',
-  subcommands,
-};
+'use strict';
+
+// Preview branches (Supabase's `supabase branches`). A branch is a project of
+// its own on the Console, cut from the linked project; these commands address
+// it by its name (e.g. the git branch) or its project id.
+
+const api = require('../api');
+const config = require('../config');
+const { output, requireArg, consoleProjectPath } = require('./_util');
+
+const COLUMNS = [
+  { key: 'name', label: 'NAME' },
+  { key: 'project', label: 'PROJECT' },
+  { key: 'gitBranch', label: 'GIT BRANCH' },
+  { key: 'status', label: 'STATUS' },
+  { key: 'running', label: 'RUNNING' },
+  { key: 'createdAt', label: 'CREATED' },
+];
+
+const branchPath = (ctx, name, action = '') =>
+  consoleProjectPath(ctx, `/branches/${encodeURIComponent(requireArg(name, 'name'))}${action}`);
+
+function action(verb, summary, render) {
+  return {
+    summary,
+    usage: `motherbase branches ${verb} <name>`,
+    async run(ctx, args) {
+      const data = await api.consoleRequest(ctx, 'POST', branchPath(ctx, args[0], `/${verb}`));
+      output(ctx, data, (d, ui) => render(d, ui));
+    },
+  };
+}
+
+const subcommands = {
+  create: {
+    summary: 'Create a preview branch of the linked project',
+    usage: 'motherbase branches create <name> [--git-branch <ref>] [--with-data]',
+    async run(ctx, args, flags) {
+      const body = { name: requireArg(args[0], 'name'), withData: Boolean(flags['with-data']) };
+      if (flags['git-branch']) body.gitBranch = String(flags['git-branch']);
+      const data = await api.consoleRequest(ctx, 'POST', consoleProjectPath(ctx, '/branches'), { body });
+      output(ctx, data, (d, ui) => {
+        ui.success(`Creating branch ${d.name} as project ${d.project} (${d.domain})`);
+        ui.info('This takes a few minutes. Follow it with `motherbase branches get ' + d.name + '`.');
+      });
+    },
+  },
+  list: {
+    summary: 'List the branches of the linked project, main first',
+    usage: 'motherbase branches list',
+    async run(ctx) {
+      const rows = await api.consoleRequest(ctx, 'GET', consoleProjectPath(ctx, '/branches'));
+      output(ctx, { branches: rows }, (d, ui) => ui.table(d.branches, COLUMNS));
+    },
+  },
+  get: {
+    summary: 'Show one branch, with the migrations it is ahead and behind',
+    usage: 'motherbase branches get <name>',
+    async run(ctx, args) {
+      const data = await api.consoleRequest(ctx, 'GET', branchPath(ctx, args[0]));
+      output(ctx, data, (d, ui) => {
+        const { migrations, ...rest } = d;
+        ui.keyValue(rest);
+        if (migrations) ui.keyValue({ ahead: migrations.ahead.join(', ') || '-', behind: migrations.behind.join(', ') || '-' });
+      });
+    },
+  },
+  update: {
+    summary: 'Change a branch\'s git branch',
+    usage: 'motherbase branches update <name> --git-branch <ref>',
+    async run(ctx, args, flags) {
+      const body = {};
+      if (flags['git-branch'] !== undefined) body.gitBranch = String(flags['git-branch']);
+      const data = await api.consoleRequest(ctx, 'PATCH', branchPath(ctx, args[0]), { body });
+      output(ctx, data, (d, ui) => ui.success(`Updated branch ${d.name}`));
+    },
+  },
+  delete: {
+    summary: 'Delete a branch and its whole stack',
+    usage: 'motherbase branches delete <name>',
+    async run(ctx, args) {
+      const data = await api.consoleRequest(ctx, 'DELETE', branchPath(ctx, args[0]));
+      output(ctx, data, (d, ui) => ui.success(`Deleted branch ${d.name}`));
+    },
+  },
+  pause: action('pause', 'Stop a branch\'s stack, keeping its data', (d, ui) => ui.success(`Paused ${d.name}`)),
+  unpause: action('unpause', 'Start a paused branch again', (d, ui) => ui.success(`Unpaused ${d.name}`)),
+  reset: action('reset', 'Recreate a branch from the parent as it is now (its changes are lost)',
+    (d, ui) => ui.success(`Resetting ${d.name}; it is being cut again from ${d.parent}`)),
+  merge: action('merge', 'Apply the branch\'s new migrations to the parent',
+    (d, ui) => ui.success(d.applied.length ? `Merged ${d.applied.length} migration(s): ${d.applied.join(', ')}` : 'Nothing to merge')),
+  rebase: action('rebase', 'Apply the parent\'s newer migrations to the branch',
+    (d, ui) => ui.success(d.applied.length ? `Rebased ${d.applied.length} migration(s): ${d.applied.join(', ')}` : 'Already up to date')),
+  switch: {
+    summary: 'Point this directory\'s link at a branch (or back at main)',
+    usage: 'motherbase branches switch <name|main>',
+    async run(ctx, args) {
+      const name = requireArg(args[0], 'name');
+      const rows = await api.consoleRequest(ctx, 'GET', consoleProjectPath(ctx, '/branches'));
+      const match = rows.find(b => b.name === name || b.project === name || (name === 'main' && b.isDefault));
+      if (!match) throw new Error(`No branch ${name}. See \`motherbase branches list\`.`);
+      const link = config.readLink(ctx.cwd) || {};
+      config.writeLink(ctx.cwd, { ...link, consoleUrl: ctx.consoleUrl, projectId: match.project, projectName: match.project });
+      output(ctx, { project: match.project, branch: match.name }, (d, ui) => ui.success(`Linked ${ctx.cwd} → ${d.project} (${d.branch})`));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Manage preview branches of the linked project',
+  usage: 'motherbase branches <create|list|get|update|delete|pause|unpause|reset|merge|rebase|switch> ...',
+  subcommands,
+};

package/src/commands/completion.js

@@ -1,90 +1,90 @@
-'use strict';
-
-// `completion <shell>`: a completion script generated from the command
-// registry, so it can never list a command that does not exist.
-
-const { requireArg } = require('./_util');
-const { CliError } = require('../context');
-
-// Every command path that has children, with those children:
-// [{ path: 'storage buckets', children: [{ name: 'list', summary }] }, ...].
-// The root is the path ''.
-function commandPaths(registry) {
-  const out = [];
-  const walk = (path, subcommands) => {
-    const names = Object.keys(subcommands);
-    out.push({ path, children: names.map(name => ({ name, summary: subcommands[name].summary || '' })) });
-    for (const name of names) {
-      const sub = subcommands[name].subcommands;
-      if (sub) walk(path ? `${path} ${name}` : name, sub);
-    }
-  };
-  walk('', registry);
-  return out;
-}
-
-// The words typed so far, flags skipped, are the path whose children complete.
-function bash(paths) {
-  const cases = paths
-    .map(p => `    "${p.path}") words="${p.children.map(c => c.name).join(' ')}" ;;`)
-    .join('\n');
-  return `# motherbase bash completion. Load with: source <(motherbase completion bash)
-_motherbase() {
-  local cur="\${COMP_WORDS[COMP_CWORD]}" path="" words="" i
-  for ((i = 1; i < COMP_CWORD; i++)); do
-    [[ \${COMP_WORDS[i]} == -* ]] && continue
-    path="\${path:+$path }\${COMP_WORDS[i]}"
-  done
-  case "$path" in
-${cases}
-  esac
-  COMPREPLY=($(compgen -W "$words" -- "$cur"))
-}
-complete -F _motherbase motherbase
-`;
-}
-
-// zsh runs the bash function through its bashcompinit shim.
-function zsh(paths) {
-  return `# motherbase zsh completion. Load with: source <(motherbase completion zsh)
-autoload -U +X bashcompinit && bashcompinit
-${bash(paths).split('\n').slice(1).join('\n')}`;
-}
-
-function fishQuote(text) {
-  return `'${String(text).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
-function fish(paths) {
-  const lines = paths.flatMap(p =>
-    p.children.map(
-      c => `complete -c motherbase -f -n ${fishQuote(`__motherbase_at '${p.path}'`)} -a ${fishQuote(c.name)} -d ${fishQuote(c.summary)}`,
-    ),
-  );
-  return `# motherbase fish completion. Load with: motherbase completion fish | source
-function __motherbase_at
-    set -l path (string join ' ' -- (string match -v -- '-*' (commandline -opc)[2..-1]))
-    test "$path" = "$argv[1]"
-end
-${lines.join('\n')}
-`;
-}
-
-const SHELLS = { bash, zsh, fish };
-
-function completionScript(shell, registry) {
-  if (!SHELLS[shell]) throw new CliError(`shell must be one of: ${Object.keys(SHELLS).join(', ')}`);
-  return SHELLS[shell](commandPaths(registry));
-}
-
-module.exports = {
-  summary: 'Generate the autocompletion script for a shell',
-  usage: 'motherbase completion <bash|zsh|fish>',
-  run(ctx, args) {
-    const shell = requireArg(args[0], 'shell');
-    // Required here, not at the top: the registry itself requires this file.
-    const { registry } = require('./index');
-    process.stdout.write(completionScript(shell, registry));
-  },
-  completionScript,
-};
+'use strict';
+
+// `completion <shell>`: a completion script generated from the command
+// registry, so it can never list a command that does not exist.
+
+const { requireArg } = require('./_util');
+const { CliError } = require('../context');
+
+// Every command path that has children, with those children:
+// [{ path: 'storage buckets', children: [{ name: 'list', summary }] }, ...].
+// The root is the path ''.
+function commandPaths(registry) {
+  const out = [];
+  const walk = (path, subcommands) => {
+    const names = Object.keys(subcommands);
+    out.push({ path, children: names.map(name => ({ name, summary: subcommands[name].summary || '' })) });
+    for (const name of names) {
+      const sub = subcommands[name].subcommands;
+      if (sub) walk(path ? `${path} ${name}` : name, sub);
+    }
+  };
+  walk('', registry);
+  return out;
+}
+
+// The words typed so far, flags skipped, are the path whose children complete.
+function bash(paths) {
+  const cases = paths
+    .map(p => `    "${p.path}") words="${p.children.map(c => c.name).join(' ')}" ;;`)
+    .join('\n');
+  return `# motherbase bash completion. Load with: source <(motherbase completion bash)
+_motherbase() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}" path="" words="" i
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    [[ \${COMP_WORDS[i]} == -* ]] && continue
+    path="\${path:+$path }\${COMP_WORDS[i]}"
+  done
+  case "$path" in
+${cases}
+  esac
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+}
+complete -F _motherbase motherbase
+`;
+}
+
+// zsh runs the bash function through its bashcompinit shim.
+function zsh(paths) {
+  return `# motherbase zsh completion. Load with: source <(motherbase completion zsh)
+autoload -U +X bashcompinit && bashcompinit
+${bash(paths).split('\n').slice(1).join('\n')}`;
+}
+
+function fishQuote(text) {
+  return `'${String(text).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function fish(paths) {
+  const lines = paths.flatMap(p =>
+    p.children.map(
+      c => `complete -c motherbase -f -n ${fishQuote(`__motherbase_at '${p.path}'`)} -a ${fishQuote(c.name)} -d ${fishQuote(c.summary)}`,
+    ),
+  );
+  return `# motherbase fish completion. Load with: motherbase completion fish | source
+function __motherbase_at
+    set -l path (string join ' ' -- (string match -v -- '-*' (commandline -opc)[2..-1]))
+    test "$path" = "$argv[1]"
+end
+${lines.join('\n')}
+`;
+}
+
+const SHELLS = { bash, zsh, fish };
+
+function completionScript(shell, registry) {
+  if (!SHELLS[shell]) throw new CliError(`shell must be one of: ${Object.keys(SHELLS).join(', ')}`);
+  return SHELLS[shell](commandPaths(registry));
+}
+
+module.exports = {
+  summary: 'Generate the autocompletion script for a shell',
+  usage: 'motherbase completion <bash|zsh|fish>',
+  run(ctx, args) {
+    const shell = requireArg(args[0], 'shell');
+    // Required here, not at the top: the registry itself requires this file.
+    const { registry } = require('./index');
+    process.stdout.write(completionScript(shell, registry));
+  },
+  completionScript,
+};