@motherbase/cli 0.2.5 → 0.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motherbase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -146,7 +146,8 @@ emits, so `createClient<Database>(url, key)` types every row, rejects unknown
 columns and types `.rpc()` calls:
 
 ```bash
-motherbase gen types typescript > database.types.ts
+motherbase gen types typescript            # in a terminal: writes ./database.types.ts
+motherbase gen types typescript > database.types.ts   # piped: prints the file
 motherbase gen types typescript --schema shop --output src/shop.types.ts
 ```
 

package/bin/.motherbase/config.json

@@ -0,0 +1,5 @@
+{
+  "consoleUrl": "https://console.test.fidelix.pro",
+  "projectId": "gvask8",
+  "projectName": "gvask8"
+}

package/package.json

@@ -1,26 +1,35 @@
-{
-  "name": "@motherbase/cli",
-  "version": "0.2.5",
-  "description": "Motherbase operator CLI: drives the Platform Console and linked projects.",
-  "type": "commonjs",
-  "bin": {
-    "motherbase": "./bin/motherbase.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint ."
-  },
-  "files": [
-    "bin",
-    "src",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "dependencies": {}
-}
+{
+  "name": "@motherbase/cli",
+  "version": "0.2.8",
+  "description": "Motherbase operator CLI: drives the Platform Console and linked projects.",
+  "type": "commonjs",
+  "bin": {
+    "motherbase": "./bin/motherbase.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "docs:cli": "node scripts/generate-cli-docs.js",
+    "lint": "eslint ."
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JulienGuinot/Boilerplate-backend.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/JulienGuinot/Boilerplate-backend#readme",
+  "bugs": {
+    "url": "https://github.com/JulienGuinot/Boilerplate-backend/issues"
+  }
+}

package/src/api.js

@@ -1,241 +1,256 @@
-'use strict';
-
-// The one and only HTTP layer. Every command routes through here so auth headers,
-// URL construction and error mapping live in a single place.
-//
-// URL shapes:
-//   console request      -> ${consoleUrl}/api/platform${path}
-//   admin (console mode) -> ${consoleUrl}/api/projects/${projectId}/admin${path}
-//   admin (direct mode)  -> ${directUrl}/api/admin${path}
-//   edge invoke (console)-> ${consoleUrl}/api/projects/${projectId}/edge/${route}
-//   edge invoke (direct) -> ${directUrl}/api/edge/${route}
-//
-// Auth: the console session token is sent as `Authorization: Bearer <token>`.
-// Success envelopes differ across surfaces; both wrap payload under `data`, so we
-// unwrap `body.data` when present. Non-2xx becomes a thrown CliError with the
-// status and a short message/body snippet.
-
-const fs = require('fs');
-const path = require('path');
-const { Readable } = require('stream');
-const { CliError } = require('./context');
-const ui = require('./ui');
-
-function buildQuery(query) {
-  if (!query) return '';
-  const params = new URLSearchParams();
-  for (const [k, v] of Object.entries(query)) {
-    if (v === undefined || v === null) continue;
-    params.append(k, String(v));
-  }
-  const s = params.toString();
-  return s ? `?${s}` : '';
-}
-
-function unwrap(body) {
-  if (body && typeof body === 'object' && 'data' in body) return body.data;
-  return body;
-}
-
-// Non-browser clients send no Origin header. Better Auth (and reverse proxies
-// that inject cookies) then treat the request as CSRF-suspect and reject it with
-// "Missing or null Origin". Sending the target's own origin (which the server
-// keeps in its trustedOrigins (baseURL)) satisfies that check for every route.
-function originFor(url) {
-  try { return new URL(url).origin; } catch { return undefined; }
-}
-
-function errorMessage(status, body, text) {
-  const snippet = (body && (body.message || body.error)) || (text ? text.slice(0, 300) : '');
-  if (status === 401) {
-    return `Unauthorized (401)${snippet ? `: ${snippet}` : ''}. Run \`motherbase login\` (or check --token).`;
-  }
-  if (status === 403) {
-    return `Forbidden (403)${snippet ? `: ${snippet}` : ''}.`;
-  }
-  if (status === 404) {
-    return `Not found (404)${snippet ? `: ${snippet}` : ''}.`;
-  }
-  return `Request failed (${status})${snippet ? `: ${snippet}` : ''}`;
-}
-
-// `--debug` (or MOTHERBASE_DEBUG=1): one stderr line per request. Never the
-// headers or body, which carry the token and passwords.
-function trace(method, url, res) {
-  if (!process.env.MOTHERBASE_DEBUG) return;
-  ui.printErr(ui.color.dim(`[debug] ${method} ${url} → ${res.status}`));
-}
-
-async function parseResponse(res) {
-  const text = await res.text();
-  let body;
-  if (text) {
-    try { body = JSON.parse(text); } catch { body = undefined; }
-  }
-  if (!res.ok) {
-    throw new CliError(errorMessage(res.status, body, text));
-  }
-  return body === undefined ? text : unwrap(body);
-}
-
-async function doFetch(url, { method = 'GET', token, body, headers = {} } = {}) {
-  const finalHeaders = { ...headers };
-  if (token) finalHeaders['authorization'] = `Bearer ${token}`;
-  if (!finalHeaders['origin']) {
-    const origin = originFor(url);
-    if (origin) finalHeaders['origin'] = origin;
-  }
-  let payload;
-  if (body !== undefined && body !== null) {
-    finalHeaders['content-type'] = 'application/json';
-    payload = JSON.stringify(body);
-  }
-  let res;
-  try {
-    res = await fetch(url, { method, headers: finalHeaders, body: payload });
-  } catch (err) {
-    throw new CliError(`Cannot reach ${url}: ${err.message}`);
-  }
-  trace(method, url, res);
-  return parseResponse(res);
-}
-
-// ── Console (account / multi-project) ────────────────────────────────────────
-
-function consoleRequest(ctx, method, apiPath, { body, query } = {}) {
-  const { consoleUrl, token } = ctx.requireConsole();
-  const url = `${consoleUrl}/api/platform${apiPath}${buildQuery(query)}`;
-  return doFetch(url, { method, token, body });
-}
-
-// Login is special: no token yet. Uses Better Auth's native sign-in endpoint;
-// the session token comes back in the body and/or the `set-auth-token` header
-// (bearer plugin). Returns `{ token, user }` so the caller can persist it.
-async function loginRequest(consoleUrl, email, password) {
-  const url = `${consoleUrl}/api/auth/sign-in/email`;
-  let res;
-  try {
-    const headers = { 'content-type': 'application/json' };
-    const origin = originFor(url);
-    if (origin) headers['origin'] = origin;
-    res = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({ email, password }),
-    });
-  } catch (err) {
-    throw new CliError(`Cannot reach ${url}: ${err.message}`);
-  }
-  trace('POST', url, res);
-  const text = await res.text();
-  let body;
-  if (text) { try { body = JSON.parse(text); } catch { body = undefined; } }
-  if (!res.ok) {
-    throw new CliError(errorMessage(res.status, body, text));
-  }
-  const token = (body && body.token) || res.headers.get('set-auth-token') || undefined;
-  return { token, user: body && body.user };
-}
-
-// ── Admin / resource (via proxy or direct) ───────────────────────────────────
-
-function adminBase(target) {
-  if (target.mode === 'direct') {
-    return { base: `${target.baseUrl}/api/admin`, token: target.token };
-  }
-  return { base: `${target.consoleUrl}/api/projects/${target.projectId}/admin`, token: target.token };
-}
-
-function adminRequest(ctx, method, apiPath, { body, query } = {}) {
-  const target = ctx.requireProject();
-  const { base, token } = adminBase(target);
-  const url = `${base}${apiPath}${buildQuery(query)}`;
-  return doFetch(url, { method, token, body });
-}
-
-// The public URL of a project path (`/edge/<route>`, `/rest/v1/<table>`), for
-// printing. Mirrors how the proxy addresses a project in each mode.
-function projectUrl(ctx, projectPath) {
-  const target = ctx.requireProject();
-  return target.mode === 'direct'
-    ? `${target.baseUrl}/api${projectPath}`
-    : `${target.consoleUrl}/api/projects/${target.projectId}${projectPath}`;
-}
-
-// Edge invoke goes through the un-authenticated edge route, not /admin.
-function edgeInvokeRequest(ctx, route, body) {
-  const url = projectUrl(ctx, `/edge/${encodeURIComponent(route)}`);
-  const target = ctx.requireProject();
-  return doFetch(url, { method: 'POST', token: target.token, body: body || {} });
-}
-
-// ── Multipart upload (native FormData/Blob; zero-dep on Node >=18) ────────────
-
-async function uploadFile(ctx, apiPath, filePath, fields = {}) {
-  const target = ctx.requireProject();
-  const { base, token } = adminBase(target);
-  const url = `${base}${apiPath}`;
-  const buf = fs.readFileSync(filePath);
-  const form = new FormData();
-  form.append('file', new Blob([buf]), path.basename(filePath));
-  for (const [k, v] of Object.entries(fields)) {
-    if (v !== undefined && v !== null) form.append(k, String(v));
-  }
-  const uploadHeaders = token ? { authorization: `Bearer ${token}` } : {};
-  const uploadOrigin = originFor(url);
-  if (uploadOrigin) uploadHeaders['origin'] = uploadOrigin;
-  let res;
-  try {
-    res = await fetch(url, {
-      method: 'POST',
-      headers: uploadHeaders,
-      body: form,
-    });
-  } catch (err) {
-    throw new CliError(`Cannot reach ${url}: ${err.message}`);
-  }
-  trace('POST', url, res);
-  return parseResponse(res);
-}
-
-// ── Streamed download to a local file ────────────────────────────────────────
-
-async function downloadFile(ctx, apiPath, destPath, { query } = {}) {
-  const target = ctx.requireProject();
-  const { base, token } = adminBase(target);
-  const url = `${base}${apiPath}${buildQuery(query)}`;
-  const dlHeaders = token ? { authorization: `Bearer ${token}` } : {};
-  const dlOrigin = originFor(url);
-  if (dlOrigin) dlHeaders['origin'] = dlOrigin;
-  let res;
-  try {
-    res = await fetch(url, { headers: dlHeaders });
-  } catch (err) {
-    throw new CliError(`Cannot reach ${url}: ${err.message}`);
-  }
-  trace('GET', url, res);
-  if (!res.ok) {
-    const text = await res.text().catch(() => '');
-    let body; try { body = JSON.parse(text); } catch { /* noop */ }
-    throw new CliError(errorMessage(res.status, body, text));
-  }
-  await new Promise((resolve, reject) => {
-    const out = fs.createWriteStream(destPath);
-    out.on('error', reject);
-    out.on('finish', resolve);
-    Readable.fromWeb(res.body).pipe(out);
-  });
-  return { path: destPath, contentType: res.headers.get('content-type') || undefined };
-}
-
-module.exports = {
-  consoleRequest,
-  loginRequest,
-  adminRequest,
-  edgeInvokeRequest,
-  projectUrl,
-  uploadFile,
-  downloadFile,
-  buildQuery,
-  unwrap,
-};
+'use strict';
+
+// The one and only HTTP layer. Every command routes through here so auth headers,
+// URL construction and error mapping live in a single place.
+//
+// URL shapes:
+//   console request      -> ${consoleUrl}/api/platform${path}
+//   admin (console mode) -> ${consoleUrl}/api/projects/${projectId}/admin${path}
+//   admin (direct mode)  -> ${directUrl}/api/admin${path}
+//
+// Auth: the console session token is sent as `Authorization: Bearer <token>`.
+// Success envelopes differ across surfaces; both wrap payload under `data`, so we
+// unwrap `body.data` when present. Non-2xx becomes a thrown CliError with the
+// status and a short message/body snippet.
+
+const fs = require('fs');
+const path = require('path');
+const { Readable } = require('stream');
+const { pipeline } = require('stream/promises');
+const { CliError } = require('./context');
+const ui = require('./ui');
+
+function buildQuery(query) {
+  if (!query) return '';
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined || v === null) continue;
+    params.append(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : '';
+}
+
+function unwrap(body) {
+  if (body && typeof body === 'object' && 'data' in body) return body.data;
+  return body;
+}
+
+// Non-browser clients send no Origin header. Better Auth (and reverse proxies
+// that inject cookies) then treat the request as CSRF-suspect and reject it with
+// "Missing or null Origin". Sending the target's own origin (which the server
+// keeps in its trustedOrigins (baseURL)) satisfies that check for every route.
+function originFor(url) {
+  try { return new URL(url).origin; } catch { return undefined; }
+}
+
+function errorMessage(status, body, text) {
+  const snippet = (body && (body.message || body.error)) || (text ? text.slice(0, 300) : '');
+  if (status === 401) {
+    return `Unauthorized (401)${snippet ? `: ${snippet}` : ''}. Run \`motherbase login\` (or check --token).`;
+  }
+  if (status === 403) {
+    return `Forbidden (403)${snippet ? `: ${snippet}` : ''}.`;
+  }
+  if (status === 404) {
+    return `Not found (404)${snippet ? `: ${snippet}` : ''}.`;
+  }
+  return `Request failed (${status})${snippet ? `: ${snippet}` : ''}`;
+}
+
+// `--debug` (or MOTHERBASE_DEBUG=1): one stderr line per request. Never the
+// headers or body, which carry the token and passwords.
+function trace(method, url, res) {
+  if (!process.env.MOTHERBASE_DEBUG) return;
+  ui.printErr(ui.color.dim(`[debug] ${method} ${url} → ${res.status}`));
+}
+
+async function parseResponse(res) {
+  const text = await res.text();
+  let body;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = undefined; }
+  }
+  if (!res.ok) {
+    throw new CliError(errorMessage(res.status, body, text));
+  }
+  return body === undefined ? text : unwrap(body);
+}
+
+async function doFetch(url, { method = 'GET', token, body, headers = {} } = {}) {
+  const finalHeaders = { ...headers };
+  if (token) finalHeaders['authorization'] = `Bearer ${token}`;
+  if (!finalHeaders['origin']) {
+    const origin = originFor(url);
+    if (origin) finalHeaders['origin'] = origin;
+  }
+  let payload;
+  if (body !== undefined && body !== null) {
+    finalHeaders['content-type'] = 'application/json';
+    payload = JSON.stringify(body);
+  }
+  let res;
+  try {
+    res = await fetch(url, { method, headers: finalHeaders, body: payload });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  trace(method, url, res);
+  return parseResponse(res);
+}
+
+// ── Console (account / multi-project) ────────────────────────────────────────
+
+function consoleRequest(ctx, method, apiPath, { body, query } = {}) {
+  const { consoleUrl, token } = ctx.requireConsole();
+  const url = `${consoleUrl}/api/platform${apiPath}${buildQuery(query)}`;
+  return doFetch(url, { method, token, body });
+}
+
+// Login is special: no token yet, so it talks to Better Auth's native endpoints
+// directly. Returns the raw response next to the parsed body because the token
+// lives in the `set-auth-token` header (bearer plugin) and the 2FA step needs
+// the response cookies.
+async function authPost(url, body, headers = {}) {
+  const finalHeaders = { 'content-type': 'application/json', ...headers };
+  const origin = originFor(url);
+  if (origin) finalHeaders['origin'] = origin;
+  let res;
+  try {
+    res = await fetch(url, { method: 'POST', headers: finalHeaders, body: JSON.stringify(body) });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  trace('POST', url, res);
+  const text = await res.text();
+  let parsed;
+  if (text) { try { parsed = JSON.parse(text); } catch { parsed = undefined; } }
+  if (!res.ok) {
+    throw new CliError(errorMessage(res.status, parsed, text));
+  }
+  return { res, body: parsed };
+}
+
+// The `two_factor` cookie (prefixed `__Secure-` on https) scopes the
+// verify-totp call to the pending sign-in.
+function twoFactorCookie(res) {
+  const setCookies = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : [];
+  const pair = setCookies.map(c => c.split(';')[0]).find(c => /two_factor=./.test(c));
+  if (!pair) throw new CliError('two-factor sign-in started but the server sent no two_factor cookie');
+  return pair;
+}
+
+// Returns `{ token, user }`, or `{ twoFactorCookie }` when the account has 2FA
+// enrolled. In that case Better Auth answers `{ twoFactorRedirect: true }` and
+// the `set-auth-token` header still carries the pre-2FA session it has just
+// deleted, so the header must not be trusted (see the console login route).
+async function loginRequest(consoleUrl, email, password) {
+  const { res, body } = await authPost(`${consoleUrl}/api/auth/sign-in/email`, { email, password });
+  if (body && body.twoFactorRedirect) return { twoFactorCookie: twoFactorCookie(res) };
+  const token = (body && body.token) || res.headers.get('set-auth-token') || undefined;
+  return { token, user: body && body.user };
+}
+
+// Second step of a 2FA sign-in: trade the TOTP code for the real session token.
+async function verifyTotpRequest(consoleUrl, cookie, code) {
+  const { res, body } = await authPost(`${consoleUrl}/api/auth/two-factor/verify-totp`, { code }, { cookie });
+  const token = res.headers.get('set-auth-token') || (body && body.token) || undefined;
+  return { token, user: body && body.user };
+}
+
+// ── Admin / resource (via proxy or direct) ───────────────────────────────────
+
+function adminBase(target) {
+  if (target.mode === 'direct') {
+    return { base: `${target.baseUrl}/api/admin`, token: target.token };
+  }
+  return { base: `${target.consoleUrl}/api/projects/${target.projectId}/admin`, token: target.token };
+}
+
+function adminRequest(ctx, method, apiPath, { body, query } = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}${buildQuery(query)}`;
+  return doFetch(url, { method, token, body });
+}
+
+// The public URL of a project path (`/edge/<route>`, `/rest/v1/<table>`), for
+// printing. Mirrors how the proxy addresses a project in each mode.
+function projectUrl(ctx, projectPath) {
+  const target = ctx.requireProject();
+  return target.mode === 'direct'
+    ? `${target.baseUrl}/api${projectPath}`
+    : `${target.consoleUrl}/api/projects/${target.projectId}${projectPath}`;
+}
+
+// ── Multipart upload (native FormData/Blob; zero-dep on Node >=18) ────────────
+
+async function uploadFile(ctx, apiPath, filePath, fields = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}`;
+  const buf = fs.readFileSync(filePath);
+  const form = new FormData();
+  form.append('file', new Blob([buf]), path.basename(filePath));
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== undefined && v !== null) form.append(k, String(v));
+  }
+  const uploadHeaders = token ? { authorization: `Bearer ${token}` } : {};
+  const uploadOrigin = originFor(url);
+  if (uploadOrigin) uploadHeaders['origin'] = uploadOrigin;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: uploadHeaders,
+      body: form,
+    });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  trace('POST', url, res);
+  return parseResponse(res);
+}
+
+// ── Streamed download to a local file ────────────────────────────────────────
+
+async function downloadFile(ctx, apiPath, destPath, { query } = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}${buildQuery(query)}`;
+  const dlHeaders = token ? { authorization: `Bearer ${token}` } : {};
+  const dlOrigin = originFor(url);
+  if (dlOrigin) dlHeaders['origin'] = dlOrigin;
+  let res;
+  try {
+    res = await fetch(url, { headers: dlHeaders });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  trace('GET', url, res);
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    let body; try { body = JSON.parse(text); } catch { /* noop */ }
+    throw new CliError(errorMessage(res.status, body, text));
+  }
+  try {
+    await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(destPath));
+  } catch (err) {
+    // A dropped connection leaves a truncated file that looks like a download.
+    fs.rmSync(destPath, { force: true });
+    throw new CliError(`Download failed: ${err.message}`);
+  }
+  return { path: destPath, contentType: res.headers.get('content-type') || undefined };
+}
+
+module.exports = {
+  consoleRequest,
+  loginRequest,
+  verifyTotpRequest,
+  adminRequest,
+  projectUrl,
+  uploadFile,
+  downloadFile,
+  buildQuery,
+  unwrap,
+};

package/src/commands/_util.js

@@ -2,6 +2,7 @@
 
 // Small shared helpers for command modules.
 
+const path = require('path');
 const { CliError } = require('../context');
 const { outputFormat, toYaml, toEnv } = require('../format');
 
@@ -90,4 +91,16 @@ function consoleProjectPath(ctx, suffix = '') {
   return `/projects/${encodeURIComponent(ctx.projectId)}${suffix}`;
 }
 
-module.exports = { parseKeyValues, output, alias, parseDotenv, requireArg, splitRef, consoleProjectPath };
+// 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 };