onboarding-kit 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Formato do arquivo onboarding.json.
+ * Chaves que começam com "_" (ex.: "_instructions") são para a IA e são ignoradas pelo visualizador.
+ */
+/** Referência a um trecho do código: "caminho/arquivo.ts" ou "caminho/arquivo.ts:42". */
+export type Evidence = string;
+export type Framework = "next" | "nest" | "node";
+export interface OnboardingMeta {
+    schemaVersion: string;
+    /** "pending" enquanto a IA não preencheu; "filled" depois. */
+    status: "pending" | "filled";
+    /** Idioma em que a IA deve escrever o conteúdo, ex.: "pt-BR". */
+    language: string;
+    framework: Framework | "";
+    generatedAt: string;
+    generatedBy: string;
+    /** Hash do commit (git rev-parse HEAD) analisado. */
+    commit: string;
+}
+export interface OnboardingProject {
+    name: string;
+    tagline: string;
+    purpose: string;
+    audience: string;
+    status: string;
+    repoUrl: string;
+}
+export interface GettingStarted {
+    prerequisites: string[];
+    setup: string[];
+    commands: {
+        name: string;
+        command: string;
+        description: string;
+    }[];
+    envVars: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}
+export interface StackItem {
+    name: string;
+    category: string;
+    version: string;
+    why: string;
+    evidence: Evidence[];
+}
+export interface ArchitectureModule {
+    name: string;
+    path: string;
+    responsibility: string;
+}
+export interface Architecture {
+    summary: string;
+    /** Diagrama em sintaxe Mermaid (sem as cercas ```). */
+    diagram: string;
+    modules: ArchitectureModule[];
+}
+export interface Convention {
+    title: string;
+    description: string;
+    example: string;
+    evidence: Evidence[];
+}
+export interface BusinessActor {
+    name: string;
+    description: string;
+    evidence: Evidence[];
+}
+export interface BusinessFlow {
+    name: string;
+    steps: string[];
+    evidence: Evidence[];
+}
+export interface Business {
+    /** Como o produto gera valor ou receita. */
+    model: string;
+    /** O valor entregue para quem usa. */
+    valueProposition: string;
+    actors: BusinessActor[];
+    flows: BusinessFlow[];
+}
+export interface GlossaryTerm {
+    term: string;
+    definition: string;
+}
+export interface BusinessRule {
+    title: string;
+    description: string;
+    evidence: Evidence[];
+}
+export interface Feature {
+    name: string;
+    description: string;
+    entryPoints: Evidence[];
+    status: string;
+}
+export interface TourStep {
+    file: Evidence;
+    explanation: string;
+}
+export interface Tour {
+    title: string;
+    description: string;
+    steps: TourStep[];
+}
+export interface Gotcha {
+    title: string;
+    description: string;
+    evidence: Evidence[];
+}
+export interface Decision {
+    title: string;
+    context: string;
+    decision: string;
+    evidence: Evidence[];
+}
+export interface FirstTask {
+    title: string;
+    description: string;
+    files: Evidence[];
+}
+export interface BrandInfo {
+    /** Cor principal da marca em hex (#RRGGBB). */
+    primaryColor: string;
+    /** Outras cores da paleta em hex. */
+    palette: string[];
+    /** Caminho relativo do logo (ex.: public/logo.svg). */
+    logo: string;
+    /** Caminho relativo do favicon (ex.: public/favicon.ico). */
+    favicon: string;
+    evidence: Evidence[];
+}
+export interface OnboardingData {
+    $schema?: string;
+    _instructions?: unknown;
+    meta: OnboardingMeta;
+    project: OnboardingProject;
+    /** Opcional em arquivos gerados antes da v0.2. */
+    business?: Business;
+    gettingStarted: GettingStarted;
+    stack: StackItem[];
+    architecture: Architecture;
+    conventions: Convention[];
+    domain: {
+        glossary: GlossaryTerm[];
+        businessRules: BusinessRule[];
+    };
+    features: Feature[];
+    tours: Tour[];
+    gotchas: Gotcha[];
+    decisions: Decision[];
+    firstTasks: FirstTask[];
+    /** Cores e logo do projeto, usados para dar a cara da marca à apresentação. Opcional. */
+    brand?: BrandInfo;
+}
+export interface OnboardingOptions {
+    /** Caminho do onboarding.json. Padrão: "<cwd>/onboarding.json". */
+    file?: string;
+    /** Liga ou desliga a rota. Padrão: ligada fora de produção (NODE_ENV !== "production"). */
+    enabled?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Formato do arquivo onboarding.json.
+ * Chaves que começam com "_" (ex.: "_instructions") são para a IA e são ignoradas pelo visualizador.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+export interface Issue {
+    level: "error" | "warning";
+    path: string;
+    message: string;
+}
+export interface ValidateOptions {
+    /** Raiz do repositório, usada para conferir as evidências. */
+    root: string;
+    /** Commit atual (git rev-parse HEAD), para avisar quando o JSON está desatualizado. */
+    headCommit?: string;
+}
+/** Separa "src/a.ts:10" ou "src/a.ts:10-20" em caminho e linha. */
+export declare function parseEvidence(ref: string): {
+    file: string;
+    line?: number;
+};
+export declare function validateOnboarding(data: unknown, options: ValidateOptions): Issue[];

package/dist/validate.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEvidence = parseEvidence;
+exports.validateOnboarding = validateOnboarding;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const brand_1 = require("./brand");
+const load_1 = require("./load");
+/** Campo que identifica cada item e precisa estar preenchido. */
+const ARRAY_SECTIONS = [
+    { path: "business.actors", key: "name", evidence: "warning", optional: true },
+    { path: "business.flows", key: "name", evidence: "warning", optional: true },
+    { path: "stack", key: "name", evidence: "warning", min: 1 },
+    { path: "architecture.modules", key: "path" },
+    { path: "conventions", key: "title", evidence: "error" },
+    { path: "domain.glossary", key: "term" },
+    { path: "domain.businessRules", key: "title", evidence: "error" },
+    { path: "features", key: "name", min: 1 },
+    { path: "tours", key: "title" },
+    { path: "gotchas", key: "title", evidence: "error" },
+    { path: "decisions", key: "title", evidence: "warning" },
+    { path: "firstTasks", key: "title" },
+    { path: "gettingStarted.commands", key: "command" },
+    { path: "gettingStarted.envVars", key: "name" },
+];
+const EVIDENCE_KEYS = new Set(["evidence", "entryPoints", "files"]);
+const SECRET_PATTERNS = [
+    { name: "chave AWS", re: /\bAKIA[0-9A-Z]{16}\b/, level: "error" },
+    { name: "chave de API (sk-...)", re: /\bsk-[A-Za-z0-9_-]{20,}/, level: "error" },
+    { name: "token do GitHub", re: /\bgh[pousr]_[A-Za-z0-9]{30,}/, level: "error" },
+    { name: "token do Slack", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/, level: "error" },
+    { name: "chave do Google", re: /\bAIza[0-9A-Za-z_-]{35}\b/, level: "error" },
+    { name: "chave privada", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, level: "error" },
+    { name: "JWT", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, level: "error" },
+    { name: "URL com usuário e senha", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/"]+:[^\s@/"]+@/i, level: "warning" },
+];
+function get(obj, path) {
+    return path.split(".").reduce((acc, key) => (acc && typeof acc === "object" ? acc[key] : undefined), obj);
+}
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Separa "src/a.ts:10" ou "src/a.ts:10-20" em caminho e linha. */
+function parseEvidence(ref) {
+    const match = /^(.*?)(?::(\d+)(?:-\d+)?)?$/.exec(ref.trim());
+    const file = (match?.[1] ?? ref).trim();
+    const line = match?.[2] ? Number(match[2]) : undefined;
+    return { file, line };
+}
+function checkEvidence(ref, at, root, issues) {
+    if (typeof ref !== "string" || ref.trim() === "")
+        return;
+    const { file, line } = parseEvidence(ref);
+    if ((0, node_path_1.isAbsolute)(file)) {
+        issues.push({ level: "error", path: at, message: `use caminho relativo à raiz, não absoluto: "${ref}"` });
+        return;
+    }
+    const full = (0, node_path_1.resolve)(root, file);
+    const rel = (0, node_path_1.relative)(root, full);
+    if (rel.startsWith("..") || rel.split(node_path_1.sep).includes("..")) {
+        issues.push({ level: "error", path: at, message: `caminho fora do repositório: "${ref}"` });
+        return;
+    }
+    if (!(0, node_fs_1.existsSync)(full)) {
+        issues.push({ level: "error", path: at, message: `arquivo não existe: "${file}"` });
+        return;
+    }
+    if (line !== undefined && (0, node_fs_1.statSync)(full).isFile()) {
+        const total = (0, node_fs_1.readFileSync)(full, "utf8").split("\n").length;
+        if (line < 1 || line > total) {
+            issues.push({ level: "warning", path: at, message: `linha ${line} não existe em "${file}" (${total} linhas)` });
+        }
+    }
+}
+function walkEvidence(value, at, root, issues) {
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => walkEvidence(v, `${at}[${i}]`, root, issues));
+        return;
+    }
+    if (!isObj(value))
+        return;
+    for (const [key, v] of Object.entries(value)) {
+        if (key.startsWith("_") || key === "meta")
+            continue;
+        const here = at ? `${at}.${key}` : key;
+        if (EVIDENCE_KEYS.has(key) && Array.isArray(v)) {
+            v.forEach((ref, i) => checkEvidence(ref, `${here}[${i}]`, root, issues));
+        }
+        else if ((key === "file" || key === "logo" || key === "favicon") && typeof v === "string") {
+            checkEvidence(v, here, root, issues);
+        }
+        else {
+            walkEvidence(v, here, root, issues);
+        }
+    }
+}
+function validateOnboarding(data, options) {
+    const issues = [];
+    const err = (path, message) => issues.push({ level: "error", path, message });
+    const warn = (path, message) => issues.push({ level: "warning", path, message });
+    if (!isObj(data)) {
+        err("", "o arquivo precisa ser um objeto JSON");
+        return issues;
+    }
+    // meta
+    const meta = data.meta;
+    if (!isObj(meta)) {
+        err("meta", "seção ausente");
+    }
+    else {
+        if (meta.status !== "filled")
+            err("meta.status", 'ainda não foi preenchido pela IA (esperado "filled")');
+        if ((0, load_1.isBlank)(meta.generatedAt))
+            warn("meta.generatedAt", "vazio");
+        if ((0, load_1.isBlank)(meta.generatedBy))
+            warn("meta.generatedBy", "vazio");
+        if (options.headCommit) {
+            if ((0, load_1.isBlank)(meta.commit)) {
+                warn("meta.commit", "vazio: preencha com `git rev-parse HEAD`");
+            }
+            else if (!options.headCommit.startsWith(String(meta.commit)) && !String(meta.commit).startsWith(options.headCommit)) {
+                warn("meta.commit", `gerado no commit ${String(meta.commit).slice(0, 7)}, mas o HEAD é ${options.headCommit.slice(0, 7)}: peça à IA para atualizar`);
+            }
+        }
+    }
+    // project
+    const project = data.project;
+    if (!isObj(project)) {
+        err("project", "seção ausente");
+    }
+    else {
+        for (const key of ["name", "purpose"]) {
+            if ((0, load_1.isBlank)(project[key]))
+                err(`project.${key}`, "obrigatório");
+        }
+        for (const key of ["tagline", "audience"]) {
+            if ((0, load_1.isBlank)(project[key]))
+                warn(`project.${key}`, "vazio");
+        }
+    }
+    // architecture
+    const architecture = data.architecture;
+    if (!isObj(architecture)) {
+        err("architecture", "seção ausente");
+    }
+    else {
+        if ((0, load_1.isBlank)(architecture.summary))
+            warn("architecture.summary", "vazio");
+        if (typeof architecture.diagram === "string" && architecture.diagram.trim().startsWith("```")) {
+            err("architecture.diagram", "remova as cercas ``` e deixe só o código Mermaid");
+        }
+    }
+    const business = data.business;
+    if (business === undefined) {
+        warn("business", "seção ausente: rode `npx onboarding-kit init --force` num arquivo novo ou peça à IA para adicionar o modelo de negócio");
+    }
+    else if (!isObj(business)) {
+        err("business", "precisa ser um objeto");
+    }
+    else {
+        if ((0, load_1.isBlank)(business.model))
+            warn("business.model", "vazio");
+        if ((0, load_1.isBlank)(business.valueProposition))
+            warn("business.valueProposition", "vazio");
+        if (Array.isArray(business.flows)) {
+            business.flows.forEach((flow, i) => {
+                if (isObj(flow) && !(0, load_1.isBlank)(flow) && Array.isArray(flow.steps) && flow.steps.some(load_1.isBlank)) {
+                    err(`business.flows[${i}].steps`, "tem passos em branco");
+                }
+            });
+        }
+    }
+    const brand = data.brand;
+    if (brand !== undefined && !isObj(brand)) {
+        err("brand", "precisa ser um objeto");
+    }
+    else if (isObj(brand)) {
+        const colors = [["brand.primaryColor", brand.primaryColor], ...(Array.isArray(brand.palette) ? brand.palette.map((c, i) => [`brand.palette[${i}]`, c]) : [])];
+        for (const [path, value] of colors) {
+            if (typeof value === "string" && !(0, load_1.isBlank)(value) && !(0, brand_1.parseColor)(value))
+                warn(String(path), `cor não reconhecida: "${value}" (use hex, ex.: #4f46e5)`);
+        }
+    }
+    if (!isObj(data.gettingStarted))
+        err("gettingStarted", "seção ausente");
+    if (!isObj(data.domain))
+        err("domain", "seção ausente");
+    // listas
+    for (const section of ARRAY_SECTIONS) {
+        const list = get(data, section.path);
+        if (list === undefined) {
+            if (!section.optional)
+                err(section.path, "seção ausente");
+            continue;
+        }
+        if (!Array.isArray(list)) {
+            err(section.path, "precisa ser uma lista");
+            continue;
+        }
+        let real = 0;
+        list.forEach((item, i) => {
+            const at = `${section.path}[${i}]`;
+            if ((0, load_1.isBlank)(item)) {
+                err(at, "item modelo em branco: substitua por um item real ou remova");
+                return;
+            }
+            real++;
+            if (!isObj(item))
+                return;
+            if ((0, load_1.isBlank)(item[section.key]))
+                err(`${at}.${section.key}`, "obrigatório");
+            if (section.evidence && Array.isArray(item.evidence) && item.evidence.every(load_1.isBlank)) {
+                issues.push({ level: section.evidence, path: `${at}.evidence`, message: "sem evidência no código" });
+            }
+        });
+        if (section.min && real < section.min)
+            err(section.path, `precisa de pelo menos ${section.min} item`);
+    }
+    for (const key of ["prerequisites", "setup"]) {
+        const list = get(data, `gettingStarted.${key}`);
+        if (Array.isArray(list) && list.length > 0 && list.every(load_1.isBlank)) {
+            err(`gettingStarted.${key}`, "só tem itens em branco: preencha ou deixe a lista vazia");
+        }
+    }
+    walkEvidence(data, "", options.root, issues);
+    // segredos (ignora as instruções)
+    const { _instructions, ...content } = data;
+    void _instructions;
+    const text = JSON.stringify(content);
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.re.test(text)) {
+            issues.push({ level: pattern.level, path: "(arquivo)", message: `possível segredo encontrado: ${pattern.name}. Remova antes de commitar.` });
+        }
+    }
+    return issues;
+}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "onboarding-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Onboarding de projetos gerado pela sua IA local: um JSON descreve o projeto e o onboarding-kit o apresenta em /onboarding.",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "onboarding-kit": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/adapters/node.d.ts",
+      "default": "./dist/adapters/node.js"
+    },
+    "./next": {
+      "types": "./dist/adapters/next.d.ts",
+      "default": "./dist/adapters/next.js"
+    },
+    "./nest": {
+      "types": "./dist/adapters/nest.d.ts",
+      "default": "./dist/adapters/nest.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "node": [
+        "./dist/adapters/node.d.ts"
+      ],
+      "next": [
+        "./dist/adapters/next.d.ts"
+      ],
+      "nest": [
+        "./dist/adapters/nest.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "onboarding",
+    "documentation",
+    "ai",
+    "nextjs",
+    "nestjs",
+    "developer-experience"
+  ],
+  "peerDependencies": {
+    "@nestjs/common": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.6.0"
+  }
+}