synthesisui 0.16.137 → 0.16.139

package/dist/commands/mcp.js

@@ -4,6 +4,7 @@ import { readToken, resolveRegistry } from "../config.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
+import { repoStateOf } from "../repo-state.js";
 import { component } from "./component.js";
 import { loadSystem, walkAll } from "./doctor.js";
 const send = (msg) => {
@@ -577,7 +578,9 @@ async function validateRecipes(root, entries) {
  * verdade. Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra -
  * telemetria que atrasa a ferramenta é telemetria que alguém desliga.
  */
-function countAgentRead(root, component, action) {
+function countAgentRead(root, component, action, 
+/** A versão que está reportando - ver `repoStateOf`. Ausente = não reporta estado. */
+cli) {
     void (async () => {
         try {
             const token = await readToken();
@@ -604,6 +607,7 @@ function countAgentRead(root, component, action) {
             }
             if (!slug)
                 return;
+            const repo = cli ? await repoStateOf(root, slug, cli) : null;
             const base = resolveRegistry();
             await fetch(`${base}/api/telemetry/agent-read`, {
                 method: "POST",
@@ -611,7 +615,20 @@ function countAgentRead(root, component, action) {
                     Authorization: `Bearer ${token}`,
                     "content-type": "application/json",
                 },
-                body: JSON.stringify({ slug, component, action }),
+                /**
+                 * O ESTADO DO REPO PEGA CARONA AQUI - ver `repoStateOf`.
+                 *
+                 * Este ping já é automático e já manda slug/componente/ação em toda leitura de receita
+                 * pelo agente. "Em que versão eu estou" é o mesmo tipo de sinal, no mesmo momento, e
+                 * assim a tela tem o número sem depender de o cliente lembrar de rodar `sync` - que é
+                 * manual de propósito e vai continuar sendo.
+                 */
+                body: JSON.stringify({
+                    slug,
+                    component,
+                    action,
+                    ...(repo ? { repo } : {}),
+                }),
             });
         }
         catch {
@@ -798,7 +815,9 @@ async function addComponent(root, name) {
     return `${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`;
 }
 // ── The protocol ─────────────────────────────────────────────────────────────
-async function callTool(root, name, args) {
+async function callTool(root, name, args, 
+/** A versão que reporta o estado do repo no ping - ver `countAgentRead`. */
+cli) {
     switch (name) {
         case "check_file":
             return text(await checkFile(root, String(args.path ?? ".")));
@@ -807,10 +826,10 @@ async function callTool(root, name, args) {
         case "list_components":
             return text(await listComponents(root));
         case "describe_component":
-            countAgentRead(root, String(args.name ?? ""), "describe");
+            countAgentRead(root, String(args.name ?? ""), "describe", cli);
             return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
-            countAgentRead(root, String(args.name ?? ""), "add");
+            countAgentRead(root, String(args.name ?? ""), "add", cli);
             return text(await addComponent(root, String(args.name ?? "")));
         case "recipe_vocabulary":
             return text(await recipeVocabulary());
@@ -893,7 +912,12 @@ async function isPromisedByContract(root, name) {
  * Split out from the stdin loop so the protocol can be exercised without a
  * pipe: the loop below is framing, this is the protocol.
  */
-export async function handleRequest(root, req) {
+export async function handleRequest(root, req, 
+/**
+ * A versão que reporta o estado do repo no ping do agente - ver `repoStateOf`. Opcional porque os
+ * specs chamam esta função direto, e ali a versão não é o que está sob teste.
+ */
+cli) {
     const id = req.id;
     if (id === undefined)
         return null;
@@ -919,7 +943,11 @@ export async function handleRequest(root, req) {
             case "tools/call": {
                 const name = String(req.params?.name ?? "");
                 const args = (req.params?.arguments ?? {});
-                return { jsonrpc: "2.0", id, result: await callTool(root, name, args) };
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: await callTool(root, name, args, cli),
+                };
             }
             default:
                 return {
@@ -960,7 +988,7 @@ export async function mcp(opts) {
             catch {
                 continue; // Unparseable frame with no id: nobody to answer.
             }
-            const res = await handleRequest(root, req);
+            const res = await handleRequest(root, req, opts.cli);
             if (res)
                 send(res);
         }

package/dist/commands/sync.js

@@ -4,6 +4,7 @@ import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { body, section } from "../output.js";
+import { repoStateOf } from "../repo-state.js";
 /**
  * What each decision means ON THIS MACHINE - the card decides, the sync
  * enacts. The web never touches the local file; this line is printed right
@@ -87,6 +88,7 @@ export async function sync(opts) {
     // CHECKED, not because someone remembered to say so (dono, 29/07).
     const verified = await verifyAndCloseRequests(root);
     const events = await readEvents(root);
+    const repo = opts.cli ? await repoStateOf(root, slug, opts.cli) : null;
     const requests = await readRequests(root);
     if (events.length === 0 && requests.length === 0) {
         console.log(section("Sync"));
@@ -99,7 +101,17 @@ export async function sync(opts) {
             "content-type": "application/json",
             Authorization: `Bearer ${token}`,
         },
-        body: JSON.stringify({ slug, events, requests }),
+        /**
+         * O ESTADO DO REPO VAI JUNTO - ver `repoStateOf`. É o `sync` que ELE dispara, então nada
+         * passou a ser enviado sem que já fosse: a versão instalada viaja no mesmo pacote que o
+         * registro de checagens, e é o que permite a tela dizer "você está em v2 e existe v4".
+         */
+        body: JSON.stringify({
+            slug,
+            events,
+            requests,
+            ...(repo ? { repo } : {}),
+        }),
     }).catch(() => null);
     if (!res) {
         console.log(section("Sync"));

package/dist/index.js

@@ -235,7 +235,8 @@ async function main() {
         // Long-lived: it owns stdin/stdout until the client closes the pipe, so
         // it must not be reached by anything that prints.
         case "mcp":
-            await mcp({ dir });
+            // A versão que reporta o estado do repo no ping do agente - ver `repoStateOf`.
+            await mcp({ dir, cli: CLI_VERSION });
             return;
         case "doctor":
             // positional paths scope the READING (the system is still found from the
@@ -421,7 +422,8 @@ async function main() {
             await clean({ dir, force: flags.force === true });
             break;
         case "sync":
-            await sync({ dir, registry });
+            // A versão que reporta o estado do repo - ver `repoStateOf`.
+            await sync({ dir, registry, cli: CLI_VERSION });
             break;
         case "request": {
             // `synthesisui request` lists; `request component --name x --for "..."`

package/dist/repo-state.js

@@ -0,0 +1,64 @@
+/**
+ * O ESTADO DO REPO DELE, medido no repo dele.
+ *
+ * A plataforma sabe o que publicou e não sabia em que versão o repo do cliente está - então a tela
+ * não podia escrever "você está em v2 e existe v4", porque ela não tinha o primeiro número (dono,
+ * 05/08).
+ *
+ * O `.lock` de cada DS instalado (`_synthesisui/ds/<slug>/.lock`) tem esse número desde sempre. O
+ * que faltava era ele viajar.
+ *
+ * E ELE VIAJA NOS CANAIS QUE JÁ FALAM, nunca num novo:
+ *
+ *     `sync`          manual, e é assim que a landing promete. Leva o registro local
+ *                     inteiro quando ELE decide.
+ *     ping do MCP     automático, e já existe: toda leitura de receita pelo agente já
+ *                     manda slug/componente/ação. "Em que versão eu estou" é o mesmo
+ *                     tipo de sinal, no mesmo momento.
+ *
+ * Nada passou a ser enviado que já não fosse, e nenhum canal novo foi aberto. Transformar o `sync`
+ * em telemetria silenciosa mudaria o contrato de privacidade da landing, e isso não se faz de lado.
+ *
+ * NADA POR PESSOA. Nem nome de branch, nem autor, nem caminho de arquivo: só a versão instalada, a
+ * versão do CLI, e quando o doctor rodou. Um painel que ranqueia desenvolvedor transforma a
+ * checagem em adversário, e adversário é desinstalado.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readEvents } from "./doctor/ledger.js";
+/**
+ * O estado de um slug neste projeto, ou nada quando não há `.lock`.
+ *
+ * Silencioso de propósito: um projeto sem o DS instalado não é um erro a reportar, e um `.lock`
+ * ilegível não vale derrubar um `sync` que existe para levar o registro de checagens.
+ */
+export async function repoStateOf(projectRoot, slug, cli) {
+    const lock = await readJson(join(projectRoot, "_synthesisui", "ds", slug, ".lock"));
+    /**
+     * O ÚLTIMO DOCTOR, PELO MESMO LEITOR QUE O `sync` USA (`readEvents`). Abrir o arquivo por conta
+     * própria aqui seria uma segunda implementação do formato do registro - e a primeira coisa que
+     * ela faria é discordar da outra sobre o que é uma linha válida.
+     */
+    const doctor = (await readEvents(projectRoot))
+        .filter((e) => e.kind === "doctor" && e.at)
+        .sort((a, b) => String(b.at).localeCompare(String(a.at)))[0];
+    const payload = {
+        ...(typeof lock?.version === "number" ? { installed: lock.version } : {}),
+        ...(lock?.adopted === true ? { adopted: true } : {}),
+        cli,
+        ...(doctor?.at ? { doctorAt: doctor.at } : {}),
+        ...(typeof doctor?.phantoms === "number"
+            ? { drifts: doctor.phantoms }
+            : {}),
+    };
+    /** Só o `cli` não é estado: sem nada do repo, não há o que reportar. */
+    return Object.keys(payload).length > 1 ? payload : null;
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/skill-import.js

@@ -74,6 +74,31 @@ and narrating it - *"registry is production, so no --registry flag needed"* - sp
 person's attention on a decision that was never theirs (dono, 01/08). Say something only when
 there is nothing to say to: no token, or the wrong host.
 
+### 0b. ASK THE REGISTRY WHAT EXISTS - never your notes
+
+If your memory says this repo already produced a system, **verify it before you say it out loud**,
+and verify it per SLUG:
+
+\`\`\`
+curl -s -o /dev/null -w "%{http_code}" <registry>/api/registry/ds/<slug>
+\`\`\`
+
+\`404\` means it does not exist. \`200\` means it does. That is the whole check, and it costs one call.
+
+**\`synthesisui list\` does NOT answer this.** It returns the public gallery - 13 systems, none of
+them private - so a private system of theirs is invisible to it and a \`list\` that does not mention
+\`their-slug\` proves nothing.
+
+This exists because of a real run (dono, 05/08). The owner had deleted every system on his account,
+and the skill opened with *"my notes from the previous twelve runs say this repo has already
+produced two published systems"* - then offered three options built on that: upgrade a slug the
+registry answers \`404\` for, avoid a name collision that no longer existed, and warn that a \`--dry\`
+would wipe files it does not touch. One \`curl\` would have replaced all of it.
+
+**A memory may report the past; it may never assert the present.** *"The last run produced
+\`signalui\`"* is a fine sentence. *"This repo has two published systems"* is a claim about the server,
+and the server is the only thing that can make it.
+
 ## How to narrate
 
 The person cares about **what you found in their code** and **what you are about to create**.
@@ -880,6 +905,13 @@ Copying \`dark\` in at the top level of a recipe costs you that block, silently,
 component that has one - and \`import\` already converts it for the recipes IT writes, so the
 only place this can be lost is a recipe you hand-built (not-expressed.md, dono, 03/08).
 
+**Which means: do NOT pre-convert the dark half inside \`looks[X]\`.** The conversion already
+happens on the way in, so adding a \`scheme: "dark"\` layer to the census's own look while leaving
+the \`dark\` key in place produces the SAME layer twice - measured at 28 components in one real
+import, with the properties in a different key order so it did not even look like a duplicate
+(dono, 05/08). \`validate_recipe\` telling you a top-level \`dark\` would be dropped is true about a
+RECIPE and says nothing about the reading: you send a reading, and the reading's \`dark\` is read.
+
 **In ONE call.** Build every recipe in memory, then send the whole reading to
 \`validate_recipes\` - one round trip for 35 components instead of 35. \`validate_recipe\`
 (singular) is for the one recipe you rewrote after the batch named it; reaching for it in a
@@ -1162,10 +1194,20 @@ and pass on the ones that matter.
 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 add <slug> [--registry …]       # INSTALLS it: writes _synthesisui/ds/<slug>/
 npx synthesisui doctor [paths…]                 # the contract starts being enforced
+npx synthesisui upgrade <slug> [--registry …]   # LATER, when a new version is published
 \`\`\`
 
+**The order is not a preference: \`upgrade\` reads the \`.lock\` of an installed DS and refuses
+without one** - \`"<slug>" is not installed here - run \\\`synthesisui add <slug>\\\` first.\` So
+offering \`upgrade\` to somebody who has never installed hands them a command that fails on contact
+(dono, 05/08). Check for \`_synthesisui/ds/<slug>/.lock\` before you recommend either one.
+
+And say what each writes, because one of them rewrites code: \`add\` and \`upgrade\` write inside
+\`_synthesisui/\`, and \`upgrade\` ALSO regenerates components - but only files carrying the
+\`Generated by SynthesisUI\` header, so their own components are never touched.
+
 \`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.
@@ -1186,8 +1228,16 @@ The user should end up with a system that reads like theirs and not like ours:
 
 ## What to resist
 
+- **Do not let memory speak for the server.** Notes report the past; a claim about what exists
+  now needs the one \`curl\` in step 0b. Four statements in one real run were wrong this way, and
+  every option offered on top of them was wrong too (dono, 05/08).
 - **Do not run \`import\` without \`--dry\` to explore.** It creates a real system on their
   account. Measure with \`--dry\`, read, then send once.
+- **\`--dry\` does not delete anything.** It writes \`census.json\` and creates the folder if needed -
+  there is no \`rm\` in the import path. What it DOES do is overwrite that one file, so a reading
+  injected into it is lost; everything else under \`_synthesisui/\` (the config, \`ds/<slug>/\`, the
+  hook's marker, \`not-expressed.md\`) survives untouched. Telling somebody a measure will wipe their
+  install talks them out of a safe command (dono, 05/08).
 - **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

package/package.json

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