jarvis-ai-framework 6.0.0 → 7.0.0

package/bin/lib/core/env-upgrade.js

@@ -1,8 +1,11 @@
 // Upgrade do ENV.md (`jarvis init --upgrade`): acrescenta as chaves do template que faltam.
 // Regra: só acrescenta. Nenhuma chave existente muda, preenchida, vazia ou com lista de opções.
-// Mesmas regras do Upgrade (C) do skill jarvis-init (itens 4, 5, 9, 10 e 11).
+// Exceção declarada (automática): `JARVIS_PROJECT=` vazio recebe o valor oficial do template.
+// As outras exceções (CENTRAL_DOCS_LOCATION e esvaziar o TOKEN_TASK_MANAGER) pedem confirmação
+// e ficam no Upgrade (C) do skill jarvis-init (item 9). Mesmas regras dos itens 4, 5, 9, 10 e 11.
 import { readFileSync, writeFileSync } from "node:fs";
 import { detectWorkspaceMode } from "./workspace-mode.js";
+import { getVendor } from "../integrations/cli-runner.js";
 
 const KEY_LINE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
 
@@ -34,13 +37,21 @@ function isDataOnlyKey(key) {
   return key.startsWith("DATA_") && key !== "DATA_SPECIALIZATIONS";
 }
 
+// Chave existente e vazia que o upgrade preenche com o valor do template (exceção automática).
+const FILL_WHEN_EMPTY = ["JARVIS_PROJECT"];
+
+// Eixos de integração: vendor fora do catálogo vira aviso (o eixo fica em freelance).
+const AXES = ["TASK_MANAGER", "VERSION_CONTROL"];
+
 /**
  * Calcula o que o upgrade acrescenta, sem gravar nada.
  * @param {string} envText
  * @param {string} templateText
  * @param {{ workspaceDir?: string }} [options] - `workspaceDir`: pasta que contém o `$IDE/`, para detectar o `WORKSPACE_MODE`
- * @returns {{ added: {key: string, value: string}[], pending: string[], warnings: string[] }}
- *   `pending` e `warnings` trazem só nomes de chave, nunca valores do ENV.
+ * @returns {{ added: {key: string, value: string}[], filled: {key: string, value: string}[], pending: string[], warnings: string[] }}
+ *   `filled`: chaves existentes e vazias preenchidas com o valor do template (só `JARVIS_PROJECT`).
+ *   `pending` e `warnings` trazem só nomes de chave, nunca valores do ENV
+ *   (exceto o nome do vendor não suportado, em `UNSUPPORTED:{CHAVE}:{vendor}`).
  */
 export function planEnvUpgrade(envText, templateText, { workspaceDir } = {}) {
   const env = parseEnvEntries(envText);
@@ -49,6 +60,7 @@ export function planEnvUpgrade(envText, templateText, { workspaceDir } = {}) {
   const area = (env.get("AREA") || "").toUpperCase();
 
   const added = [];
+  const filled = [];
   const pending = [];
   const warnings = [];
 
@@ -75,23 +87,57 @@ export function planEnvUpgrade(envText, templateText, { workspaceDir } = {}) {
 
   if (env.has("PROD_MODE") && !env.get("PROD_MODE")) pending.push("PROD_MODE");
 
+  for (const key of FILL_WHEN_EMPTY) {
+    const value = template.get(key);
+    if (env.has(key) && !env.get(key) && value && !isOptionList(value)) filled.push({ key, value });
+  }
+
+  // O token não é mais usado (o login é o da CLI do vendor). Só o nome da chave sai daqui.
+  if (env.get("TOKEN_TASK_MANAGER")) warnings.push("TOKEN_TASK_MANAGER");
+
+  for (const key of AXES) {
+    const vendor = (env.get(key) || "").toLowerCase();
+    if (vendor && !isOptionList(vendor) && !getVendor(vendor)) {
+      warnings.push(`UNSUPPORTED:${key}:${vendor.replace(/[^a-z0-9_-]/g, "")}`);
+    }
+  }
+
   if (env.get("CENTRAL_DOCS_REPO") && !env.has("CENTRAL_DOCS_STORAGE")) {
     warnings.push("CENTRAL_DOCS_REPO");
   }
 
-  return { added, pending, warnings };
+  return { added, filled, pending, warnings };
 }
 
 /**
- * Grava as chaves novas no fim do ENV, num bloco datado. Nenhuma linha existente muda.
+ * Grava as chaves novas no fim do ENV, num bloco datado, e preenche as chaves de `plan.filled`
+ * (linha `CHAVE=` vazia). Nenhuma outra linha existente muda.
  * `overrides` troca o valor de chaves novas (ex.: recusa em mover os discoveries).
  * @returns {boolean} true se gravou
  */
 export function applyEnvUpgrade(envPath, plan, today, overrides = {}) {
-  if (plan.added.length === 0) return false;
-  const text = readFileSync(envPath, "utf-8");
-  const lines = plan.added.map(({ key, value }) => `${key}=${overrides[key] ?? value}`);
-  const sep = text.endsWith("\n") ? "" : "\n";
-  writeFileSync(envPath, `${text}${sep}\n# --- Upgrade ${today} ---\n${lines.join("\n")}\n`);
+  const filled = plan.filled || [];
+  if (plan.added.length === 0 && filled.length === 0) {
+    plan.filledApplied = [];
+    return false;
+  }
+  let text = readFileSync(envPath, "utf-8");
+  // `plan.filledApplied`: só as chaves que de fato mudaram (para o resumo não mentir).
+  plan.filledApplied = [];
+  for (const { key, value } of filled) {
+    const before = text;
+    // `\r?` cobre ENV com CRLF; a função evita que um `$` do valor vire referência de grupo.
+    text = text.replace(
+      new RegExp(`^([ \\t]*)${key}=[ \\t]*(\\r?)$`, "m"),
+      (_m, indent, cr) => `${indent}${key}=${value}${cr}`
+    );
+    if (text !== before) plan.filledApplied.push(key);
+  }
+  if (plan.added.length > 0) {
+    const lines = plan.added.map(({ key, value }) => `${key}=${overrides[key] ?? value}`);
+    const sep = text.endsWith("\n") ? "" : "\n";
+    text = `${text}${sep}\n# --- Upgrade ${today} ---\n${lines.join("\n")}\n`;
+  }
+  writeFileSync(envPath, text);
   return true;
 }

package/bin/lib/core/mcp-config.js

@@ -0,0 +1,197 @@
+// MCP obrigatório (Context7) no arquivo e no formato que cada IDE lê (`jarvis init`).
+// Os caminhos vêm de `getMCPTargets` (ide-config.js). Regras:
+//   - arquivo ausente → cria só com o Context7;
+//   - arquivo presente → acrescenta o `context7` se faltar, sem tocar nos outros servidores
+//     e mantendo a indentação, o BOM e a quebra de linha (LF ou CRLF);
+//   - o que não reconhece com segurança (JSON com comentários ou inválido, raiz ou lista de
+//     servidores que não é objeto, TOML que não parseia ou em que o bloco não cabe) → não mexe
+//     e devolve o trecho para a pessoa colar. O TOML é lido com parser (smol-toml), mas nunca
+//     reescrito: o bloco é acrescentado no fim;
+//   - config só global (`~/…`) → não grava fora do workspace: devolve o trecho.
+// Nada disso muda o código de saída do `jarvis init`: são avisos.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { parse as parseTomlText } from "smol-toml";
+import { getMCPTargets } from "../config/ide-config.js";
+
+export const CONTEXT7 = Object.freeze({
+  name: "context7",
+  command: "npx",
+  args: Object.freeze(["-y", "@upstash/context7-mcp"]),
+});
+
+/** Arquivo que existe mas não dá para alterar com segurança: fica intacto e vira `manual`. */
+class Unrecognized extends Error {}
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+const filled = (v) => typeof v === "string" && v.trim() !== "";
+
+/** Chaves de URL de servidor remoto: `url`, `httpUrl` (Gemini CLI), `serverUrl` (Antigravity). */
+const URL_KEYS = ["url", "httpUrl", "serverUrl"];
+
+/**
+ * A entrada parece um servidor MCP utilizável? Objeto com `command` (string não vazia ou, só
+ * onde a IDE aceita, como no OpenCode, array não vazio de strings não vazias) ou com uma URL
+ * não vazia (`URL_KEYS`).
+ */
+function looksLikeServer(entry, commandAsList) {
+  if (!isPlainObject(entry)) return false;
+  const { command } = entry;
+  const hasCommand = Array.isArray(command)
+    ? commandAsList && command.length > 0 && command.every(filled)
+    : filled(command);
+  return hasCommand || URL_KEYS.some((k) => filled(entry[k]));
+}
+
+/**
+ * O servidor `context7` já está declarado? `true` se a entrada parece um servidor
+ * (`looksLikeServer`); `false` se não existe; `Unrecognized` se existe mas não parece
+ * (`1`, `false`, `[]`, tabela vazia, `command` vazio…), para não dizer "já configurado" sem estar.
+ * Um servidor válido com `enabled = false` conta como declarado: o init não liga o que a
+ * pessoa desligou.
+ */
+function hasContext7(servers, target) {
+  if (!servers || !Object.hasOwn(servers, CONTEXT7.name)) return false;
+  if (!looksLikeServer(servers[CONTEXT7.name], target.style === "opencode")) {
+    throw new Unrecognized(
+      `"${CONTEXT7.name}" existe mas não parece um servidor (sem command nem url preenchidos)`
+    );
+  }
+  return true;
+}
+
+/** Item do servidor no formato do alvo. */
+function serverEntry(style) {
+  if (style === "opencode") {
+    return { type: "local", command: [CONTEXT7.command, ...CONTEXT7.args], enabled: true };
+  }
+  const entry = { command: CONTEXT7.command, args: [...CONTEXT7.args] };
+  return style === "stdio" ? { type: "stdio", ...entry } : entry;
+}
+
+/** Trecho pronto para colar (usado nos alvos globais e nos arquivos não reconhecidos). */
+export function mcpSnippet(target) {
+  if (target.format === "toml") {
+    return [
+      `[${target.key}.${CONTEXT7.name}]`,
+      `command = "${CONTEXT7.command}"`,
+      `args = [${CONTEXT7.args.map((a) => `"${a}"`).join(", ")}]`,
+      "",
+    ].join("\n");
+  }
+  const block = { [target.key]: { [CONTEXT7.name]: serverEntry(target.style) } };
+  return `${JSON.stringify(block, null, 2)}\n`;
+}
+
+/** Indentação de um JSON existente: tab ou N espaços (2 se não der para saber). */
+function detectIndent(text) {
+  const m = text.match(/^([ \t]+)\S/m);
+  if (!m) return 2;
+  return m[1].startsWith("\t") ? "\t" : m[1].length;
+}
+
+/** Quebra de linha usada no arquivo: CRLF se aparecer, senão LF. */
+const detectEol = (text) => (text.includes("\r\n") ? "\r\n" : "\n");
+
+const BOM = "\uFEFF";
+
+function ensureJson(file, target) {
+  let data = {};
+  let indent = 2;
+  let bom = "";
+  let eol = "\n";
+  if (existsSync(file)) {
+    const raw = readFileSync(file, "utf-8");
+    bom = raw.startsWith(BOM) ? BOM : "";
+    const text = raw.slice(bom.length);
+    indent = detectIndent(text);
+    eol = detectEol(text);
+    try {
+      data = JSON.parse(text);
+    } catch (err) {
+      const detail = err.message.split("\n")[0];
+      const reason = "não consegui ler o JSON com segurança (comentários ou erro de sintaxe";
+      throw new Unrecognized(`${reason}: ${detail})`);
+    }
+    if (!isPlainObject(data)) throw new Unrecognized("o arquivo não é um objeto JSON");
+  } else if (target.style === "opencode") {
+    data.$schema = "https://opencode.ai/config.json";
+  }
+  const current = data[target.key];
+  if (current != null && !isPlainObject(current)) {
+    throw new Unrecognized(`"${target.key}" não é um objeto`);
+  }
+  const servers = current ?? {};
+  if (hasContext7(servers, target)) return false;
+  data[target.key] = { ...servers, [CONTEXT7.name]: serverEntry(target.style) };
+  mkdirSync(dirname(file), { recursive: true });
+  const body = JSON.stringify(data, null, indent).replace(/\n/g, eol);
+  writeFileSync(file, `${bom}${body}${eol}`);
+  return true;
+}
+
+/** Lê um TOML; devolve `null` se não parseia. */
+function parseToml(text) {
+  try {
+    return parseTomlText(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Codex: lê o `config.toml` com um parser (smol-toml) para saber se o servidor já existe.
+ * O texto nunca é reescrito pelo parser (comentários e formatação ficam); o bloco é
+ * acrescentado no fim, com o EOL do arquivo, e só se o resultado também parsear.
+ */
+function ensureToml(file, target) {
+  const text = existsSync(file) ? readFileSync(file, "utf-8") : "";
+  const data = parseToml(text);
+  if (!data) throw new Unrecognized("o TOML não pôde ser lido (sintaxe inválida)");
+  const servers = data[target.key];
+  if (servers !== undefined && !isPlainObject(servers)) {
+    throw new Unrecognized(`"${target.key}" não é uma tabela`);
+  }
+  if (hasContext7(servers, target)) return false;
+  const eol = detectEol(text);
+  const sep = text === "" || text.endsWith(eol + eol) ? "" : text.endsWith(eol) ? eol : eol + eol;
+  const addition = `${sep}${mcpSnippet(target).replace(/\n/g, eol)}`;
+  if (!parseToml(text + addition)?.[target.key]?.[CONTEXT7.name]) {
+    throw new Unrecognized(`acrescentar [${target.key}.${CONTEXT7.name}] deixaria o TOML inválido`);
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, addition);
+  return true;
+}
+
+/**
+ * Garante o Context7 na configuração de MCP da IDE.
+ * @param {string} workspaceDir - pasta que contém o `$IDE/`
+ * @param {string} ide - slug da IDE
+ * @returns {{ written: string[], present: string[],
+ *   manual: {path: string, snippet: string, reason?: string}[], errors: string[] }}
+ *   caminhos relativos ao workspace (ou com `~/`, nos globais). `manual` sem `reason` é
+ *   config só global; com `reason`, é arquivo do workspace que ficou intacto.
+ */
+export function ensureContext7(workspaceDir, ide) {
+  const result = { written: [], present: [], manual: [], errors: [] };
+  for (const target of getMCPTargets(ide)) {
+    if (target.global) {
+      result.manual.push({ path: target.path, snippet: mcpSnippet(target) });
+      continue;
+    }
+    const file = join(workspaceDir, target.path);
+    try {
+      const wrote = target.format === "toml" ? ensureToml(file, target) : ensureJson(file, target);
+      (wrote ? result.written : result.present).push(target.path);
+    } catch (err) {
+      if (err instanceof Unrecognized) {
+        result.manual.push({ path: target.path, snippet: mcpSnippet(target), reason: err.message });
+      } else {
+        result.errors.push(`${target.path}: ${err.message.split("\n")[0]}`);
+      }
+    }
+  }
+  return result;
+}

package/bin/lib/core/workspace-mode.js

@@ -25,17 +25,28 @@ function listGitSubdirs(dir) {
     .sort();
 }
 
+/**
+ * A raiz é um repositório (tem `.git`, pasta ou arquivo)? É o critério do `.gitignore`:
+ * só se cria ou altera o `.gitignore` de uma raiz versionada. Uma pasta sem nenhum `.git`
+ * é `project` para o modo, mas não é versionada.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function rootIsRepo(dir) {
+  return existsSync(join(dir, ".git"));
+}
+
 /**
  * @param {string} workspaceDir - pasta que contém o `$IDE/`
  * @param {{ repos?: string[] }} [options] - `repos`: allowlist (WORKSPACE_REPOS); vazia = todas
  * @returns {{ mode: "workspace"|"project", repos: string[], warning: string|null }}
  */
 export function detectWorkspaceMode(workspaceDir, { repos = [] } = {}) {
-  const rootIsRepo = existsSync(join(workspaceDir, ".git"));
+  const isRepo = rootIsRepo(workspaceDir);
   const allow = new Set(repos);
   const found = listGitSubdirs(workspaceDir).filter((n) => allow.size === 0 || allow.has(n));
 
-  if (rootIsRepo) {
+  if (isRepo) {
     return {
       mode: "project",
       repos: [],

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

@@ -18,7 +18,10 @@ import { getStorage } from "./storage/index.js";
 export function openStorageFromEnv(flags = {}, { cwd = process.cwd(), deps } = {}) {
   const { path, root } = resolveEnvPath(cwd, flags);
   const env = loadEnv(cwd, path);
-  return { env, root, storage: getStorage(env, { root, deps }) };
+  // O ENV.md lido aqui (com --ide/--env-file) segue até o gate do acesso no MR do Central docs
+  // (o `docs sync` e o `fetch` não abrem MR e ignoram o fileEnvResult).
+  const storageDeps = { fileEnvResult: { vars: env, error: null }, ...deps };
+  return { env, root, storage: getStorage(env, { root, deps: storageDeps }) };
 }
 
 /**

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

@@ -3,7 +3,7 @@
  * (`CENTRAL_DOCS_STORAGE`), a consolidação do que foi implementado, gerada pelo
  * `/eng.spec-consolidate`: o documento da funcionalidade (`feature-*.md`, em
  * `{SQUAD}/product/{produto}/`) e o registro da entrega (`delivery-*.md`, em
- * `{SQUAD}/engineering/{produto}/`). Documentos de trabalho (PRD, FRD, ARD, RFC…)
+ * `{SQUAD}/engineering/{produto}/`). Documentos de trabalho (PRD, FRD, ARD, RFC, SPEC…)
  * não são publicados. O índice do squad é regenerado a cada publicação.
  * @module docs/publish-file
  */
@@ -28,6 +28,7 @@ export const WORKING_DOC_TYPES = Object.freeze([
   "task",
   "ard",
   "rfc",
+  "spec",
   "swagger",
   "qa-report",
 ]);

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

@@ -12,7 +12,7 @@
 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 { createMergeRequest as defaultCreateMergeRequest, newMergeRequestUrl } from "../../vcs/api.js";
 import { logger } from "../../utils/logger.js";
 import { buildIndex, walkFiles } from "./build-index.js";
 
@@ -55,7 +55,8 @@ export function safePath(root, rel) {
  * @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)
+ * @param {Object} [cfg.deps] - `runGit` e `createMergeRequest` injetáveis (testes); `fileEnvResult`:
+ *   o ENV.md já lido pelo comando, repassado ao gate do `VERSION_CONTROL_ACCESS` no MR
  */
 export function createFilesystemStorage({
   location,
@@ -183,12 +184,34 @@ export function createFilesystemStorage({
         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,
-        });
+        let mr = null;
+        try {
+          // O ENV.md que o comando já leu (com --ide/--env-file) vai junto para o gate do acesso.
+          mr = await createMergeRequest(
+            remoteUrl,
+            {
+              source: branch,
+              target: targetBranch,
+              title: `docs(${squad}): ${tipo} ${basename(destPath)}`,
+              description,
+            },
+            deps.fileEnvResult ? { fileEnvResult: deps.fileEnvResult } : {}
+          );
+        } catch (error) {
+          // Indisponível (sem CLI ou sem login): o push já foi feito, o MR fica para abrir à mão.
+          // Enviado com erro continua subindo: o MR pode ter sido criado.
+          if (error.sent) throw error;
+          let link = "";
+          try {
+            link = newMergeRequestUrl(remoteUrl, branch, targetBranch);
+          } catch {
+            // remote fora de github/gitlab: sem link
+          }
+          logger.warn(
+            `⚠️  MR não aberto (${error.message.split("\n")[0]}). A branch ${branch} já está no remote` +
+              (link ? `; abra o MR à mão: ${link}` : "; abra o MR à mão no host.")
+          );
+        }
 
         return { destPath, indexPath, sha, branch, mr };
       } finally {

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

@@ -2,7 +2,8 @@ import { readFileSync } from 'node:fs'
 import { parseFrontmatter, extractFrontmatterBlock } from '../utils/frontmatter.js'
 
 /**
- * Valida frontmatter YAML de documentos (PRD, FRD, épico, história, tarefa, ARD, RFC)
+ * Valida frontmatter YAML da consolidação do Central docs (feature, delivery) e de documentos
+ * de trabalho (PRD, FRD, épico, história, tarefa, ARD, RFC, relatório de QA)
  * 
  * @param {string} filePath - Caminho do arquivo
  * @param {string} tipo - Tipo do documento (ver VALID_TYPES em publish-file.js)
@@ -55,10 +56,11 @@ export function validateFrontmatter(filePath, tipo) {
 
   // Validar status
   // Produto (rules/product/prod-rules.md), ARD (templates/engineering/ARD-template.md),
-  // discovery (prod-discovery-template.md) e RFC (RFC-template.md)
+  // discovery (prod-discovery-template.md), RFC (RFC-template.md) e
+  // SPEC (templates/engineering/ref-spec-template.md)
   const validStatuses = [
     'icebox', 'in_review', 'backlog', 'in_progress', 'in_production', 'cancelled', 'deprecated',
-    'proposed', 'approved',
+    'proposed', 'approved', 'superseded',
     'Draft', 'In Review', 'Ready for Decision', 'Accepted', 'Rejected', 'Superseded'
   ]