stoaken 0.1.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # stoaken
 
-The official CLI for [Stoaken](https://stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
+The official CLI for [Stoaken](https://www.stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
 
 ## Quickstart
 
@@ -13,10 +13,35 @@ Run it in the root of the project you want connected to a Stoaken Brand. It will
 1. Ask how you'd like to sign in -- open your browser for a real OAuth 2.1 login, or let you paste an API key you've already created at `/settings/api-keys`.
 2. List the real Brands your account can see, and let you pick one.
 3. Write `stoaken.config.json` (which Brand, which server -- safe to commit, holds no secret) and `.stoaken/credentials.json` (your bearer credential, `chmod 600`, automatically added to `.gitignore`).
-4. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents (Claude Code, Cursor) explaining how to connect to this project's Stoaken MCP server and what its tools do.
+4. Ask which AI tool to connect (or take `--client`) and write that tool's MCP config.
+5. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents explaining how this project connects to Stoaken's MCP server and what its tools do.
 
 Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
 
+## Connect an AI tool
+
+```
+npx stoaken init --client cursor
+```
+
+| `--client` | What init writes |
+| --- | --- |
+| `claude-code` | `.mcp.json` (`mcpServers.stoaken`, `type: http`) |
+| `cursor` | `.cursor/mcp.json` (`mcpServers.stoaken`) |
+| `codex` | `.codex/config.toml` (`[mcp_servers.stoaken]`; loads for trusted projects only) |
+| `copilot` | `.vscode/mcp.json` (`servers.stoaken`, VS Code agent mode) |
+| `claude-desktop` | Nothing: prints the steps to add a custom connector (Customize > Connectors) |
+| `v0` | Nothing: prints the steps to add a custom MCP server in v0 (+ > MCPs) |
+
+init merges: other servers in the file are kept and only the `stoaken` entry is replaced. If the
+file isn't plain JSON (for example `.vscode/mcp.json` with comments) it is left alone and you're told.
+No secret goes into these files, so they are safe to commit:
+
+- Signed in with the browser: the entry has just the URL, and the tool signs you in itself with
+  OAuth (Claude Code `/mcp`, Cursor Connect, `codex mcp login stoaken`, VS Code Start).
+- Pasted an API key: the entry reads the `STOAKEN_API_KEY` environment variable (VS Code instead
+  asks for the key once and stores it securely).
+
 ## Authentication
 
 Two paths, both landing on the same bearer credential:
@@ -24,9 +49,59 @@ Two paths, both landing on the same bearer credential:
 - **Log in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata), registers itself as an OAuth client on first run, and opens your browser to sign in.
 - **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one at `/settings/api-keys` in the Stoaken app.
 
+## Export your tokens as code
+
+`stoaken export` writes a theme's live release as a file: CSS variables, W3C JSON, Style
+Dictionary v4 JSON, or a JS/TS module. There are no timestamps in the output, so committed files
+give clean diffs.
+
+```sh
+npx stoaken export --theme Default --format css --out src/styles/tokens.css
+npx stoaken export --theme Default --format json-dtcg --mode color-scheme:dark --out tokens/dark.json
+npx stoaken export --theme Default --format ts --out src/tokens.ts
+npx stoaken export --theme Default --out -        # to stdout
+```
+
+| Option | |
+| --- | --- |
+| `--theme <name\|id>` | Which theme (needed when the Brand has more than one) |
+| `--format` | `css` (default), `json-dtcg`, `json-sd4`, `js`, `ts` |
+| `--mode <key>` | A mode combination for the one-mode formats; CSS includes every mode |
+| `--prefix <prefix>` | CSS only: a prefix for every variable name |
+| `--release <id>` | One release (e.g. one still in review) instead of the live one |
+| `--out <file\|->` | Where to write; default is the server's file name |
+| `--check` | Write nothing; exit 1 if the file on disk is out of date |
+
+Save your targets in `stoaken.config.json` and a plain `npx stoaken export` runs them all
+(`npx stoaken export --check` checks them all):
+
+```json
+{
+  "brandId": "…",
+  "brandName": "Acme",
+  "serverUrl": "https://www.stoaken.com",
+  "exports": [
+    { "theme": "Default", "format": "css", "out": "src/styles/tokens.css" },
+    { "theme": "Default", "format": "ts", "out": "src/tokens.ts" }
+  ]
+}
+```
+
+**In CI**, set `STOAKEN_TOKEN` to an API key (Settings > API keys); it's used instead of the
+sign-in saved by `stoaken init`. For example, to fail a build when the committed tokens are behind
+the live release:
+
+```sh
+STOAKEN_TOKEN=${{ secrets.STOAKEN_TOKEN }} npx stoaken export --check
+```
+
+`--check` ignores CRLF vs LF line endings (unreleased change, Stage 332), so Windows runners
+that check files out as CRLF don't fail it. Ready-made pipelines for GitHub Actions, GitLab CI,
+Bitbucket Pipelines, Azure Pipelines and Vercel builds: see /docs/webhooks#ci and /docs/cli#ci.
+
 ## What this connects to
 
-Once set up, any MCP-capable client (Claude Code, Cursor, Claude Desktop) or a direct HTTP client can use the credential in `.stoaken/credentials.json` as a Bearer token against Stoaken's MCP server, which exposes four tools:
+Once set up, any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Copilot, v0) or a direct HTTP client can reach Stoaken's MCP server at `/mcp`. Its main tools (full list at /docs/mcp):
 
 - `list_brands` -- every Brand you hold at least Viewer on.
 - `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as p3 from "@clack/prompts";
+import * as p4 from "@clack/prompts";
 
 // src/commands/init.ts
 import * as p2 from "@clack/prompts";
@@ -44,6 +44,14 @@ async function writeCredentials(cwd, credentials) {
   await writeFile(path, `${JSON.stringify(credentials, null, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
+async function readCredentials(cwd) {
+  try {
+    const raw = await readFile(join(cwd, CREDENTIALS_FILE), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 async function readOAuthClient(cwd) {
   try {
     const raw = await readFile(join(cwd, OAUTH_CLIENT_FILE), "utf8");
@@ -121,7 +129,7 @@ function generatePkce() {
   return { verifier, challenge };
 }
 function waitForCallback() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const server = createServer((req, res) => {
       const url = new URL(req.url ?? "/", REDIRECT_URI);
       if (url.pathname !== "/callback") {
@@ -140,7 +148,7 @@ function waitForCallback() {
       } else if (!code) {
         reject(new Error("No authorization code in the callback"));
       } else {
-        resolve(code);
+        resolve2(code);
       }
     });
     server.on("error", reject);
@@ -189,8 +197,8 @@ async function promptForApiKey() {
   const key = await p.password({
     message: "Paste your Stoaken API key (from /settings/api-keys):",
     validate: (value) => {
-      if (!value?.startsWith("twk_")) {
-        return "That doesn't look like a Stoaken API key (should start with twk_)";
+      if (!value?.startsWith("stk_") && !value?.startsWith("twk_")) {
+        return "That doesn't look like a Stoaken API key (should start with stk_)";
       }
     }
   });
@@ -201,13 +209,12 @@ async function promptForApiKey() {
 }
 
 // src/mcp-client.ts
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 async function listBrands(serverUrl, credential) {
   const transport = new StreamableHTTPClientTransport(new URL("/mcp", serverUrl), {
     requestInit: { headers: { Authorization: `Bearer ${credential}` } }
   });
-  const client = new Client({ name: "stoaken-cli", version: "0.1.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.4.0" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -221,20 +228,178 @@ async function listBrands(serverUrl, credential) {
   }
 }
 
+// src/client-config.ts
+var CLIENTS = ["claude-code", "claude-desktop", "cursor", "codex", "copilot", "v0"];
+var SERVER_NAME = "stoaken";
+var API_KEY_ENV = "STOAKEN_API_KEY";
+var CLIENT_LABELS = {
+  "claude-code": "Claude Code",
+  "claude-desktop": "Claude Desktop / claude.ai",
+  cursor: "Cursor",
+  codex: "OpenAI Codex",
+  copilot: "GitHub Copilot (VS Code)",
+  v0: "v0 (Vercel)"
+};
+function isClient(value) {
+  return CLIENTS.includes(value);
+}
+function mcpUrl(serverUrl) {
+  return `${serverUrl.replace(/\/+$/, "")}/mcp`;
+}
+function planFor(client, auth, serverUrl) {
+  const url = mcpUrl(serverUrl);
+  const keyStep = `Set ${API_KEY_ENV} in your shell to an API key from Settings > API keys (never commit it).`;
+  switch (client) {
+    case "claude-code":
+      return {
+        file: ".mcp.json",
+        nextSteps: auth === "oauth" ? ["Start Claude Code, approve the project server, then run /mcp and choose stoaken to sign in."] : [keyStep, "Start Claude Code and approve the project server."]
+      };
+    case "cursor":
+      return {
+        file: ".cursor/mcp.json",
+        nextSteps: auth === "oauth" ? ["Open Cursor Settings > MCP, enable stoaken and click Connect to sign in."] : [keyStep, "Restart Cursor so it picks up the variable, then enable stoaken in Settings > MCP."]
+      };
+    case "codex":
+      return {
+        file: ".codex/config.toml",
+        nextSteps: auth === "oauth" ? ["Trust this project in Codex (project config only loads for trusted projects).", "Run: codex mcp login stoaken"] : [keyStep, "Trust this project in Codex (project config only loads for trusted projects)."]
+      };
+    case "copilot":
+      return {
+        file: ".vscode/mcp.json",
+        nextSteps: auth === "oauth" ? ["In VS Code open .vscode/mcp.json, click Start above stoaken and sign in in the browser.", "Use Copilot Chat in Agent mode."] : ["In VS Code open .vscode/mcp.json, click Start above stoaken and paste an API key when asked (VS Code stores it securely).", "Use Copilot Chat in Agent mode."]
+      };
+    case "claude-desktop":
+      return {
+        file: null,
+        nextSteps: [
+          "Claude Desktop and claude.ai add remote servers as connectors, not through a project file.",
+          "Customize > Connectors > + Add > Add custom connector.",
+          `Name: Stoaken. URL: ${url}. Sign in with OAuth (Register automatically), or add the header Authorization: Bearer <API key>.`,
+          "On Team/Enterprise only an Owner can add it. Connections come from Anthropic's cloud, so this needs the public server."
+        ]
+      };
+    case "v0":
+      return {
+        file: null,
+        nextSteps: [
+          "v0 adds MCP servers in its own UI, not through a project file.",
+          "In a v0 chat: + > MCPs > custom server.",
+          `URL: ${url}. Auth: OAuth, or Bearer Token with an API key from Settings > API keys.`,
+          "v0 uses the tools while it generates; the app it builds cannot call them."
+        ]
+      };
+  }
+}
+function jsonEntry(client, auth, serverUrl) {
+  const url = mcpUrl(serverUrl);
+  if (client === "claude-code") {
+    return auth === "oauth" ? { type: "http", url } : { type: "http", url, headers: { Authorization: `Bearer \${${API_KEY_ENV}}` } };
+  }
+  if (client === "cursor") {
+    return auth === "oauth" ? { url } : { url, headers: { Authorization: `Bearer \${env:${API_KEY_ENV}}` } };
+  }
+  return auth === "oauth" ? { type: "http", url } : { type: "http", url, headers: { Authorization: "Bearer ${input:stoaken-api-key}" } };
+}
+var ConfigMergeError = class extends Error {
+};
+function parseObject(existing, file) {
+  if (existing === null || existing.trim() === "") return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    throw new ConfigMergeError(`${file} isn't plain JSON (comments?), so it was left alone. Add the stoaken entry by hand.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ConfigMergeError(`${file} isn't a JSON object, so it was left alone.`);
+  }
+  return parsed;
+}
+var COPILOT_INPUT = {
+  type: "promptString",
+  id: "stoaken-api-key",
+  description: "Stoaken API key (Settings > API keys)",
+  password: true
+};
+function mergeJsonConfig(client, existing, auth, serverUrl) {
+  const file = planFor(client, auth, serverUrl).file;
+  const doc = parseObject(existing, file);
+  const key = client === "copilot" ? "servers" : "mcpServers";
+  const current = doc[key];
+  if (current !== void 0 && (typeof current !== "object" || current === null || Array.isArray(current))) {
+    throw new ConfigMergeError(`${file} has a "${key}" that isn't an object, so it was left alone.`);
+  }
+  doc[key] = { ...current, [SERVER_NAME]: jsonEntry(client, auth, serverUrl) };
+  if (client === "copilot") {
+    const inputs = Array.isArray(doc.inputs) ? doc.inputs : [];
+    const others = inputs.filter((i) => !(typeof i === "object" && i !== null && i.id === COPILOT_INPUT.id));
+    if (auth === "api_key") doc.inputs = [...others, COPILOT_INPUT];
+    else if (doc.inputs !== void 0) doc.inputs = others;
+  }
+  return `${JSON.stringify(doc, null, 2)}
+`;
+}
+function codexTable(auth, serverUrl) {
+  const lines = [`[mcp_servers.${SERVER_NAME}]`, `url = ${JSON.stringify(mcpUrl(serverUrl))}`];
+  if (auth === "api_key") lines.push(`bearer_token_env_var = "${API_KEY_ENV}"`);
+  return `${lines.join("\n")}
+`;
+}
+function mergeCodexToml(existing, auth, serverUrl) {
+  const table = codexTable(auth, serverUrl);
+  if (existing === null || existing.trim() === "") return table;
+  const header = /^\s*\[\s*mcp_servers\.(?:stoaken|"stoaken")\s*(?:\]|\.)/;
+  const anyHeader = /^\s*\[/;
+  const kept = [];
+  let skipping = false;
+  for (const line of existing.split("\n")) {
+    if (header.test(line)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && anyHeader.test(line)) skipping = false;
+    if (!skipping) kept.push(line);
+  }
+  const body = kept.join("\n").replace(/\n+$/, "");
+  return body === "" ? table : `${body}
+
+${table}`;
+}
+
 // src/skill-template.ts
-function generateSkillFile(config) {
+function connectSection(target, serverUrl) {
+  if (!target) {
+    return `Connect with the credential in \`.stoaken/credentials.json\` as a Bearer token (never commit that
+file -- it's already in \`.gitignore\`).
+`;
+  }
+  const { client, auth } = target;
+  const plan = planFor(client, auth, serverUrl);
+  const how = auth === "oauth" ? "the client signs in with OAuth" : `it reads the \`${API_KEY_ENV}\` environment variable`;
+  const where = plan.file ? `It is configured for ${CLIENT_LABELS[client]} in \`${plan.file}\` (no secret in that file: ${how}).` : `${CLIENT_LABELS[client]} connects through its own settings, not a project file.`;
+  return `${where}
+
+${plan.nextSteps.map((step) => `- ${step}`).join("\n")}
+`;
+}
+function generateSkillFile(config, client) {
   return `# Working with Stoaken
 
 This project is connected to the **${config.brandName}** Brand on Stoaken (\`${config.serverUrl}\`).
 
-Stoaken's MCP server exposes four tools. Connect to it at \`${config.serverUrl}/mcp\` using
-the credential in \`.stoaken/credentials.json\` as a Bearer token (never commit that file --
-it's already in \`.gitignore\`).
-
+Stoaken's MCP server exposes the tools below at \`${mcpUrl(config.serverUrl)}\`.
+${connectSection(client, config.serverUrl)}
 ## Tools
 
 - **list_brands** -- every Brand you hold at least Viewer on.
-- **get_theme_tokens(themeId)** -- a Theme's cascade-merged token tree.
+- **get_theme_tokens(themeId)** -- a Theme's cascade-merged token tree (aliases left raw).
+- **get_resolved_theme_tokens(themeId, mode?)** -- a Theme's fully resolved tokens (aliases followed,
+  inheritance applied) for every mode-combination, or just \`mode\`.
+- **list_deprecated_tokens(themeId, mode?)** -- deprecated tokens, each with its notice, its named
+  replacement, and the tokens still referencing it. **Don't use a deprecated token in new code --
+  use its replacement.** A resolved token carrying \`$deprecated\` is deprecated.
 - **list_releases(themeId)** -- a Theme's Releases with version, status, and change summary.
 - **propose_token_change(themeId, tokenSetId, document, version, versionType)** -- updates a Token
   Set's document and submits a new Release for approval. **This never publishes.** The Release
@@ -242,6 +407,16 @@ it's already in \`.gitignore\`).
   Command Center before it goes live -- exactly the same gate a person editing through the UI
   goes through. There is no tool that publishes a Release; propose changes, then ask a human to
   review them.
+- **list_webhooks / create_webhook / update_webhook / rotate_webhook_secret / ping_webhook** -- manage a Brand's webhooks (Admin on the Brand; Team plan). A created or rotated secret is returned once; after a rotation the old secret keeps signing for 24 hours.
+- **create_theme / update_theme / delete_theme** -- manage a Brand's themes: which token sets they stack and in what order (Editor on the Brand; Team plan). create_theme can copy another theme's modes. Settings, not token changes: no release needed. Only never-released themes can be deleted.
+- **export_tokens(themeId | releaseId, format, mode?, prefix?)** -- read-only: a live release as a file (css, css-auto, scss, tailwind, tailwind4, swift, android, compose, json-dtcg, json-sd4, js, ts). Use it to update a project's committed token file.
+- **propose_token_edits(themeId, tokenSetId, operations, version, versionType, baseHash?)** -- the
+  same review gate, but with targeted edits instead of a whole document: \`set\`, \`add\`,
+  \`rename\` (references follow), \`delete\`, \`rename_group\` and \`describe\`, applied all or
+  nothing. Prefer it to propose_token_change for small changes.
+- **propose_token_deprecation(themeId, tokenPath, action, replacement?, note?, version)** --
+  deprecates (or un-deprecates) one token, naming its replacement, and submits a Release for review
+  the same way. Deprecation is a reviewed change, never a silent edit.
 
 ## This Brand
 
@@ -249,12 +424,21 @@ it's already in \`.gitignore\`).
 - Brand name: ${config.brandName}
 - Server: ${config.serverUrl}
 
+## Tokens as code
+
+\`npx stoaken export --theme <name> --format css|css-auto|scss|tailwind|tailwind4|swift|android|compose|json-dtcg|json-sd4|js|ts --out <file>\` writes a
+theme's live release as a file (no timestamps, so diffs stay clean). \`--check\` fails when the
+committed file is out of date. In CI, set \`STOAKEN_TOKEN\` to an API key.
+
 Re-run \`stoaken init\` if you need to switch Brands or re-authenticate.
 `;
 }
 
 // src/commands/init.ts
-var DEFAULT_SERVER_URL = "https://stoaken.com";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname, join as join2 } from "path";
+var DEFAULT_SERVER_URL = "https://www.stoaken.com";
 async function runInit(options) {
   const cwd = process.cwd();
   const serverUrl = options.server ?? DEFAULT_SERVER_URL;
@@ -340,13 +524,354 @@ async function runInit(options) {
     await writeCredentials(cwd, { kind: credentialKind, token: credential });
     skipToWrite = { brandId: brand.id, brandName: brand.name };
   }
-  const config = { brandId: skipToWrite.brandId, brandName: skipToWrite.brandName, serverUrl };
+  const keepExports = existing?.brandId === skipToWrite.brandId && existing.exports !== void 0;
+  const config = {
+    brandId: skipToWrite.brandId,
+    brandName: skipToWrite.brandName,
+    serverUrl,
+    ...keepExports ? { exports: existing.exports } : {}
+  };
   await writeConfig(cwd, config);
   await ensureGitignored(cwd);
-  await writeSkillFile(cwd, generateSkillFile(config));
+  let client = null;
+  if (options.client) {
+    client = options.client;
+  } else {
+    const pick = await p2.select({
+      message: "Which AI tool should connect to Stoaken?",
+      options: [
+        ...CLIENTS.map((c) => ({ value: c, label: CLIENT_LABELS[c] })),
+        { value: "none", label: "None for now (just write .stoaken/SKILL.md)" }
+      ]
+    });
+    if (p2.isCancel(pick)) {
+      p2.cancel("Cancelled.");
+      return;
+    }
+    client = pick === "none" ? null : pick;
+  }
+  const auth = (await readCredentials(cwd))?.kind === "api_key" ? "api_key" : "oauth";
+  if (client) {
+    const plan = planFor(client, auth, serverUrl);
+    if (plan.file) {
+      const path = join2(cwd, plan.file);
+      const existingText = existsSync2(path) ? await readFile2(path, "utf8") : null;
+      try {
+        const next = client === "codex" ? mergeCodexToml(existingText, auth, serverUrl) : mergeJsonConfig(client, existingText, auth, serverUrl);
+        await mkdir2(dirname(path), { recursive: true });
+        await writeFile2(path, next, "utf8");
+        p2.log.success(`${existingText === null ? "Wrote" : "Updated"} ${plan.file} (other servers kept).`);
+      } catch (error) {
+        if (!(error instanceof ConfigMergeError)) throw error;
+        p2.log.warn(error.message);
+      }
+    }
+    p2.note(plan.nextSteps.map((s) => `- ${s}`).join("\n"), `Next, in ${CLIENT_LABELS[client]}`);
+  }
+  await writeSkillFile(cwd, generateSkillFile(config, client ? { client, auth } : void 0));
   p2.outro(`Done -- this project is set up for ${config.brandName}.`);
 }
 
+// src/commands/export.ts
+import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, relative, resolve } from "path";
+import * as p3 from "@clack/prompts";
+
+// src/api.ts
+var ApiProblem = class extends Error {
+  constructor(problem) {
+    super(problem.detail ?? problem.title ?? `HTTP ${problem.status}`);
+    this.problem = problem;
+    this.name = "ApiProblem";
+  }
+  problem;
+};
+async function call(serverUrl, token, path) {
+  let response;
+  try {
+    response = await fetch(new URL(path, serverUrl), {
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.4.0" }
+    });
+  } catch (error) {
+    throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) {
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+    }
+    throw new ApiProblem({ ...body, status: response.status });
+  }
+  return response;
+}
+async function listThemes(serverUrl, token, brandId) {
+  const themes = [];
+  let cursor = null;
+  for (let page = 0; page < 50; page++) {
+    const query = new URLSearchParams({ limit: "100" });
+    if (cursor) query.set("cursor", cursor);
+    const response = await call(serverUrl, token, `/api/brands/${encodeURIComponent(brandId)}/themes?${query}`);
+    const body = await response.json();
+    themes.push(...body.data.map((t) => ({ id: t.id, name: t.name })));
+    cursor = body.next_cursor;
+    if (!cursor) break;
+  }
+  return themes;
+}
+async function fetchExport(serverUrl, token, target) {
+  const query = new URLSearchParams({ format: target.format });
+  if (target.mode) query.set("mode", target.mode);
+  if (target.prefix) query.set("prefix", target.prefix);
+  const path = target.releaseId ? `/api/releases/${encodeURIComponent(target.releaseId)}/export?${query}` : `/api/themes/${encodeURIComponent(target.themeId ?? "")}/export?${query}`;
+  const response = await call(serverUrl, token, path);
+  return {
+    text: await response.text(),
+    filename: response.headers.get("content-disposition"),
+    warnings: Number(response.headers.get("stoaken-export-warnings") ?? 0) || 0
+  };
+}
+
+// src/export-plan.ts
+var EXPORT_FORMATS = ["css", "css-auto", "json-dtcg", "json-sd4", "js", "ts", "scss", "tailwind", "swift", "android", "tailwind4", "compose"];
+var ExportUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ExportUsageError";
+  }
+};
+var VALUE_FLAGS = ["theme", "format", "mode", "prefix", "release", "out", "server"];
+function isExportFormat(value) {
+  return typeof value === "string" && EXPORT_FORMATS.includes(value);
+}
+function parseExportArgs(argv) {
+  const values = {};
+  let check = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+    const match = /^--([a-z]+)(?:=(.*))?$/.exec(arg);
+    const name = match?.[1];
+    if (!match || !name || !VALUE_FLAGS.includes(name)) {
+      throw new ExportUsageError(`Unknown option: ${arg}. Run "stoaken export --help" for the options.`);
+    }
+    let value = match[2];
+    if (value === void 0) {
+      value = argv[i + 1];
+      i++;
+    }
+    if (value === void 0 || value.startsWith("--") && value !== "-") {
+      throw new ExportUsageError(`--${name} needs a value.`);
+    }
+    values[name] = value;
+  }
+  if (values.format !== void 0 && !isExportFormat(values.format)) {
+    throw new ExportUsageError(`Unknown format "${values.format}". Use one of: ${EXPORT_FORMATS.join(", ")}.`);
+  }
+  const hasTarget = ["theme", "format", "mode", "prefix", "release", "out"].some((k) => values[k] !== void 0);
+  return {
+    check,
+    server: values.server,
+    target: hasTarget ? {
+      theme: values.theme,
+      format: values.format ?? "css",
+      mode: values.mode,
+      prefix: values.prefix,
+      release: values.release,
+      out: values.out
+    } : null
+  };
+}
+function readSavedTargets(exportsValue) {
+  if (exportsValue === void 0 || exportsValue === null) return [];
+  if (!Array.isArray(exportsValue)) throw new ExportUsageError('"exports" in stoaken.config.json must be a list.');
+  return exportsValue.map((raw, i) => {
+    const where = `"exports" item ${i + 1} in stoaken.config.json`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new ExportUsageError(`${where} must be an object.`);
+    const item = raw;
+    for (const key of Object.keys(item)) {
+      if (!["theme", "format", "mode", "prefix", "release", "out"].includes(key)) {
+        throw new ExportUsageError(`${where} has an unknown field "${key}".`);
+      }
+      if (typeof item[key] !== "string" || item[key] === "") throw new ExportUsageError(`${where}: "${key}" must be text.`);
+    }
+    const format = item.format ?? "css";
+    if (!isExportFormat(format)) throw new ExportUsageError(`${where}: unknown format "${String(format)}". Use one of: ${EXPORT_FORMATS.join(", ")}.`);
+    return {
+      theme: item.theme,
+      format,
+      mode: item.mode,
+      prefix: item.prefix,
+      release: item.release,
+      out: item.out
+    };
+  });
+}
+function chooseTheme(themes, wanted, brandName, interactive) {
+  const names = themes.map((t) => t.name).join(", ");
+  if (themes.length === 0) throw new ExportUsageError(`${brandName} has no themes yet.`);
+  if (wanted !== void 0) {
+    const byId = themes.find((t) => t.id === wanted);
+    if (byId) return { kind: "theme", theme: byId };
+    const byName = themes.filter((t) => t.name.trim().toLowerCase() === wanted.trim().toLowerCase());
+    if (byName.length === 1) return { kind: "theme", theme: byName[0] };
+    if (byName.length > 1) throw new ExportUsageError(`More than one theme is called "${wanted}". Use its id instead.`);
+    throw new ExportUsageError(`${brandName} has no theme called "${wanted}". Themes: ${names}.`);
+  }
+  if (themes.length === 1) return { kind: "theme", theme: themes[0] };
+  if (interactive) return { kind: "ask", themes };
+  throw new ExportUsageError(`${brandName} has ${themes.length} themes, so name one with --theme. Themes: ${names}.`);
+}
+function filenameFrom(disposition, fallback) {
+  const match = disposition ? /filename="?([^";]+)"?/i.exec(disposition) : null;
+  const name = (match?.[1] ?? fallback).replace(/[/\\]/g, "-").replace(/^\.+/, "");
+  return name || fallback;
+}
+function problemMessage(problem, context) {
+  const what = context.themeName ? `"${context.themeName}"` : "this theme";
+  switch (problem.status) {
+    case 401:
+      return context.usingEnvToken ? "Stoaken didn't accept STOAKEN_TOKEN. Check it's a current API key (Settings > API keys)." : `Stoaken didn't accept your saved sign-in. Run "stoaken init" again, or set STOAKEN_TOKEN to an API key.`;
+    case 403:
+    case 404:
+      return `You can't see ${what}, or it doesn't exist. Check the Brand in stoaken.config.json and your access.`;
+    case 409:
+      return problem.detail ? `${context.themeName ? `"${context.themeName}": ` : ""}${problem.detail}` : `${context.themeName ? `"${context.themeName}" has` : "This has"} nothing to export yet: approve a release first.`;
+    case 400: {
+      const modes = problem.available_modes?.filter((m) => m !== "");
+      if (problem.available_modes && modes?.length === 0) return "This theme has no modes, so leave out --mode.";
+      const extra = modes?.length ? ` Modes: ${modes.join(", ")}.` : problem.available_formats?.length ? ` Formats: ${problem.available_formats.join(", ")}.` : "";
+      return `${problem.detail ?? problem.title ?? "Stoaken refused the request."}${extra}`;
+    }
+    case 429:
+      return "Too many requests. Wait a minute and try again.";
+    default:
+      return `Stoaken answered ${problem.status}${problem.detail ? `: ${problem.detail}` : problem.title ? `: ${problem.title}` : "."}`;
+  }
+}
+function isUpToDate(onDisk, live) {
+  if (onDisk === null) return false;
+  const lf = (s) => s.replace(/\r\n/g, "\n");
+  return lf(onDisk) === lf(live);
+}
+function formatBytes(n) {
+  return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
+}
+
+// src/commands/export.ts
+var EXPORT_HELP = [
+  "stoaken export -- write your tokens as code",
+  "",
+  "Usage:",
+  "  stoaken export [options]",
+  "",
+  "Options:",
+  "  --theme <name|id>   Which theme (needed when the Brand has more than one)",
+  `  --format <format>   ${EXPORT_FORMATS.join(", ")} (default css)`,
+  "  --mode <key>        A mode combination for the one-mode formats, e.g. color-scheme:dark",
+  "  --prefix <prefix>   CSS only: a prefix for every variable name",
+  "  --release <id>      Export one release instead of the theme's live one",
+  "  --out <file|->      Where to write it (- for stdout); default: the server's file name",
+  "  --check             Write nothing; fail if the file on disk is out of date",
+  "  --server <url>      Override the server in stoaken.config.json",
+  "",
+  `With no options, every target in stoaken.config.json's "exports" list runs.`,
+  'Credentials: STOAKEN_TOKEN (an API key, for CI), else the sign-in from "stoaken init".'
+].join("\n");
+var say = (text) => process.stderr.write(`${text}
+`);
+async function runExport(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    say(EXPORT_HELP);
+    return 0;
+  }
+  const cwd = process.cwd();
+  try {
+    const args = parseExportArgs(argv);
+    const config = await readConfig(cwd);
+    if (!config) throw new ExportUsageError('No stoaken.config.json here. Run "stoaken init" in your project first.');
+    const serverUrl = args.server ?? config.serverUrl;
+    const envToken = process.env.STOAKEN_TOKEN?.trim();
+    const token = envToken || (await readCredentials(cwd))?.token;
+    if (!token) throw new ExportUsageError('No credentials. Run "stoaken init", or set STOAKEN_TOKEN to an API key.');
+    const targets = args.target ? [args.target] : readSavedTargets(config.exports);
+    if (targets.length === 0) targets.push({ format: "css" });
+    let themes = null;
+    let failed = 0;
+    for (const target of targets) {
+      let themeName;
+      try {
+        let themeId;
+        if (!target.release) {
+          themes ??= await listThemes(serverUrl, token, config.brandId);
+          const choice = chooseTheme(themes, target.theme, config.brandName, Boolean(process.stdin.isTTY && process.stderr.isTTY));
+          const theme = choice.kind === "theme" ? choice.theme : await askForTheme(choice.themes);
+          if (!theme) return 1;
+          themeId = theme.id;
+          themeName = theme.name;
+        }
+        await exportOne(serverUrl, token, target, { themeId, themeName }, args.check, cwd);
+      } catch (error) {
+        failed++;
+        say(`\u2716 ${describe(error, themeName, Boolean(envToken))}`);
+      }
+    }
+    return failed > 0 ? 1 : 0;
+  } catch (error) {
+    say(`\u2716 ${describe(error, void 0, Boolean(process.env.STOAKEN_TOKEN?.trim()))}`);
+    return 1;
+  }
+}
+async function askForTheme(themes) {
+  const choice = await p3.select({ message: "Which theme?", options: themes.map((t) => ({ value: t.id, label: t.name })) });
+  if (p3.isCancel(choice)) {
+    p3.cancel("Cancelled.");
+    return null;
+  }
+  return themes.find((t) => t.id === choice) ?? null;
+}
+async function exportOne(serverUrl, token, target, theme, check, cwd) {
+  const file = await fetchExport(serverUrl, token, {
+    themeId: theme.themeId,
+    releaseId: target.release,
+    format: target.format,
+    mode: target.mode,
+    prefix: target.prefix
+  });
+  const label = theme.themeName ?? `release ${target.release}`;
+  const warnings = file.warnings > 0 ? ` (${file.warnings} warning${file.warnings === 1 ? "" : "s"}: some values can't be written in this format)` : "";
+  if (target.out === "-") {
+    if (check) throw new ExportUsageError("--check needs a file to compare with, not --out -.");
+    process.stdout.write(file.text);
+    if (warnings) say(`! ${label}${warnings}`);
+    return;
+  }
+  const path = resolve(cwd, target.out ?? filenameFrom(file.filename, `tokens.${target.format}`));
+  const shown = relative(cwd, path) || path;
+  if (check) {
+    let current = null;
+    try {
+      current = await readFile3(path, "utf8");
+    } catch {
+    }
+    if (!isUpToDate(current, file.text)) {
+      throw new ExportUsageError(`${shown} is out of date with ${label}${current === null ? " (it doesn't exist)" : ""}. Run "stoaken export" and commit the result.`);
+    }
+    say(`\u2714 ${shown} is up to date with ${label}`);
+    return;
+  }
+  await mkdir3(dirname2(path), { recursive: true });
+  await writeFile3(path, file.text, "utf8");
+  say(`\u2714 ${label} \u2192 ${shown} (${target.format}, ${formatBytes(Buffer.byteLength(file.text))})${warnings}`);
+}
+function describe(error, themeName, usingEnvToken) {
+  if (error instanceof ApiProblem) return problemMessage(error.problem, { themeName, usingEnvToken });
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/index.ts
 var [command, ...rest] = process.argv.slice(2);
 function flagValue(args, name) {
@@ -354,22 +879,35 @@ function flagValue(args, name) {
   return index === -1 ? void 0 : args[index + 1];
 }
 switch (command) {
-  case "init":
-    await runInit({ server: flagValue(rest, "server") });
+  case "init": {
+    const client = flagValue(rest, "client");
+    if (client !== void 0 && !isClient(client)) {
+      p4.log.error(`Unknown --client "${client}". Use one of: ${CLIENTS.join(", ")}`);
+      process.exitCode = 1;
+      break;
+    }
+    await runInit({ server: flagValue(rest, "server"), client });
+    break;
+  }
+  case "export":
+    process.exitCode = await runExport(rest);
     break;
   case void 0:
   case "--help":
   case "-h":
-    p3.log.message(
+    p4.log.message(
       [
         "stoaken -- Stoaken CLI",
         "",
         "Usage:",
-        "  stoaken init [--server <url>]   Authenticate, pick a Brand, and set up this project"
+        "  stoaken init [--server <url>] [--client <name>]",
+        "                                  Authenticate, pick a Brand, and connect an AI tool",
+        `                                  (${CLIENTS.join(", ")})`,
+        "  stoaken export [options]        Write your tokens as code (stoaken export --help)"
       ].join("\n")
     );
     break;
   default:
-    p3.log.error(`Unknown command: ${command}`);
+    p4.log.error(`Unknown command: ${command}`);
     process.exitCode = 1;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stoaken",
-  "version": "0.1.0",
-  "description": "Stoaken CLI -- authenticate, pick a Brand, and get set up for MCP/API access in one command.",
+  "version": "0.4.0",
+  "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
   ],
   "author": "Stoaken",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --clean --shims",
@@ -39,8 +39,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "open": "^11.0.2"
+    "open": "^11.0.2",
+    "@modelcontextprotocol/client": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.5.0",