stoaken 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Stoaken. All rights reserved.
+
+This software and associated documentation are proprietary and confidential.
+No license, express or implied, to any intellectual property rights is
+granted by this document, except that you may install and run this software
+as distributed for its intended purpose. Unauthorized copying, modification,
+distribution, sublicensing, or reverse engineering of this software, in
+whole or in part, is strictly prohibited without prior written permission
+from Stoaken.
+
+THIS 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

@@ -0,0 +1,39 @@
+# 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.
+
+## Quickstart
+
+```
+npx stoaken init
+```
+
+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.
+
+Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
+
+## Authentication
+
+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.
+
+## 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:
+
+- `list_brands` -- every Brand you hold at least Viewer on.
+- `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.
+- `list_releases(themeId)` -- a Theme's Releases with version, status, and change summary.
+- `propose_token_change(themeId, tokenSetId, document, version, versionType)` -- proposes a token change and submits it for approval. **This never publishes.** A human reviewer always approves through the Stoaken Command Center before it goes live.
+
+## Links
+
+- [Stoaken on GitHub](https://github.com/craig-astravale/stoaken)
+- [Report an issue](https://github.com/craig-astravale/stoaken/issues)

package/dist/index.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as p3 from "@clack/prompts";
+
+// src/commands/init.ts
+import * as p2 from "@clack/prompts";
+
+// src/auth.ts
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import * as p from "@clack/prompts";
+import open from "open";
+
+// src/config.ts
+import { existsSync } from "fs";
+import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+var CONFIG_FILE = "stoaken.config.json";
+var STOAKEN_DIR = ".stoaken";
+var CREDENTIALS_FILE = join(STOAKEN_DIR, "credentials.json");
+var OAUTH_CLIENT_FILE = join(STOAKEN_DIR, "oauth-client.json");
+function configPath(cwd) {
+  return join(cwd, CONFIG_FILE);
+}
+async function readConfig(cwd) {
+  try {
+    const raw = await readFile(configPath(cwd), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeConfig(cwd, config) {
+  await writeFile(configPath(cwd), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function ensureStoakenDir(cwd) {
+  await mkdir(join(cwd, STOAKEN_DIR), { recursive: true });
+}
+async function writeCredentials(cwd, credentials) {
+  await ensureStoakenDir(cwd);
+  const path = join(cwd, CREDENTIALS_FILE);
+  await writeFile(path, `${JSON.stringify(credentials, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+}
+async function readOAuthClient(cwd) {
+  try {
+    const raw = await readFile(join(cwd, OAUTH_CLIENT_FILE), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeOAuthClient(cwd, client) {
+  await ensureStoakenDir(cwd);
+  await writeFile(join(cwd, OAUTH_CLIENT_FILE), `${JSON.stringify(client, null, 2)}
+`, "utf8");
+}
+async function writeSkillFile(cwd, content) {
+  await ensureStoakenDir(cwd);
+  await writeFile(join(cwd, STOAKEN_DIR, "SKILL.md"), content, "utf8");
+}
+async function ensureGitignored(cwd) {
+  const gitignorePath = join(cwd, ".gitignore");
+  const entry = `${STOAKEN_DIR}/`;
+  let existing = "";
+  if (existsSync(gitignorePath)) {
+    existing = await readFile(gitignorePath, "utf8");
+  }
+  const alreadyPresent = existing.split("\n").map((line) => line.trim()).includes(entry);
+  if (alreadyPresent) {
+    return;
+  }
+  const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+  const prefix = needsLeadingNewline ? "\n" : "";
+  await appendFile(gitignorePath, `${prefix}${entry}
+`, "utf8");
+}
+
+// src/auth.ts
+var CALLBACK_PORT = 51820;
+var REDIRECT_URI = `http://127.0.0.1:${CALLBACK_PORT}/callback`;
+async function discoverAuthorizationServer(serverUrl) {
+  const metadataUrl = new URL("/.well-known/oauth-protected-resource", serverUrl);
+  const response = await fetch(metadataUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to discover the authorization server (${response.status}) at ${metadataUrl}`);
+  }
+  const metadata = await response.json();
+  const authServer = metadata.authorization_servers?.[0];
+  if (!authServer) {
+    throw new Error(`${metadataUrl} did not name an authorization server`);
+  }
+  return authServer;
+}
+async function registerOAuthClient(authServer) {
+  const response = await fetch(`${authServer}/oauth2/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "Stoaken CLI",
+      redirect_uris: [REDIRECT_URI],
+      grant_types: ["authorization_code"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Dynamic Client Registration failed (${response.status}): ${await response.text()}`);
+  }
+  const data = await response.json();
+  return data.client_id;
+}
+function base64url(buffer) {
+  return buffer.toString("base64url");
+}
+function generatePkce() {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+function waitForCallback() {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", REDIRECT_URI);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        error ? "<p>Login failed. You can close this tab and return to the terminal.</p>" : "<p>Login complete -- you can close this tab and return to the terminal.</p>"
+      );
+      server.close();
+      if (error) {
+        reject(new Error(`WorkOS returned an error: ${error}`));
+      } else if (!code) {
+        reject(new Error("No authorization code in the callback"));
+      } else {
+        resolve(code);
+      }
+    });
+    server.on("error", reject);
+    server.listen(CALLBACK_PORT, "127.0.0.1");
+  });
+}
+async function exchangeCodeForToken(authServer, clientId, code, verifier) {
+  const response = await fetch(`${authServer}/oauth2/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: REDIRECT_URI,
+      client_id: clientId,
+      code_verifier: verifier
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Token exchange failed (${response.status}): ${await response.text()}`);
+  }
+  const data = await response.json();
+  return data.access_token;
+}
+async function loginWithBrowser(cwd, serverUrl) {
+  const authServer = await discoverAuthorizationServer(serverUrl);
+  let clientId = (await readOAuthClient(cwd))?.clientId;
+  if (!clientId) {
+    clientId = await registerOAuthClient(authServer);
+    await writeOAuthClient(cwd, { clientId });
+  }
+  const { verifier, challenge } = generatePkce();
+  const authorizeUrl = new URL("/oauth2/authorize", authServer);
+  authorizeUrl.searchParams.set("client_id", clientId);
+  authorizeUrl.searchParams.set("redirect_uri", REDIRECT_URI);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  const callbackPromise = waitForCallback();
+  await open(authorizeUrl.toString());
+  p.log.info(`Opened your browser to sign in. Waiting for you to finish...`);
+  const code = await callbackPromise;
+  return exchangeCodeForToken(authServer, clientId, code, verifier);
+}
+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 (p.isCancel(key)) {
+    return null;
+  }
+  return key;
+}
+
+// src/mcp-client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+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" });
+  await client.connect(transport);
+  try {
+    const result = await client.callTool({ name: "list_brands", arguments: {} });
+    const firstContent = result.content[0];
+    if (!firstContent || firstContent.type !== "text" || !firstContent.text) {
+      throw new Error("list_brands returned an unexpected response shape");
+    }
+    return JSON.parse(firstContent.text);
+  } finally {
+    await client.close();
+  }
+}
+
+// src/skill-template.ts
+function generateSkillFile(config) {
+  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\`).
+
+## Tools
+
+- **list_brands** -- every Brand you hold at least Viewer on.
+- **get_theme_tokens(themeId)** -- a Theme's cascade-merged token tree.
+- **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
+  lands in \`pending_approval\` and a human reviewer must approve it through the Stoaken
+  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.
+
+## This Brand
+
+- Brand ID: \`${config.brandId}\`
+- Brand name: ${config.brandName}
+- Server: ${config.serverUrl}
+
+Re-run \`stoaken init\` if you need to switch Brands or re-authenticate.
+`;
+}
+
+// src/commands/init.ts
+var DEFAULT_SERVER_URL = "https://stoaken.com";
+async function runInit(options) {
+  const cwd = process.cwd();
+  const serverUrl = options.server ?? DEFAULT_SERVER_URL;
+  p2.intro("stoaken init");
+  const existing = await readConfig(cwd);
+  let skipToWrite = null;
+  if (existing) {
+    const choice = await p2.select({
+      message: `This project is already set up for ${existing.brandName}. What would you like to do?`,
+      options: [
+        { value: "continue", label: `Continue with ${existing.brandName}` },
+        { value: "switch", label: "Switch Brand" },
+        { value: "reauth", label: "Re-authenticate" }
+      ]
+    });
+    if (p2.isCancel(choice)) {
+      p2.cancel("Cancelled.");
+      return;
+    }
+    if (choice === "continue") {
+      skipToWrite = { brandId: existing.brandId, brandName: existing.brandName };
+    }
+  }
+  let credential;
+  let credentialKind;
+  if (!skipToWrite) {
+    const authChoice = await p2.select({
+      message: "How would you like to sign in?",
+      options: [
+        { value: "browser", label: "Log in with browser" },
+        { value: "key", label: "Paste an API key" }
+      ]
+    });
+    if (p2.isCancel(authChoice)) {
+      p2.cancel("Cancelled.");
+      return;
+    }
+    if (authChoice === "browser") {
+      const s2 = p2.spinner();
+      s2.start("Waiting for you to finish signing in...");
+      try {
+        credential = await loginWithBrowser(cwd, serverUrl);
+        credentialKind = "oauth";
+        s2.stop("Signed in.");
+      } catch (error) {
+        s2.stop("Sign-in failed.");
+        p2.log.error(error instanceof Error ? error.message : String(error));
+        return;
+      }
+    } else {
+      const key = await promptForApiKey();
+      if (!key) {
+        p2.cancel("Cancelled.");
+        return;
+      }
+      credential = key;
+      credentialKind = "api_key";
+    }
+    const s = p2.spinner();
+    s.start("Fetching your Brands...");
+    let brands;
+    try {
+      brands = await listBrands(serverUrl, credential);
+    } catch (error) {
+      s.stop("Failed to reach Stoaken.");
+      p2.log.error(error instanceof Error ? error.message : String(error));
+      return;
+    }
+    s.stop(`Found ${brands.length} Brand${brands.length === 1 ? "" : "s"}.`);
+    if (brands.length === 0) {
+      p2.outro("No Brands available to this account. Ask an editor to invite you, then run init again.");
+      return;
+    }
+    const brandChoice = await p2.select({
+      message: "Which Brand is this project for?",
+      options: brands.map((brand2) => ({ value: brand2.id, label: brand2.name }))
+    });
+    if (p2.isCancel(brandChoice)) {
+      p2.cancel("Cancelled.");
+      return;
+    }
+    const brand = brands.find((b) => b.id === brandChoice);
+    await writeCredentials(cwd, { kind: credentialKind, token: credential });
+    skipToWrite = { brandId: brand.id, brandName: brand.name };
+  }
+  const config = { brandId: skipToWrite.brandId, brandName: skipToWrite.brandName, serverUrl };
+  await writeConfig(cwd, config);
+  await ensureGitignored(cwd);
+  await writeSkillFile(cwd, generateSkillFile(config));
+  p2.outro(`Done -- this project is set up for ${config.brandName}.`);
+}
+
+// src/index.ts
+var [command, ...rest] = process.argv.slice(2);
+function flagValue(args, name) {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? void 0 : args[index + 1];
+}
+switch (command) {
+  case "init":
+    await runInit({ server: flagValue(rest, "server") });
+    break;
+  case void 0:
+  case "--help":
+  case "-h":
+    p3.log.message(
+      [
+        "stoaken -- Stoaken CLI",
+        "",
+        "Usage:",
+        "  stoaken init [--server <url>]   Authenticate, pick a Brand, and set up this project"
+      ].join("\n")
+    );
+    break;
+  default:
+    p3.log.error(`Unknown command: ${command}`);
+    process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "stoaken",
+  "version": "0.1.0",
+  "description": "Stoaken CLI -- authenticate, pick a Brand, and get set up for MCP/API access in one command.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "stoaken": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/craig-astravale/stoaken.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/craig-astravale/stoaken/issues"
+  },
+  "homepage": "https://github.com/craig-astravale/stoaken/tree/main/cli#readme",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "design-system"
+  ],
+  "author": "Stoaken",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --shims",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "open": "^11.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}