jarvis-ai-framework 3.2.0 → 4.0.0

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

@@ -1,194 +1,122 @@
 /**
- * @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.
+ * @fileoverview Publica um documento no Central docs pelo adaptador configurado
+ * (`CENTRAL_DOCS_STORAGE`). O destino segue a estrutura única
+ * `{SQUAD}/{product|engineering}/{produto}/{arquivo}` e o índice do squad é
+ * regenerado a cada publicação (ver `storage/build-index.js`).
  * @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 { basename, extname } from "node:path";
+import { validateFrontmatter } from "./validate-frontmatter.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" };
+/** @constant {Readonly<Record<string, "product"|"engineering">>} Área de cada tipo */
+export const AREA_BY_TYPE = Object.freeze({
+  prd: "product",
+  frd: "product",
+  feat: "product",
+  epic: "product",
+  story: "product",
+  task: "product",
+  ard: "engineering",
+  rfc: "engineering",
+  swagger: "engineering",
+  "qa-report": "engineering",
+});
+
+/** @constant {ReadonlyArray<string>} Tipos aceitos pelo `jarvis docs publish` */
+export const VALID_TYPES = Object.freeze(Object.keys(AREA_BY_TYPE));
+
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+function assertSegment(label, value) {
+  if (!value || !SEGMENT.test(value)) {
+    throw new Error(
+      `${label} inválido: "${value ?? ""}" (use letras, números, "-" ou "_", sem "/" nem "..")`
+    );
   }
-
-  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 }}
+ * Calcula o destino do documento no Central docs.
+ * O nome é o do arquivo local quando ele já segue `{tipo}-…` (ex: `prd-001-checkout.md`);
+ * senão vem de `--feature` (`{tipo}-{feature}.{ext}`).
+ *
+ * @param {Object} p
+ * @param {string} p.tipo
+ * @param {string} p.squad
+ * @param {string} p.produto - Padrão: WORKSPACE (o caller resolve)
+ * @param {string} p.localFile
+ * @param {string} [p.feature]
+ * @returns {{ destPath: string, area: "product"|"engineering", fileName: string }}
  */
-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 };
-    }
+export function resolveDestPath({ tipo, squad, produto, localFile, feature }) {
+  const area = AREA_BY_TYPE[tipo];
+  if (!area) {
+    throw new Error(`Tipo inválido: ${tipo}\nTipos válidos: ${VALID_TYPES.join(", ")}`);
+  }
+  assertSegment("Squad", squad);
+  assertSegment("Produto", produto);
+
+  const local = basename(localFile);
+  const ext = extname(local).toLowerCase() || ".md";
+  const followsPattern = local.toLowerCase().startsWith(`${tipo}-`) && /\.(md|ya?ml|json)$/.test(ext);
+
+  let fileName;
+  if (followsPattern) {
+    fileName = local;
+  } else if (feature) {
+    assertSegment("Feature", feature);
+    fileName = `${tipo}-${feature}${ext}`;
+  } else {
+    throw new Error(
+      `O arquivo "${local}" não segue o padrão {tipo}-{id}-{nome}${ext}.\n` +
+        `Renomeie o arquivo ou informe --feature <slug>.`
+    );
   }
 
-  const trimmed = content.replace(/\n+$/, "");
-  return { content: `${trimmed}\n\n## ${area}\n${newLine}\n`, found: false };
+  return { destPath: `${squad}/${area}/${produto}/${fileName}`, area, fileName };
 }
 
 /**
  * @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 } }>}
+ * @param {Object} opts.storage - Adaptador (`getStorage`)
+ * @param {string} opts.localFile
+ * @param {string} opts.tipo
+ * @param {string} opts.squad
+ * @param {string} opts.produto
+ * @param {string} [opts.feature]
+ * @returns {Promise<{ destPath: string, indexPath: string, sha?: string, branch?: string, mr?: Object }>}
  */
-export async function publishFile(opts) {
-  const {
-    localFile,
-    tipo,
-    feature,
-    squad,
-    workspace,
-    repo,
-    targetBranch = "dev",
-    cacheTtl = "3600",
-  } = opts;
-
-  if (!repo) {
+export async function publishFile({ storage, localFile, tipo, squad, produto, feature }) {
+  if (!storage) {
     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"
+      "Central docs desligado (CENTRAL_DOCS_STORAGE vazio). Configure-o no /jarvis-init."
     );
   }
 
-  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 } = resolveDestPath({ tipo, squad, produto, localFile, feature });
 
-  const { destPath, area } = resolveDestPath({ tipo, squad, workspace, feature, localFile });
-  const indexPath = `${squad}/${workspace}/index.md`;
-  const branchName = `docs/${squad}/${workspace}/${tipo}-${feature}`;
+  const isStructuredSwagger = tipo === "swagger" && !localFile.toLowerCase().endsWith(".md");
+  if (!isStructuredSwagger) {
+    logger.info("Validando frontmatter...");
+    validateFrontmatter(localFile, tipo);
+    logger.info("✅ Frontmatter válido");
+  }
 
   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(`  Armazenamento: ${storage.kind}${storage.isGit ? " (git)" : ""}`);
   logger.info(`  Destino: ${destPath}`);
-  logger.info(`  Branch: ${branchName} → ${targetBranch}`);
   logger.info("");
 
-  const fileContentBase64 = readFileSync(localFile).toString("base64");
+  const result = await storage.publish({ localFile, destPath, squad, tipo });
 
-  logger.info("Buscando index.md do workspace...");
-  let indexContent = "";
-  try {
-    indexContent = await fetchFile(indexPath, targetBranch, { repo, cacheTtl });
-  } catch {
-    indexContent = "";
+  logger.info(`✅ Publicado em ${destPath}`);
+  logger.info(`🗂️  Índice regenerado: ${result.indexPath}`);
+  if (result.mr) {
+    logger.info(`🔀 Pull/Merge Request: ${result.mr.url}`);
   }
 
-  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 };
+  return result;
 }

package/bin/lib/docs/storage/build-index.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Gera o `{SQUAD}/index.md` do Central docs a partir do frontmatter
+ * dos documentos. O índice é sempre regenerado pela listagem (nunca editado), para
+ * duas publicações seguidas não apagarem a entrada uma da outra.
+ * @module docs/storage/build-index
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { parseFrontmatter } from "../../utils/frontmatter.js";
+
+/** @constant {ReadonlyArray<string>} Áreas do Central docs, na ordem do índice */
+export const AREAS = Object.freeze(["product", "engineering"]);
+
+/**
+ * Lista arquivos (recursivo) de uma pasta, em ordem alfabética.
+ * @param {string} dir
+ * @returns {string[]} caminhos absolutos
+ */
+export function walkFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .sort()
+    .flatMap((name) => {
+      const full = join(dir, name);
+      return statSync(full).isDirectory() ? walkFiles(full) : [full];
+    });
+}
+
+/**
+ * Monta o conteúdo do índice de um squad.
+ * Formato: `# SQUAD` › `## área` › `### produto` › `- [arquivo](caminho) | vX | status | nome`.
+ * @param {string} root - Pasta do Central docs
+ * @param {string} squad
+ * @returns {string}
+ */
+export function renderIndex(root, squad) {
+  const out = [`# ${squad}`, ""];
+
+  for (const area of AREAS) {
+    const areaDir = join(root, squad, area);
+    const files = walkFiles(areaDir).filter((f) => !f.endsWith(`${sep}index.md`));
+    out.push(`## ${area}`, "");
+    if (files.length === 0) {
+      out.push("_Nenhum documento._", "");
+      continue;
+    }
+
+    const byProduct = new Map();
+    for (const file of files) {
+      const [product = "", ...rest] = relative(areaDir, file).split(sep);
+      if (rest.length === 0) continue; // arquivo solto na área, sem pasta de produto
+      if (!byProduct.has(product)) byProduct.set(product, []);
+      byProduct.get(product).push(file);
+    }
+
+    for (const [product, productFiles] of byProduct) {
+      out.push(`### ${product}`);
+      for (const file of productFiles) {
+        const rel = relative(join(root, squad), file).split(sep).join("/");
+        const name = rel.split("/").pop();
+        const meta = file.endsWith(".md") ? parseFrontmatter(readFileSync(file, "utf-8")) : {};
+        let line = `- [${name}](${rel})`;
+        if (meta.version) line += ` | v${meta.version}`;
+        if (meta.status) line += ` | ${meta.status}`;
+        if (meta.name) line += ` | ${meta.name}`;
+        out.push(line);
+      }
+      out.push("");
+    }
+  }
+
+  return out.join("\n").replace(/\n+$/, "\n");
+}
+
+/**
+ * Regenera e grava `{root}/{squad}/index.md`.
+ * @param {string} root - Pasta do Central docs
+ * @param {string} squad
+ * @returns {{ path: string, content: string }}
+ */
+export function buildIndex(root, squad) {
+  const content = renderIndex(root, squad);
+  const path = join(root, squad, "index.md");
+  writeFileSync(path, content);
+  return { path, content };
+}

package/bin/lib/docs/storage/filesystem.js

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Adaptador `filesystem` do Central docs: uma pasta do disco
+ * (dentro do workspace ou em qualquer caminho). Se a pasta tiver `.git` (clone
+ * de um repositório de documentação), liga a camada git: `pull` antes de ler e
+ * branch + commit + push + PR ao publicar.
+ *
+ * Todo comando externo usa `execFileSync` com argumentos (sem shell), e todo
+ * caminho recebido é resolvido dentro da pasta (sem `..`).
+ * @module docs/storage/filesystem
+ */
+
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createMergeRequest as defaultCreateMergeRequest } from "../../vcs/api.js";
+import { logger } from "../../utils/logger.js";
+import { buildIndex, walkFiles } from "./build-index.js";
+
+/**
+ * Executa `git` na pasta informada, sem shell.
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string} stdout sem espaços nas pontas
+ */
+export function runGit(args, cwd) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/**
+ * Resolve um caminho relativo dentro de `root`, rejeitando o que sair dela.
+ * @param {string} root
+ * @param {string} rel
+ * @returns {string} caminho absoluto
+ * @throws {Error} caminho absoluto, com `..` que escape da pasta, ou vazio
+ */
+export function safePath(root, rel) {
+  if (!rel || isAbsolute(rel)) {
+    throw new Error(`Caminho inválido para o Central docs: "${rel}"`);
+  }
+  const full = resolve(root, rel);
+  const fromRoot = relative(root, full);
+  if (fromRoot === "" || fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+    throw new Error(`Caminho fora da pasta do Central docs: "${rel}"`);
+  }
+  return full;
+}
+
+/**
+ * @param {Object} cfg
+ * @param {string} cfg.location - Pasta do Central docs (absoluta)
+ * @param {string} [cfg.ref] - Branch lida no `pull` (CENTRAL_DOCS_REF)
+ * @param {string} [cfg.targetBranch] - Branch base do PR (CENTRAL_DOCS_TARGET_BRANCH)
+ * @param {string} [cfg.reviewers] - Revisores (vão na descrição do PR)
+ * @param {Object} [cfg.deps] - `runGit` e `createMergeRequest` injetáveis (testes)
+ */
+export function createFilesystemStorage({
+  location,
+  ref = "main",
+  targetBranch = "main",
+  reviewers = "",
+  deps = {},
+}) {
+  const git = deps.runGit ?? runGit;
+  const createMergeRequest = deps.createMergeRequest ?? defaultCreateMergeRequest;
+  const isGit = existsSync(join(location, ".git"));
+  let pulled = false;
+
+  /** `git pull --ff-only` uma vez por instância; falha vira aviso e a leitura segue local. */
+  function pullOnce() {
+    if (!isGit || pulled) return;
+    pulled = true;
+    try {
+      git(["pull", "--ff-only", "origin", ref], location);
+    } catch (error) {
+      logger.warn(`⚠️  Não foi possível atualizar o Central docs (git pull): ${error.message.split("\n")[0]}`);
+      logger.warn("   Usando a cópia local.");
+    }
+  }
+
+  function ensureLocation() {
+    if (!existsSync(location)) {
+      throw new Error(
+        `Pasta do Central docs não encontrada: ${location}\nCrie a pasta ou ajuste CENTRAL_DOCS_LOCATION no ENV.md (/jarvis-init).`
+      );
+    }
+  }
+
+  return {
+    kind: "filesystem",
+    location,
+    isGit,
+
+    /**
+     * Lê um documento.
+     * @param {string} path - Caminho dentro do Central docs (ex: `CORE/index.md`)
+     * @returns {Promise<string>}
+     * @throws {Error} com `code = 404` se o arquivo não existir
+     */
+    async fetch(path) {
+      ensureLocation();
+      pullOnce();
+      const full = safePath(location, path);
+      if (!existsSync(full)) {
+        const err = new Error(`Arquivo não encontrado no Central docs: ${path}`);
+        err.code = 404;
+        throw err;
+      }
+      return readFileSync(full, "utf-8");
+    },
+
+    /**
+     * Lista os `.md` sob um prefixo.
+     * @param {string} prefix
+     * @returns {Promise<string[]>} caminhos relativos à pasta, com `/`
+     */
+    async list(prefix) {
+      ensureLocation();
+      pullOnce();
+      return walkFiles(safePath(location, prefix))
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => relative(location, f).split(sep).join("/"));
+    },
+
+    /**
+     * Regenera `{squad}/index.md`. Com `.git` e `scripts/build-index.sh` no repositório,
+     * usa o script dele (o CI do repositório confere o índice com ele).
+     * @param {string} squad
+     * @returns {string} caminho relativo do índice
+     */
+    buildIndex(squad) {
+      const script = join(location, "scripts", "build-index.sh");
+      if (isGit && existsSync(script)) {
+        execFileSync("bash", [script], { cwd: location, stdio: ["ignore", "pipe", "pipe"] });
+      } else {
+        buildIndex(location, squad);
+      }
+      return `${squad}/index.md`;
+    },
+
+    /**
+     * Grava um documento e regenera o índice do squad.
+     * Sem `.git`: copia e pronto. Com `.git`: branch → cópia → índice → commit → push → PR.
+     * @param {Object} p
+     * @param {string} p.localFile - Arquivo de origem
+     * @param {string} p.destPath - Destino dentro do Central docs (`{SQUAD}/{área}/{produto}/{arquivo}`)
+     * @param {string} p.squad
+     * @param {string} p.tipo
+     * @returns {Promise<{ destPath: string, indexPath: string, sha?: string, branch?: string, mr?: Object }>}
+     */
+    async publish({ localFile, destPath, squad, tipo }) {
+      ensureLocation();
+      const dest = safePath(location, destPath);
+
+      if (!isGit) {
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(localFile, dest);
+        const indexPath = this.buildIndex(squad);
+        return { destPath, indexPath };
+      }
+
+      const branch = `docs/${destPath.replace(extname(destPath), "")}`;
+      git(["checkout", targetBranch], location);
+      try {
+        git(["pull", "--ff-only", "origin", targetBranch], location);
+      } catch (error) {
+        logger.warn(`⚠️  git pull falhou (${error.message.split("\n")[0]}); seguindo com a cópia local.`);
+      }
+      git(["checkout", "-b", branch], location);
+
+      try {
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(localFile, dest);
+        const indexPath = this.buildIndex(squad);
+        git(["add", "--", destPath, indexPath], location);
+        git(["commit", "-m", `docs(${squad}): add ${tipo} ${basename(destPath)}`], location);
+        const sha = git(["rev-parse", "HEAD"], location);
+
+        git(["push", "-u", "origin", branch], location);
+        const remoteUrl = git(["remote", "get-url", "origin"], location);
+        let description = `## Documento\n\n- **Tipo**: ${tipo}\n- **Arquivo**: \`${destPath}\``;
+        if (reviewers) description += `\n- **Revisores**: ${reviewers}`;
+        const mr = await createMergeRequest(remoteUrl, {
+          source: branch,
+          target: targetBranch,
+          title: `docs(${squad}): ${tipo} ${basename(destPath)}`,
+          description,
+        });
+
+        return { destPath, indexPath, sha, branch, mr };
+      } finally {
+        try {
+          git(["checkout", targetBranch], location);
+        } catch {
+          // a branch de trabalho fica; o erro original (se houver) é o que importa
+        }
+      }
+    },
+  };
+}

package/bin/lib/docs/storage/index.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Fábrica dos adaptadores de armazenamento do Central docs.
+ * O valor de `CENTRAL_DOCS_STORAGE` escolhe o adaptador; `CENTRAL_DOCS_LOCATION`
+ * diz onde ele guarda. Hoje só existe o `filesystem` (com camada git opcional);
+ * S3 e Google Drive são as issues #144 e #145.
+ * @module docs/storage
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { createFilesystemStorage } from "./filesystem.js";
+
+/** @constant {ReadonlyArray<string>} Adaptadores disponíveis */
+export const SUPPORTED_STORAGES = Object.freeze(["filesystem"]);
+
+/**
+ * Erro de configuração do Central docs (variável ausente, valor não suportado).
+ */
+export class StorageConfigError extends Error {}
+
+/**
+ * Resolve `CENTRAL_DOCS_LOCATION` a partir da pasta do workspace (a que contém `$IDE/`).
+ * @param {string} location
+ * @param {string} root - Pasta do workspace
+ * @returns {string} caminho absoluto
+ */
+export function resolveLocation(location, root) {
+  return isAbsolute(location) ? location : resolve(root, location);
+}
+
+/**
+ * Devolve o adaptador configurado no ENV.md, ou `null` se o Central docs estiver desligado.
+ *
+ * @param {Record<string, string>} env - Variáveis do ENV.md (`loadEnv`)
+ * @param {Object} opts
+ * @param {string} opts.root - Pasta do workspace (`resolveEnvPath(...).root`)
+ * @param {Object} [opts.deps] - Dependências injetáveis (testes): `runGit`, `createMergeRequest`
+ * @returns {ReturnType<typeof createFilesystemStorage> | null}
+ * @throws {StorageConfigError} valor de STORAGE não suportado, LOCATION ausente ou variável antiga
+ */
+export function getStorage(env, { root, deps } = {}) {
+  const storage = (env.CENTRAL_DOCS_STORAGE || "").trim().toLowerCase();
+
+  if (!storage) {
+    if (env.CENTRAL_DOCS_REPO) {
+      throw new StorageConfigError(
+        "CENTRAL_DOCS_REPO não é mais usado. Rode o /jarvis-init e escolha Upgrade (C) para migrar " +
+          "para CENTRAL_DOCS_STORAGE + CENTRAL_DOCS_LOCATION."
+      );
+    }
+    return null;
+  }
+
+  if (!SUPPORTED_STORAGES.includes(storage)) {
+    throw new StorageConfigError(
+      `Armazenamento "${storage}" ainda não suportado. Use: ${SUPPORTED_STORAGES.join(", ")}.`
+    );
+  }
+
+  if (!env.CENTRAL_DOCS_LOCATION) {
+    throw new StorageConfigError(
+      "CENTRAL_DOCS_LOCATION não definido no ENV.md (pasta do Central docs)."
+    );
+  }
+  if (!root) {
+    throw new StorageConfigError("getStorage: pasta do workspace (root) não informada.");
+  }
+
+  return createFilesystemStorage({
+    location: resolveLocation(env.CENTRAL_DOCS_LOCATION, root),
+    ref: env.CENTRAL_DOCS_REF || "main",
+    targetBranch: env.CENTRAL_DOCS_TARGET_BRANCH || "main",
+    reviewers: env.CENTRAL_DOCS_REVIEWERS || "",
+    deps,
+  });
+}