@tavaressan/vetor 0.1.0

package/templates/opencode/scripts/ensure-external-directory-permission_test.ts

@@ -0,0 +1,142 @@
+// Reprodução da issue #313: `issue-worker`/`code-review` rodam com `--dir <worktree>`, mas
+// `config.json`/`module-test-map.md`/status file vivem em `<repo-root>/.claude/vetor/`, fora da
+// árvore do worktree. O OpenCode trata esse acesso como `external_directory`, default `"*": "ask"`
+// — em `opencode run` não-interativo (sem TTY) isso auto-rejeita em vez de bloquear esperando
+// input. Este CLI garante, de forma idempotente, uma regra `permission.external_directory` em
+// `<repo-root>/opencode.json` apontando para `<repo-root>/.claude/vetor/**`, para que o
+// issue-coordinator a gere uma única vez (Fase 3) antes do primeiro `opencode run --dir` da sessão.
+
+import { assertEquals } from "@std/assert";
+
+const SCRIPT = new URL("./ensure-external-directory-permission.ts", import.meta.url).pathname;
+
+async function git(args: string[], cwd: string): Promise<void> {
+  await new Deno.Command("git", { args, cwd, stdout: "null", stderr: "null" }).output();
+}
+
+async function makeRepo(): Promise<string> {
+  const dir = await Deno.makeTempDir();
+  await git(["init", "-q", "-b", "main"], dir);
+  await git(["config", "user.email", "test@example.com"], dir);
+  await git(["config", "user.name", "Test"], dir);
+  await git(["commit", "-q", "--allow-empty", "-m", "init"], dir);
+  return dir;
+}
+
+async function runCli(
+  input: unknown,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const command = new Deno.Command("deno", {
+    args: ["run", "-A", SCRIPT],
+    stdin: "piped",
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const child = command.spawn();
+  const writer = child.stdin.getWriter();
+  await writer.write(new TextEncoder().encode(JSON.stringify(input)));
+  await writer.close();
+  const out = await child.output();
+  return {
+    code: out.code,
+    stdout: new TextDecoder().decode(out.stdout).trim(),
+    stderr: new TextDecoder().decode(out.stderr).trim(),
+  };
+}
+
+async function readOpencodeJson(repo: string): Promise<Record<string, unknown>> {
+  return JSON.parse(await Deno.readTextFile(`${repo}/opencode.json`));
+}
+
+/**
+ * `Deno.makeTempDir()` devolve path nativo (com `\` no Windows), mas o script resolve o root via
+ * `git rev-parse --path-format=absolute`, que normaliza para `/` — mesma convenção já usada por
+ * `resolveWorktree()`/`resolve-model.ts`. Normaliza aqui só para montar a chave esperada no teste.
+ */
+function toForwardSlashes(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+Deno.test("cria opencode.json com a regra external_directory quando o arquivo não existe", async () => {
+  const repo = await makeRepo();
+
+  const result = await runCli({ cwd: repo });
+
+  assertEquals(result.code, 0);
+  const config = await readOpencodeJson(repo);
+  const rule = (config.permission as { external_directory?: Record<string, string> })
+    .external_directory;
+  assertEquals(rule?.[`${toForwardSlashes(repo)}/.claude/vetor/**`], "allow");
+});
+
+Deno.test("mescla a regra num opencode.json existente sem apagar outras chaves", async () => {
+  const repo = await makeRepo();
+  await Deno.writeTextFile(
+    `${repo}/opencode.json`,
+    JSON.stringify({
+      "$schema": "https://opencode.ai/config.json",
+      mcp: { docker: { type: "local", command: ["docker-mcp"] } },
+      permission: { external_directory: { "/algum/outro/path/**": "ask" } },
+    }),
+  );
+
+  const result = await runCli({ cwd: repo });
+
+  assertEquals(result.code, 0);
+  const config = await readOpencodeJson(repo);
+  assertEquals((config.mcp as Record<string, unknown>).docker !== undefined, true);
+  const rule = (config.permission as { external_directory?: Record<string, string> })
+    .external_directory;
+  assertEquals(rule?.[`${toForwardSlashes(repo)}/.claude/vetor/**`], "allow");
+  assertEquals(rule?.["/algum/outro/path/**"], "ask");
+});
+
+Deno.test("idempotente: segunda chamada não altera o conteúdo já correto", async () => {
+  const repo = await makeRepo();
+
+  const first = await runCli({ cwd: repo });
+  assertEquals(first.code, 0);
+  const afterFirst = await Deno.readTextFile(`${repo}/opencode.json`);
+
+  const second = await runCli({ cwd: repo });
+  assertEquals(second.code, 0);
+  const afterSecond = await Deno.readTextFile(`${repo}/opencode.json`);
+
+  assertEquals(afterSecond, afterFirst);
+});
+
+Deno.test("não sobrescreve opencode.json existente e ilegível — falha com mensagem acionável", async () => {
+  const repo = await makeRepo();
+  await Deno.writeTextFile(`${repo}/opencode.json`, "{ isto não é json válido");
+
+  const result = await runCli({ cwd: repo });
+
+  assertEquals(result.code, 1);
+  const raw = await Deno.readTextFile(`${repo}/opencode.json`);
+  assertEquals(raw, "{ isto não é json válido");
+});
+
+// Issue #307 (mesma classe já corrigida em resolve-model.ts): no Git Bash do Windows, `$(pwd)`
+// produz um path POSIX-style (`/c/Users/...`), não nativo — precisa resolver o mesmo repo real.
+function toPosixPath(nativePath: string): string {
+  return nativePath.replace(/^([A-Za-z]):\\/, (_, d) => `/${d.toLowerCase()}/`).replaceAll(
+    "\\",
+    "/",
+  );
+}
+
+Deno.test({
+  name: "resolve o root real mesmo com cwd POSIX-style (Git Bash Windows)",
+  ignore: Deno.build.os !== "windows",
+  fn: async () => {
+    const repo = await makeRepo();
+
+    const result = await runCli({ cwd: toPosixPath(repo) });
+
+    assertEquals(result.code, 0);
+    const config = await readOpencodeJson(repo);
+    const rule = (config.permission as { external_directory?: Record<string, string> })
+      .external_directory;
+    assertEquals(rule?.[`${toForwardSlashes(repo)}/.claude/vetor/**`], "allow");
+  },
+});

package/templates/opencode/scripts/lib/guard.ts

@@ -0,0 +1,45 @@
+// Guarda de escrita dos workers: dentro de um worktree, só se escreve no próprio worktree.
+//
+// Com até 5 workers em paralelo, um Edit/Write apontando para fora do worktree contamina
+// o trabalho dos outros. A única exceção é o status file, escrito na raiz de propósito
+// (é por ele que o issue-coordinator agrega o andamento).
+
+/** Resolve `.`/`..` e uniformiza separadores. Não toca no disco: o alvo pode não existir. */
+export function normalizePath(path: string): string {
+  const segments: string[] = [];
+  const raw = path.replaceAll("\\", "/");
+
+  for (const segment of raw.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === ".." && segments.length > 0 && segments.at(-1) !== "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+
+  const prefix = raw.startsWith("/") ? "/" : "";
+  const joined = prefix + segments.join("/");
+  // Windows: comparação de path é case-insensitive.
+  return Deno.build.os === "windows" ? joined.toLowerCase() : joined;
+}
+
+export function isWithin(child: string, parent: string): boolean {
+  const c = normalizePath(child);
+  const p = normalizePath(parent);
+  return c === p || c.startsWith(p.endsWith("/") ? p : `${p}/`);
+}
+
+/**
+ * `worktree` é o cwd do agente; `root`, a raiz do repositório principal.
+ * Fora de um worktree linkado o guard não se aplica — quem chama decide isso.
+ */
+export function isWriteAllowed(target: string, worktree: string, root: string): boolean {
+  if (isWithin(target, worktree)) return true;
+
+  const statusDir = normalizePath(`${root}/.claude/vetor/status`);
+  const normalizedTarget = normalizePath(target);
+  const fileName = normalizedTarget.slice(statusDir.length + 1);
+  return normalizedTarget.startsWith(`${statusDir}/`) && !fileName.includes("/") &&
+    fileName.endsWith(".md");
+}

package/templates/opencode/scripts/lib/model-health.ts

@@ -0,0 +1,133 @@
+// Persistência de saúde de modelo/provedor entre processos separados do OpenCode (issue #83).
+//
+// Cada worker `opencode run --dir` é um processo do SO distinto — não há estado compartilhado
+// em memória entre eles nem com o `issue-coordinator`. Por isso o sinal de rate-limit/quota
+// detectado pelo hook `event` (opencode/plugin/vetor.ts, escutando `session.error`) precisa ser
+// gravado em disco, em `.claude/vetor/status/model-health.json`, na raiz do repositório
+// principal — fora de qualquer worktree, mesmo local onde já vivem os status files dos workers
+// (ver scripts/lib/status.ts).
+//
+// Payload do evento confirmado contra @opencode-ai/sdk v1.18.4 instalado
+// (dist/gen/types.gen.d.ts:86 `ApiError`, :518 `EventSessionError`) em 2026-07-21:
+//   ApiError.data = { message, statusCode?, isRetryable, responseHeaders?, responseBody? }
+// `EventSessionError.properties` só carrega `sessionID`+`error` — sem provider/model. Por isso
+// o plugin correlaciona sessionID -> "<providerID>/<modelID>" via `chat.params` (que recebe
+// `model: Model` com `providerID`/`id`) antes do erro chegar.
+
+/** Só 429 (rate limit) e 529 (overloaded, comum em provedores como Anthropic) contam como
+ *  degradação reativa — outros 4xx/5xx (auth, bad request, erro de servidor genérico) não
+ *  implicam necessariamente indisponibilidade do modelo em si. */
+const RATE_LIMIT_OR_QUOTA_STATUS_CODES = new Set([429, 529]);
+
+export function isRateLimitOrQuotaStatus(statusCode: number | undefined): boolean {
+  return statusCode !== undefined && RATE_LIMIT_OR_QUOTA_STATUS_CODES.has(statusCode);
+}
+
+/** Sem `retry-after` do provedor, backoff fixo curto — revisitado no próximo erro se persistir. */
+export const DEFAULT_BACKOFF_MS = 60_000;
+
+/**
+ * `retry-after` HTTP aceita segundos (inteiro) ou uma data no formato RFC 7231. Nenhum valor
+ * utilizável (ausente, não numérico e não parseável como data) cai no backoff fixo.
+ */
+export function computeUntil(
+  now: number,
+  responseHeaders: Record<string, string> | undefined,
+): number {
+  const raw = responseHeaders &&
+    Object.entries(responseHeaders).find(([k]) => k.toLowerCase() === "retry-after")?.[1];
+
+  if (raw !== undefined) {
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0) return now + seconds * 1000;
+
+    const asDate = Date.parse(raw);
+    if (!Number.isNaN(asDate)) return asDate;
+  }
+
+  return now + DEFAULT_BACKOFF_MS;
+}
+
+export interface ModelHealthEntry {
+  status: "degraded";
+  until: number;
+  lastError: string;
+}
+
+export type ModelHealthFile = Record<string, ModelHealthEntry>;
+
+const LOCK_RETRY_MS = 10;
+
+function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readModelHealthFile(path: string): ModelHealthFile {
+  if (!exists(path)) return {};
+  try {
+    const parsed = JSON.parse(Deno.readTextFileSync(path));
+    return parsed && typeof parsed === "object" ? parsed as ModelHealthFile : {};
+  } catch {
+    // JSON corrompido/parcial (ex.: escrita concorrente de outro worker): recomeça do zero em
+    // vez de travar o registro do novo sinal — perder histórico é preferível a nunca gravar.
+    return {};
+  }
+}
+
+/**
+ * Atualiza (cria ou sobrescreve) a entrada de `key` ("<provider>/<model>") em
+ * `.claude/vetor/status/model-health.json` e persiste o arquivo inteiro.
+ */
+export function recordModelHealth(
+  path: string,
+  key: string,
+  entry: ModelHealthEntry,
+): ModelHealthFile {
+  const dir = path.slice(0, path.lastIndexOf("/"));
+  if (dir) Deno.mkdirSync(dir, { recursive: true });
+
+  const lockPath = `${path}.lock`;
+  while (true) {
+    try {
+      Deno.openSync(lockPath, { createNew: true, write: true }).close();
+      break;
+    } catch (error) {
+      if (!(error instanceof Deno.errors.AlreadyExists)) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+    }
+  }
+
+  try {
+    const file = readModelHealthFile(path);
+    file[key] = entry;
+    const tempPath = `${path}.${Deno.pid}.${crypto.randomUUID()}.tmp`;
+    Deno.writeTextFileSync(tempPath, JSON.stringify(file, null, 2) + "\n");
+    Deno.renameSync(tempPath, path);
+    return file;
+  } finally {
+    Deno.removeSync(lockPath);
+  }
+}
+
+/** Entrada ausente ou `until` no passado = saudável. Consumido pelo issue-coordinator (#84). */
+export function isHealthy(entry: ModelHealthEntry | undefined, now: number): boolean {
+  return entry === undefined || entry.status !== "degraded" || entry.until <= now;
+}
+
+/**
+ * Percorre `fallback` (lista ordenada de "<provider>/<model>") e devolve o primeiro que estiver
+ * saudável em `health`. `null` se todos os modelos da lista estiverem `degraded` e não expirados
+ * — o issue-coordinator (issue #84) trata isso como "não despache, mantenha o grupo QUEUED".
+ */
+export function pickHealthyModel(
+  fallback: string[],
+  health: ModelHealthFile,
+  now: number,
+): string | null {
+  return fallback.find((model) => isHealthy(health[model], now)) ?? null;
+}

package/templates/opencode/scripts/lib/model-health_test.ts

@@ -0,0 +1,181 @@
+import { assert, assertEquals } from "@std/assert";
+import {
+  computeUntil,
+  DEFAULT_BACKOFF_MS,
+  isHealthy,
+  isRateLimitOrQuotaStatus,
+  pickHealthyModel,
+  recordModelHealth,
+} from "./model-health.ts";
+
+Deno.test("isRateLimitOrQuotaStatus - 429 e 529 são rate limit/quota", () => {
+  assert(isRateLimitOrQuotaStatus(429));
+  assert(isRateLimitOrQuotaStatus(529));
+});
+
+Deno.test("isRateLimitOrQuotaStatus - outros códigos não são", () => {
+  assert(!isRateLimitOrQuotaStatus(500));
+  assert(!isRateLimitOrQuotaStatus(401));
+  assert(!isRateLimitOrQuotaStatus(undefined));
+});
+
+Deno.test("computeUntil - deriva de retry-after em segundos", () => {
+  const now = 1_000_000;
+  const until = computeUntil(now, { "retry-after": "30" });
+  assertEquals(until, now + 30_000);
+});
+
+Deno.test("computeUntil - retry-after é case-insensitive no nome do header", () => {
+  const now = 1_000_000;
+  const until = computeUntil(now, { "Retry-After": "5" });
+  assertEquals(until, now + 5_000);
+});
+
+Deno.test("computeUntil - deriva de retry-after como data HTTP", () => {
+  const now = Date.parse("2026-07-21T00:00:00Z") - 10_000;
+  const until = computeUntil(now, { "retry-after": "Tue, 21 Jul 2026 00:00:00 GMT" });
+  assertEquals(until, Date.parse("2026-07-21T00:00:00Z"));
+});
+
+Deno.test("computeUntil - sem retry-after cai no backoff fixo", () => {
+  const now = 1_000_000;
+  assertEquals(computeUntil(now, undefined), now + DEFAULT_BACKOFF_MS);
+  assertEquals(computeUntil(now, {}), now + DEFAULT_BACKOFF_MS);
+});
+
+Deno.test("computeUntil - retry-after inválido cai no backoff fixo", () => {
+  const now = 1_000_000;
+  assertEquals(
+    computeUntil(now, { "retry-after": "não-é-nem-número-nem-data" }),
+    now + DEFAULT_BACKOFF_MS,
+  );
+});
+
+Deno.test("recordModelHealth - cria model-health.json com a entrada degraded", async () => {
+  const dir = await Deno.makeTempDir();
+  const path = `${dir}/.claude/vetor/status/model-health.json`;
+
+  const file = recordModelHealth(path, "anthropic/claude-sonnet-4-5", {
+    status: "degraded",
+    until: 2_000_000,
+    lastError: "HTTP 429: rate limited",
+  });
+
+  assertEquals(file["anthropic/claude-sonnet-4-5"].status, "degraded");
+  assertEquals(file["anthropic/claude-sonnet-4-5"].until, 2_000_000);
+
+  const onDisk = JSON.parse(await Deno.readTextFile(path));
+  assertEquals(onDisk["anthropic/claude-sonnet-4-5"].until, 2_000_000);
+});
+
+Deno.test("recordModelHealth - atualiza entrada existente sem apagar outras chaves", async () => {
+  const dir = await Deno.makeTempDir();
+  const path = `${dir}/.claude/vetor/status/model-health.json`;
+
+  recordModelHealth(path, "openai/gpt-5", { status: "degraded", until: 1, lastError: "a" });
+  const file = recordModelHealth(path, "anthropic/claude-haiku-4-5", {
+    status: "degraded",
+    until: 2,
+    lastError: "b",
+  });
+
+  assertEquals(Object.keys(file).sort(), ["anthropic/claude-haiku-4-5", "openai/gpt-5"]);
+});
+
+Deno.test("recordModelHealth - processos concorrentes preservam ambas as entradas", async () => {
+  const dir = await Deno.makeTempDir();
+  const path = `${dir}/.claude/vetor/status/model-health.json`;
+  const gate = `${dir}/start`;
+  const moduleUrl = new URL("./model-health.ts", import.meta.url).href;
+  const run = (key: string) =>
+    new Deno.Command(Deno.execPath(), {
+      args: [
+        "eval",
+        `import { recordModelHealth } from ${JSON.stringify(moduleUrl)};
+while (!await Deno.stat(${JSON.stringify(gate)}).then(() => true).catch(() => false)) {
+  await new Promise((resolve) => setTimeout(resolve, 1));
+}
+recordModelHealth(${JSON.stringify(path)}, ${JSON.stringify(key)}, {
+  status: "degraded", until: 2_000_000, lastError: "HTTP 429"
+});`,
+      ],
+    }).output();
+
+  const first = run("anthropic/claude-sonnet-4-5");
+  const second = run("openai/gpt-5");
+  await Deno.writeTextFile(gate, "go");
+  const results = await Promise.all([first, second]);
+
+  assert(
+    results.every((result) => result.success),
+    results.map((result) => new TextDecoder().decode(result.stderr)).join("\n"),
+  );
+  assertEquals(Object.keys(JSON.parse(await Deno.readTextFile(path))).sort(), [
+    "anthropic/claude-sonnet-4-5",
+    "openai/gpt-5",
+  ]);
+});
+
+Deno.test("isHealthy - entrada ausente é saudável", () => {
+  assert(isHealthy(undefined, Date.now()));
+});
+
+Deno.test("isHealthy - entrada com until no futuro é degraded", () => {
+  const now = 1_000_000;
+  assert(!isHealthy({ status: "degraded", until: now + 5_000, lastError: "x" }, now));
+});
+
+Deno.test("isHealthy - entrada com until no passado é saudável (expirada)", () => {
+  const now = 1_000_000;
+  assert(isHealthy({ status: "degraded", until: now - 5_000, lastError: "x" }, now));
+});
+
+Deno.test("pickHealthyModel - escolhe o primeiro saudável da lista", () => {
+  const now = 1_000_000;
+  const fallback = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"];
+  assertEquals(pickHealthyModel(fallback, {}, now), "anthropic/claude-haiku-4-5");
+});
+
+Deno.test("pickHealthyModel - modelo preferencial degraded e não expirado cai para o próximo", () => {
+  const now = 1_000_000;
+  const fallback = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"];
+  const health = {
+    "anthropic/claude-haiku-4-5": {
+      status: "degraded" as const,
+      until: now + 60_000,
+      lastError: "HTTP 429",
+    },
+  };
+  assertEquals(pickHealthyModel(fallback, health, now), "anthropic/claude-sonnet-4-5");
+});
+
+Deno.test("pickHealthyModel - modelo preferencial degraded mas expirado é escolhido de novo", () => {
+  const now = 1_000_000;
+  const fallback = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"];
+  const health = {
+    "anthropic/claude-haiku-4-5": {
+      status: "degraded" as const,
+      until: now - 1_000,
+      lastError: "HTTP 429",
+    },
+  };
+  assertEquals(pickHealthyModel(fallback, health, now), "anthropic/claude-haiku-4-5");
+});
+
+Deno.test("pickHealthyModel - todos degraded devolve null", () => {
+  const now = 1_000_000;
+  const fallback = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-5"];
+  const health = {
+    "anthropic/claude-haiku-4-5": {
+      status: "degraded" as const,
+      until: now + 60_000,
+      lastError: "HTTP 429",
+    },
+    "anthropic/claude-sonnet-4-5": {
+      status: "degraded" as const,
+      until: now + 60_000,
+      lastError: "HTTP 429",
+    },
+  };
+  assertEquals(pickHealthyModel(fallback, health, now), null);
+});