synthesisui 0.16.59 → 0.16.60

package/dist/commands/connect.js

@@ -1,6 +1,9 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { wireAgent } from "../agent-wiring.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { body, section, snippet } from "../output.js";
+import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
 /**
  * `synthesisui connect` - put the three layers where they actually run.
  *
@@ -39,10 +42,31 @@ export async function connect(opts) {
             : "· .mcp.json              already had it"));
     }
     console.log(body("✓ CLAUDE.md              rewritten for what is installed"));
+    /**
+     * The fourth layer, and the one that had no installer at all: the import
+     * skill existed only in our own repo, so the only way to get it was to clone
+     * the monorepo and copy a folder (dono, 31/07). A skill nobody can install is
+     * a skill nobody has.
+     *
+     * It belongs here because `connect` is already "wire your agent", it is
+     * already idempotent, and rerunning it is already the answer to "did
+     * something change" - so nobody has to remember a second command.
+     */
+    const skillPath = join(root, IMPORT_SKILL_PATH);
+    const before = await readFile(skillPath, "utf8").catch(() => null);
+    if (before !== IMPORT_SKILL) {
+        await mkdir(dirname(skillPath), { recursive: true });
+        await writeFile(skillPath, IMPORT_SKILL, "utf8");
+    }
+    console.log(body(before === IMPORT_SKILL
+        ? "· /import-design-system  already current"
+        : before == null
+            ? "✓ /import-design-system  the import, orchestrated"
+            : "✓ /import-design-system  updated to this CLI's pipeline"));
     // The step that cost a round trip the first time this was tried by hand,
     // and would cost every single person one.
     console.log("");
-    console.log(body("Reopen your editor session - both are read at startup."));
+    console.log(body("Reopen your editor session - all of them are read at startup."));
     if (want.mcp) {
         console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
     }

package/dist/skill-import.js

@@ -0,0 +1,220 @@
+/**
+ * THE IMPORT SKILL, as the CLI ships it.
+ *
+ * It lives here rather than as a file copied at build time for one reason: the
+ * build is `tsc` and nothing else, so a `.md` would need a copy step that can
+ * silently not run. A TypeScript module cannot fail to be packaged.
+ *
+ * THIS IS THE SOURCE. The copy in our own `.claude/skills/` is what our editor
+ * reads, and `skill-import.spec.ts` asserts the two are identical - so drift
+ * turns a test red instead of shipping a skill that describes a pipeline the
+ * CLI no longer has.
+ */
+export const IMPORT_SKILL = `---
+name: import-design-system
+description: Turn a codebase the user ALREADY has into a SynthesisUI design system. Use when someone points at an existing repo, app or component library and asks to import it, adopt it, bring it in, or "make a design system from this" (e.g. "/import-design-system", "importa o meu packages/ui", "turn this app into a design system"). Drives the full pipeline - census → your reading → import → v2 proposal - and answers the questions arithmetic cannot.
+---
+
+# Import Design System
+
+Read a project the user already built and give it back to them as a system that governs it.
+
+The census is **arithmetic** and it is not yours to redo. Every colour ranked, every ΔE
+measured, every component crosswalked - the CLI does all of it, deterministically, for free,
+and it will be right. Your job is the part with no closed form: **understanding how this
+project is structured.**
+
+## The golden rule
+
+**You may judge. You may never invent.**
+
+Every hex you name has to be one the census already observed - the endpoint drops the rest
+silently, and a "faithful" import carrying a colour the author never wrote is the one failure
+this whole pipeline exists to prevent. The same discipline applies to everything else you
+report: if you did not read it in their files, do not claim it.
+
+When you are unsure, say so in \`concept\` and leave the field out. An absent answer falls back
+to arithmetic, which is honest. A confident wrong answer inverts someone's product.
+
+## The pipeline
+
+### 0. Check the login FIRST, and stop if there is none
+
+\`\`\`
+cat ~/.synthesisui/credentials.json 2>/dev/null || echo "NO TOKEN"
+\`\`\`
+
+No token, or a run that later comes back **HTTP 401**, means there is nothing to send to. **Stop
+there.** Do not measure, do not read the project, do not write a reading - say this and wait:
+
+\`\`\`
+You need to authenticate first:
+
+    npx synthesisui login
+\`\`\`
+
+It is a device flow: it opens a browser and needs a person. You cannot complete it, and there
+is no point doing twenty minutes of reading against a session that will refuse the payload at
+the end (dono, 31/07 - a full read ended on a 401 that a first command would have caught).
+
+**Read the \`registry\` field in that file, and pass it to EVERY later command.** A token belongs
+to the host that issued it. One minted by \`login --registry http://localhost:3000\` and then
+sent to the default (production) earns a 401 that reads as an expired session - and a session
+cannot expire on a host that never issued it. That is how a full read ended in a dead end
+twice (dono, 31/07).
+
+So if the file says \`"registry": "http://localhost:3000"\`, every command in this skill carries
+\`--registry http://localhost:3000\`. If it says production, pass nothing. The CLI now refuses a
+mismatch instead of letting the server reject it, but the point is not to reach that.
+
+### 1. Measure
+
+\`\`\`
+npx synthesisui import --dry --dir <the folder that holds the design decisions>
+\`\`\`
+
+In a monorepo that folder is almost never the repo root. Look for the package every app
+imports from - \`packages/ui\`, \`packages/design-system\`, \`libs/shared-ui\`. The CLI names the
+candidates and ranks them by how many tokens they declare; if it printed a workspace summary,
+read it before choosing. Scoping to the wrong folder measures the wrong thing, and the score
+it reports will be meaninglessly low.
+
+This writes \`_synthesisui/census.json\` and **sends nothing**. Read that file.
+
+### 2. Read what arithmetic cannot
+
+Open the project and answer the questions below. Then add a \`reading\` object to
+\`_synthesisui/census.json\`:
+
+\`\`\`json
+"reading": {
+  "themes": { "default": "dark", "has": ["dark"] },
+  "roles": { "canvas": "#050505", "foreground": "#f9fafb", "primary": "#4A90E2" },
+  "fonts": { "display": "Inter", "body": "Inter" },
+  "concept": "one paragraph on what this product is",
+  "by": "claude"
+}
+\`\`\`
+
+Every field is optional. Leave out what you did not establish.
+
+**\`themes\` - which themes the product actually ships, and which one it opens in.**
+
+This is the field that matters most and the one only you can fill. The ladder can say which
+*values* exist; it cannot say which themes the product *has*, because that answer lives in a
+\`dark:\` class name, a \`ThemeProvider\`, a toggle component, a \`prefers-color-scheme\` query -
+places no token reader sees. A real library declared nine near-blacks and five light greys in
+one \`:root\` block, and the import handed its near-black dashboard a white page.
+
+Go and look:
+
+- \`grep -rn "dark:" --include=*.tsx\` - Tailwind's dark variant, invisible to a token reader
+- a theme provider, \`useTheme\`, \`next-themes\`, a \`data-theme\` attribute, a toggle in the shell
+- \`prefers-color-scheme\` in the CSS
+- the root layout: what class or attribute does \`<html>\` or \`<body>\` carry by default
+- failing all of that, open the app's main page component and see what it paints
+
+\`has: ["dark"]\` on a dark-only product is the right answer. It is better than filling a light
+slot on their behalf, and it makes adding light a deliberate act they take later.
+
+**\`roles\` - which of their values carries which meaning**, when their token names do not say.
+A project naming its neutrals by temperature (\`--color-darkgray-900\`) has told you nothing
+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.
+
+### 3. Send it
+
+\`\`\`
+npx synthesisui import --census _synthesisui/census.json --name "<their name for it>" [--registry <the one from step 0>]
+\`\`\`
+
+**One real write, and it creates a system on their account.** Say what you are about to send
+and what it will be called before you run it.
+
+The CLI asks for a name unless \`--name\` is passed. It does **not** ask about the scheme when
+your reading already answered - a second question would only be a chance to contradict you.
+
+If it refuses, it will tell you which of the two problems it is: no session, an expired one, or
+a token issued by a different host than the one you are sending to. All three are recoverable
+from the census already on disk; none of them need a re-measure.
+
+### 4. Tell them exactly what they have, and what is theirs to decide
+
+The import publishes **v1** as a faithful baseline and opens a **v2 draft** holding the
+proposal. Say all of this in your own words - do not just print the link:
+
+**What landed in v1**, and it is theirs, not ours:
+
+- the scheme it opens in, and whether a second one was built
+- their ramps under their own family names
+- their exclusive components as contracts - **axes declared, every style block empty.** Say
+  this out loud, because a component list full of blank recipes looks like a failure until
+  someone explains it was deliberate. The platform shows them as *Not written yet*, not as a
+  zero.
+
+**What is waiting in v2**, which only they can approve: near-duplicate colours collapsed,
+unnamed heavy hitters given a place. Point at the link the CLI printed and name the two or
+three biggest items so they know whether it is worth opening now.
+
+**What the report said no to.** The notes carry every silent drop made loud - a value not
+found in their code, a token that is not ramp-shaped, a name the document refused. Read them
+and pass on the ones that matter.
+
+### 5. Close the loop in their repo
+
+The system is only worth something once it governs the code it came from:
+
+\`\`\`
+npx synthesisui upgrade <slug> [--registry …]   # brings the contract in
+npx synthesisui doctor [paths…]                 # the contract starts being enforced
+\`\`\`
+
+\`doctor\` is where the promise pays off: every design value written by hand, the token their
+own system already has for it, and the components used outside the axes their contract
+declares. In a monorepo, scope it per app - one system, N consumers.
+
+## What good looks like
+
+The user should end up with a system that reads like theirs and not like ours:
+
+- **their names travel** - \`vivid-pink\`, \`darkgray-900\`, whatever they called it
+- **their default face** - a dark product opens dark
+- **no borrowed colour** - if it is in the system, it is in their code
+- **their exclusive components arrive as contracts** - axes declared, every style block empty,
+  because a contract says what may vary and a recipe would be us redesigning their component
+- **the duplicates are named out loud** - three components that all read as a badge, a brand
+  colour painted 275 times with no token
+
+## What to resist
+
+- **Do not run \`import\` without \`--dry\` to explore.** It creates a real system on their
+  account. Measure with \`--dry\`, read, then send once.
+- **Do not redo the arithmetic.** If you find yourself counting colours, you are in the wrong
+  half of the pipeline.
+- **Do not fill \`roles\` with what looks nice.** It is a reading of what their code already
+  does, not a redesign. The v2 proposal is where improvement belongs, and the user approves it.
+- **Do not guess \`themes\` to be helpful.** Omitting it falls back to counting rungs, which is
+  a guess the product labels as a guess. A wrong confident answer does not get labelled.
+- **Do not apologise for the empty contracts.** They are the design. Explain them.
+
+## Not yet true
+
+Say so if it comes up, rather than implying otherwise:
+
+- **The v2 proposal covers colour only.** Near-duplicate collapse and unnamed heavy hitters.
+  It does not yet propose swapping a raw value in a recipe for the token that holds it, nor
+  retiring an option nothing passes, nor a categorical chart palette - all measured, none
+  offered.
+- **You do not write recipes.** Exclusive components arrive as contracts and stay that way
+  until someone writes the look. When that lands, the rule will be **provenance, not
+  membership**: a value transcribed out of their file cites the file and line, and is
+  legitimate even if the census never saw it, because the census measures less than a project
+  contains.
+- **Nothing confirms the import back.** You send, the CLI prints a link, and nobody asks the
+  platform whether what arrived is what you meant. Until that exists, tell them to open the
+  link and check.
+`;
+/** Where it lands in the consumer's repo. */
+export const IMPORT_SKILL_PATH = ".claude/skills/import-design-system/SKILL.md";

package/package.json

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