synthesisui 0.16.426 → 0.16.427

package/dist/commands/import.js

@@ -490,7 +490,13 @@ export async function takeCensus(root, opts) {
      * `textarea` (dono, 01/08). Fetched rather than shipped, and the fallback is announced
      * with what it costs - a smaller answer is fine, a silently smaller one is not.
      */
-    const fetched = await fetchCatalogue(opts?.registry);
+    const fetched = opts?.offline
+        ? {
+            ok: false,
+            why: "offline",
+            because: "this run makes no network calls by contract",
+        }
+        : await fetchCatalogue(opts?.registry);
     useLiveCatalogue(fetched.ok ? asCatalogueTable(fetched.index) : null);
     /** Todo arquivo de estilo do escopo, para o ledger - ver o parâmetro `into`. */
     const styleFiles = [];
@@ -4315,7 +4321,16 @@ export async function runImport(opts) {
          * every file opened, every candidate ruled out - is the machine talking to
          * itself (dono, 01/08).
          */
-        phase(1, 3, "Measuring the repository");
+        /**
+         * "1/3" É UMA PROMESSA DE TRÊS PASSOS, e o `inspect` tem UM.
+         *
+         * O contador existe para quem está importando: ele diz em qual das três fases a pessoa está
+         * e que ainda faltam duas. Quem rodou `inspect` não vai mandar nada e não vai resolver
+         * leitura nenhuma - abrir o primeiro contato do produto anunciando dois passos que não vêm é
+         * prometer trabalho que ninguém pediu.
+         */
+        if (!opts.inspect)
+            phase(1, 3, "Measuring the repository");
         console.log(section("Reading your project"));
         /**
          * UMA MEDIÇÃO POR ESCOPO, E DEPOIS A FUSÃO.
@@ -4338,6 +4353,8 @@ export async function runImport(opts) {
                 ...(i === 0 && usage.length > 0 ? { usage } : {}),
                 ...(one ? { scopeLabel: one } : {}),
                 ...(opts.cli ? { cli: opts.cli } : {}),
+                /** `inspect` não fala com ninguém - ver `offline` em `takeCensus`. */
+                ...(opts.inspect ? { offline: true } : {}),
             });
             if (one)
                 c.scope = one;
@@ -4359,6 +4376,23 @@ export async function runImport(opts) {
      */
     if (!opts.census)
         await resolveReadParts(census, root);
+    /**
+     * O QUE ELE ESCREVEU VEM ANTES DO QUE ELE REPETIU - e a ordem era a inversa.
+     *
+     * `summarize` abre com "13 distinct design values · 17 colour · 10 spacing", e os componentes
+     * com as variantes que este leitor extraiu do código dele vinham no fim, atrás de tudo. Quem lê
+     * um terminal lê de cima para baixo e conclui pela primeira seção: a leitura profunda era
+     * apresentada como se fosse um contador de pixels repetidos.
+     *
+     * `Button variant(primary|ghost) size(lg)` é a coisa mais difícil que esta esteira faz, e é a
+     * que diz que o vocabulário do frontend dele foi entendido. Ela abre.
+     *
+     * E ABRE NOS DOIS COMANDOS. Duas ordens para a mesma leitura é a mesma doença de duas verdades:
+     * o `import` não ganha nada sendo a versão pior de si mesmo, e quem roda os dois na mesma
+     * semana teria que aprender duas telas (dono, 13/09 - a decisão de ordem é do terminal, não do
+     * produto, e portanto minha).
+     */
+    printComponents(census);
     await summarize(census, root, scope);
     /**
      * ONDE ESTOU vem antes de O QUE EU LEIO, e o `!scope` calava exatamente quem
@@ -4402,6 +4436,27 @@ export async function runImport(opts) {
     // there - config, `ds/<slug>/`, the hook's marker - and the census was the
     // only artefact that travelled with `--dir`, which is how two of them ended
     // up disagreeing about which import happened (dono, 31/07).
+    /**
+     * A FRONTEIRA DO `inspect`, e ela é uma linha só porque a leitura já terminou.
+     *
+     * Tudo acima imprimiu; a primeira escrita é a próxima instrução. Retornar aqui entrega os
+     * quatro contratos de uma vez, sem um caminho paralelo que possa divergir.
+     *
+     * O QUE ELE VÊ NO LUGAR DO ARQUIVO: a frase que diz o que sobra a fazer - e ela NÃO faz.
+     * Um comando de primeiro contato que termina executando o passo seguinte é o comando que a
+     * pessoa não vai rodar de novo.
+     */
+    if (opts.inspect) {
+        sayReach(census);
+        console.log("");
+        console.log(section("Your agent cannot ask any of this yet"));
+        console.log(body("Nothing was written, and nothing was sent."));
+        console.log("");
+        console.log(body("To let it ask before it invents:"));
+        console.log(body(`    ${paint.strong("npx synthesisui@latest connect")}`));
+        console.log("");
+        return;
+    }
     const out = opts.census ?? join(root, "_synthesisui", "census.json");
     await mkdir(dirname(out), { recursive: true });
     await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");
@@ -4427,7 +4482,8 @@ export async function runImport(opts) {
     if (opts.dry) {
         console.log(body("Nothing was sent. Read the file, then run it without --dry."));
         sayReach(census);
-        printComponents(census);
+        /* `printComponents` subiu para antes de `summarize` e vale para todo caminho - repetir
+           aqui imprimiria os componentes duas vezes na mesma execução. */
         printAgentContract();
         console.log("");
         return;

package/dist/doctor/catalogue-fetch.js

@@ -84,5 +84,21 @@ export function asCatalogueTable(index) {
  * "using the built-in list" is not.
  */
 export function describeFallback(result, floorSize) {
-    return `${result.because}. Matching used the ${floorSize} names built into this CLI instead of the live catalogue, so a component of yours that lines up with something we added recently will read as exclusively yours. That is a smaller answer, not a wrong one - re-run with a session to get the full one.`;
+    /**
+     * "RE-RUN WITH A SESSION" É UM CONSELHO ERRADO PARA QUEM JÁ TEM UMA - e `offline` é
+     * exatamente esse caso.
+     *
+     * Os outros dois motivos são falhas de acesso: sem sessão, ou recusada. Entrar resolve, e a
+     * frase manda entrar. `offline` é uma ESCOLHA do comando - `inspect` não fala com ninguém por
+     * contrato -, então a mesma frase virava uma contradição na tela: o terminal dizia "esta
+     * execução não faz chamada de rede" e, na oração seguinte, "rode de novo com uma sessão"
+     * para alguém que estava logada o tempo todo (medido em 13/09, rodando na máquina do dono).
+     *
+     * Dizer a verdade aqui custa uma condição, e a alternativa é ensinar a pessoa a desconfiar
+     * das outras frases do mesmo relatório.
+     */
+    const saida = result.why === "offline"
+        ? "`synthesisui import` matches against the full list"
+        : "re-run with a session to get the full one";
+    return `${result.because}. Matching used the ${floorSize} names built into this CLI instead of the live catalogue, so a component of yours that lines up with something we added recently will read as exclusively yours. That is a smaller answer, not a wrong one - ${saida}.`;
 }

package/dist/index.js

@@ -61,6 +61,10 @@ Usage - deterministic, FREE:
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
 
 Usage - governance (deterministic, FREE):
+  synthesisui inspect [--scope <p>]        read this repository and say what it sees: your components,
+                                           their variant axes and options, their parts and shape, and
+                                           where one is built from another - then the values you repeat,
+                                           with file and line. No account, no network, nothing written
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
   synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
@@ -257,6 +261,45 @@ async function main() {
                 registry,
             });
             break;
+        /**
+         * `inspect` - LEIA O MEU CÓDIGO E ME DIGA O QUE VOCÊ VÊ.
+         *
+         * O QUE O CLIENTE GANHA: em segundos, sem criar conta e sem que nada seja escrito no
+         * repositório dele, ele vê o vocabulário do próprio frontend lido de volta - os componentes,
+         * os eixos de variante com as opções, as partes, a forma como elas se aninham no código dele,
+         * e onde um componente dele é feito de outro. Depois os valores que ele repete, com arquivo e
+         * linha. E o que este leitor NÃO entendeu, também com arquivo e linha.
+         *
+         * POR QUE ELE EXISTE, SE `import --dry` já fazia isso: fazia, e com o nome errado para o
+         * momento errado. Para quem nunca ouviu falar da plataforma, `import` promete escrita e
+         * `--dry` é jargão nosso - e, pior, aquele caminho REALMENTE escrevia três arquivos
+         * (`census.json`, `not-expressed.md` e o `ledger.jsonl` que nasce junto com a pasta). A
+         * pergunta que ele provocava era *"posso confiar neste comando?"*, quando a única pergunta
+         * que deveria estar na cabeça de quem roda é *"como é que ele entendeu o meu Button?"*.
+         *
+         * ELE NÃO SUBSTITUI O `doctor`, e os dois não se fundem: `inspect` responde "o que você vê?",
+         * `doctor` responde "onde isto está derivando?". São perguntas de momentos diferentes, e um
+         * comando que responde as duas responde mal as duas.
+         */
+        case "inspect":
+            await runImport({
+                root: dir,
+                cli: CLI_VERSION,
+                inspect: true,
+                scope: Array.isArray(flags.scope)
+                    ? flags.scope
+                    : typeof flags.scope === "string"
+                        ? flags.scope
+                        : undefined,
+                usage: [flags.usage]
+                    .flat()
+                    .filter((v) => typeof v === "string")
+                    .flatMap((v) => v.split(","))
+                    .map((v) => v.trim())
+                    .filter(Boolean),
+                registry,
+            });
+            break;
         case "adopt":
             // Dry by default: `--write` is the only way anything lands on disk.
             await adopt({

package/package.json

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