jarvis-ai-framework 2.1.0 → 3.0.0

package/bin/lib/core/token-report.js

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Estimativa do que o framework carrega no início de uma sessão.
+ *
+ * Mede, por tipo, os arquivos que a IDE lê no início para um perfil (HUB,
+ * POSITION, AREA, SQUAD). Tokens são uma **estimativa** (bytes ÷ 4): serve
+ * para comparar antes e depois, não para cobrar custo.
+ * @module core/token-report
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { listRulesForProfile } from "./profile-filter.js";
+
+/** Bytes por token usados na estimativa. */
+export const BYTES_PER_TOKEN = 4;
+
+/**
+ * @param {number} bytes
+ * @returns {number} tokens estimados (bytes ÷ 4, arredondado)
+ */
+export function estimateTokens(bytes) {
+  return Math.round(bytes / BYTES_PER_TOKEN);
+}
+
+/**
+ * Tamanho em bytes do bloco de frontmatter (do primeiro `---` ao segundo `---`).
+ * @param {string} content
+ * @returns {number} 0 quando não há frontmatter
+ */
+export function frontmatterBytes(content) {
+  const match = content.match(/^---\s*\n[\s\S]*?\n---/);
+  return match ? Buffer.byteLength(match[0], "utf-8") : 0;
+}
+
+function fileBytes(path) {
+  return Buffer.byteLength(readFileSync(path, "utf-8"), "utf-8");
+}
+
+function category(id, label, files, note = "") {
+  const sorted = [...files].sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
+  const bytes = sorted.reduce((sum, f) => sum + f.bytes, 0);
+  return { id, label, note, files: sorted, bytes, tokens: estimateTokens(bytes) };
+}
+
+/**
+ * @param {string} root - Raiz do framework (`rules/`, `skills/`, `workflows/`, `AGENTS.md`)
+ * @param {import("./profile-filter.js").Profile} profile
+ * @param {{ rtkEnabled?: boolean }} [opts]
+ */
+export function buildReport(root, profile, opts = {}) {
+  const rtkEnabled = Boolean(opts.rtkEnabled);
+
+  const rules = listRulesForProfile(join(root, "rules"), profile, { rtkEnabled });
+
+  const agentsMd = existsSync(join(root, "AGENTS.md"))
+    ? [{ path: "AGENTS.md", bytes: fileBytes(join(root, "AGENTS.md")) }]
+    : [];
+
+  const skillsDir = join(root, "skills");
+  const skills = [];
+  if (existsSync(skillsDir)) {
+    for (const name of readdirSync(skillsDir)) {
+      const skillMd = join(skillsDir, name, "SKILL.md");
+      if (!statSync(join(skillsDir, name)).isDirectory() || !existsSync(skillMd)) continue;
+      const bytes = frontmatterBytes(readFileSync(skillMd, "utf-8"));
+      if (bytes > 0) skills.push({ path: `skills/${name}/SKILL.md`, bytes });
+    }
+  }
+
+  const warmupPath = join(root, "workflows", "warm-up.md");
+  const warmup = existsSync(warmupPath)
+    ? [{ path: "workflows/warm-up.md", bytes: fileBytes(warmupPath) }]
+    : [];
+
+  const categories = [
+    category("rules", "Rules", rules, "carregadas no início pelo Claude Code"),
+    category("agents-md", "AGENTS.md", agentsMd, "instrução de projeto"),
+    category(
+      "skills-frontmatter",
+      "Frontmatter dos skills",
+      skills,
+      "sempre visível; o corpo só ao invocar"
+    ),
+    category("warmup", "warm-up", warmup, "só se executado no início da sessão"),
+  ];
+
+  const bytes = categories.reduce((sum, c) => sum + c.bytes, 0);
+  return {
+    profile: {
+      HUB: profile.HUB,
+      POSITION: profile.POSITION,
+      AREA: profile.AREA,
+      SQUAD: profile.SQUAD,
+    },
+    rtkEnabled,
+    estimate: `tokens = bytes ÷ ${BYTES_PER_TOKEN} (estimativa)`,
+    categories,
+    total: { bytes, tokens: estimateTokens(bytes) },
+  };
+}

package/bin/lib/docs/fetch-file.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Busca um arquivo do central-docs (GitLab/GitHub/Bitbucket), com
+ * cache Redis best-effort. Substitui `fetch-file.sh` (removido) — mesmo
+ * comportamento, sem subprocess: chama `fetchRawFile` de `vcs/api.js` direto.
+ * @module docs/fetch-file
+ */
+
+import { fetchRawFile } from "../vcs/api.js";
+import { redisGet, redisSetex } from "./redis-cache.js";
+
+/**
+ * @param {string} filePath - Path do arquivo dentro do repo central-docs
+ * @param {string} [ref] - Branch/ref (padrão: "main")
+ * @param {Object} [opts]
+ * @param {string} [opts.repo] - CENTRAL_DOCS_REPO (padrão: `process.env.CENTRAL_DOCS_REPO`)
+ * @param {string|number} [opts.cacheTtl] - TTL do cache em segundos (padrão: `process.env.CENTRAL_DOCS_CACHE_TTL` ou 3600)
+ * @returns {Promise<string>} conteúdo do arquivo
+ * @throws {Error} sem `filePath`, sem `repo`, ou erro do adapter (404/401/403 — ver `fetchRawFile`)
+ */
+export async function fetchFile(filePath, ref = "main", opts = {}) {
+  if (!filePath) {
+    throw new Error("fetchFile: file-path é obrigatório");
+  }
+
+  const repo = opts.repo ?? process.env.CENTRAL_DOCS_REPO;
+  if (!repo) {
+    throw new Error("CENTRAL_DOCS_REPO não definido no ENV.md");
+  }
+
+  const cacheKey = `docs:${filePath}:${ref}`;
+  const cached = redisGet(cacheKey);
+  if (cached) return cached;
+
+  const content = await fetchRawFile(repo, filePath, ref);
+
+  redisSetex(cacheKey, opts.cacheTtl ?? process.env.CENTRAL_DOCS_CACHE_TTL ?? "3600", content);
+
+  return content;
+}

package/bin/lib/docs/publish-file.js

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Publica um documento no central-docs (branch + commit + MR/PR).
+ * Substitui `publish-file.sh` (removido) — chama os adapters de `vcs/api.js`
+ * direto, sem subprocess, sem arquivo temporário para passar JSON/body.
+ * @module docs/publish-file
+ */
+
+import { readFileSync } from "node:fs";
+import { validateFrontmatter, extractMetadata } from "./validate-frontmatter.js";
+import { commitFiles, createMergeRequest } from "../vcs/api.js";
+import { fetchFile } from "./fetch-file.js";
+import { redisDel } from "./redis-cache.js";
+import { logger } from "../utils/logger.js";
+
+const VALID_TYPES = ["prd", "frd", "ard", "rfc", "swagger", "qa-report"];
+
+/**
+ * @param {{ tipo: string, squad: string, workspace: string, feature: string, localFile: string }} p
+ * @returns {{ destPath: string, area: "product"|"engineering" }}
+ */
+export function resolveDestPath({ tipo, squad, workspace, feature, localFile }) {
+  const base = `${squad}/${workspace}`;
+
+  if (tipo === "prd" || tipo === "frd") {
+    return { destPath: `${base}/product/${tipo}-${feature}.md`, area: "product" };
+  }
+  if (tipo === "ard") {
+    return { destPath: `${base}/engineering/ARD/${tipo}-${feature}.md`, area: "engineering" };
+  }
+  if (tipo === "rfc") {
+    return { destPath: `${base}/engineering/RFC/${tipo}-${feature}.md`, area: "engineering" };
+  }
+  if (tipo === "swagger") {
+    const ext = localFile.split(".").pop().toLowerCase();
+    const swaggerExt = ext === "yaml" || ext === "yml" ? ext : ext === "json" ? "json" : null;
+    const destPath = swaggerExt
+      ? `${base}/engineering/swagger/api-${feature}.${swaggerExt}`
+      : `${base}/engineering/swagger/swagger-${feature}.md`; // default: .md (wrapper com metadados)
+    return { destPath, area: "engineering" };
+  }
+  if (tipo === "qa-report") {
+    return { destPath: `${base}/engineering/qa/qa-report-${feature}.md`, area: "engineering" };
+  }
+
+  throw new Error(`Tipo inválido: ${tipo}\nTipos válidos: ${VALID_TYPES.join(", ")}`);
+}
+
+/**
+ * Insere `newLine` logo após o header `## {area}` — sem nunca descartar uma
+ * linha existente. O `publish-file.sh` original usava `getline` do AWK para
+ * "pular" a linha seguinte ao header antes de imprimir a nova entrada; essa
+ * linha pulada nunca era reimpressa, o que apagava silenciosamente a entrada
+ * anterior do índice na segunda publicação numa mesma seção (reproduzido e
+ * documentado em `architecture.md` desta sessão, seção 3.4).
+ * @param {string} content
+ * @param {"product"|"engineering"} area
+ * @param {string} newLine
+ * @returns {{ content: string, found: boolean }}
+ */
+export function insertIndexLine(content, area, newLine) {
+  const lines = content.split("\n");
+  const headerPattern = /^## (product|engineering)\b/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(headerPattern);
+    if (match && match[1] === area) {
+      lines.splice(i + 1, 0, newLine);
+      return { content: lines.join("\n"), found: true };
+    }
+  }
+
+  const trimmed = content.replace(/\n+$/, "");
+  return { content: `${trimmed}\n\n## ${area}\n${newLine}\n`, found: false };
+}
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.localFile - Caminho do arquivo local (ex: `./docs/engineering/ard-x.md`)
+ * @param {string} opts.tipo - prd|frd|ard|rfc|swagger|qa-report
+ * @param {string} opts.feature - Slug da feature (kebab-case)
+ * @param {string} opts.squad - Squad (já resolvido pelo caller: override ou ENV.md)
+ * @param {string} opts.workspace - Workspace (já resolvido pelo caller: override ou ENV.md)
+ * @param {string} opts.repo - CENTRAL_DOCS_REPO
+ * @param {string} [opts.targetBranch] - Branch base do MR/PR (padrão: "dev")
+ * @param {string|number} [opts.cacheTtl] - TTL do cache do index.md em segundos (padrão: 3600)
+ * @returns {Promise<{ sha: string, mr: { vendor: string, iid: number|string, url: string } }>}
+ */
+export async function publishFile(opts) {
+  const {
+    localFile,
+    tipo,
+    feature,
+    squad,
+    workspace,
+    repo,
+    targetBranch = "dev",
+    cacheTtl = "3600",
+  } = opts;
+
+  if (!repo) {
+    throw new Error(
+      "CENTRAL_DOCS_REPO não configurado no ENV.md\n\nConfigure a URL do repositório central:\n  CENTRAL_DOCS_REPO=https://gitlab.com/org/central-docs.git"
+    );
+  }
+
+  logger.info("Validando frontmatter...");
+  validateFrontmatter(localFile, tipo);
+  logger.info("✅ Frontmatter válido");
+
+  const metadata = extractMetadata(localFile);
+  const version = metadata.version || "1.0.0";
+  const status = metadata.status || "draft";
+  const jira = metadata.jira || "";
+  const docName = metadata.name || "";
+
+  const { destPath, area } = resolveDestPath({ tipo, squad, workspace, feature, localFile });
+  const indexPath = `${squad}/${workspace}/index.md`;
+  const branchName = `docs/${squad}/${workspace}/${tipo}-${feature}`;
+
+  logger.info("");
+  logger.info("📋 Resumo da Publicação:");
+  logger.info(`  Squad: ${squad}`);
+  logger.info(`  Workspace: ${workspace}`);
+  logger.info(`  Tipo: ${tipo}`);
+  logger.info(`  Feature: ${feature}`);
+  logger.info(`  Destino: ${destPath}`);
+  logger.info(`  Branch: ${branchName} → ${targetBranch}`);
+  logger.info("");
+
+  const fileContentBase64 = readFileSync(localFile).toString("base64");
+
+  logger.info("Buscando index.md do workspace...");
+  let indexContent = "";
+  try {
+    indexContent = await fetchFile(indexPath, targetBranch, { repo, cacheTtl });
+  } catch {
+    indexContent = "";
+  }
+
+  let indexAction;
+  if (!indexContent) {
+    logger.info("⚠️  index.md não encontrado, será criado");
+    indexAction = "create";
+    indexContent = `# ${workspace}\n\n**Squad:** ${squad}\n\n## ${area}\n\n`;
+  } else {
+    indexAction = "update";
+  }
+
+  let newLine = `- [${tipo}-${feature}.md](${area}/${tipo}-${feature}.md) | v${version} | ${status}`;
+  if (jira) newLine += ` | jira: ${jira}`;
+  if (docName) newLine += ` | ${docName}`;
+
+  const { content: updatedIndex } = insertIndexLine(indexContent, area, newLine);
+  const updatedIndexBase64 = Buffer.from(updatedIndex, "utf-8").toString("base64");
+
+  logger.info("Criando branch e commit...");
+  const commitResult = await commitFiles(repo, {
+    branch: branchName,
+    startBranch: targetBranch,
+    message: `docs(${squad}): add ${tipo} ${feature}`,
+    files: [
+      { path: destPath, contentBase64: fileContentBase64, action: "create" },
+      { path: indexPath, contentBase64: updatedIndexBase64, action: indexAction },
+    ],
+  });
+  logger.info(`✅ Commit criado: ${commitResult.sha}`);
+
+  logger.info("Criando Merge/Pull Request...");
+  let mrDescription = `## Documento\n\n- **Tipo**: ${tipo}\n- **Workspace**: ${workspace}\n- **Feature**: ${feature}`;
+  if (jira) mrDescription += `\n- **Card**: ${jira}`;
+  if (docName) mrDescription += `\n- **Nome**: ${docName}`;
+
+  const mr = await createMergeRequest(repo, {
+    source: branchName,
+    target: targetBranch,
+    title: `docs(${squad}): ${tipo} ${feature}`,
+    description: mrDescription,
+  });
+
+  logger.info("");
+  logger.info("✅ Merge/Pull Request criado com sucesso!");
+  logger.info("");
+  logger.info(`  #${mr.iid}: ${branchName} → ${targetBranch}`);
+  logger.info(`  URL: ${mr.url}`);
+  logger.info("");
+
+  redisDel(`docs:${indexPath}:${targetBranch}`);
+  redisDel(`docs:${indexPath}:main`);
+  logger.info("🔄 Cache Redis invalidado");
+  logger.info("");
+  logger.info("✅ Publicação concluída!");
+
+  return { sha: commitResult.sha, mr };
+}

package/bin/lib/docs/redis-cache.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Cache best-effort via `redis-cli` para fetch-file.js/publish-file.js.
+ * Nunca lança — falha de leitura/escrita no cache nunca quebra o fluxo principal
+ * (mesmo contrato do `fetch-file.sh`/`publish-file.sh` originais, que faziam
+ * `redis-cli ... 2>/dev/null || true`).
+ * @module docs/redis-cache
+ */
+
+import { execFileSync } from "node:child_process";
+
+/**
+ * @param {string} key
+ * @returns {string} valor em cache, ou "" se não houver (ou `redis-cli` falhar)
+ */
+export function redisGet(key) {
+  try {
+    return execFileSync("redis-cli", ["GET", key], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {string|number} ttlSeconds
+ * @param {string} value
+ */
+export function redisSetex(key, ttlSeconds, value) {
+  try {
+    execFileSync("redis-cli", ["-x", "SETEX", key, String(ttlSeconds)], {
+      input: value,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/** @param {string} key */
+export function redisDel(key) {
+  try {
+    execFileSync("redis-cli", ["DEL", key], { stdio: "ignore" });
+  } catch {
+    // best-effort
+  }
+}

package/bin/lib/docs/validate-frontmatter.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs'
+import { parseFrontmatter, extractFrontmatterBlock } from '../utils/frontmatter.js'
 
 /**
  * Valida frontmatter YAML de documentos (PRD, FRD, ARD, RFC)
@@ -10,11 +11,10 @@ import { readFileSync } from 'node:fs'
  */
 export function validateFrontmatter(filePath, tipo) {
   const content = readFileSync(filePath, 'utf-8')
-  
-  // Extrair frontmatter YAML (entre --- e ---)
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
-  
-  if (!frontmatterMatch) {
+
+  const frontmatter = extractFrontmatterBlock(content)
+
+  if (frontmatter === null) {
     throw new Error(
       `Frontmatter YAML não encontrado em ${filePath}\n` +
       'Formato esperado:\n' +
@@ -25,8 +25,7 @@ export function validateFrontmatter(filePath, tipo) {
     )
   }
 
-  const frontmatter = frontmatterMatch[1]
-  const metadata = parseFrontmatter(frontmatter)
+  const metadata = parseFrontmatter(content)
 
   // Validar campos obrigatórios por tipo
   const requiredFields = getRequiredFields(tipo)
@@ -67,34 +66,6 @@ export function validateFrontmatter(filePath, tipo) {
   return metadata
 }
 
-/**
- * Parseia frontmatter YAML simples (key: value)
- * 
- * @param {string} frontmatter - Conteúdo do frontmatter
- * @returns {Object} Metadados parseados
- */
-function parseFrontmatter(frontmatter) {
-  const metadata = {}
-  const lines = frontmatter.split('\n')
-
-  for (const line of lines) {
-    const trimmed = line.trim()
-    if (!trimmed || trimmed.startsWith('#')) continue
-
-    const colonIndex = trimmed.indexOf(':')
-    if (colonIndex === -1) continue
-
-    const key = trimmed.slice(0, colonIndex).trim()
-    const value = trimmed.slice(colonIndex + 1).trim()
-
-    if (key && value) {
-      metadata[key] = value
-    }
-  }
-
-  return metadata
-}
-
 /**
  * Retorna campos obrigatórios por tipo de documento
  * 
@@ -121,13 +92,12 @@ function getRequiredFields(tipo) {
  */
 export function extractMetadata(filePath) {
   const content = readFileSync(filePath, 'utf-8')
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
-  
-  if (!frontmatterMatch) {
+
+  if (extractFrontmatterBlock(content) === null) {
     return {}
   }
 
-  const metadata = parseFrontmatter(frontmatterMatch[1])
+  const metadata = parseFrontmatter(content)
 
   // Normalizar campos (suportar variações de nomenclatura)
   const taskLink = metadata.task_link || metadata.jira

package/bin/lib/env-loader.js

@@ -2,25 +2,7 @@ import { readFileSync, existsSync } from "node:fs";
 
 import { join, isAbsolute, dirname, basename } from "node:path";
 
-const IDE_DIRS = {
-  windsurf: ".windsurf",
-  claude: ".claude",
-  cursor: ".cursor",
-  vscode: ".vscode",
-  codex: ".codex",
-  opencode: ".opencode",
-  gemini: ".gemini",
-};
-
-const AUTO_DETECT_ORDER = [
-  "windsurf",
-  "claude",
-  "cursor",
-  "vscode",
-  "codex",
-  "opencode",
-  "gemini",
-];
+import { getIDEFolder, getIDEValues, isIDESupported } from "./config/ide-config.js";
 
 function* walkAncestors(start) {
   let dir = start;
@@ -33,12 +15,11 @@ function* walkAncestors(start) {
 }
 
 function envsAt(dir, ideFilter = null) {
-  const ides = ideFilter ? [ideFilter] : AUTO_DETECT_ORDER;
+  const ides = ideFilter ? [ideFilter] : getIDEValues();
   const found = [];
   for (const ide of ides) {
-    const folder = IDE_DIRS[ide];
-    if (!folder) continue;
-    const p = join(dir, folder, "ENV.md");
+    if (!isIDESupported(ide)) continue;
+    const p = join(dir, `.${getIDEFolder(ide)}`, "ENV.md");
     if (existsSync(p)) found.push({ ide, path: p, root: dir });
   }
   return found;
@@ -65,13 +46,10 @@ export function deriveWorkspaceName(envPath) {
 export function resolveEnvPath(cwd, flags = {}) {
   // 1. --env-file
   if (flags["env-file"]) {
-    const p = isAbsolute(flags["env-file"])
-      ? flags["env-file"]
-      : join(cwd, flags["env-file"]);
+    const p = isAbsolute(flags["env-file"]) ? flags["env-file"] : join(cwd, flags["env-file"]);
     if (!existsSync(p)) {
       throw new Error(
-        `ENV.md não encontrado: ${p}\n` +
-          `Dica: verifique o path passado em --env-file`,
+        `ENV.md não encontrado: ${p}\n` + `Dica: verifique o path passado em --env-file`
       );
     }
     return { path: p, source: "--env-file", warnings: [], root: dirname(dirname(p)) };
@@ -79,10 +57,9 @@ export function resolveEnvPath(cwd, flags = {}) {
 
   // 2. --ide (cwd e ancestrais — abre um repo filho e ainda acha o workspace)
   if (flags.ide) {
-    if (!IDE_DIRS[flags.ide]) {
+    if (!isIDESupported(flags.ide)) {
       throw new Error(
-        `IDE não suportada: "${flags.ide}"\n` +
-          `IDEs válidas: ${Object.keys(IDE_DIRS).join(", ")}`,
+        `IDE não suportada: "${flags.ide}"\n` + `IDEs válidas: ${getIDEValues().join(", ")}`
       );
     }
     for (const dir of walkAncestors(cwd)) {
@@ -98,7 +75,7 @@ export function resolveEnvPath(cwd, flags = {}) {
     }
     throw new Error(
       `ENV.md não encontrado para --ide ${flags.ide} a partir de ${cwd}\n` +
-        `Dica: rode jarvis init --ide ${flags.ide} na pasta do workspace`,
+        `Dica: rode jarvis init --ide ${flags.ide} na pasta do workspace`
     );
   }
 
@@ -114,7 +91,7 @@ export function resolveEnvPath(cwd, flags = {}) {
   }
 
   // 4. IDE env var
-  if (process.env.IDE && IDE_DIRS[process.env.IDE]) {
+  if (process.env.IDE && isIDESupported(process.env.IDE)) {
     for (const dir of walkAncestors(cwd)) {
       const found = envsAt(dir, process.env.IDE);
       if (found.length === 1) {
@@ -135,7 +112,7 @@ export function resolveEnvPath(cwd, flags = {}) {
       const ides = found.map((f) => f.ide).join(" | ");
       throw new Error(
         `Múltiplos ENV.md encontrados em ${dir} (${ides}).\n` +
-          `Especifique a IDE ativa. Exemplo: --ide claude`,
+          `Especifique a IDE ativa. Exemplo: --ide claude`
       );
     }
     if (found.length === 1) {

package/bin/lib/flow-map/index.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Índice nome → artefato (workflows, skills e agentes ativos).
+ *
+ * Montado a cada execução, sem arquivo persistido. O nome identifica o item:
+ * - workflow: arquivo `workflows/**\/{nome}.md` (sem README e AGENTS)
+ * - skill: pasta `skills/{nome}/SKILL.md`
+ * - agente: arquivo `agents/**\/{nome}.md` (fora de `archive/`, sem README e AGENTS)
+ * @module flow-map/index
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+
+const IGNORED_FILES = new Set(["README.md", "AGENTS.md"]);
+
+function walkMarkdown(dir, skipDirs = []) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      return skipDirs.includes(name) ? [] : walkMarkdown(path, skipDirs);
+    }
+    return name.endsWith(".md") && !IGNORED_FILES.has(name) ? [path] : [];
+  });
+}
+
+/**
+ * @typedef {Object} FlowItem
+ * @property {string} name
+ * @property {"workflow" | "skill" | "agent"} type
+ * @property {string} path - Caminho relativo à raiz do framework, com `/`
+ */
+
+/**
+ * @param {string} root - Raiz do framework (`workflows/`, `skills/`, `agents/`)
+ * @returns {{ items: Map<string, FlowItem>, duplicates: string[] }}
+ */
+export function buildIndex(root) {
+  const items = new Map();
+  const duplicates = [];
+  const rel = (path) => relative(root, path).split(sep).join("/");
+
+  function add(item) {
+    if (items.has(item.name)) duplicates.push(item.name);
+    else items.set(item.name, item);
+  }
+
+  for (const file of walkMarkdown(join(root, "workflows"))) {
+    add({ name: basename(file, ".md"), type: "workflow", path: rel(file) });
+  }
+
+  const skillsDir = join(root, "skills");
+  if (existsSync(skillsDir)) {
+    for (const dir of readdirSync(skillsDir)) {
+      const skillMd = join(skillsDir, dir, "SKILL.md");
+      if (existsSync(skillMd)) add({ name: dir, type: "skill", path: rel(skillMd) });
+    }
+  }
+
+  for (const file of walkMarkdown(join(root, "agents"), ["archive"])) {
+    add({ name: basename(file, ".md"), type: "agent", path: rel(file) });
+  }
+
+  return { items, duplicates };
+}