@flareum/mcp 0.5.0 → 0.5.8

package/dist/cli.js

@@ -69,7 +69,9 @@ try {
         // The server reads this lock to decide whether to pull. Without it a CLI pull was invisible,
         // and the next connection fetched the same version again.
         if (!isRetryable(result))
-            await writeLock(process.cwd(), makeLock(projectIdFromToken(config.token), result.publishedVersionId, outDir, new Date().toISOString()));
+            // An explicit pull is the deliberate act applying.md ends on, so it advances BOTH: these
+            // stylesheets, and the version the code is now written against.
+            await writeLock(process.cwd(), makeLock(projectIdFromToken(config.token), result.publishedVersionId, outDir, new Date().toISOString(), result.publishedVersionId));
         console.log(pullReport(result, outDir));
         return result;
     };

package/dist/first-pull.js

@@ -101,14 +101,17 @@ export const configuredOut = (cwd, env) => {
 };
 export const runFirstPull = async (client, cwd, env, configuredOut, knownVersion, now = () => new Date().toISOString()) => {
     const exists = path => existsSync(resolve(cwd, path));
-    const isEmpty = path => {
+    // Any FILE, at any depth. An empty directory tree is what a git clean leaves behind, not somebody
+    // else's work — counting those as content refused to ever pull again.
+    const holdsNoFiles = (dir) => {
         try {
-            return readdirSync(resolve(cwd, path)).length === 0;
+            return readdirSync(dir, { withFileTypes: true }).every(entry => entry.isDirectory() && holdsNoFiles(join(dir, entry.name)));
         }
         catch {
             return true;
         }
     };
+    const isEmpty = path => holdsNoFiles(resolve(cwd, path));
     const dir = chooseStylesDir(exists, configuredOut);
     if (!autoPullEnabled(env))
         return { ran: false, reason: 'disabled', dir };
@@ -128,12 +131,15 @@ export const runFirstPull = async (client, cwd, env, configuredOut, knownVersion
         // Claimed BEFORE the first write: an interrupted pull leaves files with no completed version,
         // and without this it would read as somebody else's folder and never be finished.
         await mkdir(resolve(cwd, dir), { recursive: true });
-        await writeLock(cwd, makeLock(projectId, IN_FLIGHT, dir, now()));
+        // The applied version is carried across every write here: this pull is unattended, and
+        // advancing it would consume the diff window before an agent could read it.
+        const applied = lock?.appliedVersionId ?? syncedVersion(lock, dir) ?? undefined;
+        await writeLock(cwd, makeLock(projectId, IN_FLIGHT, dir, now(), applied));
         const result = await pullStyles(client, fileWriter(resolve(cwd, dir)));
         // Recorded only when the WHOLE version landed: pullStyles resolves even when files failed, so
         // stamping on its return marked a half-pulled folder complete and never retried it.
         if (!isRetryable(result))
-            await writeLock(cwd, makeLock(projectId, result.publishedVersionId, dir, now()));
+            await writeLock(cwd, makeLock(projectId, result.publishedVersionId, dir, now(), applied));
         return { ran: true, dir, result };
     }
     catch (error) {

package/dist/lock.d.ts

@@ -2,6 +2,7 @@ export declare const LOCK_PATH = ".flareum/lock.json";
 export type Lock = {
     projectId: string;
     syncedVersionId: string;
+    appliedVersionId?: string;
     syncedAt: string;
     out: string;
     prefix?: string;
@@ -12,7 +13,8 @@ export declare const readLock: (cwd: string) => Lock | null;
 export declare const owns: (lock: Lock | null, dir: string) => boolean;
 export declare const syncedVersion: (lock: Lock | null, dir: string) => string | null;
 export declare const writeLock: (cwd: string, lock: Lock) => Promise<void>;
-export declare const makeLock: (projectId: string, syncedVersionId: string, out: string, at: string, prefix?: string) => Lock;
+export declare const makeLock: (projectId: string, syncedVersionId: string, out: string, at: string, appliedVersionId?: string, prefix?: string) => Lock;
+export declare const appliedVersion: (lock: Lock | null) => string;
 export declare const LEGACY_STAMP = ".flareum-version";
 export declare const legacyVersion: (cwd: string, dir: string) => string | null;
 export declare const legacyStampExists: (cwd: string, dir: string) => boolean;

package/dist/lock.js

@@ -20,7 +20,17 @@ export const writeLock = async (cwd, lock) => {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
 };
-export const makeLock = (projectId, syncedVersionId, out, at, prefix) => ({ projectId, syncedVersionId, syncedAt: at, out, ...(prefix ? { prefix } : {}) });
+export const makeLock = (projectId, syncedVersionId, out, at, appliedVersionId, prefix) => ({
+    projectId, syncedVersionId, syncedAt: at, out,
+    ...(appliedVersionId ? { appliedVersionId } : {}),
+    ...(prefix ? { prefix } : {}),
+});
+// What an agent diffs FROM. Falls back to the stylesheets for a lock written before this field, and
+// never returns the in-flight sentinel — a pull half-done is not a version anything was applied to.
+export const appliedVersion = (lock) => {
+    const applied = lock?.appliedVersionId ?? lock?.syncedVersionId;
+    return !applied || applied === IN_FLIGHT ? '' : applied;
+};
 // A project pulled by 0.2.x recorded the version in a stamp beside the stylesheets. Adopted rather
 // than ignored, so an upgrade does not re-pull a version already on disk.
 export const LEGACY_STAMP = '.flareum-version';

package/dist/server.js

@@ -11,10 +11,10 @@ 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';
-import { readLock } from './lock.js';
+import { appliedVersion, readLock } from './lock.js';
 // The agent should not have to be told which version to diff from — the lock in the project is the
 // answer, and asking the model to supply it invites a guess.
-const lockedVersion = () => readLock(process.cwd())?.syncedVersionId ?? '';
+const lockedVersion = () => appliedVersion(readLock(process.cwd()));
 // 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;
@@ -75,8 +75,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         if (request.params.name === 'flareum_search')
             return text(formatSearch(await client.search(String(args.query ?? ''), Number(args.limit) || undefined)));
-        if (request.params.name === 'flareum_changes_since')
-            return text(formatChanges(await client.changes(String(args.since ?? '')), lockedVersion()));
+        if (request.params.name === 'flareum_changes_since') {
+            // Defaulted here, not left to the model: the lock is the answer, and asking for it invites a guess.
+            const locked = lockedVersion();
+            const since = String(args.since ?? '') || locked;
+            return text(formatChanges(await client.changes(since), locked));
+        }
         if (request.params.name === 'flareum_get')
             return text(formatVariable(await client.variable(String(args.path ?? ''))));
         return text(`Unknown tool: ${request.params.name}`);

package/dist/tools.js

@@ -72,7 +72,8 @@ export const TOOL_DESCRIPTIONS = {
     get: 'Read one design token in full: its value in every mode, its type, which components use it, and '
         + 'which other tokens reference it. Use it to judge what a change would affect before making one.',
     changes: 'List what changed in Flareum since the version this project last synced. Call it when the user '
-        + 'asks to update, sync or migrate tokens, and at the start of a session in a project that has a '
+        + 'says "update flareum", or asks to sync, update or migrate tokens, and at the start of a '
+        + 'session in a project that has a '
         + '.flareum/lock.json. A rename reads as a rename with both names, so rewrite the call sites '
         + 'rather than deleting and adding. A removed token carries what to use instead. Read every '
         + 'entry before editing anything, and say what you are about to change.',
@@ -80,14 +81,14 @@ export const TOOL_DESCRIPTIONS = {
 // Written for a model that is about to EDIT files: the CSS names first, because those are what it
 // greps for, and the action stated per line so a rename is never applied as a delete plus an add.
 export const formatChanges = ({ since, totalChanges, entries, truncated, liveVersionId }, lockedVersion = '') => {
-    if (!totalChanges)
+    if (!totalChanges || !entries.length)
         return since
             ? `No changes since ${since}. The project is at ${liveVersionId}.`
             : `This project has no tokens yet.`;
     const lines = [
         since
-            ? `${totalChanges} change(s) since ${since}. The project is now at ${liveVersionId}.`
-            : `${totalChanges} change(s). No baseline was given, so this is everything the project has.`,
+            ? `${entries.length} change(s) since ${since}. The project is now at ${liveVersionId}.`
+            : `${entries.length} change(s). No baseline was given, so this is everything the project has.`,
         '',
     ];
     if (lockedVersion && since && lockedVersion !== since)
@@ -114,7 +115,8 @@ const changeLine = (entry) => {
     if (change === 'typeChanged')
         return `${kind} type: ${nameOf(before)} is now ${after?.type} (was ${before?.type})`;
     if (change === 'valueChanged')
-        return `${kind} value${mode}: ${nameOf(before)}  ${before?.value} → ${after?.value}`;
+        return `${kind} value${mode}: ${nameOf(before)}  ${before?.value ?? '(not set)'} → `
+            + `${after?.value ?? '(not set)'}`;
     if (change === 'movedCollection')
         return `${kind} moved collection: ${nameOf(before)} → ${nameOf(after)}`;
     return `${kind} ${change}: ${nameOf(after ?? before)}`;

package/package.json

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

package/skill/SKILL.md

@@ -5,106 +5,90 @@ description: Use the project's Flareum design tokens instead of literal values.
 
 # Flareum design tokens
 
-This project's design tokens live in Flareum. The generated CSS/SCSS in the repo is a **rendering**
-of them — the tokens themselves, with their types, modes, comments and usage, are reachable through
-the `flareum_search` and `flareum_get` tools.
+Tokens live in Flareum. `flareum_search` and `flareum_get` read them; the CSS/SCSS in the repo is a
+rendering of them.
 
-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.
+Names below use **`[prefix]`** for this project's own prefix — the string every `cssName` 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.**
 
-A hardcoded `#5B8DEF` is a token that escaped the system. A newly invented `color/border/muted` beside
-an existing `color/border/secondary` is worse — it looks like a decision, and nobody will ever
-reconcile the two. `flareum_search` takes a hex, an rgb(), a path fragment, a phrase from a comment,
-or a component name.
+A hardcoded `#5B8DEF` is a token that escaped the system. An invented `color/border/muted` beside an
+existing `color/border/secondary` is worse — it looks like a decision, and nobody reconciles the two.
+Search takes a hex, an rgb(), a path fragment, a comment phrase, or a component name.
 
-## The rules, by topic
+## Before the first token in a project
 
-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.
+Three checks. All three fail silently — a correct `var([prefix]-…)` renders as nothing, which reads
+as the token being wrong rather than missing.
 
-| 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) |
-| Applying what `flareum_changes_since` returned — a sync, an update, a migration | [references/applying.md](references/applying.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.
+**1. Are they on disk?** Look in `src/styles/flareum/`, or wherever `out` in `.flareum/config.json`
+points. If it is missing or holds no stylesheets:
 
-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:
+```bash
+npx -y -p @flareum/mcp flareum pull
+```
 
-| 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 |
+Pull into the folder this project already keeps styles in. If the default would miss it:
+`npx -y -p @flareum/mcp flareum pull --out app/styles/flareum`.
 
-Add the import at the **top**, before anything that uses a token:
+**2. Are they imported?** Add it to the global stylesheet, at the top:
 
 ```scss
-@use './styles/flareum/main';   // SCSS
-```
-```css
-@import './styles/flareum/main.css';   /* plain CSS */
+@use './styles/flareum/main';
 ```
 
-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.
+That file is the `styles` entry in `angular.json` (usually `src/styles.scss`), `app/globals.css` in
+Next.js, or whatever the entry module imports. Confirm it worked — build, or grep the built CSS for a
+`--[prefix]-` declaration.
 
-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.
+**3. Are they current?** Call `flareum_changes_since`. If it reports changes, the local stylesheets
+are behind the designer — a token you are about to use may have been renamed or removed. **Say what
+changed and ask before updating. Do not pull silently.** On yes, follow "Update Flareum". On no, use
+the tokens as they are on disk and say which choices may be affected.
 
-## When the project is behind
+**Never write tokens against stylesheets that are not there.**
 
-A project with a `.flareum/lock.json` was synced at a particular version. `flareum_changes_since`
-says what has changed since — a rename reads as a rename, a removed token carries what to use
-instead. Reach for it when the user asks to sync, update or migrate tokens, and at the start of a
-session in a project that has a lock.
+## "Update Flareum"
 
-**Applying those entries has an order that matters**, and getting it wrong leaves a project that
-reports itself synced while still referencing dead tokens:
-[references/applying.md](references/applying.md).
+When the user says **update flareum**, or asks to sync or migrate tokens:
 
-## Reading a search result
-
-The header tells you which kind of answer you got, and they mean different things:
+1. `flareum_changes_since`.
+2. **Say what it means** — how many renames, removals and value changes, and how many files each
+   rename touches. A removal with a recorded successor is substituted; one **without** is reported
+   and left alone: you have no basis for choosing a successor, and a guess is how a design system
+   quietly acquires wrong semantics.
+3. **Ask before changing anything.** A no stops there.
+4. On yes: **rewrite the call sites first, pull last.** The pull brings the stylesheets AND records
+   the project as synced, so pulling first then failing halfway leaves a project that reports itself
+   current while still using dead tokens. Rewrite names only — a value change needs no code edit.
 
-- **`Match for "…"`** — use it. The `cssName` is ready to paste.
-- **`No confident match for "…"`** — the listed tokens are **nearest neighbours, not matches**. One
-  of them is often the thing you want under a name you would not have guessed. **Do not create a
-  token or hardcode a value on the strength of this.** Ask which to use, or search again with the
-  value rather than the name.
+If nothing has changed, say so in one line and stop.
 
-An empty project says so explicitly. Anything else always returns candidates.
+## Reading a search result
 
-## If the token genuinely does not exist
+- **`Match for "…"`** — use it. The `cssName` is ready to paste.
+- **`No confident match for "…"`** — these are nearest neighbours, not matches. One is often what
+  you want under a name you would not have guessed. **Do not invent a token or hardcode a value on the
+  strength of this.** Ask which to use, or search again by value.
 
-This integration is **read-only** — there is no tool that writes to Flareum, by design. So:
+## If the token does not exist
 
-1. Say which token is missing and what it would be for.
-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 integration is **read-only** — nothing writes to Flareum. Say which token is missing and what it
+is for, propose a name that fits [the grammar](references/naming.md), and do not hardcode the value
+and move on.
 
-## Blast radius before a change
+## Before changing a token
 
-`flareum_get` reports two independent things, and they answer different questions:
+`flareum_get` reports **component usage** (which components consume it) and **referrers** (which
+tokens reference it, and would break). No usage data means **unknown**, not unused — grep the repo
+before treating a token as safe to change.
 
-- **component usage** — which components consume it (from an imported analysis).
-- **referrers** — which other tokens reference it, and would break.
+## By topic
 
-If it says no usage data has been imported, that means **unknown**, not unused. Grep the repo
-yourself before treating a token as safe to change.
+| Writing | Read |
+|---|---|
+| Any text — heading, label, body copy, a pseudo-element's `content` | [references/typography.md](references/typography.md) |
+| A token name, or judging one that exists | [references/naming.md](references/naming.md) |

package/skill/references/applying.md

@@ -1,70 +0,0 @@
-# Applying what changed
-
-Read this when `flareum_changes_since` returns entries, or the user asks to sync, update or migrate
-tokens.
-
-## The order is the safety
-
-**Rewrite the call sites first. Pull last.**
-
-`flareum pull` brings the new stylesheets AND stamps `.flareum/lock.json`, which is what records the
-project as synced. Pull first and a rewrite that fails halfway leaves the lock advanced over a
-codebase still referencing dead tokens — the next session reports nothing to do, and the breakage is
-invisible. Pull last and a failed rewrite simply leaves the project where it was.
-
-```
-1. flareum_changes_since        read every entry before editing anything
-2. show the developer           what you are about to change, and what you cannot
-3. rewrite the call sites       names only
-4. npx -p @flareum/mcp flareum pull      the new tree, and the lock
-```
-
-Do not update `lock.json` by hand. It is stamped by a successful pull, and stamping it any other way
-is claiming work that did not happen.
-
-## What you may change, and what you may not
-
-| You may | You may not |
-|---|---|
-| Rewrite `var(--old)` → `var(--new)` across the repo | Change a **value**. Only a name. |
-| Substitute a removed token's recorded replacement | Guess a replacement when none is recorded |
-| Replace the pulled `variables/` tree by pulling | Hand-edit anything inside it — it is generated |
-| Report what you could not resolve | Silently skip an entry |
-
-## Entry by entry
-
-**`renamed` / `moved`** — one entry carries both names. Rewrite every occurrence of `before.cssName`
-to `after.cssName`. It is a rename: do not delete the old and add the new, and do not touch the value.
-
-**`viaFolder`** — this rename is part of a whole folder moving. Apply it as one prefix rewrite across
-the members rather than N independent edits, and say so once rather than N times.
-
-**`deleted` with a replacement** — substitute it. The replacement is what the designer recorded as
-the successor, and it may be a token, a formula or a literal.
-
-**`deleted` with NO replacement** — **report it and leave it alone.** You have no basis for choosing
-a successor, and a plausible-looking guess is how a design system quietly acquires wrong semantics.
-Name the token, name the files that use it, and let the developer decide.
-
-**`valueChanged`** — nothing to do in the code. The value lives in the stylesheets the pull replaces;
-a call site referencing the token gets the new value for free. Mention it only if the change is large
-enough that someone should look at the result.
-
-**`typeChanged`** — the token still exists under the same name, but it is a different kind of value
-now (a colour that became a number). The call sites may still compile and be wrong. Report each one;
-do not rewrite them silently.
-
-**`added`** — nothing to apply. Worth mentioning only if it replaces something you are about to
-report as removed.
-
-**`reordered`** — ignore. It affects the order tokens are emitted in, not any call site.
-
-## Before you touch a file
-
-Say what you are about to do, in the developer's terms: how many call sites, in how many files, and
-what you will not be touching. A migration nobody agreed to is a migration nobody can review.
-
-## When it does not go cleanly
-
-Report what failed and **do not pull**. A partial rewrite with the old stylesheets still in place is
-a working project; a partial rewrite with the lock advanced is a broken one that claims to be current.