@flareum/mcp 0.2.6 → 0.2.9

package/dist/first-pull.js

@@ -39,8 +39,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;
 };

package/dist/key-check.d.ts

@@ -0,0 +1,14 @@
+export type KeyCheck = {
+    usable: true;
+} | {
+    usable: false;
+    fatal: true;
+    message: string;
+} | {
+    usable: false;
+    fatal: false;
+    message: string;
+};
+export declare const classifyKeyCheck: (error: unknown) => KeyCheck;
+/** One cheap authenticated call, so "connected" cannot mean "holding a key the server rejects". */
+export declare const checkKey: (probe: () => Promise<unknown>) => Promise<KeyCheck>;

package/dist/key-check.js

@@ -0,0 +1,34 @@
+import { FlareumApiError } from './client.js';
+// A revoked key answers this; a project with nothing pushed answers NOT_PUBLISHED, which proves the
+// key works. Anything else is the network, and a blip must not take the server down.
+const REJECTED = new Set(['UNAUTHORIZED', 'FORBIDDEN', 'HTTP_401', 'HTTP_403']);
+export const classifyKeyCheck = (error) => {
+    if (!error)
+        return { usable: true };
+    if (error instanceof FlareumApiError && REJECTED.has(error.code))
+        return {
+            usable: false,
+            fatal: true,
+            message: `[flareum] ${error.message} ${error.hint}\n`
+                + '[flareum] Refusing to start: a connected server holding a dead key reports itself healthy, '
+                + 'and every token lookup then fails for a reason nothing on screen explains.',
+        };
+    if (error instanceof FlareumApiError)
+        return { usable: true };
+    return {
+        usable: false,
+        fatal: false,
+        message: `[flareum] could not verify the key — ${error instanceof Error ? error.message : String(error)}. `
+            + 'Starting anyway; the token tools will report their own errors.',
+    };
+};
+/** One cheap authenticated call, so "connected" cannot mean "holding a key the server rejects". */
+export const checkKey = async (probe) => {
+    try {
+        await probe();
+        return { usable: true };
+    }
+    catch (error) {
+        return classifyKeyCheck(error);
+    }
+};

package/dist/project-config.d.ts

@@ -0,0 +1,10 @@
+export type ConfigWrite = {
+    wrote: false;
+    reason: 'already-there' | 'no-token';
+} | {
+    wrote: true;
+    path: string;
+    gitignored: boolean;
+};
+export declare const writeProjectConfig: (cwd: string, env: Record<string, string | undefined>, out?: string) => Promise<ConfigWrite>;
+export declare const projectConfigReport: (result: ConfigWrite) => string | null;

package/dist/project-config.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { appendFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CONFIG_PATH } from './config.js';
+const IGNORE_LINE = '.flareum/';
+// Appended only when the pattern is absent: this file holds a key, and a project that commits it
+// has published one. Never rewrites an existing .gitignore beyond that one line.
+const ensureGitignored = async (cwd) => {
+    const path = join(cwd, '.gitignore');
+    try {
+        if (existsSync(path) && readFileSync(path, 'utf8').split('\n').some(l => l.trim() === IGNORE_LINE))
+            return true;
+        if (!existsSync(join(cwd, '.git')))
+            return false;
+        await appendFile(path, `\n# Holds a Flareum API key\n${IGNORE_LINE}\n`, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+// Gives the CLI the key the server was started with, so a connected project is never keyless.
+// Written once and never overwritten — an existing file is the developer's.
+export const writeProjectConfig = async (cwd, env, out) => {
+    const path = join(cwd, CONFIG_PATH);
+    if (existsSync(path))
+        return { wrote: false, reason: 'already-there' };
+    if (!env.FLAREUM_TOKEN)
+        return { wrote: false, reason: 'no-token' };
+    const gitignored = await ensureGitignored(cwd);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({
+        token: env.FLAREUM_TOKEN,
+        ...(env.FLAREUM_API ? { api: env.FLAREUM_API } : {}),
+        ...(out ? { out } : {}),
+    }, null, 2)}\n`, 'utf8');
+    return { wrote: true, path, gitignored };
+};
+export const projectConfigReport = (result) => {
+    if (!result.wrote)
+        return null;
+    const head = `[flareum] wrote ${CONFIG_PATH} so \`flareum pull\` works here without a key argument.`;
+    return result.gitignored ? head
+        : `${head} It holds a key — add ${IGNORE_LINE} to your .gitignore.`;
+};

package/dist/server.js

@@ -9,6 +9,8 @@ import { FlareumApiError, FlareumClient } from './client.js';
 import { TOOL_DESCRIPTIONS, formatError, formatSearch, formatVariable } from './tools.js';
 import { installSkill, skillInstallReport } from './skill.js';
 import { configuredOut, firstPullReport, runFirstPull } from './first-pull.js';
+import { projectConfigReport, writeProjectConfig } from './project-config.js';
+import { checkKey } from './key-check.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;
@@ -76,6 +78,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 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.
+// The CLI reads its key from the project, the server from its environment — two sources that can
+// disagree, and did: `flareum pull` said "no key" in a project whose server was connected.
+// "Connected" only means this process started, so a revoked key looked healthy while every lookup
+// failed. One authenticated call decides it before anything else runs.
+const key = await checkKey(() => client.published());
+if (!key.usable) {
+    console.error(key.message);
+    if (key.fatal)
+        process.exit(1);
+}
+const configWritten = projectConfigReport(await writeProjectConfig(process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
+if (configWritten)
+    console.error(configWritten);
 const firstPull = firstPullReport(await runFirstPull(client, process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
 if (firstPull)
     console.error(firstPull);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flareum/mcp",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "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: