onboarding-kit 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# onboarding-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Onboarding de projetos gerado pela **sua IA local** e exibido em `/onboarding`, dentro do próprio app.
+
+1. O `onboarding-kit` cria um `onboarding.json` com todos os campos em branco e instruções para a IA.
+2. Você pede para a IA que já usa no projeto (Claude Code, Cursor, Copilot…) ler e preencher o arquivo.
+3. O `onboarding-kit` valida o resultado e mostra uma apresentação do projeto em `/onboarding`.
+
+Funciona com **Next.js**, **NestJS** e **Node.js** (Express, http nativo e similares). Não tem dependências em runtime.
+
+## Começando
+
+```bash
+npm i -D onboarding-kit
+npx onboarding-kit init
+```
+
+O `init` detecta o framework e:
+
+- **Next.js (App Router):** cria `app/onboarding/route.ts` (ou `src/app/...`).
+- **NestJS:** adiciona `OnboardingModule.register()` em `src/app.module.ts`.
+- **Node.js:** mostra o trecho para registrar a rota no seu servidor.
+
+Depois, envie isto para a sua IA:
+
+> Leia o arquivo onboarding.json e siga as instruções em "_instructions" para preenchê-lo com base neste repositório. No final, rode "npx onboarding-kit validate" e corrija o que ele apontar.
+
+Para ver o resultado, abra `/onboarding` com o app rodando em dev, ou rode `npx onboarding-kit serve`.
+
+Se você abrir `/onboarding` antes da IA terminar, a página mostra o prompt pronto para copiar, acompanha as seções conforme a IA preenche o arquivo e abre a apresentação sozinha quando ela termina. Sem `onboarding.json`, o prompt já pede para a IA rodar o `init` antes.
+
+## Comandos
+
+| Comando | O que faz |
+|---|---|
+| `init` | Cria o `onboarding.json` e liga a rota. Opções: `--framework`, `--lang`, `--no-route`, `--force` |
+| `prompt` | Mostra o texto para enviar à IA |
+| `validate` | Confere campos obrigatórios, itens-modelo esquecidos, se as evidências existem, se há segredos e se o JSON está atrás do commit atual. Sai com código 1 em caso de erro (útil na CI) |
+| `serve` | Abre a apresentação em `http://localhost:4321` (`--port` para mudar) |
+
+## A apresentação
+
+A página `/onboarding` é um tour em slides, contado como uma história: boas-vindas → o porquê → o negócio → o produto → vocabulário (com cartões que viram e um quiz) → regras do jogo → stack → arquitetura → rodando na máquina → jeito da casa → tour pelo código → cuidados → decisões → primeira missão → final.
+
+Os capítulos entram com uma cortina animada, os elementos aparecem em cascata, o fundo muda de cor junto com o capítulo e os cartões inclinam com o mouse. Tudo isso é desligado quando o sistema pede movimento reduzido.
+
+Navegação por ← →, espaço, swipe no celular ou pelos segmentos coloridos no topo. `O` abre o índice. O progresso e as tarefas marcadas ficam salvos no navegador. Tem tema claro e escuro. Capítulos sem conteúdo são pulados e listas longas viram vários slides.
+
+## Cara da marca
+
+A apresentação usa as cores e o logo do projeto. A IA preenche `brand` (`primaryColor`, `palette`, `logo`, `favicon`) e o que ficar vazio é detectado automaticamente:
+
+- **Cores:** `tailwind.config` (`brand`, `primary`, `accent`, inclusive `colors.indigo`), `@theme` do Tailwind v4, variáveis CSS como `--primary` e `--brand` (hex, rgb, hsl, o formato do shadcn/ui e oklch), variáveis SCSS/LESS, temas JS (`palette.primary.main`) e o `theme_color` do manifest.
+- **Logo e favicon:** `public/`, `assets/`, `src/assets/` e `app/` (`logo.*`, `icon.*`, `favicon.*`). Os arquivos de exemplo do framework (`next.svg`, `vercel.svg`, `vite.svg`…) são ignorados.
+
+Com uma cor, os capítulos variam em torno dela. Com várias, eles se revezam entre elas. Marcas em preto e branco viram um tema monocromático.
+
+## O que vai no JSON
+
+`project`, `business` (modelo de negócio, valor entregue, perfis e jornadas), `gettingStarted`, `stack`, `architecture` (com diagrama Mermaid), `conventions`, `domain` (glossário e regras de negócio), `features`, `tours` pelo código, `gotchas`, `decisions`, `firstTasks` e `brand` (cores e logo).
+
+Toda afirmação aponta para arquivos reais (`evidence: ["src/orders/orders.service.ts:42"]`). Quando `project.repoUrl` está preenchido, essas referências viram links para o código.
+
+As chaves que começam com `_` (como `_instructions`) são só para a IA: a página as ignora. Deixe-as no arquivo, porque a IA usa essas instruções para **atualizar** o onboarding depois (com `git diff` desde `meta.commit`).
+
+## Uso manual dos adapters
+
+```ts
+// Next.js — app/onboarding/route.ts
+import { createOnboardingRoute } from "onboarding-kit/next";
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const GET = createOnboardingRoute();
+
+// Next.js Pages Router — pages/api/onboarding.ts (+ rewrite de /onboarding)
+import { createOnboardingApiHandler } from "onboarding-kit/next";
+export default createOnboardingApiHandler();
+
+// NestJS — app.module.ts (com globalPrefix "api", a rota fica /api/onboarding)
+import { OnboardingModule } from "onboarding-kit/nest";
+@Module({ imports: [OnboardingModule.register({ path: "onboarding" })] })
+
+// Express / Node
+import { createOnboardingHandler } from "onboarding-kit/node";
+app.get("/onboarding", createOnboardingHandler());
+```
+
+Todos os adapters aceitam `{ file?: string; enabled?: boolean }`.
+
+## Segurança
+
+- A rota fica **desligada quando `NODE_ENV=production`**. Para ligar de propósito, passe `enabled: true`.
+- A página envia `noindex` e não usa cache.
+- O `validate` procura tokens, chaves privadas, JWTs e URLs com senha.
+- Todo o conteúdo do JSON passa por escape antes de entrar no HTML.
+
+## Desenvolvimento
+
+```bash
+npm install
+npm test        # compila e roda os testes
+node dist/cli/index.js serve   # mostra o onboarding do próprio onboarding-kit
+```

package/dist/adapters/nest.d.ts

@@ -0,0 +1,15 @@
+import { DynamicModule } from "@nestjs/common";
+import type { OnboardingOptions } from "../types";
+export interface OnboardingModuleOptions extends OnboardingOptions {
+    /** Caminho da rota. Padrão: "onboarding". O globalPrefix do app, se houver, é aplicado antes. */
+    path?: string;
+}
+/**
+ * Módulo NestJS que serve a apresentação do projeto.
+ *
+ * app.module.ts:
+ *   imports: [OnboardingModule.register()]
+ */
+export declare class OnboardingModule {
+    static register(options?: OnboardingModuleOptions): DynamicModule;
+}

package/dist/adapters/nest.js

@@ -0,0 +1,53 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var OnboardingModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnboardingModule = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../index");
+const load_1 = require("../load");
+/**
+ * Módulo NestJS que serve a apresentação do projeto.
+ *
+ * app.module.ts:
+ *   imports: [OnboardingModule.register()]
+ */
+let OnboardingModule = OnboardingModule_1 = class OnboardingModule {
+    static register(options = {}) {
+        const { path = "onboarding", ...rest } = options;
+        let OnboardingController = class OnboardingController {
+            async show() {
+                if (!(0, load_1.resolveEnabled)(rest))
+                    throw new common_1.NotFoundException();
+                // Páginas de erro (JSON inválido etc.) também são HTML legível, então sempre devolvemos o corpo.
+                const page = await (0, index_1.renderOnboardingPage)(rest.file);
+                return page.html;
+            }
+        };
+        __decorate([
+            (0, common_1.Get)(),
+            (0, common_1.Header)("Content-Type", index_1.HTML_HEADERS["Content-Type"]),
+            (0, common_1.Header)("Cache-Control", index_1.HTML_HEADERS["Cache-Control"]),
+            (0, common_1.Header)("X-Robots-Tag", index_1.HTML_HEADERS["X-Robots-Tag"]),
+            __metadata("design:type", Function),
+            __metadata("design:paramtypes", []),
+            __metadata("design:returntype", Promise)
+        ], OnboardingController.prototype, "show", null);
+        OnboardingController = __decorate([
+            (0, common_1.Controller)(path)
+        ], OnboardingController);
+        return { module: OnboardingModule_1, controllers: [OnboardingController] };
+    }
+};
+exports.OnboardingModule = OnboardingModule;
+exports.OnboardingModule = OnboardingModule = OnboardingModule_1 = __decorate([
+    (0, common_1.Module)({})
+], OnboardingModule);

package/dist/adapters/next.d.ts

@@ -0,0 +1,23 @@
+import type { OnboardingOptions } from "../types";
+export type { OnboardingOptions };
+/**
+ * Route handler para o App Router do Next.js.
+ *
+ * app/onboarding/route.ts:
+ *   import { createOnboardingRoute } from "onboarding-kit/next";
+ *   export const runtime = "nodejs";
+ *   export const dynamic = "force-dynamic";
+ *   export const GET = createOnboardingRoute();
+ */
+export declare function createOnboardingRoute(options?: OnboardingOptions): () => Promise<Response>;
+/**
+ * Handler para o Pages Router (pages/api/onboarding.ts).
+ * Para servir em /onboarding, adicione no next.config:
+ *   async rewrites() { return [{ source: "/onboarding", destination: "/api/onboarding" }]; }
+ */
+export declare function createOnboardingApiHandler(options?: OnboardingOptions): (_req: unknown, res: {
+    status(code: number): {
+        send(body: string): void;
+    };
+    setHeader(name: string, value: string): void;
+}) => Promise<void>;

package/dist/adapters/next.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOnboardingRoute = createOnboardingRoute;
+exports.createOnboardingApiHandler = createOnboardingApiHandler;
+const index_1 = require("../index");
+const load_1 = require("../load");
+/**
+ * Route handler para o App Router do Next.js.
+ *
+ * app/onboarding/route.ts:
+ *   import { createOnboardingRoute } from "onboarding-kit/next";
+ *   export const runtime = "nodejs";
+ *   export const dynamic = "force-dynamic";
+ *   export const GET = createOnboardingRoute();
+ */
+function createOnboardingRoute(options = {}) {
+    return async function GET() {
+        if (!(0, load_1.resolveEnabled)(options)) {
+            return new Response("Not Found", { status: 404 });
+        }
+        const page = await (0, index_1.renderOnboardingPage)(options.file);
+        return new Response(page.html, { status: page.status, headers: index_1.HTML_HEADERS });
+    };
+}
+/**
+ * Handler para o Pages Router (pages/api/onboarding.ts).
+ * Para servir em /onboarding, adicione no next.config:
+ *   async rewrites() { return [{ source: "/onboarding", destination: "/api/onboarding" }]; }
+ */
+function createOnboardingApiHandler(options = {}) {
+    return async function handler(_req, res) {
+        if (!(0, load_1.resolveEnabled)(options)) {
+            res.status(404).send("Not Found");
+            return;
+        }
+        const page = await (0, index_1.renderOnboardingPage)(options.file);
+        for (const [name, value] of Object.entries(index_1.HTML_HEADERS))
+            res.setHeader(name, value);
+        res.status(page.status).send(page.html);
+    };
+}

package/dist/adapters/node.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OnboardingOptions } from "../types";
+export type { OnboardingOptions };
+/**
+ * Handler para Node.js puro, Express, Connect e similares.
+ *
+ * Express:  app.get("/onboarding", createOnboardingHandler());
+ * Node:     http.createServer((req, res) => req.url === "/onboarding" ? handler(req, res) : ...)
+ */
+export declare function createOnboardingHandler(options?: OnboardingOptions): (_req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => Promise<void>;

package/dist/adapters/node.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOnboardingHandler = createOnboardingHandler;
+const index_1 = require("../index");
+const load_1 = require("../load");
+/**
+ * Handler para Node.js puro, Express, Connect e similares.
+ *
+ * Express:  app.get("/onboarding", createOnboardingHandler());
+ * Node:     http.createServer((req, res) => req.url === "/onboarding" ? handler(req, res) : ...)
+ */
+function createOnboardingHandler(options = {}) {
+    return async function onboardingHandler(_req, res, next) {
+        if (!(0, load_1.resolveEnabled)(options)) {
+            if (next)
+                return next();
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Not Found");
+            return;
+        }
+        try {
+            const page = await (0, index_1.renderOnboardingPage)(options.file);
+            res.writeHead(page.status, index_1.HTML_HEADERS);
+            res.end(page.html);
+        }
+        catch (err) {
+            if (next)
+                return next(err);
+            res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Internal Server Error");
+        }
+    };
+}

package/dist/brand.d.ts

@@ -0,0 +1,38 @@
+import type { OnboardingData } from "./types";
+/** Cor em HSL: h 0–360, s e l 0–100. */
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+export interface ResolvedBrand {
+    /** Cores da marca, a principal primeiro. */
+    colors: Hsl[];
+    /** Logo e favicon como data URI, prontos para <img>/<link>. */
+    logo?: string;
+    favicon?: string;
+}
+/**
+ * Lê uma cor CSS: #hex, rgb(), hsl(), oklch(), o trio "222 47% 11%" do shadcn/ui
+ * ou um nome da paleta do Tailwind ("indigo", "indigo-600").
+ */
+export declare function parseColor(input: string): Hsl | undefined;
+export declare function toHex({ h, s, l }: Hsl): string;
+/** Cor sem matiz perceptível (preto, branco, cinzas). */
+export declare function isAchromatic(c: Hsl): boolean;
+/** Procura cores nomeadas como brand/primary/accent em CSS, SCSS, configs JS/TS e manifestos. */
+export declare function extractColors(source: string): {
+    role: string;
+    value: string;
+}[];
+export declare function detectColors(root: string): Hsl[];
+export declare function detectImage(root: string, kind: "logo" | "favicon"): string | undefined;
+/** Lê uma imagem do repositório como data URI, só se estiver dentro da raiz e for uma imagem pequena. */
+export declare function imageDataUri(root: string, path: string): string | undefined;
+/**
+ * Junta o que a IA preencheu em `brand` com o que dá para detectar no repositório.
+ * O JSON tem prioridade; a detecção cobre o que faltar. Sem `root`, usa só o JSON.
+ */
+export declare function resolveBrand(data: Partial<OnboardingData> | undefined, root?: string): ResolvedBrand;
+/** Nome do package.json da raiz, para identificar o projeto antes da IA preencher o onboarding. */
+export declare function packageName(root?: string): string | undefined;

package/dist/brand.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseColor = parseColor;
+exports.toHex = toHex;
+exports.isAchromatic = isAchromatic;
+exports.extractColors = extractColors;
+exports.detectColors = detectColors;
+exports.detectImage = detectImage;
+exports.imageDataUri = imageDataUri;
+exports.resolveBrand = resolveBrand;
+exports.packageName = packageName;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const load_1 = require("./load");
+/* ───────────────────────── cores ───────────────────────── */
+/** Tons 500 da paleta padrão do Tailwind, para configs como `primary: colors.indigo`. */
+const TAILWIND_500 = {
+    slate: "#64748b", gray: "#6b7280", zinc: "#71717a", neutral: "#737373", stone: "#78716c",
+    red: "#ef4444", orange: "#f97316", amber: "#f59e0b", yellow: "#eab308", lime: "#84cc16",
+    green: "#22c55e", emerald: "#10b981", teal: "#14b8a6", cyan: "#06b6d4", sky: "#0ea5e9",
+    blue: "#3b82f6", indigo: "#6366f1", violet: "#8b5cf6", purple: "#a855f7", fuchsia: "#d946ef",
+    pink: "#ec4899", rose: "#f43f5e",
+};
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+function num(value, scale = 1) {
+    return value.endsWith("%") ? (parseFloat(value) / 100) * scale : parseFloat(value);
+}
+function hslToRgb(h, s, l) {
+    s = clamp01(s / 100);
+    l = clamp01(l / 100);
+    const k = (n) => (n + h / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+    return [f(0) * 255, f(8) * 255, f(4) * 255];
+}
+function oklchToRgb(L, C, H) {
+    const a = C * Math.cos((H * Math.PI) / 180);
+    const b = C * Math.sin((H * Math.PI) / 180);
+    const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const linear = [
+        4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    ];
+    return linear.map((x) => {
+        const v = x <= 0.0031308 ? 12.92 * x : 1.055 * Math.abs(x) ** (1 / 2.4) - 0.055;
+        return clamp01(v) * 255;
+    });
+}
+function rgbToHsl([r, g, b]) {
+    r /= 255;
+    g /= 255;
+    b /= 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    const d = max - min;
+    if (d === 0)
+        return { h: 0, s: 0, l: l * 100 };
+    const s = d / (1 - Math.abs(2 * l - 1));
+    const h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    return { h: (h * 60 + 360) % 360, s: s * 100, l: l * 100 };
+}
+/**
+ * Lê uma cor CSS: #hex, rgb(), hsl(), oklch(), o trio "222 47% 11%" do shadcn/ui
+ * ou um nome da paleta do Tailwind ("indigo", "indigo-600").
+ */
+function parseColor(input) {
+    const value = input.trim().toLowerCase().replace(/\s*!important$/, "");
+    const hex = /^#([0-9a-f]{3,8})$/.exec(value);
+    if (hex) {
+        let digits = hex[1];
+        if (digits.length === 3 || digits.length === 4)
+            digits = [...digits.slice(0, 3)].map((d) => d + d).join("");
+        if (digits.length !== 6 && digits.length !== 8)
+            return undefined;
+        return rgbToHsl([0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16)));
+    }
+    const rgb = /^rgba?\(\s*([\d.]+%?)[\s,]+([\d.]+%?)[\s,]+([\d.]+%?)/.exec(value);
+    if (rgb)
+        return rgbToHsl([num(rgb[1], 255), num(rgb[2], 255), num(rgb[3], 255)]);
+    const hsl = /^(?:hsla?\(\s*)?([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/.exec(value);
+    if (hsl)
+        return rgbToHsl(hslToRgb(parseFloat(hsl[1]), parseFloat(hsl[2]), parseFloat(hsl[3])));
+    const oklch = /^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+)(?:deg)?/.exec(value);
+    if (oklch)
+        return rgbToHsl(oklchToRgb(num(oklch[1]), num(oklch[2], 0.4), parseFloat(oklch[3])));
+    const named = /^([a-z]+)(?:-\d{2,3})?$/.exec(value);
+    if (named && TAILWIND_500[named[1]])
+        return parseColor(TAILWIND_500[named[1]]);
+    return undefined;
+}
+function toHex({ h, s, l }) {
+    return `#${hslToRgb(h, s, l)
+        .map((c) => Math.round(c).toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+/** Cor sem matiz perceptível (preto, branco, cinzas). */
+function isAchromatic(c) {
+    return c.s < 12 || c.l < 6 || c.l > 96;
+}
+/** Remove cores praticamente iguais, mantendo a ordem. */
+function dedupe(colors) {
+    const out = [];
+    for (const c of colors) {
+        const same = out.some((o) => {
+            if (isAchromatic(o) && isAchromatic(c))
+                return true;
+            const dh = Math.min(Math.abs(o.h - c.h), 360 - Math.abs(o.h - c.h));
+            return dh < 14 && Math.abs(o.s - c.s) < 30;
+        });
+        if (!same)
+            out.push(c);
+    }
+    return out;
+}
+/* ───────────────────────── detecção ───────────────────────── */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".output", ".svelte-kit", "coverage", ".turbo", ".vercel", ".cache", "vendor"]);
+const STYLE_FILE = /(^tailwind\.config\.[cm]?[jt]s$)|(\.(css|scss|sass|less)$)|(^(theme|colors|tokens|palette|brand)\.[cm]?[jt]sx?$)|(^(manifest\.json|site\.webmanifest|manifest\.webmanifest)$)/i;
+const MAX_FILES = 40;
+const MAX_STYLE_BYTES = 300_000;
+/** Peso do nome da variável: quanto menor, mais "cara da marca". */
+const ROLE_WEIGHT = { brand: 0, primary: 1, theme_color: 1.5, themecolor: 1.5, accent: 2, secondary: 3 };
+function listStyleFiles(root) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > 4 || found.length >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found.length >= MAX_FILES)
+                return;
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith("."))
+                    walk((0, node_path_1.join)(dir, entry.name), depth + 1);
+            }
+            else if (STYLE_FILE.test(entry.name) && !entry.name.endsWith(".min.css")) {
+                found.push((0, node_path_1.join)(dir, entry.name));
+            }
+        }
+    };
+    walk(root, 0);
+    // configs do Tailwind e manifestos primeiro: são as fontes mais confiáveis
+    return found.sort((a, b) => Number(!/tailwind\.config|manifest/i.test(a)) - Number(!/tailwind\.config|manifest/i.test(b)));
+}
+/** Procura cores nomeadas como brand/primary/accent em CSS, SCSS, configs JS/TS e manifestos. */
+function extractColors(source) {
+    const found = [];
+    const add = (role, value, index) => found.push({ role: role.toLowerCase(), value: value.trim(), index });
+    const ROLE = "(brand|primary|accent|secondary)";
+    const SHADE = "(?:[-_](?:color|default|main|base|500|600))?";
+    // CSS: --primary, --color-brand-500 (Tailwind v4 @theme), --brand-color
+    for (const m of source.matchAll(new RegExp(`--(?:color-)?${ROLE}${SHADE}\\s*:\\s*([^;}{]+)`, "gi")))
+        add(m[1], m[2], m.index ?? 0);
+    // SCSS / LESS: $primary, @brand-color
+    for (const m of source.matchAll(new RegExp(`[$@]${ROLE}${SHADE}\\s*:\\s*([^;\\n]+)`, "gi")))
+        add(m[1], m[2], m.index ?? 0);
+    // JS/TS/JSON: primary: "#..." / "brand": "#..." / themeColor: "#..."
+    for (const m of source.matchAll(/["']?(brand|primary|accent|secondary|theme_color|themeColor)["']?\s*:\s*(["'`])([^"'`\n]+)\2/gi))
+        add(m[1], m[3], m.index ?? 0);
+    // JS/TS: primary: { DEFAULT: "#...", 500: "#..." } e MUI primary: { main: "#..." }
+    for (const m of source.matchAll(new RegExp(`["']?${ROLE}["']?\\s*:\\s*\\{([^{}]*)\\}`, "gi"))) {
+        const inner = /["']?(?:DEFAULT|main|500|600)["']?\s*:\s*(["'`])([^"'`\n]+)\1/i.exec(m[2]);
+        if (inner)
+            add(m[1], inner[2], m.index ?? 0);
+    }
+    // Tailwind: primary: colors.indigo
+    for (const m of source.matchAll(new RegExp(`["']?${ROLE}["']?\\s*:\\s*colors\\.(\\w+)`, "gi")))
+        add(m[1], m[2], m.index ?? 0);
+    return found.sort((a, b) => a.index - b.index).map(({ role, value }) => ({ role, value }));
+}
+function detectColors(root) {
+    const candidates = [];
+    let order = 0;
+    for (const file of listStyleFiles(root)) {
+        let source;
+        try {
+            if ((0, node_fs_1.statSync)(file).size > MAX_STYLE_BYTES)
+                continue;
+            source = (0, node_fs_1.readFileSync)(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const { role, value } of extractColors(source)) {
+            const color = parseColor(value);
+            if (!color || color.l > 96)
+                continue; // branco não serve como cor de destaque
+            const weight = (ROLE_WEIGHT[role] ?? 4) + (isAchromatic(color) ? 2.5 : 0);
+            candidates.push({ color, weight, order: order++ });
+        }
+    }
+    candidates.sort((a, b) => a.weight - b.weight || a.order - b.order);
+    return dedupe(candidates.map((c) => c.color)).slice(0, 5);
+}
+const IMAGE_TYPES = {
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+};
+const IMAGE_DIRS = ["public", "public/images", "public/img", "public/assets", "public/static", "static", "assets", "src/assets", "src/assets/images", "app", "src/app"];
+/** Arquivos que vêm nos templates do create-next-app, Vite etc. e não são a marca do projeto. */
+const BOILERPLATE = /^(next|vercel|vite|react|file|globe|window|nuxt|svelte|angular|placeholder)\.(svg|png)$/i;
+const MAX_IMAGE_BYTES = 400_000;
+function imageScore(name, kind) {
+    const base = name.toLowerCase();
+    if (BOILERPLATE.test(base))
+        return undefined;
+    const ext = (0, node_path_1.extname)(base);
+    if (!IMAGE_TYPES[ext])
+        return undefined;
+    const extRank = [".svg", ".png", ".webp", ".avif", ".ico", ".jpg", ".jpeg", ".gif"].indexOf(ext) / 10;
+    const variant = /(white|light|inverse|negative|mono)/.test(base) ? 0.5 : 0;
+    const rank = kind === "logo"
+        ? /logo/.test(base) ? 0 : /brand|wordmark/.test(base) ? 0.5 : /mark|symbol/.test(base) ? 1 : /^(icon|apple-icon|apple-touch-icon)/.test(base) ? 2 : /^favicon/.test(base) ? 3 : undefined
+        : /^favicon/.test(base) ? 0 : /^icon\./.test(base) ? 0.5 : /apple-(touch-)?icon/.test(base) ? 1 : /logo/.test(base) ? 2 : undefined;
+    return rank === undefined ? undefined : rank + variant + extRank;
+}
+function detectImage(root, kind) {
+    let best;
+    for (const dir of IMAGE_DIRS) {
+        let names;
+        try {
+            names = (0, node_fs_1.readdirSync)((0, node_path_1.join)(root, dir));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const score = imageScore(name, kind);
+            if (score === undefined || (best && best.score <= score))
+                continue;
+            const path = `${dir}/${name}`;
+            try {
+                if ((0, node_fs_1.statSync)((0, node_path_1.join)(root, path)).isFile())
+                    best = { path, score };
+            }
+            catch {
+                // ignora
+            }
+        }
+    }
+    return best?.path;
+}
+/** Lê uma imagem do repositório como data URI, só se estiver dentro da raiz e for uma imagem pequena. */
+function imageDataUri(root, path) {
+    const full = (0, node_path_1.resolve)(root, path);
+    const rel = (0, node_path_1.relative)(root, full);
+    if (!rel || rel.startsWith("..") || rel.split(node_path_1.sep).includes(".."))
+        return undefined;
+    const type = IMAGE_TYPES[(0, node_path_1.extname)(full).toLowerCase()];
+    if (!type || !(0, node_fs_1.existsSync)(full))
+        return undefined;
+    try {
+        if ((0, node_fs_1.statSync)(full).size > MAX_IMAGE_BYTES)
+            return undefined;
+        return `data:${type};base64,${(0, node_fs_1.readFileSync)(full).toString("base64")}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ───────────────────────── resolução ───────────────────────── */
+const cache = new Map();
+const CACHE_MS = 5_000;
+function detect(root) {
+    const hit = cache.get(root);
+    if (hit && Date.now() - hit.at < CACHE_MS)
+        return hit;
+    const value = { at: Date.now(), colors: detectColors(root), logo: detectImage(root, "logo"), favicon: detectImage(root, "favicon") };
+    cache.set(root, value);
+    return value;
+}
+/**
+ * Junta o que a IA preencheu em `brand` com o que dá para detectar no repositório.
+ * O JSON tem prioridade; a detecção cobre o que faltar. Sem `root`, usa só o JSON.
+ */
+function resolveBrand(data, root) {
+    const b = data?.brand;
+    const declared = dedupe([b?.primaryColor, ...(Array.isArray(b?.palette) ? b.palette : [])]
+        .filter((v) => typeof v === "string" && !(0, load_1.isBlank)(v))
+        .map(parseColor)
+        .filter((c) => !!c));
+    const found = root ? detect(root) : undefined;
+    const colors = declared.length ? dedupe([...declared, ...(declared.length < 2 ? found?.colors ?? [] : [])]).slice(0, 5) : found?.colors ?? [];
+    const image = (declaredPath, detected) => {
+        if (!root)
+            return undefined;
+        return (declaredPath && !(0, load_1.isBlank)(declaredPath) ? imageDataUri(root, declaredPath) : undefined) ?? (detected ? imageDataUri(root, detected) : undefined);
+    };
+    const logo = image(b?.logo, found?.logo);
+    const favicon = image(b?.favicon, found?.favicon) ?? logo;
+    return { colors, logo, favicon };
+}
+/** Nome do package.json da raiz, para identificar o projeto antes da IA preencher o onboarding. */
+function packageName(root) {
+    if (!root)
+        return undefined;
+    try {
+        const name = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(root, "package.json"), "utf8")).name;
+        return typeof name === "string" && name.trim() ? name.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import type { Framework } from "../types";
+export declare function detectFramework(pkg: Record<string, any> | undefined): Framework;
+/** Adiciona o OnboardingModule ao app.module.ts quando dá para fazer isso com segurança. */
+export declare function patchNestAppModule(source: string): string | undefined;