onboarding-kit 0.0.0-stage → 0.1.0

package/dist/render/copy.d.ts

@@ -0,0 +1,132 @@
+export type ChapterId = "welcome" | "why" | "business" | "product" | "language" | "rules" | "stack" | "architecture" | "setup" | "conventions" | "tours" | "gotchas" | "decisions" | "mission" | "finale";
+/** Matiz (HSL) de cada capítulo: cada etapa do tour tem a sua cor. */
+export declare const CHAPTER_HUES: Record<ChapterId, number>;
+declare const pt: {
+    chapters: Record<ChapterId, string>;
+    welcome: {
+        hi: string;
+        title: (name: string) => string;
+        intro: (min: number) => string;
+        start: string;
+        journey: string;
+    };
+    why: {
+        title: string;
+        lede: string;
+        audience: string;
+        status: string;
+    };
+    business: {
+        title: string;
+        lede: string;
+        model: string;
+        value: string;
+        actorsTitle: string;
+        actorsLede: string;
+        flowsTitle: string;
+        flowsLede: string;
+    };
+    product: {
+        title: string;
+        lede: string;
+    };
+    language: {
+        title: string;
+        lede: string;
+        tap: string;
+        quizTitle: string;
+        quizLede: string;
+        question: (term: string) => string;
+        right: string;
+        wrong: string;
+        score: string;
+    };
+    rules: {
+        title: string;
+        lede: string;
+        rule: string;
+    };
+    stack: {
+        title: string;
+        lede: string;
+    };
+    architecture: {
+        title: string;
+        modulesTitle: string;
+        modulesLede: string;
+    };
+    setup: {
+        title: string;
+        lede: string;
+        prereq: string;
+        commandsTitle: string;
+        commandsLede: string;
+        envTitle: string;
+        envLede: string;
+        required: string;
+        optional: string;
+        copy: string;
+        copied: string;
+    };
+    conventions: {
+        title: string;
+        lede: string;
+    };
+    tours: {
+        kicker: string;
+        intro: string;
+        stops: string;
+        stop: (i: number, total: number) => string;
+    };
+    gotchas: {
+        title: string;
+        lede: string;
+    };
+    decisions: {
+        title: string;
+        lede: string;
+        context: string;
+        decision: string;
+    };
+    mission: {
+        title: string;
+        lede: string;
+    };
+    finale: {
+        title: string;
+        lede: string;
+        recap: string;
+        tasks: string;
+        restart: string;
+        index: string;
+    };
+    ui: {
+        prev: string;
+        next: string;
+        overview: string;
+        theme: string;
+        keys: string;
+        resume: string;
+        resumeYes: string;
+        resumeNo: string;
+        close: string;
+        chapters: string;
+        generated: string;
+        by: string;
+        minutes: string;
+    };
+    pending: {
+        title: string;
+        body: string;
+    };
+    missing: {
+        title: string;
+        body: string;
+    };
+    invalid: {
+        title: string;
+    };
+};
+export type Copy = typeof pt;
+export declare function copyFor(language?: string): Copy;
+export {};

package/dist/render/copy.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAPTER_HUES = void 0;
+exports.copyFor = copyFor;
+/** Matiz (HSL) de cada capítulo: cada etapa do tour tem a sua cor. */
+exports.CHAPTER_HUES = {
+    welcome: 255,
+    why: 275,
+    business: 158,
+    product: 330,
+    language: 192,
+    rules: 28,
+    stack: 220,
+    architecture: 285,
+    setup: 145,
+    conventions: 42,
+    tours: 205,
+    gotchas: 12,
+    decisions: 305,
+    mission: 165,
+    finale: 255,
+};
+const pt = {
+    chapters: {
+        welcome: "Boas-vindas",
+        why: "O porquê",
+        business: "O negócio",
+        product: "O produto",
+        language: "Vocabulário",
+        rules: "Regras do jogo",
+        stack: "A stack",
+        architecture: "Arquitetura",
+        setup: "Mãos à obra",
+        conventions: "Jeito da casa",
+        tours: "Tour pelo código",
+        gotchas: "Cuidados",
+        decisions: "Decisões",
+        mission: "Primeira missão",
+        finale: "Pronto!",
+    },
+    welcome: {
+        hi: "Oi! Que bom ter você por aqui.",
+        title: (name) => `Bem-vindo ao ${name}`,
+        intro: (min) => `Este é um tour de uns ${min} minutos com tudo o que vale saber antes de abrir o seu primeiro PR: por que o projeto existe, como o negócio funciona, como o código se organiza e onde pisar com cuidado.`,
+        start: "Começar o tour",
+        journey: "O caminho até lá",
+    },
+    why: {
+        title: "Primeiro, o porquê",
+        lede: "Antes de qualquer linha de código: o problema que a gente resolve.",
+        audience: "Quem usa",
+        status: "Em que pé estamos",
+    },
+    business: {
+        title: "Como o negócio funciona",
+        lede: "Entender o negócio é o que transforma código que funciona em código que faz sentido.",
+        model: "O modelo",
+        value: "O valor que entregamos",
+        actorsTitle: "Quem faz parte dessa história",
+        actorsLede: "Os perfis que aparecem no produto e no código.",
+        flowsTitle: "As jornadas principais",
+        flowsLede: "O caminho que as pessoas percorrem dentro do produto.",
+    },
+    product: {
+        title: "O que o produto faz",
+        lede: "As funcionalidades que você vai encontrar (e mexer) por aqui.",
+    },
+    language: {
+        title: "Fale a língua da casa",
+        lede: "Termos que aparecem nas conversas, nas telas e no código. Toque num cartão para ver o significado.",
+        tap: "toque para virar",
+        quizTitle: "Pausa rápida: valendo nada!",
+        quizLede: "Umas perguntinhas para fixar o vocabulário.",
+        question: (term) => `O que significa “${term}”?`,
+        right: "Isso aí! 🎯",
+        wrong: "Quase! A resposta certa ficou destacada.",
+        score: "Você acertou {right} de {total}.",
+    },
+    rules: {
+        title: "As regras do jogo",
+        lede: "Regras de negócio que o código garante. Quebrar uma delas costuma virar bug em produção.",
+        rule: "Regra",
+    },
+    stack: {
+        title: "As ferramentas da casa",
+        lede: "A stack, e para que cada peça serve aqui dentro.",
+    },
+    architecture: {
+        title: "Como as peças se encaixam",
+        modulesTitle: "Onde fica cada coisa",
+        modulesLede: "O mapa das pastas que importam.",
+    },
+    setup: {
+        title: "Bora rodar na sua máquina",
+        lede: "Do zero ao projeto rodando, passo a passo.",
+        prereq: "Tenha instalado",
+        commandsTitle: "Comandos do dia a dia",
+        commandsLede: "Os scripts que você vai usar toda hora.",
+        envTitle: "Variáveis de ambiente",
+        envLede: "Peça os valores ao time e nunca commite o seu .env.",
+        required: "obrigatória",
+        optional: "opcional",
+        copy: "Copiar",
+        copied: "Copiado!",
+    },
+    conventions: {
+        title: "Como a gente escreve código por aqui",
+        lede: "Seguir o jeito da casa deixa o review mais rápido (e mais feliz).",
+    },
+    tours: {
+        kicker: "Tour guiado",
+        intro: "Abra os arquivos no editor e siga comigo, uma parada de cada vez.",
+        stops: "Paradas",
+        stop: (i, total) => `Parada ${i} de ${total}`,
+    },
+    gotchas: {
+        title: "Cuidado com as cascas de banana",
+        lede: "Coisas que já pegaram alguém desprevenido. Agora não pegam mais você.",
+    },
+    decisions: {
+        title: "Por que é assim?",
+        lede: "Decisões que explicam o formato do código.",
+        context: "O contexto",
+        decision: "O que decidimos",
+    },
+    mission: {
+        title: "Sua primeira missão",
+        lede: "Tarefas pequenas e seguras para começar a contribuir. Marque conforme for fazendo.",
+    },
+    finale: {
+        title: "Você está pronto!",
+        lede: "Agora você conhece o porquê, o quê e o como do projeto. Bem-vindo ao time 💜",
+        recap: "O que você viu",
+        tasks: "{done} de {total} tarefas da primeira missão concluídas",
+        restart: "Ver de novo",
+        index: "Rever um capítulo",
+    },
+    ui: {
+        prev: "Anterior",
+        next: "Próximo",
+        overview: "Índice",
+        theme: "Alternar tema claro/escuro",
+        keys: "use ← → para navegar",
+        resume: "Continuar de onde parou (slide {n})?",
+        resumeYes: "Continuar",
+        resumeNo: "Do início",
+        close: "Fechar",
+        chapters: "Capítulos",
+        generated: "Gerado em",
+        by: "por",
+        minutes: "min",
+    },
+    pending: {
+        title: "O onboarding ainda não foi gerado",
+        body: "O arquivo existe, mas a IA ainda não o preencheu. Abra a IA que você usa neste projeto (Claude Code, Cursor, Copilot…) e envie:",
+    },
+    missing: {
+        title: "Arquivo de onboarding não encontrado",
+        body: "Rode o comando abaixo na raiz do projeto para criar o arquivo:",
+    },
+    invalid: { title: "O arquivo de onboarding tem um erro" },
+};
+const en = {
+    chapters: {
+        welcome: "Welcome",
+        why: "The why",
+        business: "The business",
+        product: "The product",
+        language: "Vocabulary",
+        rules: "Ground rules",
+        stack: "The stack",
+        architecture: "Architecture",
+        setup: "Hands on",
+        conventions: "House style",
+        tours: "Code tour",
+        gotchas: "Watch out",
+        decisions: "Decisions",
+        mission: "First mission",
+        finale: "Ready!",
+    },
+    welcome: {
+        hi: "Hi! Great to have you here.",
+        title: (name) => `Welcome to ${name}`,
+        intro: (min) => `This is a ~${min} minute tour of everything worth knowing before your first PR: why the project exists, how the business works, how the code is organized and where to tread carefully.`,
+        start: "Start the tour",
+        journey: "The road ahead",
+    },
+    why: {
+        title: "First, the why",
+        lede: "Before any line of code: the problem we solve.",
+        audience: "Who uses it",
+        status: "Where we are",
+    },
+    business: {
+        title: "How the business works",
+        lede: "Understanding the business turns code that works into code that makes sense.",
+        model: "The model",
+        value: "The value we deliver",
+        actorsTitle: "Who is part of this story",
+        actorsLede: "The roles that show up in the product and in the code.",
+        flowsTitle: "The main journeys",
+        flowsLede: "The path people take inside the product.",
+    },
+    product: { title: "What the product does", lede: "The features you will find (and touch) around here." },
+    language: {
+        title: "Speak the house language",
+        lede: "Terms you will hear in conversations, screens and code. Tap a card to see its meaning.",
+        tap: "tap to flip",
+        quizTitle: "Quick break: just for fun!",
+        quizLede: "A few questions to lock in the vocabulary.",
+        question: (term) => `What does “${term}” mean?`,
+        right: "Nailed it! 🎯",
+        wrong: "Almost! The right answer is highlighted.",
+        score: "You got {right} of {total}.",
+    },
+    rules: {
+        title: "The ground rules",
+        lede: "Business rules the code enforces. Breaking one usually becomes a production bug.",
+        rule: "Rule",
+    },
+    stack: { title: "The tools of the house", lede: "The stack, and what each piece is for in here." },
+    architecture: {
+        title: "How the pieces fit together",
+        modulesTitle: "Where everything lives",
+        modulesLede: "A map of the folders that matter.",
+    },
+    setup: {
+        title: "Let's run it on your machine",
+        lede: "From zero to running, step by step.",
+        prereq: "Have installed",
+        commandsTitle: "Everyday commands",
+        commandsLede: "The scripts you will use all the time.",
+        envTitle: "Environment variables",
+        envLede: "Ask the team for the values and never commit your .env.",
+        required: "required",
+        optional: "optional",
+        copy: "Copy",
+        copied: "Copied!",
+    },
+    conventions: {
+        title: "How we write code around here",
+        lede: "Following the house style makes reviews faster (and happier).",
+    },
+    tours: {
+        kicker: "Guided tour",
+        intro: "Open the files in your editor and follow along, one stop at a time.",
+        stops: "Stops",
+        stop: (i, total) => `Stop ${i} of ${total}`,
+    },
+    gotchas: { title: "Mind the banana peels", lede: "Things that caught someone off guard before. Not you, though." },
+    decisions: {
+        title: "Why is it like this?",
+        lede: "Decisions that explain the shape of the code.",
+        context: "The context",
+        decision: "What we decided",
+    },
+    mission: { title: "Your first mission", lede: "Small, safe tasks to start contributing. Check them off as you go." },
+    finale: {
+        title: "You're ready!",
+        lede: "You now know the why, the what and the how of this project. Welcome to the team 💜",
+        recap: "What you've seen",
+        tasks: "{done} of {total} first-mission tasks done",
+        restart: "Watch again",
+        index: "Revisit a chapter",
+    },
+    ui: {
+        prev: "Back",
+        next: "Next",
+        overview: "Index",
+        theme: "Toggle light/dark theme",
+        keys: "use ← → to navigate",
+        resume: "Pick up where you left off (slide {n})?",
+        resumeYes: "Continue",
+        resumeNo: "From the start",
+        close: "Close",
+        chapters: "Chapters",
+        generated: "Generated on",
+        by: "by",
+        minutes: "min",
+    },
+    pending: {
+        title: "Onboarding has not been generated yet",
+        body: "The file exists but your AI has not filled it in yet. Open the AI you use in this project (Claude Code, Cursor, Copilot…) and send:",
+    },
+    missing: { title: "Onboarding file not found", body: "Run this command at the project root to create it:" },
+    invalid: { title: "The onboarding file has an error" },
+};
+function copyFor(language) {
+    return language && !language.toLowerCase().startsWith("pt") ? en : pt;
+}

package/dist/render/html.d.ts

@@ -0,0 +1,12 @@
+import type { Evidence, OnboardingData } from "../types";
+export declare function escapeHtml(value: unknown): string;
+/** Texto escapado com quebras de linha e `código` inline. */
+export declare function text(value: unknown): string;
+export declare function chunk<T>(items: T[], size: number): T[][];
+/** Matiz estável (0–359) derivado de um texto, para avatares e logos. */
+export declare function hueFrom(value: string): number;
+export declare function initials(value: string): string;
+export declare function pad(n: number): string;
+export declare function repoBase(data: OnboardingData): string | undefined;
+export declare function evidenceChip(ref: Evidence, data: OnboardingData, extraClass?: string): string;
+export declare function evidenceList(refs: Evidence[] | undefined, data: OnboardingData): string;

package/dist/render/html.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtml = escapeHtml;
+exports.text = text;
+exports.chunk = chunk;
+exports.hueFrom = hueFrom;
+exports.initials = initials;
+exports.pad = pad;
+exports.repoBase = repoBase;
+exports.evidenceChip = evidenceChip;
+exports.evidenceList = evidenceList;
+const load_1 = require("../load");
+const validate_1 = require("../validate");
+function escapeHtml(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** Texto escapado com quebras de linha e `código` inline. */
+function text(value) {
+    return escapeHtml(value)
+        .replace(/`([^`\n]+)`/g, "<code>$1</code>")
+        .replace(/\n/g, "<br>");
+}
+function chunk(items, size) {
+    const pages = [];
+    for (let i = 0; i < items.length; i += size)
+        pages.push(items.slice(i, i + size));
+    return pages;
+}
+/** Matiz estável (0–359) derivado de um texto, para avatares e logos. */
+function hueFrom(value) {
+    let hash = 0;
+    for (const ch of value)
+        hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
+    return hash % 360;
+}
+function initials(value) {
+    const words = value.replace(/[^\p{L}\p{N}\s.-]/gu, " ").trim().split(/[\s.-]+/).filter(Boolean);
+    if (words.length === 0)
+        return "?";
+    if (words.length === 1)
+        return words[0].slice(0, 2).toUpperCase();
+    return (words[0][0] + words[1][0]).toUpperCase();
+}
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function repoBase(data) {
+    const url = data.project?.repoUrl?.trim();
+    if (!url || !/^https?:\/\//.test(url))
+        return undefined;
+    return url.replace(/\.git$/, "").replace(/\/$/, "");
+}
+const FILE_ICON = '<svg viewBox="0 0 16 16" aria-hidden="true" width="12" height="12"><path fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round" d="M4 1.75h5.25L12.5 5v9.25H4z M9 1.75V5.25h3.5"/></svg>';
+function evidenceChip(ref, data, extraClass = "") {
+    const { file, line } = (0, validate_1.parseEvidence)(ref);
+    const label = `${FILE_ICON}<span>${escapeHtml(ref)}</span>`;
+    const base = repoBase(data);
+    if (!base)
+        return `<span class="ev ${extraClass}">${label}</span>`;
+    const commit = data.meta?.commit?.trim() || "HEAD";
+    const href = `${base}/blob/${encodeURIComponent(commit)}/${file.split("/").map(encodeURIComponent).join("/")}${line ? `#L${line}` : ""}`;
+    return `<a class="ev ${extraClass}" href="${escapeHtml(href)}" target="_blank" rel="noopener">${label}</a>`;
+}
+function evidenceList(refs, data) {
+    const list = (0, load_1.filled)(refs);
+    if (list.length === 0)
+        return "";
+    return `<div class="evidence">${list.map((ref) => evidenceChip(ref, data)).join("")}</div>`;
+}

package/dist/render/index.d.ts

@@ -0,0 +1,5 @@
+import type { OnboardingData } from "../types";
+export { escapeHtml } from "./html";
+export declare function renderMissingPage(): string;
+export declare function renderErrorPage(message: string): string;
+export declare function renderOnboarding(data: OnboardingData): string;