synthesisui 0.16.73 → 0.16.75

package/dist/commands/add.js

@@ -6,6 +6,8 @@ import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.
 import { buildGuide } from "../guide.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
+import { describeFiltered, rulesForProject } from "../rule-filter.js";
+import { detectStack } from "../stack.js";
 async function readRootLock(path) {
     try {
         return JSON.parse(await readFile(path, "utf8"));
@@ -70,7 +72,19 @@ export async function add(slug, opts) {
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
     // 5b. governance rules (personal DS) → rules.md at the slug root (stable path,
     //     highest authority; the GUIDE tells the agent to read it first)
-    const rules = payload.rules ?? [];
+    /**
+     * The structured set wins when the registry sent one, because only this side
+     * knows what the project is built with - a rule that names `next` has no
+     * business in a Vue app. Falling back to the flat strings keeps an older
+     * registry working unchanged.
+     */
+    const stack = await detectStack(projectRoot);
+    const rules = payload.ruleSet && payload.ruleSet.length > 0
+        ? rulesForProject(payload.ruleSet, stack)
+        : (payload.rules ?? []);
+    const leftOut = payload.ruleSet
+        ? describeFiltered(payload.ruleSet, stack)
+        : null;
     if (rules.length > 0) {
         const body = `# ${payload.name} - Rules\n\n` +
             "> Accumulated rules for this design system. **Max authority - follow these first.**\n" +
@@ -79,6 +93,10 @@ export async function add(slug, opts) {
                 .join("\n")}\n`;
         await writeFile(join(slugDir, "rules.md"), body, "utf8");
     }
+    // NO SILENT DROPS. A rule removed because it belongs to another environment is
+    // a thing the person should hear once, not discover by its absence.
+    if (leftOut)
+        console.log(line(leftOut));
     // 5c. structured philosophy (personal DS) → philosophy.md at the slug root.
     //     Narrative guidance (mission, principles, voice, motion doctrine…); the
     //     GUIDE points the agent here right after rules.md.

package/dist/commands/import.js

@@ -13,6 +13,7 @@ import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
 import { rootClasses, rootTag, transcribe, transcribeParts, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
+import { detectStack } from "../stack.js";
 import { walk, walkAll } from "./doctor.js";
 /**
  * How many distinct values travel, PER KIND.
@@ -93,70 +94,6 @@ async function siblingProjects(root) {
             .map((w) => w.rel),
     };
 }
-/**
- * Dependencies as the project actually resolves them - which means reading
- * ANCESTOR package.json files too.
- *
- * Measured on our own repo: `import --dir apps/web` reported "plain css" for a
- * Next + React + Tailwind app, because a workspace hoists those to the root and
- * the leaf package.json lists only its own icons. Three levels up covers every
- * pnpm/npm workspace layout without wandering into someone's home directory.
- */
-async function resolveDeps(root) {
-    const deps = {};
-    let dir = root;
-    for (let up = 0; up < 4; up++) {
-        const raw = await readFile(join(dir, "package.json"), "utf8").catch(() => null);
-        if (raw) {
-            try {
-                const p = JSON.parse(raw);
-                // The nearest package.json wins on a version clash; we only ever ask
-                // whether a name is present, so first-seen is enough.
-                for (const [k, v] of Object.entries({
-                    ...p.dependencies,
-                    ...p.devDependencies,
-                })) {
-                    if (deps[k] == null)
-                        deps[k] = String(v);
-                }
-            }
-            catch {
-                // unreadable manifest costs the detection, not the run
-            }
-        }
-        const parent = join(dir, "..");
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return deps;
-}
-async function detectStack(root) {
-    const stack = [];
-    const has = async (f) => (await readFile(join(root, f), "utf8").catch(() => null)) !== null;
-    const deps = await resolveDeps(root);
-    if (await has("components.json"))
-        stack.push("shadcn/ui");
-    if (deps.next)
-        stack.push("next");
-    else if (deps.vite)
-        stack.push("vite");
-    if (deps.react)
-        stack.push("react");
-    else if (deps.vue)
-        stack.push("vue");
-    else if (deps.svelte)
-        stack.push("svelte");
-    if (deps.tailwindcss)
-        stack.push("tailwind");
-    if (await has("tokens.json"))
-        stack.push("tokens.json");
-    // Nothing recognised is itself a finding: plain CSS is a supported entrance,
-    // and saying so beats an empty list that reads like a failed detection.
-    if (stack.length === 0)
-        stack.push("plain css");
-    return stack;
-}
 /**
  * Their own vocabulary, read from stylesheets - the same harvest the doctor runs
  * when nothing of ours is installed.

package/dist/rule-filter.js

@@ -0,0 +1,62 @@
+/**
+ * WHICH RULES BELONG IN *THIS* PROJECT.
+ *
+ * A rule travels with the design system, and the system gets installed places it
+ * was never written for. "The state arrives through this hook" is true about Next
+ * and actively wrong about Vue - so a rule carries the environments it holds in,
+ * and the filtering happens HERE, because the consumer's stack is the one thing
+ * the platform cannot know (dono, 01/08).
+ *
+ * THE DEFAULT WHEN WE CANNOT TELL IS TO KEEP IT. A rule whose condition does not
+ * match is removed, because obeying it would be a mistake. A rule we cannot
+ * evaluate - the stack came back empty, or it names something we do not detect -
+ * stays, because a rule nobody can judge is safer present than silently gone.
+ * Those are two different situations and they get two different answers.
+ */
+const norm = (v) => v.trim().toLowerCase();
+/**
+ * True when this rule holds in a project built with `stack`.
+ *
+ * `stack` is what `detectStack` reported, so `plain css` and an unrecognised
+ * entry both read as "we could not tell" rather than as a contradiction.
+ */
+export function ruleApplies(rule, stack) {
+    const when = (rule.when ?? []).map(norm).filter(Boolean);
+    if (when.length === 0)
+        return true;
+    const here = new Set(stack.map(norm));
+    // Nothing recognised: we are not in a position to rule anything out.
+    if (here.size === 0 || (here.size === 1 && here.has("plain css")))
+        return true;
+    return when.some((w) => here.has(w));
+}
+/**
+ * The lines for `rules.md`, in the order they were written.
+ *
+ * A scoped rule names its components, so an agent reading the file knows whether
+ * the line is about the thing it has open - and a rule about a RELATION names
+ * both, which is the whole reason the field exists.
+ */
+export function rulesForProject(rules, stack) {
+    const out = [];
+    for (const rule of rules) {
+        if (!ruleApplies(rule, stack))
+            continue;
+        const text = rule.text?.trim();
+        if (!text)
+            continue;
+        const scope = rule.applies?.length > 0
+            ? `${rule.applies.map((a) => `ds-${a}`).join(" + ")}: `
+            : "";
+        out.push(`${scope}${text}`);
+    }
+    return out;
+}
+/** What was left out, and why - said out loud rather than subtracted quietly. */
+export function describeFiltered(rules, stack) {
+    const dropped = rules.filter((r) => !ruleApplies(r, stack));
+    if (dropped.length === 0)
+        return null;
+    const envs = [...new Set(dropped.flatMap((r) => r.when.map(norm)))].sort();
+    return `${dropped.length} rule${dropped.length === 1 ? "" : "s"} left out - ${dropped.length === 1 ? "it belongs" : "they belong"} to ${envs.join(", ")} and this project is ${stack.join(" · ")}`;
+}

package/dist/skill-import.js

@@ -134,6 +134,23 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   "roles": { "canvas": "#050505", "foreground": "#f9fafb", "primary": "#4A90E2" },
   "fonts": { "display": "Inter", "body": "Inter" },
   "concept": "one paragraph on what this product is",
+  "rules": [
+    {
+      "text": "A RootWrapper is what makes the app-shell components position correctly - never render a Sidebar or Topbar outside one",
+      "applies": ["RootWrapper", "Sidebar"],
+      "kind": "implementation",
+      "when": ["next"],
+      "files": 3,
+      "evidence": "all three app shells wrap them; none renders them loose"
+    },
+    {
+      "text": "MetricCard is only used inside a grid, never on its own",
+      "applies": ["MetricCard"],
+      "kind": "limit",
+      "files": 1,
+      "evidence": "one dashboard page; may just be how it happened"
+    }
+  ],
   "components": {
     "MetricCard": {
       "parts": [
@@ -175,6 +192,64 @@ about which one is the page. Read a screen and see.
 **\`fonts\` and \`concept\`** - the voice, and one paragraph on what this product is. The concept
 feeds every recommendation downstream, so a real one beats a generic one by a wide margin.
 
+**\`rules\` - how this company BUILDS, which is half of what they actually made.**
+
+A design system that arrives as tokens and recipes is only the vocabulary. The other half is the
+grammar: that a wrapper exists so the thing inside it works, that state arrives through a
+particular hook, that a card is never used loose. That is how the developer already thinks, and
+writing it down is what makes it survive them.
+
+Two dimensions, and they are independent:
+
+\`\`\`
+applies  []       the whole system
+         [a]      that component
+         [a, b]   a RELATION - two components that only work together
+
+kind     limit           a boundary, which the doctor can measure
+         implementation  how it is built, which no linter checks and an agent
+                         must be told
+\`\`\`
+
+The relation is the valuable one. \`[RootWrapper, Sidebar]\` says something neither name says
+alone, and it is exactly what an agent needs in order not to assemble it wrongly.
+
+**\`when\` - the environments a rule is true in.** Leave it out and the rule holds everywhere.
+
+This exists because the system gets installed places it was never written for. *"The state arrives
+through this hook"* is true about Next and **actively wrong** about Vue, so a rule that depends on
+the framework has to say so - and the install filters against the project it lands in, because
+only the project knows what it is built with.
+
+One dimension: a member of the stack (\`next\`, \`vue\`, \`react\`, \`svelte\`, \`tailwind\`, \`shadcn/ui\`).
+A rule may list several. It cannot combine conditions - \`next && !tailwind\` would be a query
+language, and then somebody maintains an interpreter forever.
+
+Use it only when the rule genuinely depends on the environment. Most rules do not: *"never render
+a Sidebar loose"* is true about their design regardless of framework, and pinning it to \`next\`
+would quietly drop it the day they add a second app.
+
+**Report \`files\` honestly - it decides whether the rule governs.** Three or more files is a
+habit and the rule arrives active; one file is a coincidence and it arrives as a candidate,
+inactive, waiting for the person to promote it. You do not make that call; you report the
+evidence and a threshold makes it. So a pattern you saw once should say \`"files": 1\` even when
+you are confident - being wrong about a law is worse than being slow about one.
+
+**Write \`evidence\` as what you actually saw.** "All three app shells wrap them; none renders
+them loose" lets somebody disagree with a fact. "Best practice" lets them disagree only with
+you.
+
+Things worth looking for, none of them guessable from tokens:
+
+- a wrapper or provider whose whole purpose is to make something else work
+- an environment law - "this is Next, so the state comes through this hook" - which travels
+  with the system and only applies where that environment is
+- a component that is never used alone, or never used outside something
+- an axis that is always passed the same way in one place and never in another
+
+If you cannot say where a rule came from, do not send it. An invented law is worse than a
+missing one, because it will be obeyed.
+
 **\`components[Name].parts\` - what each component is MADE OF.** This is the field that decides
 whether a component previews as itself or as a grey box with a sentence in it, and only you can
 fill it.

package/dist/stack.js

@@ -0,0 +1,77 @@
+/**
+ * WHAT THIS PROJECT IS BUILT WITH - and who needs to know.
+ *
+ * The census reports it so a system knows where it came from. The INSTALL reads
+ * it so a rule that only applies to Next does not land in a Vue project: a rule
+ * travels WITH the design system and is conditional on the consumer (dono, 01/08
+ * - "se o ambiente que estiver instalado esse DS for next, use isso").
+ *
+ * One implementation, because two detectors that disagreed would put a rule in a
+ * project the census said was something else.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Dependencies as the project actually resolves them - which means reading
+ * ANCESTOR package.json files too.
+ *
+ * Measured on our own repo: `import --dir apps/web` reported "plain css" for a
+ * Next + React + Tailwind app, because a workspace hoists those to the root and
+ * the leaf package.json lists only its own icons. Three levels up covers every
+ * pnpm/npm workspace layout without wandering into someone's home directory.
+ */
+export async function resolveDeps(root) {
+    const deps = {};
+    let dir = root;
+    for (let up = 0; up < 4; up++) {
+        const raw = await readFile(join(dir, "package.json"), "utf8").catch(() => null);
+        if (raw) {
+            try {
+                const p = JSON.parse(raw);
+                // The nearest package.json wins on a version clash; we only ever ask
+                // whether a name is present, so first-seen is enough.
+                for (const [k, v] of Object.entries({
+                    ...p.dependencies,
+                    ...p.devDependencies,
+                })) {
+                    if (deps[k] == null)
+                        deps[k] = String(v);
+                }
+            }
+            catch {
+                // unreadable manifest costs the detection, not the run
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return deps;
+}
+export async function detectStack(root) {
+    const stack = [];
+    const has = async (f) => (await readFile(join(root, f), "utf8").catch(() => null)) !== null;
+    const deps = await resolveDeps(root);
+    if (await has("components.json"))
+        stack.push("shadcn/ui");
+    if (deps.next)
+        stack.push("next");
+    else if (deps.vite)
+        stack.push("vite");
+    if (deps.react)
+        stack.push("react");
+    else if (deps.vue)
+        stack.push("vue");
+    else if (deps.svelte)
+        stack.push("svelte");
+    if (deps.tailwindcss)
+        stack.push("tailwind");
+    if (await has("tokens.json"))
+        stack.push("tokens.json");
+    // Nothing recognised is itself a finding: plain CSS is a supported entrance,
+    // and saying so beats an empty list that reads like a failed detection.
+    if (stack.length === 0)
+        stack.push("plain css");
+    return stack;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.73",
+  "version": "0.16.75",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {