@flareum/mcp 0.1.0 → 0.2.0

package/README.md

@@ -47,6 +47,40 @@ so, because "no results" reads as "no such token exists" and gets acted on.
 
 ---
 
+## Pulling the stylesheets
+
+The tools tell an agent what a token is CALLED. The stylesheets that give those names a value come
+from a Push, and this fetches them:
+
+```bash
+npx flareum pull                 # into src/styles/flareum
+npx flareum watch                # and again every time you Push in Flareum
+```
+
+Then import them once, in your global stylesheet:
+
+```scss
+@use './styles/flareum/main';
+```
+
+It copies the files a Push generated — it never rebuilds CSS from the token data, so a name in the
+file and a name the tools report cannot drift.
+
+`watch` polls for a new published version and pulls when one appears. A save in Flareum changes
+nothing; only a Push does.
+
+### Where the key comes from
+
+`--token`, then `FLAREUM_TOKEN`, then `token` in `.flareum/config.json`:
+
+```json
+{ "token": "pk_…", "out": "src/styles/flareum" }
+```
+
+**Add `.flareum/` to your `.gitignore`** — that file holds a key.
+
+---
+
 ## Configuration
 
 | Variable | |

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { FlareumClient } from './client.js';
+import { CONFIG_PATH, cliErrorReport, parseArgs, resolveConfig } from './config.js';
+import { pullReport, pullStyles } from './pull.js';
+import { DEFAULT_INTERVAL_MS, watchPublished, watchStartedReport } from './watch.js';
+const DEFAULT_OUT = 'src/styles/flareum';
+const HELP = `flareum — read a Flareum project's design tokens
+
+  flareum pull [--out <dir>] [--token pk_…] [--api <url>]
+      Write the stylesheets the last push published into <dir>
+      (default: ${DEFAULT_OUT}).
+
+  flareum watch [--out <dir>] [--interval <seconds>]
+      Stay running and pull again every time you Push in Flareum.
+
+The key is taken from --token, then FLAREUM_TOKEN, then "token" in ${CONFIG_PATH}.
+Mint one in the project's Connect screen in Flareum.`;
+const readConfigFile = async () => readFile(join(process.cwd(), CONFIG_PATH), 'utf8').then(JSON.parse).catch(() => null);
+const { command, flags } = parseArgs(process.argv.slice(2));
+const COMMANDS = ['pull', 'watch'];
+if (!COMMANDS.includes(command)) {
+    console.log(HELP);
+    process.exit(command ? 1 : 0);
+}
+try {
+    const config = resolveConfig({ flags, env: process.env, file: await readConfigFile() });
+    const outDir = config.out ?? DEFAULT_OUT;
+    const root = resolve(process.cwd(), outDir);
+    const client = new FlareumClient({ token: config.token, api: config.api });
+    const write = async (path, contents) => {
+        const target = join(root, path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, contents, 'utf8');
+    };
+    const runPull = async () => {
+        const result = await pullStyles(client, write);
+        console.log(pullReport(result, outDir));
+        return result;
+    };
+    if (command === 'watch') {
+        const intervalMs = Number(flags.interval) > 0 ? Number(flags.interval) * 1000 : DEFAULT_INTERVAL_MS;
+        console.log(watchStartedReport(outDir, intervalMs));
+        let running = true;
+        process.on('SIGINT', () => { running = false; console.log('\nStopped watching.'); process.exit(0); });
+        await watchPublished({
+            publishedVersion: async () => (await client.files()).publishedVersionId,
+            onPublish: async () => { await runPull(); },
+            onError: error => console.error(error instanceof Error ? error.message : String(error)),
+            sleep: ms => new Promise(done => { setTimeout(done, ms); }),
+            keepGoing: () => running,
+        }, intervalMs);
+        process.exit(0);
+    }
+    const result = await runPull();
+    process.exit(result.failed.length ? 1 : 0);
+}
+catch (error) {
+    console.error(cliErrorReport(error));
+    process.exit(1);
+}

package/dist/client.d.ts

@@ -21,6 +21,9 @@ export declare class FlareumClient {
     constructor({ token, api, projectId, fetchImpl }: ClientOptions);
     catalog(updatedSince?: string): Promise<CatalogResponse>;
     search(query: string, limit?: number): Promise<SearchResponse>;
+    /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    files(): Promise<FilesResponse>;
+    file(path: string): Promise<string>;
     variable(path: string): Promise<VariableResponse>;
 }
 export type CatalogResponse = {
@@ -62,6 +65,10 @@ export type SearchResponse = {
     truncated: boolean;
     candidates: Candidate[];
 };
+export type FilesResponse = {
+    publishedVersionId: string;
+    files: string[];
+};
 export type VariableMode = {
     id: string;
     name: string;

package/dist/client.js

@@ -36,8 +36,12 @@ export class FlareumClient {
         for (const [key, value] of Object.entries(query))
             if (value)
                 url.searchParams.set(key, value);
+        // Node reports an unreachable host as a bare "fetch failed", which in a watch loop repeats
+        // forever without ever saying WHICH host is down.
         const response = await this.#fetch(url.toString(), {
             headers: { Authorization: `Bearer ${this.#token}`, Accept: 'application/json' },
+        }).catch(error => {
+            throw new Error(`Could not reach ${this.#api} — ${error instanceof Error ? error.message : String(error)}`);
         });
         if (response.ok)
             return response.json();
@@ -52,12 +56,31 @@ export class FlareumClient {
                 : 'Retry; if it persists, check the project is reachable.',
         });
     }
+    async #getText(path) {
+        const url = `${this.#api}/api/v1/projects/${this.projectId}${path}`;
+        const response = await this.#fetch(url, {
+            headers: { Authorization: `Bearer ${this.#token}`, Accept: 'text/plain' },
+        });
+        if (response.ok)
+            return response.text();
+        const body = await response.json().catch(() => null);
+        throw new FlareumApiError(body?.error ?? {
+            code: `HTTP_${response.status}`, message: `The Flareum API returned ${response.status}.`, hint: '',
+        });
+    }
     catalog(updatedSince = '') {
         return this.#get('/catalog', { updatedSince });
     }
     search(query, limit) {
         return this.#get('/search', { q: query, ...(limit ? { limit: String(limit) } : {}) });
     }
+    /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    files() {
+        return this.#get('/files');
+    }
+    file(path) {
+        return this.#getText(`/files/${path.split('/').map(encodeURIComponent).join('/')}`);
+    }
     variable(path) {
         return this.#get(`/variables/${path.split('/').map(encodeURIComponent).join('/')}`);
     }

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+export type Resolved = {
+    token: string;
+    api?: string;
+    out?: string;
+};
+export type ConfigSources = {
+    flags: Record<string, string>;
+    env: Record<string, string | undefined>;
+    file: Partial<Resolved> | null;
+};
+export declare const CONFIG_PATH = ".flareum/config.json";
+export declare class MissingToken extends Error {
+    constructor();
+}
+/** A flag beats the environment beats the file — nearest to the command wins. */
+export declare const resolveConfig: ({ flags, env, file }: ConfigSources) => Resolved;
+/** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */
+export declare const parseArgs: (argv: string[]) => {
+    command: string;
+    flags: Record<string, string>;
+};
+export declare const cliErrorReport: (error: unknown) => string;

package/dist/config.js

@@ -0,0 +1,58 @@
+import { FlareumApiError } from './client.js';
+export const CONFIG_PATH = '.flareum/config.json';
+export class MissingToken extends Error {
+    constructor() {
+        // Names every place it looked, so the reader does not have to guess which one to set.
+        super('No Flareum key. Give it one of:\n'
+            + '  --token pk_…\n'
+            + '  FLAREUM_TOKEN=pk_… in the environment\n'
+            + `  a "token" in ${CONFIG_PATH}\n`
+            + 'Mint a key in the project\'s Connect screen in Flareum.');
+        this.name = 'MissingToken';
+    }
+}
+/** A flag beats the environment beats the file — nearest to the command wins. */
+export const resolveConfig = ({ flags, env, file }) => {
+    const token = flags.token || env.FLAREUM_TOKEN || file?.token;
+    if (!token)
+        throw new MissingToken();
+    return {
+        token,
+        api: flags.api || env.FLAREUM_API || file?.api,
+        out: flags.out || file?.out,
+    };
+};
+/** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */
+export const parseArgs = (argv) => {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const [name, inline] = arg.slice(2).split('=');
+        if (inline !== undefined) {
+            flags[name] = inline;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            flags[name] = next;
+            i += 1;
+        }
+        else
+            flags[name] = 'true';
+    }
+    return { command: positional[0] ?? '', flags };
+};
+// Every CLI failure reaches a user through this, so an unhandled one must read as a sentence
+// rather than the Node stack trace a rethrow prints.
+export const cliErrorReport = (error) => {
+    if (error instanceof MissingToken)
+        return error.message;
+    if (error instanceof FlareumApiError)
+        return `${error.message}\n${error.hint}`;
+    return error instanceof Error ? error.message : String(error);
+};

package/dist/pull.d.ts

@@ -0,0 +1,12 @@
+import type { FlareumClient } from './client.js';
+export type PullResult = {
+    publishedVersionId: string;
+    written: string[];
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+};
+export type Writer = (path: string, contents: string) => Promise<void>;
+export declare const pullStyles: (client: Pick<FlareumClient, "files" | "file">, write: Writer) => Promise<PullResult>;
+export declare const pullReport: ({ publishedVersionId, written, failed }: PullResult, outDir: string) => string;

package/dist/pull.js

@@ -0,0 +1,30 @@
+// Copies the ARTIFACT a push generated; never rebuilds CSS from the catalog, so a name here and a
+// name the API reports cannot disagree.
+export const pullStyles = async (client, write) => {
+    const { publishedVersionId, files } = await client.files();
+    const written = [];
+    const failed = [];
+    for (const path of files)
+        try {
+            await write(path, await client.file(path));
+            written.push(path);
+        }
+        catch (error) {
+            // One unreadable file must not lose the rest, and must not be reported as written.
+            failed.push({ path, reason: error instanceof Error ? error.message : String(error) });
+        }
+    return { publishedVersionId, written, failed };
+};
+export const pullReport = ({ publishedVersionId, written, failed }, outDir) => {
+    const lines = [`Pulled ${written.length} stylesheet(s) from version ${publishedVersionId} into ${outDir}`];
+    for (const path of written)
+        lines.push(`  ${path}`);
+    if (failed.length) {
+        lines.push(`${failed.length} could NOT be written:`);
+        for (const { path, reason } of failed)
+            lines.push(`  ${path} — ${reason}`);
+    }
+    if (!written.length && !failed.length)
+        lines.push('  nothing — this version published no stylesheets.');
+    return lines.join('\n');
+};

package/dist/watch.d.ts

@@ -0,0 +1,11 @@
+export type WatchDeps = {
+    /** The published version right now, or null when nothing is published yet. */
+    publishedVersion: () => Promise<string | null>;
+    onPublish: (version: string) => Promise<void>;
+    onError: (error: unknown) => void;
+    sleep: (ms: number) => Promise<void>;
+    keepGoing: () => boolean;
+};
+export declare const DEFAULT_INTERVAL_MS = 15000;
+export declare const watchPublished: ({ publishedVersion, onPublish, onError, sleep, keepGoing }: WatchDeps, intervalMs?: number) => Promise<void>;
+export declare const watchStartedReport: (outDir: string, intervalMs: number) => string;

package/dist/watch.js

@@ -0,0 +1,24 @@
+export const DEFAULT_INTERVAL_MS = 15_000;
+// Re-pulls when the PUBLISHED version changes — a push, never a save, so a designer mid-edit cannot
+// rewrite a file the developer is looking at.
+export const watchPublished = async ({ publishedVersion, onPublish, onError, sleep, keepGoing }, intervalMs = DEFAULT_INTERVAL_MS) => {
+    let seen = null;
+    while (keepGoing()) {
+        try {
+            const version = await publishedVersion();
+            if (version && version !== seen) {
+                // Marked seen only AFTER the pull lands: a failed write must be retried, not skipped.
+                await onPublish(version);
+                seen = version;
+            }
+        }
+        catch (error) {
+            // A server restart or a dropped connection must not end the watch — the next tick retries.
+            onError(error);
+        }
+        if (keepGoing())
+            await sleep(intervalMs);
+    }
+};
+export const watchStartedReport = (outDir, intervalMs) => `Watching for a Push in Flareum — pulling into ${outDir} every ${Math.round(intervalMs / 1000)}s.`
+    + '\nPress Ctrl+C to stop.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flareum/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Connect a coding agent to a Flareum project's design tokens.",
   "license": "MIT",
   "author": "Flareum",
@@ -20,6 +20,7 @@
   ],
   "type": "module",
   "bin": {
+    "flareum": "dist/cli.js",
     "flareum-mcp": "dist/server.js"
   },
   "files": [