onboarding-kit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,90 @@
-# 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`.
+
+## 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.
+
+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.
+
+## 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` e `firstTasks`.
+
+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/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;

package/dist/cli/index.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFramework = detectFramework;
+exports.patchNestAppModule = patchNestAppModule;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_http_1 = require("node:http");
+const node_path_1 = require("node:path");
+const node_1 = require("../adapters/node");
+const load_1 = require("../load");
+const template_1 = require("../template");
+const validate_1 = require("../validate");
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (open, close) => (s) => (useColor ? `\x1b[${open}m${s}\x1b[${close}m` : s);
+const c = {
+    bold: paint(1, 22),
+    dim: paint(2, 22),
+    green: paint(32, 39),
+    yellow: paint(33, 39),
+    red: paint(31, 39),
+    cyan: paint(36, 39),
+};
+const HELP = `
+${c.bold("onboarding-kit")} — onboarding do projeto gerado pela sua IA local
+
+${c.bold("Uso")}
+  npx onboarding-kit init       Cria o onboarding.json em branco e a rota /onboarding
+  npx onboarding-kit prompt     Mostra o texto para enviar à sua IA
+  npx onboarding-kit validate   Confere o JSON preenchido (campos, evidências, segredos)
+  npx onboarding-kit serve      Abre a apresentação em http://localhost:4321
+
+${c.bold("Opções")}
+  --file <caminho>           Arquivo de onboarding (padrão: onboarding.json)
+  --framework <next|nest|node>  Força o framework em vez de detectar (init)
+  --lang <idioma>            Idioma do conteúdo gerado (init, padrão: pt-BR)
+  --no-route                 Não cria/edita a rota no projeto (init)
+  --force                    Sobrescreve o onboarding.json existente (init)
+  --port <porta>             Porta do serve (padrão: 4321)
+`;
+function parseArgs(argv) {
+    const flags = {};
+    let command;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const [key, inline] = arg.slice(2).split("=", 2);
+            if (inline !== undefined)
+                flags[key] = inline;
+            else if (argv[i + 1] && !argv[i + 1].startsWith("--"))
+                flags[key] = argv[++i];
+            else
+                flags[key] = true;
+        }
+        else if (arg === "-h") {
+            flags.help = true;
+        }
+        else if (!command) {
+            command = arg;
+        }
+    }
+    return { command, flags };
+}
+function readPackageJson(root) {
+    const path = (0, node_path_1.join)(root, "package.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return undefined;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function detectFramework(pkg) {
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    if (deps.next)
+        return "next";
+    if (deps["@nestjs/core"])
+        return "nest";
+    return "node";
+}
+function gitHead(cwd) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+const NEXT_ROUTE = `import { createOnboardingRoute } from "onboarding-kit/next";
+
+// Criado pelo onboarding-kit. Mostra a apresentação do projeto em /onboarding.
+// Fica desligada em produção; para ligar: createOnboardingRoute({ enabled: true }).
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const GET = createOnboardingRoute();
+`;
+const NEXT_PAGES_SNIPPET = `// pages/api/onboarding.ts
+import { createOnboardingApiHandler } from "onboarding-kit/next";
+export default createOnboardingApiHandler();
+
+// next.config: para servir em /onboarding
+async rewrites() { return [{ source: "/onboarding", destination: "/api/onboarding" }]; }`;
+const NEST_SNIPPET = `// src/app.module.ts
+import { OnboardingModule } from "onboarding-kit/nest";
+
+@Module({
+  imports: [OnboardingModule.register(), /* ...seus módulos */],
+})`;
+const NODE_SNIPPET = `// Express
+import { createOnboardingHandler } from "onboarding-kit/node";
+app.get("/onboarding", createOnboardingHandler());
+
+// http nativo
+const onboarding = createOnboardingHandler();
+if (req.url === "/onboarding") return onboarding(req, res);`;
+function setupNext(root) {
+    const appDir = ["src/app", "app"].find((dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, dir)));
+    if (!appDir) {
+        return [`${c.yellow("!")} Não encontrei a pasta app/ (App Router). Para o Pages Router, adicione:`, "", c.dim(NEXT_PAGES_SNIPPET)];
+    }
+    const ext = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "tsconfig.json")) ? "ts" : "js";
+    const routeFile = (0, node_path_1.join)(root, appDir, "onboarding", `route.${ext}`);
+    const rel = (0, node_path_1.relative)(root, routeFile);
+    if ((0, node_fs_1.existsSync)(routeFile))
+        return [`${c.dim("•")} ${rel} já existe, mantive como está`];
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(routeFile), { recursive: true });
+    (0, node_fs_1.writeFileSync)(routeFile, NEXT_ROUTE);
+    return [`${c.green("✓")} Criei ${c.bold(rel)} (rota /onboarding)`];
+}
+/** Adiciona o OnboardingModule ao app.module.ts quando dá para fazer isso com segurança. */
+function patchNestAppModule(source) {
+    if (source.includes("OnboardingModule"))
+        return source;
+    const matches = source.match(/imports\s*:\s*\[/g);
+    if (!matches || matches.length !== 1)
+        return undefined;
+    const withImport = source.replace(/imports\s*:\s*\[(\s*\])?/, (m, empty) => empty ? m.replace(/\[\s*\]$/, "[OnboardingModule.register()]") : `${m}OnboardingModule.register(), `);
+    return `import { OnboardingModule } from "onboarding-kit/nest";\n${withImport}`;
+}
+function setupNest(root) {
+    const file = (0, node_path_1.join)(root, "src", "app.module.ts");
+    if ((0, node_fs_1.existsSync)(file)) {
+        const source = (0, node_fs_1.readFileSync)(file, "utf8");
+        const patched = patchNestAppModule(source);
+        if (patched === source)
+            return [`${c.dim("•")} src/app.module.ts já importa o OnboardingModule`];
+        if (patched) {
+            (0, node_fs_1.writeFileSync)(file, patched);
+            return [`${c.green("✓")} Adicionei ${c.bold("OnboardingModule.register()")} em src/app.module.ts (rota /onboarding)`];
+        }
+    }
+    return [`${c.yellow("!")} Não consegui editar o app.module.ts sozinho. Adicione:`, "", c.dim(NEST_SNIPPET)];
+}
+function cmdInit(flags) {
+    const root = process.cwd();
+    const pkg = readPackageJson(root);
+    if (!pkg) {
+        console.error(c.red("✗ Não encontrei package.json. Rode o comando na raiz do projeto."));
+        return 1;
+    }
+    const forced = typeof flags.framework === "string" ? flags.framework : undefined;
+    if (forced && !["next", "nest", "node"].includes(forced)) {
+        console.error(c.red(`✗ Framework inválido: ${forced}. Use next, nest ou node.`));
+        return 1;
+    }
+    const framework = forced ?? detectFramework(pkg);
+    const language = typeof flags.lang === "string" ? flags.lang : "pt-BR";
+    const file = (0, load_1.resolveFile)(typeof flags.file === "string" ? flags.file : undefined);
+    const relFile = (0, node_path_1.relative)(root, file);
+    const lines = [`Framework: ${c.bold(framework)}${forced ? "" : c.dim(" (detectado)")}`];
+    if ((0, node_fs_1.existsSync)(file) && !flags.force) {
+        lines.push(`${c.dim("•")} ${relFile} já existe, mantive como está ${c.dim("(use --force para recriar)")}`);
+    }
+    else {
+        (0, node_fs_1.writeFileSync)(file, JSON.stringify((0, template_1.createTemplate)({ framework, language }), null, 2) + "\n");
+        lines.push(`${c.green("✓")} Criei ${c.bold(relFile)} com os campos em branco e as instruções para a IA`);
+    }
+    if (flags.route !== false && !flags["no-route"]) {
+        if (framework === "next")
+            lines.push(...setupNext(root));
+        else if (framework === "nest")
+            lines.push(...setupNest(root));
+        else
+            lines.push(`${c.dim("•")} Para servir em /onboarding no seu servidor:`, "", c.dim(NODE_SNIPPET));
+    }
+    const prompt = (0, template_1.aiPrompt)(relFile);
+    console.log(`
+${lines.join("\n")}
+
+${c.bold("Próximo passo:")} envie para a IA que você usa neste projeto (Claude Code, Cursor, Copilot…):
+
+  ${c.cyan(prompt)}
+
+Depois rode ${c.bold("npx onboarding-kit validate")} e acesse ${c.bold("/onboarding")} no app em dev (ou ${c.bold("npx onboarding-kit serve")}).
+`);
+    return 0;
+}
+async function cmdValidate(flags) {
+    const result = await (0, load_1.loadOnboarding)(typeof flags.file === "string" ? flags.file : undefined);
+    if (!result.ok) {
+        console.error(c.red(`✗ ${result.message}`));
+        if (result.reason === "missing")
+            console.error(`  Rode ${c.bold("npx onboarding-kit init")} primeiro.`);
+        return 1;
+    }
+    const root = (0, node_path_1.dirname)(result.file);
+    const issues = (0, validate_1.validateOnboarding)(result.data, { root, headCommit: gitHead(root) });
+    const errors = issues.filter((i) => i.level === "error");
+    const warnings = issues.filter((i) => i.level === "warning");
+    for (const issue of [...errors, ...warnings]) {
+        const mark = issue.level === "error" ? c.red("✗") : c.yellow("!");
+        console.log(`${mark} ${c.bold(issue.path || "(raiz)")} ${issue.message}`);
+    }
+    if (errors.length) {
+        console.log(`\n${c.red(`${errors.length} erro(s)`)}, ${warnings.length} aviso(s). Peça à IA para corrigir e rode de novo.`);
+        return 1;
+    }
+    console.log(`${issues.length ? "\n" : ""}${c.green("✓")} ${(0, node_path_1.relative)(process.cwd(), result.file)} válido${warnings.length ? ` com ${warnings.length} aviso(s)` : ""}.`);
+    return 0;
+}
+function cmdServe(flags) {
+    const port = Number(flags.port ?? 4321);
+    const handler = (0, node_1.createOnboardingHandler)({ file: typeof flags.file === "string" ? flags.file : undefined, enabled: true });
+    const server = (0, node_http_1.createServer)((req, res) => {
+        const path = (req.url ?? "/").split("?")[0];
+        if (path === "/" || path === "/onboarding")
+            return void handler(req, res);
+        res.writeHead(302, { Location: "/" });
+        res.end();
+    });
+    return new Promise((resolvePromise) => {
+        server.on("error", (err) => {
+            console.error(c.red(`✗ ${err.code === "EADDRINUSE" ? `A porta ${port} está em uso. Use --port.` : err.message}`));
+            resolvePromise(1);
+        });
+        server.listen(port, "127.0.0.1", () => {
+            console.log(`${c.green("✓")} Onboarding em ${c.bold(`http://localhost:${port}`)} ${c.dim("(Ctrl+C para sair)")}`);
+        });
+    });
+}
+async function main() {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    if (flags["no-route"])
+        flags.route = false;
+    if (!command || flags.help || command === "help") {
+        console.log(HELP);
+        return 0;
+    }
+    switch (command) {
+        case "init":
+            return cmdInit(flags);
+        case "validate":
+            return cmdValidate(flags);
+        case "serve":
+            return cmdServe(flags);
+        case "prompt":
+            console.log((0, template_1.aiPrompt)(typeof flags.file === "string" ? flags.file : load_1.DEFAULT_FILE));
+            return 0;
+        default:
+            console.error(c.red(`✗ Comando desconhecido: ${command}`));
+            console.log(HELP);
+            return 1;
+    }
+}
+if (require.main === module) {
+    main().then((code) => {
+        if (code !== 0)
+            process.exitCode = code;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./types";
+export { createTemplate, aiPrompt, SCHEMA_VERSION } from "./template";
+export { loadOnboarding, resolveEnabled, resolveFile, isBlank, DEFAULT_FILE } from "./load";
+export { validateOnboarding, parseEvidence } from "./validate";
+export type { Issue, ValidateOptions } from "./validate";
+export { renderOnboarding, escapeHtml } from "./render";
+export interface RenderedPage {
+    status: number;
+    html: string;
+}
+/** Lê o onboarding.json a cada chamada e devolve a página pronta (usado pelos adapters). */
+export declare function renderOnboardingPage(file?: string): Promise<RenderedPage>;
+export declare const HTML_HEADERS: {
+    readonly "Content-Type": "text/html; charset=utf-8";
+    readonly "Cache-Control": "no-store";
+    readonly "X-Robots-Tag": "noindex";
+};

package/dist/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTML_HEADERS = exports.escapeHtml = exports.renderOnboarding = exports.parseEvidence = exports.validateOnboarding = exports.DEFAULT_FILE = exports.isBlank = exports.resolveFile = exports.resolveEnabled = exports.loadOnboarding = exports.SCHEMA_VERSION = exports.aiPrompt = exports.createTemplate = void 0;
+exports.renderOnboardingPage = renderOnboardingPage;
+const load_1 = require("./load");
+const render_1 = require("./render");
+__exportStar(require("./types"), exports);
+var template_1 = require("./template");
+Object.defineProperty(exports, "createTemplate", { enumerable: true, get: function () { return template_1.createTemplate; } });
+Object.defineProperty(exports, "aiPrompt", { enumerable: true, get: function () { return template_1.aiPrompt; } });
+Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return template_1.SCHEMA_VERSION; } });
+var load_2 = require("./load");
+Object.defineProperty(exports, "loadOnboarding", { enumerable: true, get: function () { return load_2.loadOnboarding; } });
+Object.defineProperty(exports, "resolveEnabled", { enumerable: true, get: function () { return load_2.resolveEnabled; } });
+Object.defineProperty(exports, "resolveFile", { enumerable: true, get: function () { return load_2.resolveFile; } });
+Object.defineProperty(exports, "isBlank", { enumerable: true, get: function () { return load_2.isBlank; } });
+Object.defineProperty(exports, "DEFAULT_FILE", { enumerable: true, get: function () { return load_2.DEFAULT_FILE; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateOnboarding", { enumerable: true, get: function () { return validate_1.validateOnboarding; } });
+Object.defineProperty(exports, "parseEvidence", { enumerable: true, get: function () { return validate_1.parseEvidence; } });
+var render_2 = require("./render");
+Object.defineProperty(exports, "renderOnboarding", { enumerable: true, get: function () { return render_2.renderOnboarding; } });
+Object.defineProperty(exports, "escapeHtml", { enumerable: true, get: function () { return render_2.escapeHtml; } });
+/** Lê o onboarding.json a cada chamada e devolve a página pronta (usado pelos adapters). */
+async function renderOnboardingPage(file) {
+    const result = await (0, load_1.loadOnboarding)(file);
+    if (!result.ok) {
+        return result.reason === "missing"
+            ? { status: 200, html: (0, render_1.renderMissingPage)() }
+            : { status: 500, html: (0, render_1.renderErrorPage)(result.message) };
+    }
+    try {
+        return { status: 200, html: (0, render_1.renderOnboarding)(result.data) };
+    }
+    catch (err) {
+        return { status: 500, html: (0, render_1.renderErrorPage)(err.message) };
+    }
+}
+exports.HTML_HEADERS = {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+    "X-Robots-Tag": "noindex",
+};

package/dist/load.d.ts

@@ -0,0 +1,19 @@
+import type { OnboardingData, OnboardingOptions } from "./types";
+export declare const DEFAULT_FILE = "onboarding.json";
+export declare function resolveFile(file?: string): string;
+export declare function resolveEnabled(options?: OnboardingOptions): boolean;
+export type LoadResult = {
+    ok: true;
+    file: string;
+    data: OnboardingData;
+} | {
+    ok: false;
+    file: string;
+    reason: "missing" | "invalid-json";
+    message: string;
+};
+export declare function loadOnboarding(file?: string): Promise<LoadResult>;
+/** true quando o valor não tem nenhum texto preenchido (strings vazias, arrays/objetos vazios). */
+export declare function isBlank(value: unknown): boolean;
+/** Remove itens-modelo em branco de um array. */
+export declare function filled<T>(items: T[] | undefined | null): T[];