@joao.dadas/lume 0.0.0-stage → 0.4.0

package/src/init.mjs

@@ -0,0 +1,308 @@
+// lume init: conduz o agente do dev, uma etapa por chamada. Cada resposta é um
+// JSON com `etapa`, `next`, `say`, `instruction`, `run`, `rules` e `details`.
+// O estado vem do próprio projeto (components.json, lume.json, arquivos), então
+// chamar de novo depois de cada passo sempre devolve o passo seguinte.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { baseInstalada, conferir, KITS, REGRAS } from "./check.mjs";
+import { LAYOUTS, lerProjeto } from "./projeto.mjs";
+import { criarRegistry, REPO } from "./registry.mjs";
+
+const PACOTE = "@joao.dadas/lume";
+
+export const RULES = [
+  "Siga uma etapa por vez: rode o que está em `run`, faça o que está em `instruction` e chame o init de novo. Não pule etapa nem escreva código de tela antes de `next` ser `migrar`.",
+  "Fale com o usuário pelo texto de `say`. Quando `next` for `perguntar`, faça a pergunta e espere a resposta antes de seguir.",
+  "O lume substitui a interface atual de uma vez. Nunca crie pasta paralela de componentes (components/lume, components/ds) nem desvie os aliases do components.json: components/ui é do lume.",
+  "Nunca edite à mão um arquivo instalado da registry (components/ui e os blocos): variação vai por className na composição. O lume check compara cada arquivo com a versão da registry.",
+  "Nunca mantenha um componente antigo com a API antiga e a aparência do lume por dentro: reescreva a tela para a API do lume (Button variant default, Dialog no lugar de Modal, render no lugar de asChild).",
+  "Nunca troque a fonte, os tamanhos, o raio, a sombra, o movimento ou os ícones. Por produto só a cor muda, por tema instalado depois do base.",
+  "Antes de escrever qualquer tela, leia a skill lume-design-engineering (.agents/skills ou .claude/skills).",
+  "Não rode git clean, não apague arquivo fora do que a etapa pede e não faça commit nem push sem o usuário pedir.",
+];
+
+function comando(versao, args) {
+  return `npx -y ${PACOTE}@${versao} ${args}`;
+}
+
+function resposta(versao, campos) {
+  return {
+    etapa: campos.etapa,
+    next: campos.next,
+    say: campos.say,
+    instruction: campos.instruction,
+    run: campos.run ?? [],
+    rules: RULES,
+    details: { versao, ...(campos.details ?? {}) },
+  };
+}
+
+/** "0.4.0" > "0.3.1"? Compara X.Y.Z como números. */
+export function versaoMaiorQue(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** Os comandos que instalam (ou reinstalam) tudo do lume numa versão. */
+async function comandosDeInstalacao(projeto, registry, versao) {
+  const itens = await registry.itens();
+  const ui = itens.filter((i) => i.type === "registry:ui").map((i) => i.name);
+  const graficos = projeto.deps.recharts ? ["kit-graficos"] : [];
+  const doLumeJson = Array.isArray(projeto.lumeJson?.itens)
+    ? projeto.lumeJson.itens
+    : [];
+  const nomes = [
+    ...new Set([
+      ...ui,
+      ...KITS,
+      ...graficos,
+      "login-form",
+      "guia",
+      ...doLumeJson,
+    ]),
+  ].filter((n) => n !== "link-next");
+  const lista = nomes.map((n) => `${REPO}/${n}#v${versao}`).join(" ");
+  const run = [`npx shadcn@latest add ${lista} --overwrite --yes`];
+  if (projeto.framework === "next") {
+    run.push(
+      `npx shadcn@latest add ${REPO}/link-next#v${versao} --overwrite --yes`,
+    );
+  }
+  return run;
+}
+
+function gravarLumeJson(raiz, lumeJson) {
+  writeFileSync(
+    path.join(raiz, "lume.json"),
+    `${JSON.stringify(lumeJson, null, 2)}\n`,
+  );
+}
+
+async function componentesFaltando(projeto, registry) {
+  const itens = await registry.itens();
+  const ui = itens.filter((i) => i.type === "registry:ui").map((i) => i.name);
+  const faltam = ui.filter(
+    (nome) =>
+      !existsSync(path.join(projeto.raiz, projeto.dirUi, `${nome}.tsx`)),
+  );
+  const shell = path.join(
+    projeto.raiz,
+    projeto.dirComponentes,
+    "app-shell",
+    "app-shell.tsx",
+  );
+  if (!existsSync(shell)) faltam.push("app-shell");
+  if (projeto.framework === "next") {
+    const link = path.join(projeto.raiz, projeto.dirComponentes, "link.tsx");
+    if (!existsSync(link) || !readFileSync(link, "utf8").includes("next/link"))
+      faltam.push("link-next");
+  }
+  return { faltam, ui };
+}
+
+function skillInstalada(raiz) {
+  return [".agents/skills", ".claude/skills"].some((d) =>
+    existsSync(path.join(raiz, d, "lume-design-engineering", "SKILL.md")),
+  );
+}
+
+function shellDoLayout(layout) {
+  if (layout === "topbar") return '<AppShell layout="topbar" ...>';
+  if (layout === "offcanvas")
+    return '<AppShell layout="sidebar" collapsible="offcanvas" ...>';
+  return '<AppShell layout="sidebar" collapsible="icon" ...>';
+}
+
+/**
+ * Uma etapa do init para o projeto em `raiz`. A versão que vale é a do
+ * lume.json; `opcoes.versao` (a do pacote) só entra num projeto sem lume.json
+ * ou quando o usuário aceita subir (`atualizar: "sim"`).
+ */
+export async function passo(raiz, opcoes) {
+  const {
+    versao: versaoPacote,
+    layout: layoutPedido,
+    atualizar,
+    buscar,
+  } = opcoes;
+  const projeto = lerProjeto(raiz);
+  let lumeJson =
+    projeto.lumeJson && !projeto.lumeJson.__invalido ? projeto.lumeJson : null;
+  let versao = SEMVER.test(String(lumeJson?.versao ?? ""))
+    ? lumeJson.versao
+    : versaoPacote;
+  let reinit = comando(versao, "init");
+
+  if (!projeto.pkg) {
+    return resposta(versao, {
+      etapa: "ler",
+      next: "bloqueado",
+      say: "Não achei um package.json aqui. Rode o comando na raiz do projeto.",
+      instruction:
+        "Vá para a raiz do projeto (a pasta do package.json) e rode o init de novo.",
+    });
+  }
+  if (!projeto.framework || projeto.tailwind !== 4) {
+    return resposta(versao, {
+      etapa: "ler",
+      next: "bloqueado",
+      say: `O lume precisa de Next ou Vite com Tailwind 4. Achei framework ${projeto.framework ?? "desconhecido"} e Tailwind ${projeto.tailwind ?? "ausente"}.`,
+      instruction:
+        "Mostre isso ao usuário e pare. Com Tailwind 3, a atualização é `npx @tailwindcss/upgrade`, que é uma tarefa própria e precisa do ok dele.",
+      details: { framework: projeto.framework, tailwind: projeto.tailwind },
+    });
+  }
+
+  if (layoutPedido) {
+    if (!LAYOUTS.includes(layoutPedido)) {
+      return resposta(versao, {
+        etapa: "ler",
+        next: "bloqueado",
+        say: `Layout "${layoutPedido}" não existe. As opções são ${LAYOUTS.join(", ")}.`,
+        instruction:
+          "Pergunte de novo ao usuário e rode o init com --layout=<escolha>.",
+      });
+    }
+    lumeJson = { ...(lumeJson ?? {}), versao, layout: layoutPedido };
+    gravarLumeJson(raiz, lumeJson);
+  }
+  if (!lumeJson?.layout) {
+    const temInterface = existsSync(path.join(raiz, projeto.dirUi));
+    return resposta(versao, {
+      etapa: "ler",
+      next: "perguntar",
+      say: [
+        `Vou aplicar o lume v${versao} neste projeto (${projeto.framework}, Tailwind 4).`,
+        temInterface
+          ? "Ele substitui a interface atual de uma vez: os componentes antigos saem e as telas são reescritas com os componentes do lume, numa mudança só."
+          : "Ele instala a base, os componentes e as regras de uma vez.",
+        "Qual layout de navegação você quer? sidebar (barra lateral que recolhe para ícones), offcanvas (barra lateral que some) ou topbar (barra no topo, até 7 zonas).",
+      ].join(" "),
+      instruction: `Faça a pergunta de \`say\` ao usuário e espere a resposta. Depois rode \`${reinit} --layout=<sidebar|offcanvas|topbar>\`.`,
+      details: {
+        framework: projeto.framework,
+        alteracoesNaoCommitadas: projeto.alteracoesGit,
+        avisoGit:
+          projeto.alteracoesGit > 0
+            ? "Há mudanças não commitadas. Sugira ao usuário commitar ou guardar antes, para a troca ficar numa mudança separada."
+            : undefined,
+      },
+    });
+  }
+  const layout = lumeJson.layout;
+
+  if (versaoMaiorQue(versaoPacote, versao) && atualizar !== "nao") {
+    const anterior = versao;
+    if (atualizar !== "sim") {
+      return resposta(versao, {
+        etapa: "atualizar",
+        next: "perguntar",
+        say: `O projeto está no lume v${anterior} e a v${versaoPacote} já saiu. Quer subir para a v${versaoPacote}? Os arquivos do lume são reinstalados com --overwrite.`,
+        instruction: `Faça a pergunta de \`say\` ao usuário e espere a resposta. Se ele quiser subir, rode \`${comando(versaoPacote, "init")} --atualizar=sim\`. Se não, rode \`${reinit}\`, que segue na v${anterior}.`,
+        details: { versaoDoProjeto: anterior, versaoNova: versaoPacote },
+      });
+    }
+    versao = versaoPacote;
+    reinit = comando(versao, "init");
+    lumeJson = { ...lumeJson, versao };
+    gravarLumeJson(raiz, lumeJson);
+    projeto.lumeJson = lumeJson;
+    if (baseInstalada(projeto)) {
+      const registry = criarRegistry(versao, buscar);
+      return resposta(versao, {
+        etapa: "atualizar",
+        next: "rodar",
+        say: `Subindo o lume de v${anterior} para v${versao}: os arquivos do lume são reinstalados na versão nova.`,
+        instruction: `O lume.json já está na v${versao}. Rode os comandos de \`run\` em ordem e depois \`${reinit}\`. O --overwrite troca os arquivos do lume pela versão nova: é o esperado. Não restaure versão antiga de nenhum deles.`,
+        run: await comandosDeInstalacao(projeto, registry, versao),
+        details: { versaoAnterior: anterior },
+      });
+    }
+  }
+  const registry = criarRegistry(versao, buscar);
+
+  if (!baseInstalada(projeto)) {
+    const cj = projeto.componentsJson;
+    const run = [];
+    let instrucao = `Rode os comandos de \`run\` na raiz do projeto, em ordem, e depois \`${reinit}\`.`;
+    if (cj) {
+      run.push("rm components.json");
+      instrucao = `O components.json atual não é o do lume (style "${cj.style}", aliases.ui "${cj.aliases?.ui}"). ${instrucao}`;
+    }
+    run.push(`npx shadcn@latest init ${REPO}/base#v${versao} -y`);
+    return resposta(versao, {
+      etapa: "base",
+      next: "rodar",
+      say: "Instalando a base do lume: tokens, fontes e o components.json.",
+      instruction: `${instrucao} Nunca use -d no init do shadcn. Se o CSS global antigo tiver tokens próprios (outro @theme inline, outro @layer base, cores próprias), apague esses blocos: fica só o que a base escreveu.`,
+      run,
+    });
+  }
+
+  const { faltam } = await componentesFaltando(projeto, registry);
+  if (faltam.length > 0) {
+    const run = await comandosDeInstalacao(projeto, registry, versao);
+    return resposta(versao, {
+      etapa: "componentes",
+      next: "rodar",
+      say: "Instalando todos os componentes do lume no lugar dos atuais.",
+      instruction: `Rode os comandos de \`run\` em ordem e depois \`${reinit}\`. O --overwrite troca os arquivos de mesmo nome em components/ui: é o esperado. Não restaure versão antiga de nenhum deles.`,
+      run,
+      details: { faltam: faltam.slice(0, 20), totalFaltando: faltam.length },
+    });
+  }
+
+  if (!skillInstalada(raiz)) {
+    return resposta(versao, {
+      etapa: "skill",
+      next: "rodar",
+      say: "Instalando a skill com as regras de design engineering do lume.",
+      instruction: `Rode o comando de \`run\` e depois \`${reinit}\`. Depois leia o SKILL.md instalado antes de seguir.`,
+      run: [`npx -y skills add ${REPO} --skill lume-design-engineering -y`],
+    });
+  }
+
+  const resultado = await conferir(raiz, { versao, buscar });
+  if (!resultado.ok) {
+    const porRegra = {};
+    for (const v of resultado.violacoes)
+      porRegra[v.regra] = (porRegra[v.regra] ?? 0) + 1;
+    const arquivos = new Set(resultado.violacoes.map((v) => v.arquivo));
+    return resposta(versao, {
+      etapa: "migrar",
+      next: "migrar",
+      say: `Base, componentes e regras instalados. Faltam ${resultado.violacoes.length} ajustes em ${arquivos.size} arquivos para o projeto ficar no lume; vou reescrever as telas com os componentes dele.`,
+      instruction: [
+        `Rode \`${comando(versao, "check")}\` para ver a lista inteira e corrija tudo, regra por regra.`,
+        "Reescreva cada tela para os componentes de components/ui, na API do lume, e apague os componentes antigos depois de trocar os imports. O que é do produto e não existe no lume vai para components/app, composto com os primitivos do lume.",
+        `Monte o shell com ${shellDoLayout(layout)}, o layout que o usuário escolheu.`,
+        'Monte cada página como o guia manda: PageHeader, StatGrid com StatCard, Card size="sm", DataTable ou Table, Field com Input, EmptyState.',
+        `Quando o check passar, rode \`${reinit}\` de novo.`,
+      ].join(" "),
+      run: [comando(versao, "check")],
+      details: {
+        layout,
+        violacoesPorRegra: porRegra,
+        dicas: Object.fromEntries(
+          Object.keys(porRegra).map((r) => [r, REGRAS[r]]),
+        ),
+      },
+    });
+  }
+
+  return resposta(versao, {
+    etapa: "pronto",
+    next: "pronto",
+    say: `O projeto está no lume v${versao}, com layout ${layout}, e o lume check passa.`,
+    instruction:
+      "Rode o typecheck, o lint, os testes e o build do projeto e mostre o resultado ao usuário. Sugira abrir o app e conferir as telas no claro e no escuro. Não faça commit nem push sem ele pedir.",
+    details: { layout },
+  });
+}

package/src/projeto.mjs

@@ -0,0 +1,188 @@
+// Leitura do projeto que vai adotar (ou já adotou) o lume. Só lê: nada aqui
+// grava arquivo.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { lerJsonc } from "./texto.mjs";
+
+export const LAYOUTS = ["sidebar", "offcanvas", "topbar"];
+
+const PULAR = new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".turbo",
+  ".vercel",
+  ".agents",
+  ".claude",
+]);
+
+function lerArquivoJson(arquivo) {
+  if (!existsSync(arquivo)) return null;
+  try {
+    return lerJsonc(readFileSync(arquivo, "utf8"));
+  } catch {
+    return { __invalido: true };
+  }
+}
+
+/** Lista recursiva de arquivos (caminhos relativos à raiz, com /). */
+export function listar(raiz, rel = "", acc = []) {
+  const dir = path.join(raiz, rel);
+  let entradas = [];
+  try {
+    entradas = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entradas) {
+    if (PULAR.has(e.name)) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) listar(raiz, r, acc);
+    else if (e.isFile()) acc.push(r);
+  }
+  return acc;
+}
+
+function lerTsconfig(raiz) {
+  return (
+    lerArquivoJson(path.join(raiz, "tsconfig.json")) ??
+    lerArquivoJson(path.join(raiz, "jsconfig.json"))
+  );
+}
+
+/** Os paths do tsconfig já resolvidos pelo baseUrl: { "@/": "src/" }. */
+export function pathsDoTsconfig(raiz) {
+  const opcoes = lerTsconfig(raiz)?.compilerOptions ?? {};
+  const base = typeof opcoes.baseUrl === "string" ? opcoes.baseUrl : ".";
+  const saida = {};
+  for (const [chave, alvos] of Object.entries(opcoes.paths ?? {})) {
+    if (!chave.endsWith("/*") || !Array.isArray(alvos) || !alvos[0]) continue;
+    const alvo = String(alvos[0]).replace(/\*$/, "");
+    const junto = path.posix.normalize(path.posix.join(base, alvo || "."));
+    const rel =
+      junto === "." || junto === "./" ? "" : junto.replace(/^\.\//, "");
+    saida[chave.slice(0, -1)] = rel && !rel.endsWith("/") ? `${rel}/` : rel;
+  }
+  return saida;
+}
+
+/**
+ * Pasta do código do app: o alvo de `@/*` no tsconfig (com baseUrl). Só sem
+ * esse path cai em `src/` quando a pasta existe.
+ */
+export function prefixoDoApp(raiz) {
+  const paths = pathsDoTsconfig(raiz);
+  if ("@/" in paths) return paths["@/"];
+  const src = path.join(raiz, "src");
+  return existsSync(src) && statSync(src).isDirectory() ? "src/" : "";
+}
+
+/** "@/components/ui" vira "src/components/ui" pelos paths do tsconfig. */
+export function resolverAlias(alias, raiz, prefixoPadrao) {
+  if (!alias) return null;
+  const paths = pathsDoTsconfig(raiz);
+  const chaves = Object.keys(paths).sort((a, b) => b.length - a.length);
+  for (const de of chaves) {
+    if (!alias.startsWith(de)) continue;
+    return `${paths[de]}${alias.slice(de.length)}`.replace(/\/$/, "");
+  }
+  if (alias.startsWith("@/") || alias.startsWith("~/")) {
+    return `${prefixoPadrao}${alias.slice(2)}`;
+  }
+  return alias;
+}
+
+/**
+ * Prefixos de import que apontam para o próprio projeto: os dos aliases do
+ * components.json (`#/`, `@app/`) e as chaves de paths do tsconfig.
+ */
+function prefixosLocais(raiz, aliases) {
+  const saida = new Set(Object.keys(pathsDoTsconfig(raiz)));
+  for (const valor of Object.values(aliases ?? {})) {
+    if (typeof valor !== "string") continue;
+    const m = /^([^/]+\/)/.exec(valor);
+    if (m) saida.add(m[1]);
+  }
+  return [...saida].filter((p) => !p.startsWith("."));
+}
+
+function versaoMaior(spec) {
+  const m = /(\d+)/.exec(String(spec ?? ""));
+  return m ? Number(m[1]) : null;
+}
+
+function gitSujo(raiz) {
+  try {
+    const saida = execFileSync("git", ["status", "--porcelain"], {
+      cwd: raiz,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return saida.split("\n").filter(Boolean).length;
+  } catch {
+    return null;
+  }
+}
+
+/** Tudo o que o init e o check precisam saber do projeto. */
+export function lerProjeto(raiz) {
+  const pkg = lerArquivoJson(path.join(raiz, "package.json"));
+  const deps = {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+  };
+  const framework = deps.next ? "next" : deps.vite ? "vite" : null;
+  const tailwind =
+    versaoMaior(deps.tailwindcss) ??
+    (deps["@tailwindcss/postcss"] || deps["@tailwindcss/vite"] ? 4 : null);
+  const prefixo = prefixoDoApp(raiz);
+  const componentsJson = lerArquivoJson(path.join(raiz, "components.json"));
+  const lumeJson = lerArquivoJson(path.join(raiz, "lume.json"));
+  const aliases = componentsJson?.aliases ?? {};
+  const dirUi = resolverAlias(aliases.ui ?? "@/components/ui", raiz, prefixo);
+  const dirComponentes = resolverAlias(
+    aliases.components ?? "@/components",
+    raiz,
+    prefixo,
+  );
+  const dirHooks = resolverAlias(aliases.hooks ?? "@/hooks", raiz, prefixo);
+  const dirLib = resolverAlias(aliases.lib ?? "@/lib", raiz, prefixo);
+  const candidatosCss = [
+    componentsJson?.tailwind?.css,
+    `${prefixo}app/globals.css`,
+    "app/globals.css",
+    `${prefixo}index.css`,
+    `${prefixo}styles/globals.css`,
+  ].filter(Boolean);
+  const css = candidatosCss.find((c) => existsSync(path.join(raiz, c))) ?? null;
+  return {
+    raiz,
+    pkg,
+    deps,
+    framework,
+    tailwind,
+    prefixo,
+    componentsJson,
+    lumeJson,
+    dirUi,
+    dirComponentes,
+    dirHooks,
+    dirLib,
+    prefixosLocais: prefixosLocais(raiz, aliases),
+    css,
+    alteracoesGit: gitSujo(raiz),
+  };
+}
+
+/** Aponta para a registry do lume (adoção, mesmo que pela metade)? */
+export function adotouLume(projeto) {
+  if (projeto.lumeJson) return true;
+  const texto = JSON.stringify(projeto.componentsJson ?? {});
+  return /joaodadas\/lume|lume-ashmont/.test(texto);
+}

package/src/registry.mjs

@@ -0,0 +1,64 @@
+// Leitura da registry do lume numa versão fixa: o registry.json da tag (lista
+// de itens e caminhos) e o public/r/<item>.json (o conteúdo de cada arquivo).
+// LUME_REGISTRY troca a origem: outra URL base ou uma pasta local do repo.
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const REPO = "joaodadas/lume";
+
+export function origem(versao) {
+  const env = process.env.LUME_REGISTRY;
+  if (env) return env.replace(/\/$/, "");
+  return `https://raw.githubusercontent.com/${REPO}/v${versao}`;
+}
+
+async function buscarPadrao(url) {
+  if (!/^https?:\/\//.test(url)) {
+    return JSON.parse(await readFile(url.replace(/^file:\/\//, ""), "utf8"));
+  }
+  const r = await fetch(url, { headers: { "user-agent": "lume-cli" } });
+  if (!r.ok) throw new Error(`${url} respondeu ${r.status}`);
+  return r.json();
+}
+
+export function criarRegistry(versao, buscar = buscarPadrao) {
+  const base = origem(versao);
+  const cache = new Map();
+  const pegar = (rel) => {
+    const url = /^https?:\/\//.test(base)
+      ? `${base}/${rel}`
+      : path.join(base, rel);
+    if (!cache.has(url)) cache.set(url, buscar(url));
+    return cache.get(url);
+  };
+  return {
+    base,
+    /** Itens da versão: { name, type, files: [{ path, target? }] }. */
+    async itens() {
+      const r = await pegar("registry.json");
+      return r.items ?? [];
+    },
+    /** O item buildado, com o conteúdo de cada arquivo. */
+    async item(nome) {
+      return pegar(`public/r/${nome}.json`);
+    },
+  };
+}
+
+/** Executa tarefas assíncronas com no máximo `n` ao mesmo tempo. */
+export async function emLotes(lista, n, fn) {
+  const saida = new Array(lista.length);
+  let proximo = 0;
+  const trabalhadores = Array.from(
+    { length: Math.min(n, lista.length) },
+    async () => {
+      while (proximo < lista.length) {
+        const i = proximo++;
+        saida[i] = await fn(lista[i], i);
+      }
+    },
+  );
+  await Promise.all(trabalhadores);
+  return saida;
+}