fluidcad 0.0.34 → 0.0.36

package/README.md

@@ -115,6 +115,11 @@ Import and export STEP files with full color support. Bring in existing CAD mode
 
 FluidCAD ships official extensions for **VS Code** and **Neovim**, but works with any editor -- just point the CLI at your project.
 
+### LLM / AI Agent Integration (MCP)
+
+FluidCAD ships an [MCP](https://modelcontextprotocol.io) server so AI agents (Claude Code, Claude Desktop, Cursor, opencode, etc.) can drive a running workspace -- take screenshots, inspect geometry, edit `.fluid.js` files, and look up the API by symbol. See [Set Up the MCP Server](#3-optional-set-up-the-mcp-server) below.
+
+
 ---
 
 ## Tutorials
@@ -234,6 +239,70 @@ This starts a local server and opens a 3D viewport in your browser. Edit your `.
 
 </details>
 
+### 3. (Optional) Set Up the MCP Server
+
+FluidCAD bundles an [MCP](https://modelcontextprotocol.io) server so LLM agents can drive your workspace -- screenshots, geometry inspection, source edits, API lookup. It's included in the `fluidcad` package; no separate install needed.
+
+Wire it into your MCP client:
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Register at user scope so it's available in every project:
+
+```bash
+claude mcp add --scope user FluidCAD -- npx -y fluidcad mcp
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop / Cursor</strong></summary>
+
+Add to `claude_desktop_config.json` or `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "FluidCAD": {
+      "command": "npx",
+      "args": ["-y", "fluidcad", "mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>opencode</strong></summary>
+
+Run `opencode mcp add` and answer the prompts, or add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "FluidCAD": {
+      "type": "local",
+      "command": ["npx", "-y", "fluidcad", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+</details>
+
+Then install the companion skill so agents follow the FluidCAD workflow:
+
+```bash
+npx skills add Fluid-CAD/FluidCAD
+```
+
+See the [MCP README](mcp/README.md) for the full tool surface, transport details, and local-testing guide.
+
+
 ---
 
 ## License

package/bin/commands/login.js

@@ -0,0 +1,148 @@
+import http from 'http';
+import os from 'os';
+import { randomBytes, createHash } from 'crypto';
+import { getHubUrl, writeCredentials } from '../lib/config.js';
+import { HubClient } from '../lib/api-client.js';
+import { readPackageVersion } from '../lib/workspace.js';
+import { openBrowser } from '../lib/browser.js';
+
+const CLIENT_ID = 'fluidcad-cli';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+function base64url(buf) {
+  return buf.toString('base64url');
+}
+
+const PLATFORM_NAMES = { darwin: 'macOS', win32: 'Windows', linux: 'Linux' };
+
+/**
+ * Human-readable device hints shown on the hub's authorize page so the user can
+ * confirm the request came from this machine. Display-only — the hub never uses
+ * them for the authorization decision (PKCE + loopback do that). The browser
+ * request already reveals OS/arch via its User-Agent, so this leaks nothing new.
+ */
+function deviceHints() {
+  const platform = PLATFORM_NAMES[process.platform] ?? process.platform;
+  // os.release() is the kernel/Darwin/NT version; the leading x.y.z is the
+  // useful part (e.g. "7.0.10-201.fc44.x86_64" → "7.0.10").
+  const release = os.release().split('-')[0];
+  return {
+    os: `${platform} ${release}`.trim(),
+    arch: process.arch,
+    version: readPackageVersion(),
+  };
+}
+
+/**
+ * Loopback + PKCE login (RFC 8252): spin up a one-shot 127.0.0.1 server, send
+ * the browser to the hub's /cli/authorize, receive the code on /callback,
+ * exchange it (with the PKCE verifier) for a token, and save it.
+ */
+function runLogin(opts) {
+  return new Promise((resolve, reject) => {
+    const hubUrl = getHubUrl(opts.hub);
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    const state = base64url(randomBytes(16));
+    let redirectUri;
+    let settled = false;
+
+    const finish = (fn, arg) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      server.close();
+      fn(arg);
+    };
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const error = url.searchParams.get('error');
+      const code = url.searchParams.get('code');
+      const returnedState = url.searchParams.get('state');
+
+      // The code has now been received here on the loopback; hand the browser
+      // to the hub's branded result screen (nav + design system) to finish.
+      const doneStatus = error ? 'denied' : code ? 'ok' : 'error';
+      res.writeHead(302, { location: `${hubUrl}/cli/done?status=${doneStatus}` });
+      res.end();
+
+      (async () => {
+        if (error) {
+          throw new Error(`authorization ${error}`);
+        }
+        if (returnedState !== state) {
+          throw new Error('state mismatch — aborting (possible CSRF)');
+        }
+        if (!code) {
+          throw new Error('no authorization code in callback');
+        }
+        const { status, body } = await new HubClient(hubUrl).postJson('/api/cli/token', {
+          client_id: CLIENT_ID,
+          code,
+          code_verifier: verifier,
+          redirect_uri: redirectUri,
+        });
+        if (status !== 200 || !body.access_token) {
+          throw new Error(`token exchange failed: ${body.error_description || body.error || `HTTP ${status}`}`);
+        }
+        writeCredentials({ token: body.access_token, email: body.user?.email ?? null, hubUrl });
+        return body.user?.email ?? null;
+      })().then(
+        (email) => finish(resolve, email),
+        (err) => finish(reject, err),
+      );
+    });
+
+    const timer = setTimeout(
+      () => finish(reject, new Error('login timed out — no response within 5 minutes')),
+      LOGIN_TIMEOUT_MS,
+    );
+
+    server.on('error', (err) => finish(reject, err));
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      redirectUri = `http://127.0.0.1:${port}/callback`;
+      const device = deviceHints();
+      const authorizeUrl =
+        `${hubUrl}/cli/authorize?` +
+        new URLSearchParams({
+          response_type: 'code',
+          client_id: CLIENT_ID,
+          redirect_uri: redirectUri,
+          code_challenge: challenge,
+          code_challenge_method: 'S256',
+          state,
+          // Display-only context for the approval screen (not part of PKCE).
+          client_version: device.version,
+          os: device.os,
+          arch: device.arch,
+        });
+      console.log('Opening your browser to authorize the FluidCAD CLI…');
+      console.log(`\n  ${authorizeUrl}\n`);
+      openBrowser(authorizeUrl);
+    });
+  });
+}
+
+export function registerLoginCommand(program) {
+  program
+    .command('login')
+    .description('Authenticate this machine with the FluidCAD hub')
+    .option('--hub <url>', 'Hub base URL (default: $FLUIDCAD_HUB_URL or https://hub.fluidcad.io)')
+    .action((opts) => {
+      runLogin(opts)
+        .then((email) => console.log(`Logged in as ${email ?? 'your account'}`))
+        .catch((err) => {
+          console.error(err?.message ?? err);
+          process.exit(1);
+        });
+    });
+}

package/bin/commands/mcp.js

@@ -1,5 +1,5 @@
 import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const mcpEntry = resolve(__dirname, '..', '..', 'mcp', 'dist', 'server.js');
@@ -10,7 +10,8 @@ async function runMcp() {
   console.log = (...args) => console.error(...args);
   console.info = (...args) => console.error(...args);
 
-  const mod = await import(mcpEntry);
+  // file:// URL required: Windows ESM loader rejects bare drive paths (D:\...).
+  const mod = await import(pathToFileURL(mcpEntry).href);
   if (typeof mod.runStdio !== 'function') {
     console.error('mcp/dist/server.js does not export runStdio.');
     process.exit(1);

package/bin/commands/pack.js

@@ -0,0 +1,49 @@
+import { writeFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { findEntry, readPackageVersion } from '../lib/workspace.js';
+
+async function runPack(opts) {
+  // The packer lives in server/ because esbuild + jszip belong at that layer;
+  // import it lazily so the rest of the CLI doesn't pay the cost.
+  const { packModel } = await import('../../server/dist/model-package/pack.js');
+
+  const workspace = resolve(opts.workspace ?? process.cwd());
+  const entry = findEntry(workspace, opts.entry);
+  const fluidcadVersion = readPackageVersion();
+
+  const { manifest, zip } = await packModel({
+    entryPath: entry,
+    workspacePath: workspace,
+    fluidcadVersion,
+    name: opts.name,
+    description: opts.description,
+  });
+
+  const outPath = opts.out
+    ? resolve(opts.out)
+    : resolve(workspace, basename(entry).replace(/\.fluid\.js$/i, '') + '.fluidpkg');
+  writeFileSync(outPath, zip);
+  const fileCount = manifest.files?.length ?? 0;
+  const assetCount = manifest.assets.length;
+  console.log(
+    `Wrote ${outPath} (${zip.length} bytes, ${fileCount} file${fileCount === 1 ? '' : 's'}, ` +
+      `${assetCount} asset${assetCount === 1 ? '' : 's'})`,
+  );
+}
+
+export function registerPackCommand(program) {
+  program
+    .command('pack')
+    .description('Package a .fluid.js model into a shareable .fluidpkg archive')
+    .option('-w, --workspace <path>', 'Workspace directory (defaults to cwd)')
+    .option('-e, --entry <file>', 'Entry .fluid.js file (auto-detected if only one exists)')
+    .option('-o, --out <path>', 'Output path (defaults to <entry-basename>.fluidpkg in the workspace)')
+    .option('-n, --name <name>', 'Package name (defaults to the entry file basename)')
+    .option('-d, --description <text>', 'Optional human description')
+    .action((opts) => {
+      runPack(opts).catch((err) => {
+        console.error(err?.message ?? err);
+        process.exit(1);
+      });
+    });
+}

package/bin/commands/publish.js

@@ -0,0 +1,231 @@
+import { resolve } from 'path';
+import { getHubUrl, readCredentials } from '../lib/config.js';
+import { HubClient } from '../lib/api-client.js';
+import { findEntry, readPackageVersion, readWorkspacePackage } from '../lib/workspace.js';
+import { readModelIdentity, writeModelConfig } from '../lib/model-config.js';
+import { isInteractive, select } from '../lib/prompt.js';
+import { openBrowser } from '../lib/browser.js';
+
+async function runPublish(opts) {
+  const creds = readCredentials();
+  if (!creds) {
+    throw new Error('Not logged in. Run `fluidcad login` first.');
+  }
+  const hubUrl = getHubUrl(opts.hub || creds.hubUrl);
+
+  const workspace = resolve(opts.workspace ?? process.cwd());
+  const entry = findEntry(workspace, opts.entry);
+
+  // Prefills from the model's own package.json + the stable identity from
+  // fluidcad.json (null on the first publish → the hub mints one).
+  const pkg = readWorkspacePackage(workspace);
+  const name = opts.name ?? pkg.name;
+  const description = opts.description ?? pkg.description;
+  const { modelId: priorModelId, name: priorName } = readModelIdentity(workspace);
+
+  // Surface who we are and where this is going *before* any bytes leave the
+  // machine, so a wrong account or hub is caught before the upload starts.
+  // (The model's own page URL is minted by the hub and printed afterwards.)
+  console.log('Publishing to the FluidCAD hub:');
+  console.log(`  account: ${creds.email || '(unknown account)'}`);
+  console.log(`  url:     ${hubUrl}`);
+  console.log('');
+
+  // Decide new-model vs new-version BEFORE the heavy build, so the user makes
+  // the call (and we do any model-list lookup) without first waiting ~110ms for
+  // the engine to load. A null target ⇒ the hub mints a fresh model.
+  const targetModelId = await resolveTargetModel({
+    opts,
+    hubUrl,
+    token: creds.token,
+    priorModelId,
+    priorName,
+  });
+  console.log(
+    targetModelId
+      ? `Publishing a new version${priorName ? ` of ${priorName}` : ''}.\n`
+      : 'Publishing as a new model.\n',
+  );
+
+  // Render once to capture the full param schema for the manifest. This also
+  // acts as a build gate — a compile/runtime error fails the publish here,
+  // before anything is uploaded.
+  //
+  // Dynamic import is deliberate (and necessary): this pulls in the whole
+  // engine — Vite + OC wasm, ~40MB / ~110ms. bin/fluidcad.js eagerly loads
+  // every command module at startup, so a top-level import here would make
+  // `init`, `serve`, `login`, `--help` etc. pay that cost too. Loading it only
+  // when `publish` actually runs is the justified exception to "no inline
+  // imports".
+  console.log('Building model…');
+  const { captureParamDefinitions } = await import(
+    '../../server/dist/model-package/capture-params.js'
+  );
+  let paramDefinitions;
+  try {
+    paramDefinitions = await captureParamDefinitions(entry, workspace);
+  } catch (err) {
+    throw new Error(`Model failed to build — fix the error and retry:\n${err?.message ?? err}`);
+  }
+
+  // Pack the whole workspace (Pack v2), embedding the captured params. Lazy
+  // import for the same reason (keeps esbuild/jszip off the startup path of
+  // non-publish commands), consistent with how `pack` loads it.
+  const { packModel } = await import('../../server/dist/model-package/pack.js');
+  const { manifest, zip } = await packModel({
+    entryPath: entry,
+    workspacePath: workspace,
+    fluidcadVersion: readPackageVersion(),
+    name,
+    description,
+    paramDefinitions,
+  });
+
+  // Show exactly what's going up so stray files/secrets get caught before they
+  // leave the machine (the .gitignore guard plus an always-exclude list).
+  const files = manifest.files ?? [];
+  console.log(`\nUploading ${files.length} file${files.length === 1 ? '' : 's'} (${(zip.length / 1024).toFixed(1)} KB):`);
+  for (const f of files) {
+    console.log(`  ${f}`);
+  }
+
+  const form = new FormData();
+  form.append('fluidpkg', new Blob([zip], { type: 'application/zip' }), 'model.fluidpkg');
+  if (targetModelId) {
+    form.append('modelId', targetModelId);
+  }
+  if (name) {
+    form.append('name', name);
+  }
+  if (opts.visibility) {
+    form.append('visibility', opts.visibility);
+  }
+
+  const { status, body } = await new HubClient(hubUrl, creds.token).postForm('/api/publish', form);
+  if (status === 401) {
+    throw new Error('Your session has expired. Run `fluidcad login` again.');
+  }
+  if (status === 403) {
+    throw new Error(body.error || 'That model belongs to another account.');
+  }
+  if (status === 422) {
+    throw new Error(body.error || 'That FluidCAD version is not hosted yet.');
+  }
+  if (status !== 200 && status !== 201) {
+    throw new Error(body.error || `Publish failed (HTTP ${status})`);
+  }
+
+  // Persist the hub-authoritative id (and the name we used) whenever it changed
+  // or the workspace had no config — covers the first publish, a deliberate new
+  // model, and re-attaching a deleted fluidcad.json (the user picked an existing
+  // model from the list). An owned-match with an unchanged name is a no-op.
+  if (body.modelId && (body.modelId !== priorModelId || (name && name !== priorName))) {
+    writeModelConfig(workspace, { modelId: body.modelId, name });
+  }
+
+  console.log('');
+  if (body.isNewVersion) {
+    console.log(`A new version (v${body.version}) will be published — add details in your browser.`);
+  } else {
+    console.log('Created model — finish setup in your browser.');
+  }
+
+  if (body.formUrl) {
+    const formUrl = body.formUrl.startsWith('http') ? body.formUrl : hubUrl + body.formUrl;
+    console.log(`\n  ${formUrl}\n`);
+    await openBrowser(formUrl);
+  } else if (body.shareUrl) {
+    // Fallback for a pre-v2 hub that deployed synchronously and has no form.
+    console.log(`\n  ${body.shareUrl}\n`);
+  }
+}
+
+/**
+ * Decide which model this publish targets: an existing model id (→ a new
+ * version) or null (→ the hub mints a new model). Honors --new-model /
+ * --new-version; otherwise asks when interactive; and with no TTY falls back to
+ * today's behavior (a saved fluidcad.json id ⇒ a version, else a new model).
+ */
+async function resolveTargetModel({ opts, hubUrl, token, priorModelId, priorName }) {
+  if (opts.newModel && opts.newVersion) {
+    throw new Error('Pass only one of --new-model / --new-version.');
+  }
+  if (opts.newModel) return null;
+  if (opts.newVersion) {
+    if (priorModelId) return priorModelId;
+    if (isInteractive()) return pickExistingModel(hubUrl, token);
+    throw new Error(
+      'No fluidcad.json here, so there is no model to version. Drop --new-version to ' +
+        'publish a new model, or run interactively to pick an existing one.',
+    );
+  }
+
+  // No explicit flag.
+  if (!isInteractive()) {
+    // Non-interactive (CI, piped input): keep the historical default.
+    return priorModelId;
+  }
+  if (priorModelId) {
+    const label = priorName ? `${priorName} (${priorModelId})` : priorModelId;
+    return select('How should this publish go up?', [
+      { label: `Publish a new version of ${label}`, value: priorModelId },
+      { label: 'Publish as a new model', value: null },
+    ]);
+  }
+  const choice = await select('How should this publish go up?', [
+    { label: 'Publish a new version of an existing model', value: '__existing__' },
+    { label: 'Publish as a new model', value: null },
+  ]);
+  return choice === '__existing__' ? pickExistingModel(hubUrl, token) : null;
+}
+
+/**
+ * Fetch the user's own models from the hub and let them pick which one this is a
+ * new version of. Returns the chosen model id, or null when they have none yet
+ * (the caller then mints a new model).
+ */
+async function pickExistingModel(hubUrl, token) {
+  const { status, body } = await new HubClient(hubUrl, token).getJson('/api/cli/models');
+  if (status === 401) {
+    throw new Error('Your session has expired. Run `fluidcad login` again.');
+  }
+  if (status !== 200) {
+    throw new Error(body.error || `Could not list your models (HTTP ${status})`);
+  }
+  const models = Array.isArray(body.models) ? body.models : [];
+  if (models.length === 0) {
+    console.log('\nYou have no models on the hub yet — publishing this as a new model.\n');
+    return null;
+  }
+  return select(
+    'Which model is this a new version of?',
+    models.map((m) => ({
+      label: `${m.name} · ${m.latestVersion ? 'v' + m.latestVersion : 'no versions yet'}`,
+      value: m.id,
+    })),
+  );
+}
+
+export function registerPublishCommand(program) {
+  program
+    .command('publish')
+    .description('Pack the current model and publish it to the FluidCAD hub')
+    .option('-w, --workspace <path>', 'Workspace directory (defaults to cwd)')
+    .option('-e, --entry <file>', 'Entry .fluid.js file (auto-detected if only one exists)')
+    .option('-n, --name <name>', 'Model name (defaults to the package name)')
+    .option('-d, --description <text>', 'Optional human description')
+    .option('--new-model', 'Publish as a new model, ignoring any saved model id')
+    .option('--new-version', 'Publish a new version of the saved (or chosen) model')
+    .option('--visibility <visibility>', 'public | unlisted | private (default: unlisted)')
+    .option('--hub <url>', 'Hub base URL (default: the hub you logged into)')
+    .action((opts) => {
+      runPublish(opts)
+        // The render spins up engine + Vite handles; exit explicitly so a
+        // successful publish doesn't hang waiting for the loop to drain.
+        .then(() => process.exit(0))
+        .catch((err) => {
+          console.error(err?.message ?? err);
+          process.exit(1);
+        });
+    });
+}

package/bin/fluidcad.js

@@ -7,6 +7,9 @@ import { fileURLToPath } from 'url';
 import { registerInitCommand } from './commands/init.js';
 import { registerServeCommand } from './commands/serve.js';
 import { registerMcpCommand } from './commands/mcp.js';
+import { registerPackCommand } from './commands/pack.js';
+import { registerLoginCommand } from './commands/login.js';
+import { registerPublishCommand } from './commands/publish.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
@@ -19,5 +22,8 @@ const program = new Command()
 registerInitCommand(program);
 registerServeCommand(program);
 registerMcpCommand(program);
+registerPackCommand(program);
+registerLoginCommand(program);
+registerPublishCommand(program);
 
 program.parseAsync(process.argv);

package/bin/lib/api-client.js

@@ -0,0 +1,48 @@
+import { getHubUrl } from './config.js';
+
+/**
+ * Tiny client for the hub API. The CLI commands are pure API clients — open a
+ * browser, store a token, POST a package — so this just wraps `fetch` with the
+ * bearer header and a uniform `{ status, body }` result.
+ */
+export class HubClient {
+  constructor(hubUrl, token) {
+    this.base = getHubUrl(hubUrl);
+    this.token = token;
+  }
+
+  #authHeaders(extra = {}) {
+    return { ...(this.token ? { authorization: `Bearer ${this.token}` } : {}), ...extra };
+  }
+
+  async #result(res) {
+    const body = await res.json().catch(() => ({}));
+    return { status: res.status, body };
+  }
+
+  async getJson(path) {
+    const res = await fetch(this.base + path, {
+      method: 'GET',
+      headers: this.#authHeaders(),
+    });
+    return this.#result(res);
+  }
+
+  async postJson(path, body) {
+    const res = await fetch(this.base + path, {
+      method: 'POST',
+      headers: this.#authHeaders({ 'content-type': 'application/json' }),
+      body: JSON.stringify(body),
+    });
+    return this.#result(res);
+  }
+
+  async postForm(path, form) {
+    const res = await fetch(this.base + path, {
+      method: 'POST',
+      headers: this.#authHeaders(),
+      body: form,
+    });
+    return this.#result(res);
+  }
+}

package/bin/lib/browser.js

@@ -0,0 +1,16 @@
+import open from 'open';
+
+/**
+ * Best-effort browser open, shared by `login` and `publish`. The caller always
+ * prints the URL too, so a failure here (headless box, SSH, no DISPLAY) is
+ * non-fatal — the user can open it manually.
+ */
+export async function openBrowser(url) {
+  try {
+    const child = await open(url);
+    // Detach so a one-shot CLI process isn't held open by the browser handle.
+    child.unref?.();
+  } catch {
+    /* ignore — the URL is printed regardless */
+  }
+}

package/bin/lib/config.js

@@ -0,0 +1,39 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from 'fs';
+
+// Where the CLI keeps its hub credentials. XDG-ish; one file, mode 0600.
+const CONFIG_DIR = join(homedir(), '.config', 'fluidcad');
+export const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials.json');
+
+const DEFAULT_HUB_URL = 'https://hub.fluidcad.io';
+
+/** Resolve the hub base URL: explicit override → $FLUIDCAD_HUB_URL → default. */
+export function getHubUrl(override) {
+  const url = override || process.env.FLUIDCAD_HUB_URL || DEFAULT_HUB_URL;
+  return url.replace(/\/+$/, '');
+}
+
+/** Read saved credentials, or null if not logged in / unreadable. */
+export function readCredentials() {
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf8'));
+    return creds && creds.token ? creds : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist credentials at mode 0600 (re-chmod in case the file pre-existed). */
+export function writeCredentials(creds) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(CREDENTIALS_PATH, 0o600);
+}
+
+/** Forget saved credentials (used by `logout`). */
+export function clearCredentials() {
+  if (existsSync(CREDENTIALS_PATH)) {
+    writeFileSync(CREDENTIALS_PATH, '{}\n', { mode: 0o600 });
+  }
+}