jarvis-ai-framework 1.0.0

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

@@ -0,0 +1,284 @@
+#!/bin/bash
+# Publica documento no central-docs (GitLab / GitHub / Bitbucket) via branch + MR/PR
+
+set -e
+
+LOCAL_FILE="$1"      # Ex: ./docs/engineering/ard-api-wallet.md
+TIPO="$2"            # prd|frd|ard|rfc
+FEATURE="$3"         # Ex: api-wallet-auth-jwt
+
+# Resolver path absoluto do script (independente de cwd)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ -z "$LOCAL_FILE" ] || [ -z "$TIPO" ] || [ -z "$FEATURE" ]; then
+  echo "Uso: publish-file.sh <local-file> <tipo> <feature>" >&2
+  echo "Tipos válidos: prd, frd, ard, rfc, swagger, qa-report" >&2
+  exit 1
+fi
+
+if [ ! -f "$LOCAL_FILE" ]; then
+  echo "Erro: Arquivo não encontrado: $LOCAL_FILE" >&2
+  exit 1
+fi
+
+# Detectar IDE directory
+if [ -d ".windsurf" ]; then
+  IDE=".windsurf"
+elif [ -d ".claude" ]; then
+  IDE=".claude"
+elif [ -d ".cursor" ]; then
+  IDE=".cursor"
+elif [ -d ".vscode" ]; then
+  IDE=".vscode"
+else
+  echo "Erro: IDE directory não encontrado (.windsurf, .claude, .cursor, .vscode)" >&2
+  exit 1
+fi
+
+# 1. Ler ENV.md (se não houver override)
+if [ -n "$SQUAD_OVERRIDE" ] && [ -n "$WORKSPACE_OVERRIDE" ]; then
+  # Usar override das variáveis de ambiente
+  SQUAD="$SQUAD_OVERRIDE"
+  WORKSPACE="$WORKSPACE_OVERRIDE"
+else
+  # Ler do ENV.md
+  if [ ! -f "$IDE/ENV.md" ]; then
+    echo "Erro: ENV.md não encontrado em $IDE/" >&2
+    echo "Ou passe --squad e --workspace via CLI" >&2
+    exit 1
+  fi
+
+  SQUAD=$(grep '^SQUAD=' "$IDE/ENV.md" | cut -d'=' -f2 | tr -d ' ')
+  WORKSPACE=$(grep '^WORKSPACE=' "$IDE/ENV.md" | cut -d'=' -f2 | tr -d ' ')
+  
+  if [ -z "$SQUAD" ] || [ -z "$WORKSPACE" ]; then
+    echo "Erro: SQUAD ou WORKSPACE não definidos no ENV.md" >&2
+    echo "Ou passe --squad e --workspace via CLI" >&2
+    exit 1
+  fi
+fi
+
+TARGET_BRANCH="${CENTRAL_DOCS_TARGET_BRANCH:-dev}"
+
+if [ -z "$CENTRAL_DOCS_REPO" ]; then
+  echo "Erro: CENTRAL_DOCS_REPO não definido no ENV.md" >&2
+  exit 1
+fi
+
+# 2. Validar frontmatter
+echo "Validando frontmatter..."
+node --input-type=module -e "
+  import { validateFrontmatter } from 'file://${SCRIPT_DIR}/validate-frontmatter.js';
+  try {
+    validateFrontmatter('$LOCAL_FILE', '$TIPO');
+    console.log('✅ Frontmatter válido');
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+"
+
+if [ $? -ne 0 ]; then
+  exit 1
+fi
+
+# 3. Extrair metadados
+METADATA=$(node --input-type=module -e "
+  import { extractMetadata } from 'file://${SCRIPT_DIR}/validate-frontmatter.js';
+  const metadata = extractMetadata('$LOCAL_FILE');
+  console.log(JSON.stringify(metadata));
+")
+
+VERSION=$(echo "$METADATA" | jq -r '.version // "1.0.0"')
+STATUS=$(echo "$METADATA" | jq -r '.status // "draft"')
+JIRA=$(echo "$METADATA" | jq -r '.jira // ""')
+DOC_NAME=$(echo "$METADATA" | jq -r '.name // ""')
+
+# 4. Definir paths
+if [ "$TIPO" = "prd" ] || [ "$TIPO" = "frd" ]; then
+  DEST_PATH="${SQUAD}/${WORKSPACE}/product/${TIPO}-${FEATURE}.md"
+  AREA="product"
+elif [ "$TIPO" = "ard" ]; then
+  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/ARD/${TIPO}-${FEATURE}.md"
+  AREA="engineering"
+elif [ "$TIPO" = "rfc" ]; then
+  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/RFC/${TIPO}-${FEATURE}.md"
+  AREA="engineering"
+elif [ "$TIPO" = "swagger" ]; then
+  # Detectar extensão do arquivo (yaml, json ou md)
+  FILE_EXT="${LOCAL_FILE##*.}"
+  if [ "$FILE_EXT" = "yaml" ] || [ "$FILE_EXT" = "yml" ]; then
+    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/api-${FEATURE}.yaml"
+  elif [ "$FILE_EXT" = "json" ]; then
+    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/api-${FEATURE}.json"
+  else
+    # Default para .md (wrapper com metadados)
+    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/swagger-${FEATURE}.md"
+  fi
+  AREA="engineering"
+elif [ "$TIPO" = "qa-report" ]; then
+  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/qa/qa-report-${FEATURE}.md"
+  AREA="engineering"
+else
+  echo "Erro: Tipo inválido: $TIPO" >&2
+  echo "Tipos válidos: prd, frd, ard, rfc, swagger, qa-report" >&2
+  exit 1
+fi
+
+INDEX_PATH="${SQUAD}/${WORKSPACE}/index.md"
+BRANCH_NAME="docs/${SQUAD}/${WORKSPACE}/${TIPO}-${FEATURE}"
+
+echo ""
+echo "📋 Resumo da Publicação:"
+echo "  Squad: $SQUAD"
+echo "  Workspace: $WORKSPACE"
+echo "  Tipo: $TIPO"
+echo "  Feature: $FEATURE"
+echo "  Destino: $DEST_PATH"
+echo "  Branch: $BRANCH_NAME → $TARGET_BRANCH"
+echo ""
+
+# 5–6. Token e parse do repo ficam no adapter VCS (api.js)
+
+# 7. Ler conteúdo do arquivo local e encodar em base64
+FILE_CONTENT=$(cat "$LOCAL_FILE" | base64)
+
+# 8. Buscar index.md atual
+echo "Buscando index.md do workspace..."
+INDEX_CONTENT=$(bash "${SCRIPT_DIR}/fetch-file.sh" "$INDEX_PATH" "$TARGET_BRANCH" 2>/dev/null || echo "")
+
+if [ -z "$INDEX_CONTENT" ]; then
+  echo "⚠️  index.md não encontrado, será criado"
+  INDEX_ACTION="create"
+  INDEX_CONTENT="# $WORKSPACE
+
+**Squad:** $SQUAD
+
+## $AREA
+
+"
+else
+  INDEX_ACTION="update"
+fi
+
+# 9. Adicionar nova linha ao index.md
+NEW_LINE="- [${TIPO}-${FEATURE}.md](${AREA}/${TIPO}-${FEATURE}.md) | v${VERSION} | ${STATUS}"
+[ -n "$JIRA" ] && NEW_LINE="${NEW_LINE} | jira: ${JIRA}"
+[ -n "$DOC_NAME" ] && NEW_LINE="${NEW_LINE} | ${DOC_NAME}"
+
+# Adicionar linha na seção correta
+UPDATED_INDEX=$(echo "$INDEX_CONTENT" | awk -v line="$NEW_LINE" -v area="$AREA" '
+  /^## (product|engineering)/ {
+    print
+    if ($2 == area) {
+      found = 1
+      getline
+      print line
+    }
+    next
+  }
+  { print }
+  END {
+    if (!found) {
+      print ""
+      print "## " area
+      print line
+    }
+  }
+')
+
+UPDATED_INDEX_B64=$(echo "$UPDATED_INDEX" | base64)
+
+# 10. Criar commit via adapter VCS
+echo "Criando branch e commit..."
+
+COMMIT_JSON=$(mktemp)
+cat > "$COMMIT_JSON" <<EOF
+{
+  "branch": $(printf '%s' "$BRANCH_NAME" | jq -Rs .),
+  "startBranch": $(printf '%s' "$TARGET_BRANCH" | jq -Rs .),
+  "message": $(printf '%s' "docs(${SQUAD}): add ${TIPO} ${FEATURE}" | jq -Rs .),
+  "files": [
+    {
+      "path": $(printf '%s' "$DEST_PATH" | jq -Rs .),
+      "contentBase64": $(printf '%s' "$FILE_CONTENT" | jq -Rs .),
+      "action": "create"
+    },
+    {
+      "path": $(printf '%s' "$INDEX_PATH" | jq -Rs .),
+      "contentBase64": $(printf '%s' "$UPDATED_INDEX_B64" | jq -Rs .),
+      "action": $(printf '%s' "$INDEX_ACTION" | jq -Rs .)
+    }
+  ]
+}
+EOF
+
+COMMIT_RESULT=$(node --input-type=module -e "
+  import { readFileSync } from 'node:fs';
+  import { commitFiles } from 'file://${SCRIPT_DIR}/../vcs/api.js';
+  const opts = JSON.parse(readFileSync('$COMMIT_JSON', 'utf-8'));
+  const result = await commitFiles(process.env.CENTRAL_DOCS_REPO, opts);
+  console.log(JSON.stringify(result));
+" 2>&1)
+COMMIT_EXIT=$?
+rm -f "$COMMIT_JSON"
+
+if [ $COMMIT_EXIT -ne 0 ]; then
+  echo "❌ Erro ao criar commit:" >&2
+  echo "$COMMIT_RESULT" >&2
+  exit 1
+fi
+
+COMMIT_SHA=$(echo "$COMMIT_RESULT" | jq -r '.sha')
+echo "✅ Commit criado: $COMMIT_SHA"
+
+# 11. Criar MR/PR
+echo "Criando Merge/Pull Request..."
+
+MR_DESCRIPTION="## Documento
+
+- **Tipo**: ${TIPO}
+- **Workspace**: ${WORKSPACE}
+- **Feature**: ${FEATURE}"
+
+[ -n "$JIRA" ] && MR_DESCRIPTION="${MR_DESCRIPTION}
+- **Card**: ${JIRA}"
+
+[ -n "$DOC_NAME" ] && MR_DESCRIPTION="${MR_DESCRIPTION}
+- **Nome**: ${DOC_NAME}"
+
+BODY_FILE=$(mktemp)
+printf '%s' "$MR_DESCRIPTION" > "$BODY_FILE"
+
+MR_RESULT=$(node "${SCRIPT_DIR}/../vcs/create-merge.js" \
+  --repo "$CENTRAL_DOCS_REPO" \
+  --source "$BRANCH_NAME" \
+  --target "$TARGET_BRANCH" \
+  --title "docs(${SQUAD}): ${TIPO} ${FEATURE}" \
+  --body-file "$BODY_FILE" 2>&1)
+MR_EXIT=$?
+rm -f "$BODY_FILE"
+
+if [ $MR_EXIT -ne 0 ]; then
+  echo "❌ Erro ao criar MR/PR:" >&2
+  echo "$MR_RESULT" >&2
+  exit 1
+fi
+
+MR_URL=$(echo "$MR_RESULT" | tail -1 | jq -r '.url // empty')
+MR_IID=$(echo "$MR_RESULT" | tail -1 | jq -r '.iid // empty')
+
+echo ""
+echo "✅ Merge/Pull Request criado com sucesso!"
+echo ""
+echo "  #${MR_IID}: ${BRANCH_NAME} → ${TARGET_BRANCH}"
+echo "  URL: ${MR_URL}"
+echo ""
+
+# 12. Invalidar cache Redis
+redis-cli DEL "docs:${INDEX_PATH}:${TARGET_BRANCH}" >/dev/null 2>&1 || true
+redis-cli DEL "docs:${INDEX_PATH}:main" >/dev/null 2>&1 || true
+
+echo "🔄 Cache Redis invalidado"
+echo ""
+echo "✅ Publicação concluída!"

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

@@ -0,0 +1,157 @@
+import { readFileSync } from 'node:fs'
+
+/**
+ * Valida frontmatter YAML de documentos (PRD, FRD, ARD, RFC)
+ * 
+ * @param {string} filePath - Caminho do arquivo
+ * @param {string} tipo - Tipo do documento (prd|frd|ard|rfc)
+ * @returns {Object} Metadados extraídos
+ * @throws {Error} Se frontmatter for inválido
+ */
+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) {
+    throw new Error(
+      `Frontmatter YAML não encontrado em ${filePath}\n` +
+      'Formato esperado:\n' +
+      '---\n' +
+      'id: DOC-001\n' +
+      'version: 1.0.0\n' +
+      '---'
+    )
+  }
+
+  const frontmatter = frontmatterMatch[1]
+  const metadata = parseFrontmatter(frontmatter)
+
+  // Validar campos obrigatórios por tipo
+  const requiredFields = getRequiredFields(tipo)
+  const missingFields = []
+
+  for (const field of requiredFields) {
+    if (!metadata[field]) {
+      missingFields.push(field)
+    }
+  }
+
+  if (missingFields.length > 0) {
+    throw new Error(
+      `Campos obrigatórios ausentes no frontmatter de ${tipo.toUpperCase()}:\n` +
+      missingFields.map(f => `  - ${f}`).join('\n') +
+      '\n\nFrontmatter atual:\n' + frontmatter
+    )
+  }
+
+  // Validar formato de version (X.Y.Z)
+  if (metadata.version && !metadata.version.match(/^\d+\.\d+(\.\d+)?$/)) {
+    throw new Error(
+      `Formato de version inválido: "${metadata.version}"\n` +
+      'Formato esperado: X.Y.Z (ex: 1.0.0 ou 1.2)'
+    )
+  }
+
+  // Validar status
+  const validStatuses = ['icebox', 'in_review', 'in_progress', 'in_production', 'deprecated', 'Proposta', 'Em desenvolvimento', 'Em validação', 'Finalizada', 'Draft', 'In Review', 'Ready for Decision', 'Accepted', 'Rejected', 'Superseded']
+  
+  if (metadata.status && !validStatuses.includes(metadata.status)) {
+    console.warn(
+      `⚠️  Status "${metadata.status}" não está na lista padrão.\n` +
+      `Status válidos: ${validStatuses.join(', ')}`
+    )
+  }
+
+  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
+ * 
+ * @param {string} tipo - Tipo do documento
+ * @returns {string[]} Lista de campos obrigatórios
+ */
+function getRequiredFields(tipo) {
+  const fields = {
+    prd: ['id', 'name', 'version', 'status'],
+    frd: ['id', 'name', 'version', 'status', 'related_prd'],
+    ard: ['Status', 'Data', 'Autor', 'Versão'],
+    rfc: ['Status', 'Criado em', 'Proponente'],
+    'qa-report': ['period', 'squad', 'version']
+  }
+
+  return fields[tipo] || []
+}
+
+/**
+ * Extrai metadados específicos do frontmatter
+ * 
+ * @param {string} filePath - Caminho do arquivo
+ * @returns {Object} Metadados extraídos (id, version, status, jira, etc)
+ */
+export function extractMetadata(filePath) {
+  const content = readFileSync(filePath, 'utf-8')
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  
+  if (!frontmatterMatch) {
+    return {}
+  }
+
+  const metadata = parseFrontmatter(frontmatterMatch[1])
+
+  // Normalizar campos (suportar variações de nomenclatura)
+  const taskLink = metadata.task_link || metadata.jira
+  const jiraId = taskLink ? extractJiraFromContent(taskLink) : extractJiraFromContent(content)
+  
+  return {
+    id: metadata.id || metadata.ID,
+    name: metadata.name || metadata.Name,
+    version: metadata.version || metadata.Version || metadata.Versão,
+    status: metadata.status || metadata.Status,
+    jira: jiraId,
+    related_prd: metadata.related_prd,
+    author: metadata.author || metadata.Autor || metadata.created_by,
+    date: metadata.date || metadata.Data || metadata.created_at
+  }
+}
+
+/**
+ * Extrai Jira ID do conteúdo (fallback se não estiver no frontmatter)
+ * 
+ * @param {string} content - Conteúdo do arquivo
+ * @returns {string|null} Jira ID ou null
+ */
+function extractJiraFromContent(content) {
+  const match = content.match(/\b([A-Z]+-\d+)\b/)
+  return match ? match[1] : null
+}

package/bin/lib/env-loader.js

@@ -0,0 +1,198 @@
+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",
+];
+
+function* walkAncestors(start) {
+  let dir = start;
+  while (true) {
+    yield dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+}
+
+function envsAt(dir, ideFilter = null) {
+  const ides = ideFilter ? [ideFilter] : AUTO_DETECT_ORDER;
+  const found = [];
+  for (const ide of ides) {
+    const folder = IDE_DIRS[ide];
+    if (!folder) continue;
+    const p = join(dir, folder, "ENV.md");
+    if (existsSync(p)) found.push({ ide, path: p, root: dir });
+  }
+  return found;
+}
+
+/** Nome do workspace: pasta que contém $IDE/ (não o repo aberto). */
+export function deriveWorkspaceName(envPath) {
+  const parent = dirname(envPath);
+  const name = basename(parent);
+  if (name.startsWith(".")) return basename(dirname(parent));
+  return name;
+}
+
+/**
+ * Resolve o path do ENV.md com a seguinte precedência:
+ *   1. --env-file (path explícito)
+ *   2. --ide (ex: windsurf → .windsurf/ENV.md) — sobe pastas se estiver num repo filho
+ *   3. JARVIS_ENV_FILE (variável de ambiente)
+ *   4. IDE (variável de ambiente → .{ide}/ENV.md)
+ *   5. Auto-detect (sobe até achar $IDE/ENV.md no workspace)
+ *
+ * Retorna { path, source, warnings, root }
+ */
+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"]);
+    if (!existsSync(p)) {
+      throw new Error(
+        `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)) };
+  }
+
+  // 2. --ide (cwd e ancestrais — abre um repo filho e ainda acha o workspace)
+  if (flags.ide) {
+    if (!IDE_DIRS[flags.ide]) {
+      throw new Error(
+        `IDE não suportada: "${flags.ide}"\n` +
+          `IDEs válidas: ${Object.keys(IDE_DIRS).join(", ")}`,
+      );
+    }
+    for (const dir of walkAncestors(cwd)) {
+      const found = envsAt(dir, flags.ide);
+      if (found.length === 1) {
+        return {
+          path: found[0].path,
+          source: `--ide ${flags.ide}`,
+          warnings: [],
+          root: found[0].root,
+        };
+      }
+    }
+    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`,
+    );
+  }
+
+  // 3. JARVIS_ENV_FILE
+  if (process.env.JARVIS_ENV_FILE) {
+    const p = isAbsolute(process.env.JARVIS_ENV_FILE)
+      ? process.env.JARVIS_ENV_FILE
+      : join(cwd, process.env.JARVIS_ENV_FILE);
+    if (!existsSync(p)) {
+      throw new Error(`ENV.md não encontrado (JARVIS_ENV_FILE): ${p}`);
+    }
+    return { path: p, source: "JARVIS_ENV_FILE", warnings: [], root: dirname(dirname(p)) };
+  }
+
+  // 4. IDE env var
+  if (process.env.IDE && IDE_DIRS[process.env.IDE]) {
+    for (const dir of walkAncestors(cwd)) {
+      const found = envsAt(dir, process.env.IDE);
+      if (found.length === 1) {
+        return {
+          path: found[0].path,
+          source: `IDE=${process.env.IDE}`,
+          warnings: [],
+          root: found[0].root,
+        };
+      }
+    }
+  }
+
+  // 5. Auto-detect (ancestral mais próximo com exatamente um ENV.md)
+  for (const dir of walkAncestors(cwd)) {
+    const found = envsAt(dir);
+    if (found.length > 1) {
+      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`,
+      );
+    }
+    if (found.length === 1) {
+      return {
+        path: found[0].path,
+        source: `auto-detect (${found[0].ide})`,
+        warnings: [],
+        root: found[0].root,
+      };
+    }
+  }
+
+  // Fallback: ENV.md na raiz (comportamento legado)
+  return {
+    path: join(cwd, "ENV.md"),
+    source: "auto-detect (root)",
+    warnings: [],
+    root: cwd,
+  };
+}
+
+/**
+ * Lê e parseia o ENV.md do projeto.
+ * @param {string} cwd - Diretório raiz do projeto
+ * @param {string|null} envPath - Path explícito do ENV.md (opcional)
+ * Retorna um objeto com todas as variáveis key=value encontradas.
+ */
+export function loadEnv(cwd, envPath = null) {
+  const p = envPath ?? join(cwd, "ENV.md");
+  if (!existsSync(p)) return {};
+
+  const lines = readFileSync(p, "utf-8").split("\n");
+  const env = {};
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const idx = trimmed.indexOf("=");
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    const value = trimmed.slice(idx + 1).trim();
+    if (key && value) env[key] = value;
+  }
+
+  if (!env.WORKSPACE) {
+    env.WORKSPACE = deriveWorkspaceName(p);
+  }
+
+  return env;
+}
+
+/** `{workspace}/.jarvis` — sobe ancestrais até achar `$IDE/ENV.md`. */
+export function getJarvisDir(cwd = process.cwd(), flags = {}) {
+  try {
+    const { root } = resolveEnvPath(cwd, flags);
+    return join(root || cwd, ".jarvis");
+  } catch {
+    return join(cwd, ".jarvis");
+  }
+}