@flareum/mcp 0.2.8 → 0.2.10

package/dist/first-pull.d.ts

@@ -8,11 +8,12 @@ export type Probe = (path: string) => boolean;
  */
 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 declare const STAMP = ".flareum-version";
+export declare const pulledVersion: (read: (path: string) => string | null, dir: string) => string | null;
+export declare const needsPull: (exists: Probe, read: (path: string) => string | null, dir: string, published: string | null) => boolean;
 export type FirstPull = {
     ran: false;
-    reason: 'disabled' | 'already-pulled';
+    reason: 'disabled' | 'up-to-date';
     dir: string;
 } | {
     ran: true;
@@ -28,4 +29,4 @@ 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>;
+export declare const runFirstPull: (client: Pick<FlareumClient, "files" | "file" | "published">, cwd: string, env: Record<string, string | undefined>, configuredOut?: string) => Promise<FirstPull>;

package/dist/first-pull.js

@@ -29,8 +29,18 @@ export const chooseStylesDir = (exists, configured) => {
 // 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);
+// A stamp beside the files, not in config.json: config is the developer's, this is bookkeeping.
+export const STAMP = '.flareum-version';
+export const pulledVersion = (read, dir) => read(join(dir, STAMP))?.trim() || null;
+// Pull when there is nothing here, or when what is published is not what is on disk. Connecting
+// used to be a one-time event, so a project pulled once never saw another push.
+export const needsPull = (exists, read, dir, published) => {
+    if (!exists(dir))
+        return true;
+    if (!published)
+        return false;
+    return pulledVersion(read, dir) !== published;
+};
 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')
@@ -39,8 +49,11 @@ export const firstPullReport = (outcome) => {
         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;
+    // Naming the import is the difference between 24 files on disk and 24 files that apply: nothing
+    // loads them until the project's global stylesheet says so.
     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.';
+        + `Import them once in your global stylesheet — \`@use '${outcome.dir.replace(/^src\//, './')}/main';\` `
+        + '— then `npx -p @flareum/mcp flareum watch` keeps them current (FLAREUM_AUTO_PULL=off to stop).';
     return failed.length ? `${head}\n[flareum] ${failed.length} could not be written: `
         + failed.map(({ path, reason }) => `${path} — ${reason}`).join('; ') : head;
 };
@@ -65,13 +78,25 @@ export const configuredOut = (cwd, env) => {
 };
 export const runFirstPull = async (client, cwd, env, configuredOut) => {
     const exists = path => existsSync(resolve(cwd, path));
+    const read = (path) => {
+        try {
+            return readFileSync(resolve(cwd, path), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
     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))) };
+        const published = await client.published().then(r => r.publishedVersionId).catch(() => null);
+        if (!needsPull(exists, read, dir, published))
+            return { ran: false, reason: 'up-to-date', dir };
+        const result = await pullStyles(client, fileWriter(resolve(cwd, dir)));
+        // Stamped only after the write, so a failed pull is retried on the next connection.
+        await writeFile(resolve(cwd, dir, STAMP), `${result.publishedVersionId}\n`, 'utf8');
+        return { ran: true, dir, result };
     }
     catch (error) {
         // A project with nothing published, an expired key, no network — none of them may stop the server.

package/package.json

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

package/skill/SKILL.md

@@ -31,6 +31,42 @@ page, and it is worth reading in full before the first line of code.
 | 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) |
 
+## Before the first token: check the stylesheets are imported
+
+A token only resolves if the pulled stylesheets are actually loaded. `flareum pull` writes them into
+the project — it does not wire them in, because which file is the global entry point is the
+project's decision, not the tool's.
+
+So the first time you use a token in a project, check the import exists, and add it if it does not.
+Otherwise every `var([prefix]-…)` you write is correct and renders as nothing — the failure is
+silent, and it looks like the token is wrong rather than absent.
+
+**Find the pulled files** (`src/styles/flareum/`, or wherever `out` in `.flareum/config.json`
+points), then **find the global stylesheet** — the one the app already loads for everything:
+
+| Project | Usually |
+|---|---|
+| Angular | the `styles` entry in `angular.json` — commonly `src/styles.scss` |
+| Vite / React / Vue | the CSS imported by the entry module — `src/main.tsx`, `src/index.css` |
+| Next.js | `app/globals.css`, imported by the root layout |
+| Plain | whatever the HTML `<link>`s |
+
+Add the import at the **top**, before anything that uses a token:
+
+```scss
+@use './styles/flareum/main';   // SCSS
+```
+```css
+@import './styles/flareum/main.css';   /* plain CSS */
+```
+
+Then confirm it resolves — build, or grep the built CSS for a `--[prefix]-` declaration. A token
+that is imported but still not applying is usually the `font:` shorthand or a missing
+`--line-height`; [references/typography.md](references/typography.md) covers both.
+
+If the pulled folder does not exist at all, the project has never pulled: say so and give the
+command — `npx -p @flareum/mcp flareum pull` — rather than writing tokens that cannot resolve.
+
 ## Reading a search result
 
 The header tells you which kind of answer you got, and they mean different things: