synthesisui 0.16.481 → 0.16.483

package/dist/colour-names.js

@@ -204,3 +204,55 @@ export function agentPrompt(plan) {
         "Change a value only where it is used as the line says. Leave every other colour as it is, and do not add or invent a name or a colour - these six were chosen by the person.",
     ].join("\n");
 }
+/**
+ * O UPGRADE TRAZ AS SEIS CORES NOVAS - etapa 01 da jornada "cada um sabe se o seu código está em dia", 29/09.
+ *
+ * Só o `colours` escrevia o bloco, então quem recebia a versão nova de um colega pelo `upgrade` ficava com os valores
+ * velhos no CSS global (medido no teste-e09: `--color-primary: #0070f3` com o sistema em `#2e5078`). Aqui o bloco que
+ * é NOSSO - entre as marcas - tem os valores trocados pelos da versão nova; nada fora dele é tocado.
+ *
+ * O papel de cada linha: pela grafia (`--<prefixo>-<palavra>`) e, quando o nome é o DELE (`--accent`), pela cor de
+ * antes - é a cor que a versão instalada dava àquele papel.
+ */
+export function refreshColourBlock(css, slug, before, after) {
+    const hit = blockMarks.END_RE(slug).exec(css);
+    if (!hit)
+        return { css, changes: [] };
+    const low = (x) => (x ?? "").trim().toLowerCase();
+    const changes = [];
+    const taken = new Set();
+    const block = hit[0].replace(/^(\s*)(--[a-z0-9-]+)(\s*:\s*)([^;]+);/gim, (line, pad, name, colon, value) => {
+        const byWord = SIX_ROLES.find((r) => !taken.has(r) &&
+            new RegExp(`^--[a-z0-9]+-${WORD[r].word}$`, "i").test(name));
+        const role = byWord ??
+            SIX_ROLES.find((r) => !taken.has(r) && before[r] && low(before[r]) === low(value));
+        if (!role)
+            return line;
+        taken.add(role);
+        const to = after[role];
+        if (!to || low(to) === low(value))
+            return line;
+        changes.push({ role, name, from: value.trim(), to });
+        return `${pad}${name}${colon}${to};`;
+    });
+    if (changes.length === 0)
+        return { css, changes };
+    return {
+        css: css.slice(0, hit.index) + block + css.slice(hit.index + hit[0].length),
+        changes,
+    };
+}
+/** O mesmo, no disco: acha o CSS global dele e reescreve só se algum valor mudou. */
+export async function refreshColourBlockOnDisk(root, slug, before, after) {
+    const v = await readVocabulary(root, slug);
+    if (!v.global)
+        return { file: null, changes: [] };
+    const path = join(root, v.global);
+    const css = await readFile(path, "utf8").catch(() => null);
+    if (css == null)
+        return { file: null, changes: [] };
+    const r = refreshColourBlock(css, slug, before, after);
+    if (r.changes.length > 0)
+        await writeFile(path, r.css, "utf8");
+    return { file: v.global, changes: r.changes };
+}

package/dist/commands/add.js

@@ -1,6 +1,5 @@
-import { neverMeasured } from "../never-measured.js";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
@@ -9,18 +8,19 @@ import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.
 import { detectAppDirs } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
+import { nextInstalledAt, readInstalledAt, writeInstalledAt, } from "../installed-at.js";
 import { censusScope } from "../measured-scope.js";
 import { recallAvailable } from "../memory/availability.js";
+import { neverMeasured } from "../never-measured.js";
 import { nextFontFacts } from "../next-font-weights.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
-import { detectStack } from "../stack.js";
+import { detectStack, resolveDeps } from "../stack.js";
 import { onlyWhatMatched } from "../their-theme.js";
 import { tongueOf } from "../their-tongue.js";
 import { pointTokensAtTheirNames } from "../their-vars.js";
-import { resolveDeps } from "../stack.js";
 import { tracksAnyOf } from "../tracked.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
@@ -75,6 +75,11 @@ const IGNORED = [
      * turno de quem instalasse faria um arquivo nosso aparecer no `git status` dele.
      */
     ".turn-clock",
+    /**
+     * A HORA EM QUE A VERSÃO ATERROU NESTE CLONE - ver `installed-at.ts` (29/09). Dentro do `.lock` ela fazia dois upgrades
+     * da mesma versão, em branches separadas, darem conflito numa linha só.
+     */
+    ".fetched-at.json",
 ];
 const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
     "# clone is governed; the measurement and the local record are not, because\n" +
@@ -196,7 +201,10 @@ async function familiesHeNames(root, families) {
     const kept = Object.entries(families).filter(([, v]) => {
         if (typeof v !== "string")
             return true;
-        const first = v.split(",")[0]?.trim().replace(/^["']|["']$/g, "") ?? "";
+        const first = v
+            .split(",")[0]
+            ?.trim()
+            .replace(/^["']|["']$/g, "") ?? "";
         return !first || /^var\(/.test(first) || css.includes(first.toLowerCase());
     });
     return Object.fromEntries(kept);
@@ -392,7 +400,9 @@ export async function add(slug, opts) {
          * E O SISTEMA QUE NUNCA FOI MEDIDO NUM CÓDIGO já nasce assim - ver `neverMeasured` (rodada 5, 27/09):
          * o fork do leigo-5 terminava o `connect` mandando rodar `sync` para uma pasta que não existe.
          */
-        ...(prev?.reading === "none" || neverMeasured(payload.document) ? { reading: "none" } : {}),
+        ...(prev?.reading === "none" || neverMeasured(payload.document)
+            ? { reading: "none" }
+            : {}),
         /** Ver `RegistryPayload.compiler`: é o que faz um conserto de CSS chegar a um install. */
         ...(payload.compiler != null ? { compiler: payload.compiler } : {}),
         ...(payload.rulesStamp ? { rules: payload.rulesStamp } : {}),
@@ -428,17 +438,21 @@ export async function add(slug, opts) {
         /** A memória do que NÓS escrevemos atravessa a re-materialização - ver `RootLock.written`. */
         ...(prev?.written ? { written: prev.written } : {}),
     };
-    const landed = (() => {
-        if (!prev?.fetchedAt)
-            return true;
-        const { fetchedAt: _was, ...before } = prev;
-        return JSON.stringify(before) !== JSON.stringify(identity);
-    })();
-    const lock = {
-        ...identity,
-        fetchedAt: landed || !prev?.fetchedAt ? new Date().toISOString() : prev.fetchedAt,
-    };
+    /**
+     * O `.lock` SEM A HORA - ver `installed-at.ts` (29/09): dois clones na mesma versão escrevem o mesmo arquivo, e a hora
+     * de cada um vai para `.fetched-at.json`, que o git ignora.
+     */
+    const slugDirOfLock = dirname(rootLockPath);
+    const installedAt = nextInstalledAt({
+        prevLock: prev ??
+            null,
+        prevAt: await readInstalledAt(slugDirOfLock, null),
+        identity: identity,
+        now: new Date().toISOString(),
+    });
+    const lock = { ...identity };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    await writeInstalledAt(slugDirOfLock, installedAt);
     /**
      * O MAPA SOBE AGORA, e é o único momento em que ele é novo.
      *
@@ -637,7 +651,9 @@ export async function add(slug, opts) {
      * `@theme` - vinte linhas depois de "100% of your 59 style decisions carry your own vocabulary".
      */
     const wearsTailwind = await projectWearsTailwind(projectRoot);
-    if (wearsTailwind && !opts.themeFollows && (aligned.dropped.length > 0 || aligned.own.length > 0)) {
+    if (wearsTailwind &&
+        !opts.themeFollows &&
+        (aligned.dropped.length > 0 || aligned.own.length > 0)) {
         console.log(line(
         /**
          * A LINHA DIZ QUE FICARAM DE FORA - e nao AFIRMA por que, porque ela nao sabe.
@@ -779,7 +795,11 @@ export async function add(slug, opts) {
      */
     const stackDeps = await resolveDeps(projectRoot).catch(() => ({}));
     const onNext = projectConfig.target === "next" && "next" in stackDeps;
-    const headHome = onNext ? "app/layout.tsx" : "vite" in stackDeps ? "index.html" : "your root HTML";
+    const headHome = onNext
+        ? "app/layout.tsx"
+        : "vite" in stackDeps
+            ? "index.html"
+            : "your root HTML";
     const fontPlan = onNext
         ? nextFontSnippet({
             families,

package/dist/commands/align.js

@@ -9,6 +9,7 @@ import { unsentEvents } from "../doctor/ledger.js";
 import { readRequests } from "../doctor/requests.js";
 import { declaredReference } from "../group-role.js";
 import { CHECKER_SINCE, installedBehind, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
+import { readInstalledAt } from "../installed-at.js";
 import { fmt, say } from "../lang.js";
 import { measuredScope } from "../measured-scope.js";
 import { body, bodyWrapped, paint, section, snippet } from "../output.js";
@@ -34,7 +35,8 @@ async function wholeRepoMeasured(root) {
         return false;
     try {
         const c = JSON.parse(raw);
-        const narrowed = (typeof c.scope === "string" && c.scope.trim() !== "") || (Array.isArray(c.scopes) && c.scopes.length > 0);
+        const narrowed = (typeof c.scope === "string" && c.scope.trim() !== "") ||
+            (Array.isArray(c.scopes) && c.scopes.length > 0);
         return c.measured != null && typeof c.measured === "object" && !narrowed;
     }
     catch {
@@ -66,7 +68,10 @@ async function locksIn(root) {
         if (!raw)
             continue;
         try {
-            out.push(JSON.parse(raw));
+            const lock = JSON.parse(raw);
+            /** A hora mora ao lado desde 29/09 - ver `installed-at.ts`; o `.lock` antigo ainda responde. */
+            const at = await readInstalledAt(join(dsDir, entry.name), lock);
+            out.push(at ? { ...lock, fetchedAt: at } : lock);
         }
         catch {
             // lock ilegível - o `status` já reporta isso com o nome do arquivo
@@ -228,7 +233,10 @@ opts = {}) {
      * sistema de 36).
      */
     const scope = await measuredScope(root, lock.slug);
-    if (!scope.system && scope.usage.length === 0 && lock.reading !== "none" && !(await wholeRepoMeasured(root)))
+    if (!scope.system &&
+        scope.usage.length === 0 &&
+        lock.reading !== "none" &&
+        !(await wholeRepoMeasured(root)))
         out.push({
             says: `"${lock.slug}" does not record where it was measured, so a re-measure would read this whole repo instead of the folder the system came from. Sync asks once and remembers the answer.`,
             /**
@@ -521,6 +529,7 @@ export async function versionBehind(root, opts = {}) {
         return repaired;
     if (body.version > lock.version)
         return {
+            kind: "version",
             says: `v${body.version} of "${lock.slug}" is published and this repo is on v${lock.version}. The CSS here and the rules your agent reads are both v${lock.version} - they move together, which is why this is worth saying rather than applying.`,
             run: `npx synthesisui upgrade ${lock.slug}`,
         };
@@ -707,7 +716,7 @@ opts = {}) {
         ...(opts.cli ? { cli: opts.cli } : {}),
         ...(opts.home ? { home: opts.home } : {}),
     }).catch(() => null);
-    if (remote)
+    if (remote && !(opts.skipVersion && remote.kind === "version"))
         items.push(remote);
     return items;
 }

package/dist/commands/colours.js

@@ -27,7 +27,11 @@ export async function colours(asked, opts) {
         ? await readFile(join(slugDir, `v${lock.version}`, "tokens.css"), "utf8").catch(() => "")
         : "";
     const roleHex = roleColours(tokens);
-    const plan = await planColourNames(root, slug, roleHex, before);
+    /** O que ele marcou na tela em "no seu código hoje" vale acima do palpite pela versão de antes (28/09). */
+    const docJson = typeof lock.version === "number"
+        ? await readFile(join(slugDir, `v${lock.version}`, "design-system.json"), "utf8").catch(() => "{}")
+        : "{}";
+    const plan = await planColourNames(root, slug, roleHex, markedBefore(before, docJson));
     console.log("");
     console.log(section("Your six colours, back in your code"));
     if (!plan.file) {
@@ -78,8 +82,23 @@ export function roleColours(tokensCss) {
     }
     return out;
 }
+/**
+ * A COR DE HOJE DE CADA PAPEL, com o que ELE marcou por cima - `foundations.color.replaces`, escrito pela tela de
+ * escolher cores (controle completo, 28/09). `""` é resposta dele: o papel é novo e não troca cor nenhuma.
+ */
+export function markedBefore(before, documentJson) {
+    let marked = {};
+    try {
+        marked =
+            JSON.parse(documentJson).foundations?.color?.replaces ?? {};
+    }
+    catch {
+        marked = {};
+    }
+    return { ...before, ...marked };
+}
 /** As seis cores da versão que está instalada agora - `{}` quando ainda não há nenhuma. */
-async function installedRoles(slugDir) {
+export async function installedRoles(slugDir) {
     const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
     if (typeof lock.version !== "number")
         return {};

package/dist/commands/sync.js

@@ -13,11 +13,16 @@ import { measuredScope, rememberScope } from "../measured-scope.js";
 import { fromCensus } from "../memory/observation.js";
 import { reportMeasurement } from "../memory/report.js";
 import { mergeCensus } from "../merge-census.js";
-import { describeGrowth, recordGrowthForTurn, whatGrew } from "../what-grew.js";
+import { readVocabulary } from "../new-project-theme.js";
+import { gitFacts, offerNewVersion } from "../new-version.js";
 import { body, paint, section, snippet } from "../output.js";
+import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
+import { describeGrowth, recordGrowthForTurn, whatGrew } from "../what-grew.js";
 import { reportWhatIsLeft } from "./align.js";
+import { installedRoles, roleColours } from "./colours.js";
 import { resolveReadParts, siblingProjects, takeCensus, } from "./import.js";
+import { upgrade } from "./upgrade.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
@@ -321,9 +326,50 @@ export async function sync(opts) {
      * dizendo o que sobrou resolve o que a dúvida realmente era: acabou ou não? Mudo quando não sobrou
      * nada, que é o caso normal.
      */
-    await reportWhatIsLeft(root);
+    /**
+     * UMA VERSÃO NOVA, DITA POR EXTENSO - etapa 02 de "cada um sabe se o seu código está em dia" (29/09): o que mudou,
+     * e o caminho sem conflito. Quando ela foi dita aqui, a lista do fim não a repete.
+     */
+    const offered = await offerNewVersionHere(root, slug, base).catch(() => "current");
+    await reportWhatIsLeft(root, offered === "current" ? {} : { skipVersion: true });
     sayRefused(refused);
 }
+async function offerNewVersionHere(root, slug, base) {
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+    if (typeof lock.version !== "number")
+        return "current";
+    const { global } = await readVocabulary(root, slug);
+    return offerNewVersion(root, { slug, version: lock.version }, { globalCss: global }, {
+        latest: async () => {
+            const p = await fetchDesignSystem(base, slug);
+            return {
+                version: p.version,
+                roles: roleColours(p.artifacts["tokens.css"] ?? ""),
+            };
+        },
+        installedRoles: () => installedRoles(slugDir),
+        git: () => gitFacts(root, slug, global),
+        ask: askYesNo,
+        upgrade: (s) => upgrade(s, { registry: base, dir: root }),
+        tty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    });
+}
+async function askYesNo(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await rl.question(question)).trim());
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * O QUE NÃO FOI ENVIADO, DITO POR ÚLTIMO - e o "por último" é o desenho, não um detalhe.
  *

package/dist/commands/upgrade.js

@@ -1,14 +1,15 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
-import { speakInHisProject } from "../in-his-form.js";
 import { join } from "node:path";
 import { pinnedHookVersion, wireAgent } from "../agent-wiring.js";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { isOlderCli } from "../cli-version.js";
+import { refreshColourBlockOnDisk } from "../colour-names.js";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { detectAppDirs } from "../global-sheet.js";
+import { speakInHisProject } from "../in-his-form.js";
 import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, themeVocabOf, } from "../project-facts.js";
@@ -19,6 +20,7 @@ import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-co
 import { editedSinceWritten, keptLine, readWritten, recordWritten, } from "../written.js";
 import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
+import { installedRoles } from "./colours.js";
 import { doctor } from "./doctor.js";
 /**
  * The highest `v<n>` below `installed` among the folder names given, or the one
@@ -384,6 +386,8 @@ export async function upgrade(asked, opts) {
         console.log(`✓ ${slug} v${installed} is newer than the registry's v${latest.version} - nothing to do.`);
         return;
     }
+    /** As seis cores de ANTES - o bloco do CSS global dele guarda estas (etapa 01, 29/09). */
+    const coloursBefore = await installedRoles(slugDir);
     // 1. re-materialize the artifacts (v<latest>/ + root re-exports + .lock);
     //    setup hints suppressed - an upgrade means the app is already wired.
     await add(slug, {
@@ -392,6 +396,11 @@ export async function upgrade(asked, opts) {
         setupHints: false,
         ...(opts.cli ? { cli: opts.cli } : {}),
     });
+    /**
+     * AS SEIS CORES NOVAS NO CSS GLOBAL DELE - etapa 01 de "cada um sabe se o seu código está em dia", 29/09. Quem
+     * recebia a versão de um colega ficava com os valores velhos no bloco que o `colours` escreveu.
+     */
+    const colourBlock = await refreshColourBlockOnDisk(root, slug, coloursBefore, await installedRoles(slugDir));
     // 2. regenerate YOUR materialized components (the ones `component` wrote)
     const config = await readProjectConfig(root);
     const regenerated = [];
@@ -541,6 +550,12 @@ export async function upgrade(asked, opts) {
     else {
         console.log(body("No breaking changes detected."));
     }
+    if (colourBlock.changes.length > 0) {
+        console.log("");
+        console.log(body(`✓ ${colourBlock.file}: ${colourBlock.changes.length === 1 ? "1 of your six colours" : `${colourBlock.changes.length} of your six colours`} now ${colourBlock.changes.length === 1 ? "has" : "have"} the new value:`));
+        for (const c of colourBlock.changes)
+            console.log(body(`    ${c.name}: ${c.from} → ${c.to}   (${c.role})`));
+    }
     if (regenerated.length > 0) {
         console.log("");
         console.log(body(`Regenerated ${regenerated.length} materialized component(s): ${regenerated.join(", ")}`));
@@ -579,5 +594,5 @@ export async function upgrade(asked, opts) {
  * `button-gen`: "Could not regenerate (...) (removed/renamed in v2?)". Sem cabeçalho, a pasta é a melhor pista.
  */
 export function recipeNameOf(head, entry) {
-    return /Generated by SynthesisUI - "([^"]+)" from the/.exec(head)?.[1] ?? entry;
+    return (/Generated by SynthesisUI - "([^"]+)" from the/.exec(head)?.[1] ?? entry);
 }

package/dist/install-marks.js

@@ -310,7 +310,11 @@
  * `[color:#ffffff]`, `font-body` em vez de `[font-family:Inter,_sans-serif]`), e a largura em px no degrau vira `w-10`.
  * Um componente escrito antes reprova na própria checagem.
  */
-export const MATERIALISER_SINCE = "0.16.476";
+/**
+ * 0.16.483 (29/09): o `.lock` sai sem a hora (`fetchedAt` vai para `.fetched-at.json`, ignorado pelo git) - dois
+ * upgrades da mesma versão, em branches separadas, davam conflito numa linha só dele. Ver `installed-at.ts`.
+ */
+export const MATERIALISER_SINCE = "0.16.483";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/installed-at.js

@@ -0,0 +1,41 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * A HORA EM QUE A VERSÃO ATERROU NESTE CLONE, FORA DO `.lock` - pedido dele em 29/09 ("tira, neste PR").
+ *
+ * MEDIDO: dois clones trouxeram a mesma versão em branches separadas e o merge parou numa linha só do `.lock` -
+ * `"fetchedAt"`, a hora de cada download. O `globals.css`, os tokens e a pasta da versão juntaram limpo. O `.lock` é
+ * commitado e o resto dele é função da versão, do compilador e das regras; a hora era a única coisa que descrevia UMA
+ * máquina, e é ela que fazia dois upgrades iguais brigarem.
+ *
+ * Então ela mora num arquivo ao lado, na lista do `.gitignore` que o CLI gerencia - como o `.last-sync.json`. Quem lê
+ * (`repairSaid` no align, `installedAt` no repo-state) lê daqui, e do `.lock` antigo quando este arquivo ainda não
+ * existe - um repo instalado antes continua respondendo.
+ */
+export const INSTALLED_AT_FILE = ".fetched-at.json";
+/** A hora nova: anda quando algo aterrou, e fica onde estava quando nada mudou - a mesma regra do `.lock` de antes. */
+export function nextInstalledAt(v) {
+    const was = v.prevAt ?? v.prevLock?.fetchedAt ?? null;
+    if (!v.prevLock || !was)
+        return v.now;
+    const { fetchedAt: _was, ...before } = v.prevLock;
+    const landed = JSON.stringify(before) !== JSON.stringify(v.identity);
+    return landed ? v.now : was;
+}
+export async function readInstalledAt(slugDir, lock) {
+    const raw = await readFile(join(slugDir, INSTALLED_AT_FILE), "utf8").catch(() => null);
+    if (raw) {
+        try {
+            const at = JSON.parse(raw).fetchedAt;
+            if (typeof at === "string")
+                return at;
+        }
+        catch {
+            // ilegível: cai no `.lock` antigo
+        }
+    }
+    return typeof lock?.fetchedAt === "string" ? lock.fetchedAt : null;
+}
+export async function writeInstalledAt(slugDir, at) {
+    await writeFile(join(slugDir, INSTALLED_AT_FILE), `${JSON.stringify({ fetchedAt: at }, null, 2)}\n`, "utf8");
+}

package/dist/new-version.js

@@ -0,0 +1,201 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { body, section, snippet } from "./output.js";
+export function pathFor(f) {
+    if (f.remoteVersion != null && f.remoteVersion >= f.latest)
+        return "pull";
+    if (f.dirty.length > 0)
+        return "commit-first";
+    return f.tty ? "ask" : "say";
+}
+/** As seis cores que mudaram entre a versão instalada e a publicada, na ordem dos papéis. */
+export function colourChanges(before, after) {
+    const low = (x) => (x ?? "").trim().toLowerCase();
+    return Object.keys(after)
+        .filter((r) => before[r] && after[r] && low(before[r]) !== low(after[r]))
+        .map((role) => ({
+        role,
+        from: before[role],
+        to: after[role],
+    }));
+}
+/**
+ * O QUADRADO DA COR (29/09, pedido dele olhando o terminal: *"deveria ter um quadrado com as cores ao lado do hex"*). Um
+ * bloco com o fundo na cor exata (24 bits); sem terminal, nada - o agente lê texto, e um código de escape é ruído.
+ */
+export function colourSwatch(hex, tty) {
+    const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+    if (!tty || !m)
+        return "";
+    const [r, g, b] = [m[1], m[2], m[3]].map((x) => Number.parseInt(x, 16));
+    return `\u001b[48;2;${r};${g};${b}m  \u001b[0m`;
+}
+/** O aviso, antes de qualquer escrita: as duas versões e o que mudou nas seis cores. */
+export function newVersionLines(v) {
+    const sw = (hex) => {
+        const s = v.swatch?.(hex) ?? "";
+        return s ? `${s} ` : "";
+    };
+    const out = [
+        `v${v.latest} of "${v.slug}" is published and this repo is on v${v.installed}.`,
+    ];
+    if (v.changes.length > 0) {
+        out.push("What changed in your six colours:");
+        for (const c of v.changes)
+            out.push(`    ${c.role.padEnd(11)}${sw(c.from)}${c.from} → ${sw(c.to)}${c.to}`);
+    }
+    else {
+        out.push("None of your six colours changed - the rest (rules, components) is listed in UPGRADE.md once it is here.");
+    }
+    return out;
+}
+function run(cmd, args, cwd, timeout = 8000) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { cwd, timeout, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => resolve(err ? null : stdout.toString()));
+    });
+}
+/**
+ * O `.lock` só difere do commit pelo `reading` que o próprio sync anota (o 404 da leitura, em `markNoReading`)?
+ * Então a mudança é nossa, e o upgrade a reescreve igual - não é trabalho dele a proteger. Achado no PASS de 29/09.
+ */
+async function onlyOurReading(root, lockPath) {
+    const committed = await run("git", ["show", `HEAD:./${lockPath}`], root);
+    const now = await readFile(join(root, lockPath), "utf8").catch(() => null);
+    if (committed == null || now == null)
+        return false;
+    try {
+        const { reading: _a, ...was } = JSON.parse(committed);
+        const { reading: _b, ...is } = JSON.parse(now);
+        return JSON.stringify(was) === JSON.stringify(is);
+    }
+    catch {
+        return false;
+    }
+}
+export async function gitFacts(root, slug, globalCss) {
+    const none = {
+        repo: false,
+        origin: false,
+        dirty: [],
+        remoteVersion: null,
+        remoteRef: null,
+        gh: false,
+    };
+    const inside = await run("git", ["rev-parse", "--is-inside-work-tree"], root);
+    if (inside?.trim() !== "true")
+        return none;
+    const paths = [`_synthesisui/ds/${slug}`, ...(globalCss ? [globalCss] : [])];
+    const status = (await run("git", ["status", "--porcelain", "--", ...paths], root)) ?? "";
+    const lockPath = `_synthesisui/ds/${slug}/.lock`;
+    const dirty = [];
+    for (const f of status
+        .split("\n")
+        .map((l) => l.slice(3).trim())
+        .filter(Boolean)) {
+        if (f === lockPath && (await onlyOurReading(root, lockPath)))
+            continue;
+        dirty.push(f);
+    }
+    let remoteVersion = null;
+    let remoteRef = null;
+    const origin = await run("git", ["remote", "get-url", "origin"], root);
+    if (origin) {
+        /** O fetch só lê; sem rede ele falha calado e o resto segue sem a informação. */
+        await run("git", ["fetch", "--quiet", "origin"], root, 10000);
+        const head = (await run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], root))?.trim();
+        const candidates = [head, "origin/main", "origin/master"].filter(Boolean);
+        const prefix = ((await run("git", ["rev-parse", "--show-prefix"], root)) ?? "").trim();
+        for (const ref of candidates) {
+            const lock = await run("git", ["show", `${ref}:${prefix}_synthesisui/ds/${slug}/.lock`], root);
+            if (lock == null)
+                continue;
+            remoteRef = ref;
+            try {
+                const v = JSON.parse(lock).version;
+                remoteVersion = typeof v === "number" ? v : null;
+            }
+            catch {
+                remoteVersion = null;
+            }
+            break;
+        }
+    }
+    const gh = (await run("gh", ["auth", "status"], root, 5000)) != null;
+    return {
+        repo: true,
+        origin: origin != null,
+        dirty,
+        remoteVersion,
+        remoteRef,
+        gh,
+    };
+}
+/**
+ * O aviso inteiro, com o caminho escolhido. Devolve o que aconteceu - o `sync` usa para não repetir, na lista do que
+ * falta, a linha de versão que acabou de ser dita aqui.
+ */
+export async function offerNewVersion(_root, lock, where, deps, print = (l) => console.log(l)) {
+    const latest = await deps.latest().catch(() => null);
+    if (!latest || latest.version <= lock.version)
+        return "current";
+    const changes = colourChanges(await deps.installedRoles(), latest.roles);
+    const facts = await deps.git();
+    const path = pathFor({
+        tty: deps.tty,
+        dirty: facts.dirty,
+        remoteVersion: facts.remoteVersion,
+        latest: latest.version,
+    });
+    const slug = lock.slug;
+    print("");
+    print(section(`A new version of ${slug}`));
+    for (const l of newVersionLines({
+        slug,
+        installed: lock.version,
+        latest: latest.version,
+        changes,
+        swatch: (hex) => colourSwatch(hex, deps.tty),
+    }))
+        print(body(l));
+    print("");
+    if (path === "pull") {
+        const branch = (facts.remoteRef ?? "origin/main").replace(/^origin\//, "");
+        print(body(`Someone on your team already brought v${latest.version} into ${facts.remoteRef}. Bring it from git instead of upgrading here - doing the same change twice, in two commits, is what makes a conflict:`));
+        print(snippet([`git pull origin ${branch}`]));
+        return path;
+    }
+    if (path === "commit-first") {
+        print(body("You have changes not committed where the upgrade writes. Commit or stash them first, so the upgrade lands in a diff of its own:"));
+        for (const f of facts.dirty)
+            print(body(`    ${f}`));
+        print("");
+        print(body("then:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return path;
+    }
+    if (path === "say") {
+        print(body("To bring it here:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return path;
+    }
+    const yes = await deps.ask(`  Bring v${latest.version} into this repo now? It rewrites _synthesisui/ds/${slug}${where.globalCss ? ` and the six colours in ${where.globalCss}` : ""}. [y/N] `);
+    if (!yes) {
+        print(body("Nothing was changed. When you want it:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return "declined";
+    }
+    await deps.upgrade(slug);
+    print("");
+    print(section("Give it to your team"));
+    print(body("It is in your files now, not in git. Commit it on a branch of its own, so whoever pulls gets it without redoing it:"));
+    print(snippet([
+        `git switch -c synthesisui-${slug}-v${latest.version}`,
+        "git status    # only what the upgrade wrote should be listed",
+        "git add -A",
+        `git commit -m "synthesisui: ${slug} v${latest.version}"`,
+        ...(facts.origin ? ["git push -u origin HEAD"] : []),
+        ...(facts.origin && facts.gh ? ["gh pr create --fill"] : []),
+    ]));
+    return "upgraded";
+}

package/dist/repo-state.js

@@ -26,6 +26,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { readEvents, } from "./doctor/ledger.js";
+import { readInstalledAt } from "./installed-at.js";
 /**
  * O estado de um slug neste projeto, ou nada quando não há `.lock`.
  *
@@ -34,6 +35,8 @@ import { readEvents, } from "./doctor/ledger.js";
  */
 export async function repoStateOf(projectRoot, slug, cli) {
     const lock = await readJson(join(projectRoot, "_synthesisui", "ds", slug, ".lock"));
+    /** A hora mora ao lado do `.lock` desde 29/09 - ver `installed-at.ts`. */
+    const installedAt = await readInstalledAt(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
@@ -93,9 +96,7 @@ export async function repoStateOf(projectRoot, slug, cli) {
             ? { unrepresentedMatches: doctor.unrepresentedMatches }
             : {}),
         ...(runs.length > 0 ? { runs } : {}),
-        ...(typeof lock?.fetchedAt === "string"
-            ? { installedAt: lock.fetchedAt }
-            : {}),
+        ...(installedAt ? { installedAt } : {}),
     };
     /** Só o `cli` não é estado: sem nada do repo, não há o que reportar. */
     return Object.keys(payload).length > 1 ? payload : null;

package/package.json

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