@flareum/mcp 0.5.1 → 0.5.8

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 };

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.',

package/package.json

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