product-runner 0.5.0

package/dist/migrations.js

@@ -0,0 +1,147 @@
+import { readdir, readFile, rename, mkdir, writeFile, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, dirname } from "node:path";
+/** Nome de arquivo de migration: exatamente `x.y.z.md`. */
+const VERSION_FILE_RE = /^\d+\.\d+\.\d+\.md$/;
+async function exists(p) {
+    try {
+        await access(p, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compara versoes semver simples (x.y.z): <0, 0, >0. */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** Converte glob simples (`*` num segmento, `**` atravessa) em RegExp. */
+export function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                if (glob[i + 2] === "/") {
+                    // `**/` atravessa zero ou mais segmentos (inclui a barra)
+                    re += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    re += ".*";
+                    i++;
+                }
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (/[.+^${}()|[\]\\]/.test(c)) {
+            re += "\\" + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+/** Parseia uma migration: frontmatter JSON entre `---` + corpo markdown. */
+export function parseMigration(content) {
+    const m = content.match(/^\uFEFF?---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+    if (!m) {
+        throw new Error("Migration sem frontmatter JSON (--- ... ---).");
+    }
+    let meta;
+    try {
+        meta = JSON.parse(m[1]);
+    }
+    catch (err) {
+        throw new Error(`Frontmatter JSON invalido: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof meta.version !== "string") {
+        throw new Error('Migration sem campo "version".');
+    }
+    return {
+        version: meta.version,
+        previous: typeof meta.previous === "string" ? meta.previous : undefined,
+        title: typeof meta.title === "string" ? meta.title : meta.version,
+        risk: meta.risk === "high" || meta.risk === "low" ? meta.risk : undefined,
+        autoApply: meta.autoApply === true,
+        affects: Array.isArray(meta.affects) ? meta.affects : [],
+        ops: Array.isArray(meta.ops) ? meta.ops : [],
+        body: (m[2] ?? "").trim(),
+    };
+}
+/** Le e parseia todas as migrations de um diretorio (arquivos `x.y.z.md`). */
+export async function discoverMigrations(dir) {
+    if (!(await exists(dir)))
+        return [];
+    const out = [];
+    for (const name of await readdir(dir)) {
+        if (!VERSION_FILE_RE.test(name))
+            continue;
+        out.push(parseMigration(await readFile(join(dir, name), "utf8")));
+    }
+    return out.sort((a, b) => compareVersions(a.version, b.version));
+}
+/** Migrations no intervalo (from, to] -- exclusivo no from, inclusivo no to. */
+export function migrationsInSpan(all, from, to) {
+    return all
+        .filter((mig) => compareVersions(mig.version, from) > 0 &&
+        compareVersions(mig.version, to) <= 0)
+        .sort((a, b) => compareVersions(a.version, b.version));
+}
+/**
+ * Aplica os `ops` mecanicos de uma migration ao projeto (rename/replace).
+ * `projectFiles` e a lista atual de arquivos (POSIX, relativos a targetDir),
+ * usada para resolver os globs de `replace`.
+ */
+export async function applyOps(targetDir, ops, projectFiles) {
+    const results = [];
+    for (const op of ops) {
+        if (op.type === "rename" && op.from && op.to) {
+            const fromAbs = join(targetDir, ...op.from.split("/"));
+            const toAbs = join(targetDir, ...op.to.split("/"));
+            if (await exists(fromAbs)) {
+                await mkdir(dirname(toAbs), { recursive: true });
+                await rename(fromAbs, toAbs);
+                results.push({ op, applied: true, detail: `${op.from} -> ${op.to}` });
+            }
+            else {
+                results.push({ op, applied: false, detail: `${op.from} ausente (no-op)` });
+            }
+        }
+        else if (op.type === "replace" && op.glob && op.find !== undefined) {
+            const matcher = globToRegExp(op.glob);
+            const find = new RegExp(op.find, "g");
+            let count = 0;
+            for (const rel of projectFiles) {
+                if (!matcher.test(rel))
+                    continue;
+                const abs = join(targetDir, ...rel.split("/"));
+                // um op anterior (rename) pode ter movido este arquivo — pula se sumiu
+                if (!(await exists(abs)))
+                    continue;
+                const before = await readFile(abs, "utf8");
+                const after = before.replace(find, op.replace ?? "");
+                if (after !== before) {
+                    await writeFile(abs, after, "utf8");
+                    count++;
+                }
+            }
+            results.push({ op, applied: count > 0, detail: `${op.glob}: ${count} arquivo(s)` });
+        }
+        else {
+            results.push({ op, applied: false, detail: `op invalida (${op.type})` });
+        }
+    }
+    return results;
+}

package/dist/scaffold.js

@@ -0,0 +1,276 @@
+import { mkdir, readFile, writeFile, access, readdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Raiz do pacote (um nível acima de dist/ ou src/), onde vivem os templates. */
+export function templatesRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..");
+}
+/** Arquivos de template que NÃO vão pra docs/ — são mesclados no CLAUDE.md. */
+const CLAUDE_MD_PARTS = new Set([
+    "claude-md.template.md",
+    "claude-md.extension.md",
+]);
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove o blockquote de aviso "este é um template / extensão" do topo de um
+ * fragmento de CLAUDE.md — instrução de uso que não faz sentido no arquivo final.
+ */
+function stripTemplateNotice(md) {
+    const lines = md.split("\n");
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const isNoticeStart = line.startsWith(">") && /\btemplate\b|\bextens[ãa]o\b/i.test(line);
+        if (isNoticeStart) {
+            // pula o bloco de citação inteiro (linhas começando com ">")
+            while (i < lines.length && lines[i].startsWith(">"))
+                i++;
+            // pula uma linha em branco logo após o bloco, se houver
+            if (i < lines.length && lines[i].trim() === "")
+                i++;
+            continue;
+        }
+        out.push(line);
+        i++;
+    }
+    return out.join("\n");
+}
+function applySubstitutions(md, sub) {
+    return md.replaceAll("{PROJECT_NAME}", sub.name).replaceAll("{PORT}", sub.port);
+}
+const DIRECTIVE_RE = /^<!--\s*prod-runner-merge:\s*(replace|append|after)\s+section="([^"]+)"\s*-->\s*$/;
+function parseDirectives(extension) {
+    const directives = [];
+    let current = null;
+    let buf = [];
+    const flush = () => {
+        if (current) {
+            current.content = buf.join("\n").replace(/^\n+|\n+$/g, "");
+            directives.push(current);
+        }
+    };
+    for (const line of extension.split("\n")) {
+        const m = line.match(DIRECTIVE_RE);
+        if (m) {
+            flush();
+            current = { mode: m[1], section: m[2], content: "" };
+            buf = [];
+        }
+        else if (current) {
+            buf.push(line);
+        }
+    }
+    flush();
+    return directives;
+}
+/** Nível (1-6) de um heading ATX, ou null se a linha não for heading. */
+function headingLevel(line) {
+    const m = line.match(/^(#{1,6})\s+/);
+    return m ? m[1].length : null;
+}
+/**
+ * Localiza uma seção pelo texto do heading. Retorna [start, end) em índices de
+ * linha; `end` é a próxima heading de nível menor-ou-igual (ou o fim do doc).
+ */
+function findSection(lines, heading) {
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const lvl = headingLevel(lines[i]);
+        if (lvl !== null && lines[i].replace(/^#{1,6}\s+/, "").trim() === heading) {
+            start = i;
+            level = lvl;
+            break;
+        }
+    }
+    if (start === -1) {
+        throw new Error(`Diretiva prod-runner-merge: seção "${heading}" não existe no CLAUDE.md base.`);
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const lvl = headingLevel(lines[i]);
+        if (lvl !== null && lvl <= level) {
+            end = i;
+            break;
+        }
+    }
+    return { start, end };
+}
+function applyDirective(lines, d) {
+    const { start, end } = findSection(lines, d.section);
+    const before = lines.slice(0, start);
+    const section = lines.slice(start, end);
+    const after = lines.slice(end);
+    const content = d.content.split("\n");
+    if (d.mode === "replace") {
+        return [...before, ...content, "", ...after];
+    }
+    if (d.mode === "after") {
+        return [...before, ...section, ...content, "", ...after];
+    }
+    // append: corpo da seção, sem linhas em branco finais, + conteúdo novo
+    const body = [...section];
+    while (body.length && body[body.length - 1].trim() === "")
+        body.pop();
+    return [...before, ...body, "", ...content, "", ...after];
+}
+/** Dobra a extensão do perfil no template-base via diretivas prod-runner-merge. */
+function mergeClaudeMd(base, extension) {
+    let lines = base.split("\n");
+    for (const directive of parseDirectives(extension)) {
+        lines = applyDirective(lines, directive);
+    }
+    // colapsa 3+ linhas em branco seguidas em no máximo 1 (resultado limpo)
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+/** Nome do manifesto escrito em docs/ — base para futuros `update`. */
+export const MANIFEST_FILENAME = ".product-runner.json";
+export function sha256(content) {
+    return "sha256:" + createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** Lista recursiva de arquivos (caminhos relativos POSIX) sob `dir`. */
+export async function listFiles(dir, base = dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await listFiles(full, base)));
+        }
+        else {
+            out.push(relative(base, full).split(sep).join("/"));
+        }
+    }
+    return out;
+}
+/** Versão do pacote (do package.json na raiz do pacote). */
+export async function packageVersion(root) {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+/**
+ * Calcula (SEM escrever) todos os arquivos que o scaffold emitiria, como um
+ * mapa destPath(relativo ao targetDir, POSIX) → Artifact. É a fonte única usada
+ * tanto pelo `scaffold` (escreve) quanto pelo `update` (compara). Garante que a
+ * "base" registrada no manifesto seja byte-idêntica ao que seria gerado.
+ */
+export async function buildArtifacts(meta) {
+    const root = templatesRoot();
+    const commonDir = join(root, "common");
+    const profileDir = join(root, `profile-${meta.profile}`);
+    const out = new Map();
+    // common/ e perfil → docs/, exceto: fragmentos do CLAUDE.md (pulados) e
+    // common/specs/* → specs/ (seeds preenchidos no projeto, fora de docs/).
+    for (const [srcDir, prefix] of [
+        [commonDir, "common"],
+        [profileDir, `profile-${meta.profile}`],
+    ]) {
+        for (const rel of await listFiles(srcDir)) {
+            const base = rel.split("/").pop() ?? "";
+            if (CLAUDE_MD_PARTS.has(base))
+                continue;
+            // docs são copiados sem substituição → conteúdo emitido == origem
+            const content = await readFile(join(srcDir, rel), "utf8");
+            const dest = rel.startsWith("specs/") ? rel : `docs/${rel}`;
+            out.set(dest, { content, fromTemplate: `${prefix}/${rel}` });
+        }
+    }
+    // CLAUDE.md = base com a extensão do perfil dobrada via diretivas
+    const template = await readFile(join(commonDir, "claude-md.template.md"), "utf8");
+    const extension = await readFile(join(profileDir, "claude-md.extension.md"), "utf8");
+    const merged = applySubstitutions(mergeClaudeMd(stripTemplateNotice(template), extension), meta).trimEnd() + "\n";
+    out.set("CLAUDE.md", {
+        content: merged,
+        fromTemplate: `merge:common/claude-md.template.md+profile-${meta.profile}/claude-md.extension.md`,
+    });
+    return out;
+}
+/**
+ * Escreve o manifesto em docs/ a partir dos artefatos emitidos. O hash de cada
+ * arquivo é do conteúdo EMITIDO — vira a "base" que torna o `update` 3-way.
+ */
+export async function writeManifest(docsPath, meta, artifacts) {
+    const files = {};
+    for (const [path, art] of artifacts) {
+        files[path] = { fromTemplate: art.fromTemplate, sha256: sha256(art.content) };
+    }
+    const manifest = {
+        manifestVersion: 1,
+        package: "product-runner",
+        version: await packageVersion(templatesRoot()),
+        profile: meta.profile,
+        projectName: meta.name,
+        port: meta.port,
+        files: Object.fromEntries(Object.keys(files)
+            .sort()
+            .map((k) => [k, files[k]])),
+    };
+    const manifestPath = join(docsPath, MANIFEST_FILENAME);
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    return manifestPath;
+}
+export async function scaffold(opts) {
+    const docsPath = join(opts.targetDir, "docs");
+    const claudeMdPath = join(opts.targetDir, "CLAUDE.md");
+    if (!opts.force) {
+        for (const p of [docsPath, claudeMdPath]) {
+            if (await exists(p)) {
+                throw new Error(`Já existe "${p}". Use --force para sobrescrever ou escolha outro --dir.`);
+            }
+        }
+    }
+    const artifacts = await buildArtifacts(opts);
+    // escreve cada artefato no destino (docs/* e CLAUDE.md na raiz)
+    for (const [rel, art] of artifacts) {
+        const dest = join(opts.targetDir, ...rel.split("/"));
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, art.content, "utf8");
+    }
+    const manifestPath = await writeManifest(docsPath, opts, artifacts);
+    return { claudeMdPath, docsPath, manifestPath };
+}
+/** Agente que o humano deve abrir após o init ("leia <este> e siga"). */
+export const ENTRY_AGENT = "agente-prod-runner.md";
+/**
+ * Par de bootstrap colocado na raiz pelo `init`: o agente de entrada (roteador
+ * + ciclo de vida) e o de discovery, que o roteador aciona em projeto novo.
+ * Ambos voltam a viver em docs/agents/ após o scaffold.
+ */
+export const BOOTSTRAP_AGENTS = [ENTRY_AGENT, "agente-kickoff.md"];
+/**
+ * Copia o par de agentes de bootstrap (de common/agents/) para a raiz do
+ * projeto. O ponto de entrada é o `agente-prod-runner.md`: a LLM o lê, diagnostica o
+ * estado do projeto e roteia (discovery, conceituação, adoção legada…).
+ */
+export async function initProject(opts) {
+    const agentsDir = join(templatesRoot(), "common", "agents");
+    const dests = BOOTSTRAP_AGENTS.map((name) => join(opts.targetDir, name));
+    if (!opts.force) {
+        for (const dest of dests) {
+            if (await exists(dest)) {
+                throw new Error(`Já existe "${dest}". Use --force para sobrescrever.`);
+            }
+        }
+    }
+    await mkdir(opts.targetDir, { recursive: true });
+    const files = [];
+    for (const name of BOOTSTRAP_AGENTS) {
+        const content = await readFile(join(agentsDir, name), "utf8");
+        const dest = join(opts.targetDir, name);
+        await writeFile(dest, content, "utf8");
+        files.push(dest);
+    }
+    return { entryPath: join(opts.targetDir, ENTRY_AGENT), files };
+}