@flareum/mcp 0.2.3 → 0.2.5

package/README.md

@@ -177,6 +177,11 @@ area — `naming.md` for how a token name is built, `typography.md` for applying
 its class rather than the mixin behind it. The whole folder is rewritten every run, so do not edit
 it, and it prints where it wrote (or why it could not) on stderr.
 
+**`claude mcp add` alone does not write it.** An MCP server starts when a client first connects, so
+nothing runs until you open a session — or run `claude mcp list`, which connects to report status
+and is why the skill sometimes appears then. `flareum pull` writes it too, so one pull sets the
+project up without waiting for a connection.
+
 On the first connection it also **pulls the stylesheets**, once. It looks for the folder this project
 already keeps its styles in — `src/styles`, `app/styles`, `scss`, and the rest — and writes them to
 `<that folder>/flareum`, falling back to `styles/flareum` in a project that has none. It says on

package/dist/cli.js

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { FlareumApiError, FlareumClient } from './client.js';
 import { CONFIG_PATH, cliErrorReport, parseArgs, resolveConfig } from './config.js';
+import { chooseStylesDir, fileWriter } from './first-pull.js';
 import { isRetryable, pullReport, pullStyles } from './pull.js';
+import { installSkill, skillInstallReport } from './skill.js';
 import { watchIntervalMs, watchPublished, watchStartedReport } from './watch.js';
-const DEFAULT_OUT = 'src/styles/flareum';
+// Where the styles go is decided in ONE place, so the CLI and the server never disagree about it.
+const defaultOut = () => chooseStylesDir(path => existsSync(resolve(process.cwd(), path)));
 // Read rather than restated: a hardcoded version is wrong the moment `npm version` runs.
 const VERSION = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
 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}).
+      (default: the folder this project keeps its styles in — here, ${defaultOut()}).
 
   flareum watch [--out <dir>] [--interval <seconds>]
       Stay running and pull again every time you Push in Flareum.
@@ -52,14 +56,12 @@ try {
         process.exit(command ? 1 : 0);
     }
     const config = resolveConfig({ flags, env: process.env, file: await readConfigFile() });
-    const outDir = config.out ?? DEFAULT_OUT;
+    const outDir = config.out ?? defaultOut();
     const client = new FlareumClient({ token: config.token, api: config.api });
-    const root = resolve(process.cwd(), outDir);
-    const write = async (path, contents) => {
-        const target = join(root, path);
-        await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, contents, 'utf8');
-    };
+    const write = fileWriter(resolve(process.cwd(), outDir));
+    // The server writes the skill too, but only when a client connects — `claude mcp add` spawns
+    // nothing, so until now the rules arrived on whatever ran first, which was luck.
+    console.log(skillInstallReport(await installSkill(process.cwd())));
     const runPull = async () => {
         const result = await pullStyles(client, write);
         console.log(pullReport(result, outDir));

package/dist/first-pull.d.ts

@@ -0,0 +1,31 @@
+import type { FlareumClient } from './client.js';
+import { type PullResult } from './pull.js';
+/** Does this path exist, relative to the project root? Injected so the choice is testable. */
+export type Probe = (path: string) => boolean;
+/**
+ * Where this project's Flareum stylesheets belong. ONE decision, used by the CLI's default and by
+ * the server's first pull — two answers would write the same files to two places.
+ */
+export declare const chooseStylesDir: (exists: Probe, configured?: string) => string;
+export declare const autoPullEnabled: (env: Record<string, string | undefined>) => boolean;
+/** Only ever the FIRST time: an existing directory is the developer's, and `flareum pull` owns updates. */
+export declare const needsFirstPull: (exists: Probe, dir: string) => boolean;
+export type FirstPull = {
+    ran: false;
+    reason: 'disabled' | 'already-pulled';
+    dir: string;
+} | {
+    ran: true;
+    dir: string;
+    result: PullResult;
+} | {
+    ran: false;
+    reason: 'failed';
+    dir: string;
+    error: string;
+};
+export declare const firstPullReport: (outcome: FirstPull) => string | null;
+/** Writes under `root`, refusing nothing the pull already refuses (see isWritablePath). */
+export declare const fileWriter: (root: string) => (path: string, contents: string) => Promise<void>;
+export declare const configuredOut: (cwd: string, env: Record<string, string | undefined>) => string | undefined;
+export declare const runFirstPull: (client: Pick<FlareumClient, "files" | "file">, cwd: string, env: Record<string, string | undefined>, configuredOut?: string) => Promise<FirstPull>;

package/dist/first-pull.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { CONFIG_PATH } from './config.js';
+import { pullStyles } from './pull.js';
+// Most specific first. A repo that keeps stylesheets in app/styles gets them there rather than in a
+// src/styles nobody in that project looks at.
+const STYLE_ROOTS = [
+    'src/styles', 'src/style', 'src/assets/styles', 'src/scss', 'src/css',
+    'app/styles', 'app/assets/styles', 'assets/styles', 'styles', 'scss', 'css',
+];
+const LEAF = 'flareum';
+/**
+ * Where this project's Flareum stylesheets belong. ONE decision, used by the CLI's default and by
+ * the server's first pull — two answers would write the same files to two places.
+ */
+export const chooseStylesDir = (exists, configured) => {
+    if (configured)
+        return configured;
+    // An earlier pull already answered this. Re-deciding would strand those files and pull a second copy.
+    const pulled = STYLE_ROOTS.map(root => `${root}/${LEAF}`).find(exists);
+    if (pulled)
+        return pulled;
+    const root = STYLE_ROOTS.find(exists);
+    if (root)
+        return `${root}/${LEAF}`;
+    return exists('src') ? `src/styles/${LEAF}` : `styles/${LEAF}`;
+};
+// Opt-out, not opt-in: a project with no stylesheets is the case this exists for, and a stdio server
+// has nobody to ask at startup. Anything but an explicit off means on.
+export const autoPullEnabled = (env) => !['off', 'false', '0', 'no'].includes((env.FLAREUM_AUTO_PULL ?? '').trim().toLowerCase());
+/** Only ever the FIRST time: an existing directory is the developer's, and `flareum pull` owns updates. */
+export const needsFirstPull = (exists, dir) => !exists(dir);
+export const firstPullReport = (outcome) => {
+    // Silence is right for a start that did nothing — this prints on every server start.
+    if (!outcome.ran && outcome.reason !== 'failed')
+        return null;
+    if (!outcome.ran)
+        return `[flareum] could NOT pull the stylesheets into ${outcome.dir} — ${outcome.error}. `
+            + 'The token tools still work; run `npx -p @flareum/mcp flareum pull` to retry.';
+    const { written, failed } = outcome.result;
+    const head = `[flareum] no local stylesheets — pulled ${written.length} into ${outcome.dir}. `
+        + 'Run `npx -p @flareum/mcp flareum watch` to keep them current, or set FLAREUM_AUTO_PULL=off.';
+    return failed.length ? `${head}\n[flareum] ${failed.length} could not be written: `
+        + failed.map(({ path, reason }) => `${path} — ${reason}`).join('; ') : head;
+};
+/** Writes under `root`, refusing nothing the pull already refuses (see isWritablePath). */
+export const fileWriter = (root) => async (path, contents) => {
+    const target = join(root, path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, contents, 'utf8');
+};
+// The same `out` the CLI honours, read the same way — otherwise the server pulls into one folder and
+// `flareum pull` updates another.
+export const configuredOut = (cwd, env) => {
+    if (env.FLAREUM_OUT)
+        return env.FLAREUM_OUT;
+    try {
+        return JSON.parse(readFileSync(resolve(cwd, CONFIG_PATH), 'utf8')).out || undefined;
+    }
+    catch {
+        // No config file, or an unreadable one: fall through to the folder probe rather than failing.
+        return undefined;
+    }
+};
+export const runFirstPull = async (client, cwd, env, configuredOut) => {
+    const exists = path => existsSync(resolve(cwd, path));
+    const dir = chooseStylesDir(exists, configuredOut);
+    if (!autoPullEnabled(env))
+        return { ran: false, reason: 'disabled', dir };
+    if (!needsFirstPull(exists, dir))
+        return { ran: false, reason: 'already-pulled', dir };
+    try {
+        return { ran: true, dir, result: await pullStyles(client, fileWriter(resolve(cwd, dir))) };
+    }
+    catch (error) {
+        // A project with nothing published, an expired key, no network — none of them may stop the server.
+        return { ran: false, reason: 'failed', dir, error: error instanceof Error ? error.message : String(error) };
+    }
+};

package/dist/server.js

@@ -8,11 +8,21 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { FlareumApiError, FlareumClient } from './client.js';
 import { TOOL_DESCRIPTIONS, formatError, formatSearch, formatVariable } from './tools.js';
 import { installSkill, skillInstallReport } from './skill.js';
-const client = new FlareumClient({
-    token: process.env.FLAREUM_TOKEN ?? '',
-    api: process.env.FLAREUM_API,
-    projectId: process.env.FLAREUM_PROJECT,
-});
+import { configuredOut, firstPullReport, runFirstPull } from './first-pull.js';
+// A missing key threw at module load, and an editor shows that as a Node stack trace with the
+// message buried in it. Say it in one line and exit, the way the CLI already does.
+let client;
+try {
+    client = new FlareumClient({
+        token: process.env.FLAREUM_TOKEN ?? '',
+        api: process.env.FLAREUM_API,
+        projectId: process.env.FLAREUM_PROJECT,
+    });
+}
+catch (error) {
+    console.error(`[flareum] ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}
 // Read, never restated: the hardcoded 0.1.0 kept reporting itself from a 0.2.1 package.
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const server = new Server({ name: 'flareum', version }, { capabilities: { tools: {} } });
@@ -64,4 +74,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 // Never silently: if the skill does not land, the agent hardcodes values and nothing says why.
 console.error(skillInstallReport(await installSkill(process.cwd())));
+// First connection with no stylesheets pulled yet: fetch them now, into the folder this project
+// already keeps its styles in. Reported, never asked — a stdio server has nobody to prompt.
+const firstPull = firstPullReport(await runFirstPull(client, process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
+if (firstPull)
+    console.error(firstPull);
 await server.connect(new StdioServerTransport());

package/dist/skill.js

@@ -1,15 +1,24 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const SKILL_DIR = ['.claude', 'skills', 'flareum'];
-// Written on every start, not once: a stale copy of the naming rules is worse than none, and the
-// file is generated rather than hand-edited.
+// Every file under skill/, not just SKILL.md: it is a router now, and a reference it points at but
+// never wrote is a rule the agent silently never reads. One failure fails the whole install.
+const copyTree = async (from, to) => {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true }))
+        if (entry.isDirectory())
+            await copyTree(join(from, entry.name), join(to, entry.name));
+        else
+            await writeFile(join(to, entry.name), await readFile(join(from, entry.name), 'utf8'), 'utf8');
+};
+// Written on every start, not once: a stale copy of the rules is worse than none, and the files are
+// generated rather than hand-edited.
 export const installSkill = async (cwd) => {
-    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill', 'SKILL.md');
+    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill');
     const path = join(cwd, ...SKILL_DIR, 'SKILL.md');
     try {
-        await mkdir(join(cwd, ...SKILL_DIR), { recursive: true });
-        await writeFile(path, await readFile(source, 'utf8'), 'utf8');
+        await copyTree(source, join(cwd, ...SKILL_DIR));
         return { ok: true, path };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flareum/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Connect a coding agent to a Flareum project's design tokens.",
   "license": "MIT",
   "author": "Flareum",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flareum
-description: Use the project's Flareum design tokens instead of literal values. Invoke whenever you are about to write a colour, size, spacing, radius, shadow or duration in CSS/SCSS, or need to know which token a value corresponds to.
+description: Use the project's Flareum design tokens instead of literal values. Invoke whenever you are about to write a colour, size, spacing, radius, shadow, duration or text style in CSS/SCSS/HTML, or need to know which token a value corresponds to.
 ---
 
 # Flareum design tokens
@@ -9,6 +9,9 @@ This project's design tokens live in Flareum. The generated CSS/SCSS in the repo
 of them — the tokens themselves, with their types, modes, comments and usage, are reachable through
 the `flareum_search` and `flareum_get` tools.
 
+Every name here is written with **`[prefix]`** where your project's own token prefix goes — the
+string every `cssName` in a search result starts with. Substitute it; never write `[prefix]` itself.
+
 ## The one rule
 
 **Search before you write a literal value, and before you propose a token name.**
@@ -18,6 +21,16 @@ an existing `color/border/secondary` is worse — it looks like a decision, and
 reconcile the two. `flareum_search` takes a hex, an rgb(), a path fragment, a phrase from a comment,
 or a component name.
 
+## The rules, by topic
+
+This page is the workflow. Open the one below that covers what you are about to write — each is a
+page, and it is worth reading in full before the first line of code.
+
+| Writing | Read |
+|---|---|
+| Any text — a heading, a label, body copy, a pseudo-element's `content` | [references/typography.md](references/typography.md) |
+| A token name, or judging one that already exists | [references/naming.md](references/naming.md) |
+
 ## Reading a search result
 
 The header tells you which kind of answer you got, and they mean different things:
@@ -35,33 +48,9 @@ An empty project says so explicitly. Anything else always returns candidates.
 This integration is **read-only** — there is no tool that writes to Flareum, by design. So:
 
 1. Say which token is missing and what it would be for.
-2. Propose a name that fits the grammar below, so the designer can create it in one step.
+2. Propose a name that fits [the grammar](references/naming.md), so the designer can create it in one step.
 3. Do not silently hardcode the value and move on.
 
-## The naming grammar
-
-A token name is a serialized hierarchy, general → specific, terminal value last:
-
-```
---[prefix]-[category]-[layer?]-[path...]-[value]
-```
-
-- **`category` always comes first** after the prefix: `color`, `space`, `size`, `radius`, `shadow`,
-  `blur`, `duration`, `z`, `opacity`, `font`, `border`.
-- **`layer`** is optional and names the tier. For colour: `primitive`, `global`, `semantic`,
-  `action_palette`, `action_state`, `action`. A raw scale (`--fui-space-4`) has none.
-- **A component is a `path` segment, never a top-level layer.**
-
-```css
-/* ✓ */ --fui-color-semantic-button-background-primary-hover
-/* ✗ */ --fui-button-color-background-primary-hover     /* component-first */
-/* ✗ */ --fui-semantic-color-text-primary               /* layer hoisted above the category */
-```
-
-Spell each segment the way the system already spells it — `disabled` not `disable`, `background` not
-`bg`, `accent` not `acent`. Search for the segment before coining a second spelling of a word that
-already exists; a new word is for a genuinely new concept only.
-
 ## Blast radius before a change
 
 `flareum_get` reports two independent things, and they answer different questions:

package/skill/references/naming.md

@@ -0,0 +1,36 @@
+# Token naming
+
+Read this before proposing a token name, or when judging whether a name that already exists is the
+one you want.
+
+## The grammar
+
+A token name is a serialized hierarchy, general → specific, terminal value last:
+
+```
+--[prefix]-[category]-[layer?]-[path...]-[value]
+```
+
+- **`category` always comes first** after the prefix: `color`, `space`, `size`, `radius`, `shadow`,
+  `blur`, `duration`, `z`, `opacity`, `font`, `border`.
+- **`layer`** is optional and names the tier. For colour: `primitive`, `global`, `semantic`,
+  `action_palette`, `action_state`, `action`. A raw scale (`--[prefix]-space-4`) has none.
+- **A component is a `path` segment, never a top-level layer.**
+
+```css
+/* ✓ */ --[prefix]-color-semantic-button-background-primary-hover
+/* ✗ */ --[prefix]-button-color-background-primary-hover     /* component-first */
+/* ✗ */ --[prefix]-semantic-color-text-primary               /* layer hoisted above the category */
+```
+
+Build the tree first, then serialize it — `color → semantic → input → border → error` is what makes
+`--[prefix]-color-semantic-input-border-error` the only possible spelling of it.
+
+## One word per concept
+
+Spell each segment the way the system already spells it — `disabled` not `disable`, `background` not
+`bg`, `accent` not `acent`. Two spellings of one word mean nobody can find every token for it, or
+trust that they have.
+
+So `flareum_search` for the segment before coining a word. A new word is for a genuinely new concept
+only; a shorter way to write one that exists is not a new concept.

package/skill/references/typography.md

@@ -0,0 +1,55 @@
+# Text styles
+
+Read this before styling any text — a heading, a label, body copy, a value in a table cell, or a
+pseudo-element's `content`.
+
+## The class, not the mixin
+
+Flareum exports every text style twice — a ready-made **class** in `typography/_styles.scss`, and the
+**mixin** it is built from in `typography/_mixins.scss`. They are not two ways of doing the same
+thing. **The class is how a text style is applied; the mixin is a fallback for the few elements a
+class cannot reach.**
+
+Put the pair on the element that holds the text — the base class plus the style class:
+
+```html
+<h2 class="[prefix]-typography [prefix]-h5">Export settings</h2>
+<p class="[prefix]-typography [prefix]-t2">Choose which collections ship to Figma.</p>
+<span class="[prefix]-typography [prefix]-t2 [prefix]-bold">12 variables</span>
+```
+
+Both halves are required. The base class declares the shared properties (`--line-height` among them)
+and the style class re-points them, so a style class on its own applies nothing. A variant slot —
+`bold`, `regular`, `highlight` — is a third class beside the style, never a replacement for it.
+
+Why the class wins: it names the style in the markup, where the next person reading the template can
+see which style an element uses and change it without opening a stylesheet; and one rule serves every
+element that carries it, instead of each component compiling its own copy of the same declarations.
+
+## The exception
+
+**Reach for the mixin only where no class can be placed** — a pseudo-element, or markup you do not
+render (a third-party widget, generated HTML) and therefore cannot add an attribute to.
+
+```scss
+// ::after has no class attribute — the only way to give it the style
+.field::after {
+  content: attr(data-hint);
+  @include [prefix]-typography-t3;
+}
+```
+
+That is the whole list. "It was easier from SCSS" is not on it: a mixin reached for out of convenience
+hides the style from the markup and duplicates the declarations into every component that includes it.
+
+## When a style looks like it is not applying
+
+Check these before overriding anything — each one silently beats the class rather than erroring:
+
+- **A lone style class.** `[prefix]-h5` with no `[prefix]-typography` beside it applies nothing.
+- **A `font:` shorthand on the same element.** It resets family, size, weight and line-height in one
+  go, and component styles load after the global ones. Use the longhand for the one thing you meant
+  to change.
+- **A missing `--line-height`.** Padding computed from it resolves to an invalid `calc()`, and the
+  property falls back to its initial value with nothing in the console. The typography class has to
+  be on the element that reads the variable, or an ancestor of it.