@tavaressan/vetor 0.1.0

package/templates/opencode/plugin/vetor.ts

@@ -0,0 +1,207 @@
+// Safety gate do Vetor para o OpenCode (hooks tool.execute.before / tool.execute.after).
+//
+// Ao contrário do Claude Code e do Codex, o OpenCode não tem hook declarativo em JSON —
+// um plugin é código TS/JS que recebe (input, output) e bloqueia lançando Error. Também não
+// existe `$CLAUDE_PLUGIN_ROOT`/`$PLUGIN_ROOT`: por isso este plugin resolve os scripts como
+// caminho relativo a si mesmo (`../scripts/...`), dentro da mesma pasta `opencode/` copiada
+// para o projeto-alvo — ver README, seção "Compatibilidade com OpenCode".
+//
+// A lógica de segurança em si NÃO foi duplicada: este plugin só traduz o payload do OpenCode
+// (`{tool, sessionID, args, agent}`) para o formato que scripts/safety-check.ts e
+// scripts/check-edit.ts já esperam no stdin (o mesmo usado pelo Claude Code e pelo Codex) e
+// invoca os scripts Deno originais via `deno run -A`. Fonte única de verdade continua em
+// scripts/lib/*.ts.
+//
+// Payload confirmado contra o SDK instalado (@opencode-ai/plugin, v1.18.4) em 2026-07-21 —
+// diferente do que foi possível fazer para o Codex (só doc pública, sem CLI real disponível).
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPTS_DIR = join(HERE, "..", "scripts");
+
+interface ToolExecuteBeforeInput {
+  tool: string;
+  sessionID: string;
+  callID: string;
+  agent?: string;
+}
+
+interface ToolExecuteBeforeOutput {
+  args: Record<string, unknown>;
+}
+
+/** Mesmo shape que scripts/safety-check.ts e scripts/check-edit.ts já esperam no stdin. */
+interface HookInput {
+  tool_name?: string;
+  tool_input?: { command?: string; file_path?: string };
+  cwd?: string;
+  agent_type?: string;
+  agent_id?: string;
+}
+
+const TOOL_NAME_MAP: Record<string, string> = {
+  bash: "Bash",
+  edit: "Edit",
+  write: "Write",
+};
+
+/**
+ * agent_id do Claude Code é estável por instância de subagente (issue #63: cwd contaminado
+ * entre workers paralelos). No modelo recomendado para o OpenCode (ver README — cada worker
+ * é um processo `opencode run --dir <worktree>` isolado, não a tool `task` in-process), essa
+ * classe de bug não deveria ocorrer: cada processo já nasce com cwd fixo no seu worktree.
+ * Mesmo assim, sessionID identifica a sessão/processo de forma estável e serve como proxy
+ * de agent_id para reaproveitar a segunda camada de defesa do safety-check.ts sem custo.
+ */
+function toHookInput(
+  input: ToolExecuteBeforeInput,
+  output: ToolExecuteBeforeOutput,
+  cwd: string,
+): HookInput {
+  const toolName = TOOL_NAME_MAP[input.tool];
+  const toolInput = toolName === "Bash"
+    ? { command: String(output.args.command ?? "") }
+    : { file_path: String(output.args.filePath ?? output.args.file_path ?? "") };
+
+  return {
+    tool_name: toolName,
+    tool_input: toolInput,
+    cwd,
+    agent_type: input.agent,
+    agent_id: input.sessionID,
+  };
+}
+
+function runDenoScript(
+  script: string,
+  payload: HookInput | Record<string, unknown>,
+  timeoutMs: number,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    const child = spawn("deno", ["run", "-A", join(SCRIPTS_DIR, script)], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? 0, stdout, stderr });
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      // deno ausente do PATH: mesmo pré-requisito documentado no README para as outras
+      // plataformas. Fail-open — não travar a sessão do usuário por dependência faltando.
+      resolve({ code: 0, stdout: "", stderr: "" });
+    });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}
+
+/** Payload mínimo de `ApiError` (@opencode-ai/sdk v1.18.4, dist/gen/types.gen.d.ts:86). */
+interface ApiErrorLike {
+  name?: string;
+  data?: {
+    message?: string;
+    statusCode?: number;
+    isRetryable?: boolean;
+    responseHeaders?: Record<string, string>;
+  };
+}
+
+/** `EventSessionError.properties` (types.gen.d.ts:518) — sem provider/model, só sessionID. */
+interface SessionErrorEvent {
+  type: string;
+  properties?: {
+    sessionID?: string;
+    error?: ApiErrorLike;
+  };
+}
+
+// deno-lint-ignore require-await -- assinatura exigida pela API de plugin do OpenCode (async).
+export const VetorPlugin = async ({ directory, worktree }: {
+  directory: string;
+  worktree: string;
+}) => {
+  const cwd = worktree || directory;
+
+  // `session.error` (issue #83) não carrega provider/model — só `sessionID`. `chat.params`
+  // roda antes de cada chamada ao provedor e já recebe `model: { providerID, id }`; mantemos
+  // esse mapa em memória (por processo — cada worker `opencode run --dir` já é isolado) para
+  // resolver a chave "<provider>/<model>" quando o erro chegar depois na mesma sessão.
+  const sessionModel = new Map<string, string>();
+
+  return {
+    // deno-lint-ignore require-await -- assinatura exigida pela API de plugin do OpenCode (async).
+    "chat.params": async (
+      input: { sessionID: string; model: { providerID: string; id: string } },
+      _output: unknown,
+    ) => {
+      sessionModel.set(input.sessionID, `${input.model.providerID}/${input.model.id}`);
+    },
+
+    "event": async ({ event }: { event: SessionErrorEvent }) => {
+      if (event.type !== "session.error") return;
+
+      const error = event.properties?.error;
+      if (!error || error.name !== "APIError") return;
+
+      const statusCode = error.data?.statusCode;
+      if (statusCode === undefined) return;
+
+      const sessionID = event.properties?.sessionID;
+      const model = sessionID ? sessionModel.get(sessionID) : undefined;
+
+      await runDenoScript("model-health.ts", {
+        model,
+        statusCode,
+        responseHeaders: error.data?.responseHeaders,
+        message: error.data?.message,
+        cwd,
+      }, 20_000);
+    },
+
+    "tool.execute.before": async (
+      input: ToolExecuteBeforeInput,
+      output: ToolExecuteBeforeOutput,
+    ) => {
+      if (!["bash", "edit", "write"].includes(input.tool)) return;
+
+      const payload = toHookInput(input, output, cwd);
+      const { code, stderr } = await runDenoScript("safety-check.ts", payload, 300_000);
+      if (code === 2) {
+        throw new Error(stderr.trim() || "Bloqueado pelo Vetor Safety Hook.");
+      }
+    },
+
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string; args: Record<string, unknown> },
+      output: { title: string; output: string; metadata: Record<string, unknown> },
+    ) => {
+      if (!["edit", "write"].includes(input.tool)) return;
+
+      const payload = toHookInput(input, { args: input.args }, cwd);
+      const { stdout } = await runDenoScript("check-edit.ts", payload, 20_000);
+      if (!stdout) return;
+
+      try {
+        const parsed = JSON.parse(stdout);
+        const context = parsed?.hookSpecificOutput?.additionalContext;
+        if (context) {
+          output.metadata = { ...output.metadata, vetorDiagnostics: context };
+        }
+      } catch {
+        // Saída não-JSON do check-edit.ts (não deveria acontecer): ignora silenciosamente.
+      }
+    },
+  };
+};

package/templates/opencode/scripts/agent-registration_test.ts

@@ -0,0 +1,92 @@
+// Reprodução da issue #306: `opencode agent list` só reconhece agents definidos em
+// .opencode/agent/*.md. `issue-coordinator` vivia em .opencode/skills/issue-coordinator/SKILL.md —
+// um diretório diferente, descoberto como skill, não como agent — e por isso nunca era listado nem
+// invocável via `opencode run --agent issue-coordinator "<label>"` (caía silenciosamente no agent
+// `build` default).
+//
+// Roda contra o binário `opencode` real quando disponível no PATH; do contrário, pula (o CLI é uma
+// dependência externa opcional para dev/CI local, não travável via deno.lock).
+
+import { assertMatch } from "@std/assert";
+
+const OPENCODE_SRC = `${import.meta.dirname}/../`;
+
+async function opencodeAvailable(): Promise<boolean> {
+  try {
+    const out = await new Deno.Command("opencode", {
+      args: ["--version"],
+      stdout: "null",
+      stderr: "null",
+    }).output();
+    return out.success;
+  } catch {
+    return false;
+  }
+}
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  await Deno.mkdir(dest, { recursive: true });
+  for await (const entry of Deno.readDir(src)) {
+    const srcPath = `${src}/${entry.name}`;
+    const destPath = `${dest}/${entry.name}`;
+    if (entry.isDirectory) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await Deno.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+const AVAILABLE = await opencodeAvailable();
+
+Deno.test({
+  name: "opencode agent list reconhece issue-coordinator (CLI real)",
+  ignore: !AVAILABLE,
+  fn: async () => {
+    const dir = await Deno.makeTempDir();
+    await copyDir(OPENCODE_SRC, `${dir}/.opencode`);
+
+    const out = await new Deno.Command("opencode", {
+      args: ["agent", "list"],
+      cwd: dir,
+      stdout: "piped",
+      stderr: "piped",
+    }).output();
+
+    const stdout = new TextDecoder().decode(out.stdout);
+    // Linha de agente real, ex. "issue-coordinator (primary)" — não basta checar substring: o
+    // JSON de permissões impresso logo abaixo de cada agente contém paths de external_directory que
+    // incluem "issue-coordinator" mesmo quando ele só existe como skill (falso positivo). O `mode`
+    // também é checado: a issue #306 pede explicitamente `mode: primary` (é o agent de entrada,
+    // invocado diretamente pelo usuário — diferente de `issue-worker`/`code-review`, despachados
+    // programaticamente pelo próprio coordinator).
+    assertMatch(stdout, /^issue-coordinator \(primary\)/m);
+  },
+});
+
+// Reprodução da issue #311: issue-worker e code-review tinham `mode: subagent` no frontmatter, mas
+// nunca são invocados via `task` in-process do OpenCode (não existe esse mecanismo com isolamento de
+// cwd) — o único uso real deles é como processo `opencode run --dir ... --agent <nome>` isolado,
+// disparado programaticamente pelo issue-coordinator/worktree-ship. Invocar um agent `mode: subagent`
+// diretamente via `--agent` cai silenciosamente no agent `build` default, ignorando por completo o
+// corpo do agent pedido. `mode: primary` (mesmo valor de issue-coordinator, pelo mesmo motivo) é o
+// frontmatter correto.
+Deno.test({
+  name: "opencode agent list reconhece issue-worker e code-review como primary (CLI real)",
+  ignore: !AVAILABLE,
+  fn: async () => {
+    const dir = await Deno.makeTempDir();
+    await copyDir(OPENCODE_SRC, `${dir}/.opencode`);
+
+    const out = await new Deno.Command("opencode", {
+      args: ["agent", "list"],
+      cwd: dir,
+      stdout: "piped",
+      stderr: "piped",
+    }).output();
+
+    const stdout = new TextDecoder().decode(out.stdout);
+    assertMatch(stdout, /^issue-worker \(primary\)/m);
+    assertMatch(stdout, /^code-review \(primary\)/m);
+  },
+});

package/templates/opencode/scripts/check-edit.ts

@@ -0,0 +1,147 @@
+// Diagnostics por edição (hook PostToolUse, matcher Edit|Write).
+//
+// Motivação (issue #36): sem isto, o issue-worker só descobre erro de tipo, import quebrado
+// ou símbolo inexistente RODANDO O TESTE — e cada descoberta dessas queima uma das 5
+// iterações do fix-loop. Aqui o erro volta junto com o resultado do próprio Edit, e o
+// worker corrige na hora, sem gastar iteração.
+//
+// Contrato do Claude Code: exit 0 + `hookSpecificOutput.additionalContext` injeta o texto
+// ao lado do resultado da tool. Hooks disparam dentro de subagentes, então isto alcança o
+// worker. Sem erro → silêncio absoluto: ruído a cada edição custaria mais do que resolve.
+
+import { detectProject } from "./lib/project.ts";
+import { isWithin } from "./lib/guard.ts";
+
+const CHECKABLE = /\.(ts|tsx|mts|cts)$/;
+const TIMEOUT_MS = 20_000;
+const MAX_OUTPUT = 4_000;
+
+interface HookInput {
+  tool_input?: { file_path?: string };
+  cwd?: string;
+}
+
+function quiet(): never {
+  Deno.exit(0);
+}
+
+function emit(diagnostics: string): never {
+  const text = diagnostics.length > MAX_OUTPUT
+    ? `${diagnostics.slice(0, MAX_OUTPUT)}\n[...saída truncada]`
+    : diagnostics;
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext:
+        `Typecheck do arquivo editado falhou. Corrija antes de rodar os testes:\n\n${text}`,
+    },
+  }));
+  Deno.exit(0);
+}
+
+/** Diretório do projeto mais próximo do arquivo — cobre monorepo, sem sair do cwd. */
+function nearestProjectDir(filePath: string, cwd: string): string | null {
+  let dir = filePath.replaceAll("\\", "/").split("/").slice(0, -1).join("/");
+
+  while (dir && isWithin(dir, cwd)) {
+    if (detectProject(dir).runtime !== "unknown") return dir;
+    const parent = dir.split("/").slice(0, -1).join("/");
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/** Um typecheck lento não pode segurar a edição: estourou o tempo, não diz nada. */
+async function runWithTimeout(
+  cmd: string,
+  args: string[],
+  cwd: string,
+): Promise<{ code: number; output: string } | null> {
+  const timer = new AbortController();
+  const timeout = setTimeout(() => timer.abort(), TIMEOUT_MS);
+
+  try {
+    const result = await new Deno.Command(cmd, {
+      args,
+      cwd,
+      // Sem NO_COLOR a saída vem cheia de escapes ANSI, que só ocupariam contexto do worker.
+      env: { NO_COLOR: "1" },
+      stdout: "piped",
+      stderr: "piped",
+      signal: timer.signal,
+    }).output();
+
+    const decoder = new TextDecoder();
+    return {
+      code: result.code,
+      output: (decoder.decode(result.stdout) + decoder.decode(result.stderr)).trim(),
+    };
+  } catch {
+    // Binário ausente ou timeout: sem diagnóstico a reportar.
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** tsc local do projeto. Sem ele instalado, não há typecheck a fazer. */
+function localTsc(dir: string): string | null {
+  const bin = Deno.build.os === "windows"
+    ? `${dir}/node_modules/.bin/tsc.cmd`
+    : `${dir}/node_modules/.bin/tsc`;
+  return exists(bin) ? bin : null;
+}
+
+async function main() {
+  const raw = new TextDecoder().decode(await new Response(Deno.stdin.readable).arrayBuffer());
+
+  let input: HookInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    quiet();
+  }
+
+  const filePath = input.tool_input?.file_path;
+  const cwd = input.cwd ?? Deno.cwd();
+  if (!filePath || !CHECKABLE.test(filePath) || !isWithin(filePath, cwd)) quiet();
+
+  const dir = nearestProjectDir(filePath, cwd);
+  if (!dir) quiet();
+
+  const { runtime } = detectProject(dir);
+
+  if (runtime === "deno") {
+    const result = await runWithTimeout("deno", ["check", filePath], dir);
+    if (result && result.code !== 0 && result.output) emit(result.output);
+    quiet();
+  }
+
+  if (runtime === "node") {
+    // Sem tsconfig o tsc não sabe as opções do projeto; um check com defaults produziria
+    // erros que não são erros do projeto.
+    if (!exists(`${dir}/tsconfig.json`)) quiet();
+    const tsc = localTsc(dir);
+    if (!tsc) quiet();
+
+    const result = await runWithTimeout(tsc, ["--noEmit"], dir);
+    if (result && result.code !== 0 && result.output) emit(result.output);
+    quiet();
+  }
+
+  quiet();
+}
+
+await main();

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

@@ -0,0 +1,110 @@
+// CLI invocado pelo issue-coordinator portado (opencode/agent/issue-coordinator.md, issue #313)
+// antes do primeiro `opencode run --dir <worktree>` da sessão.
+//
+// Causa raiz da #313: `issue-worker`/`code-review` rodam com `--dir <worktree>` (cwd fixado no
+// worktree), mas `config.json`/`module-test-map.md`/status file vivem em
+// `<repo-root>/.claude/vetor/`, fora da árvore do worktree — por desenho, é assim que o
+// issue-coordinator agrega progresso de múltiplos processos `opencode` isolados via polling de
+// arquivo. O OpenCode trata esse acesso como `external_directory` (default `"*": "ask"`); em
+// `opencode run` não-interativo (sem TTY) uma permissão `ask` auto-rejeita em vez de bloquear
+// esperando input.
+//
+// Confirmado contra o CLI `opencode` real (v1.18.32): uma regra `permission.external_directory`
+// em `<repo-root>/opencode.json` resolve tanto leitura quanto escrita, mesmo com o worktree dois
+// níveis abaixo (`<repo-root>/.claude/worktrees/<slug>`) — e a resolução do OpenCode é um walk-up
+// de diretório a partir do cwd, independente de git: o arquivo não precisa estar rastreado/
+// commitado para ser encontrado a partir de dentro do worktree (diferente de `.opencode/agent/*.md`,
+// que só chega ao worktree se estiver commitado — `git worktree add` só propaga arquivos
+// rastreados). Por isso este script grava um `opencode.json` **local, não versionado** na raiz do
+// repositório principal, em vez de reescrever um `.md` de agent compartilhado (opção 1 da issue,
+// descartada por risco de corrida entre workers paralelos editando o mesmo arquivo).
+//
+// Idempotente por desenho: seguro de chamar a cada dispatch (Fase 3 e Fase 4, inclusive
+// redespacho/`--resume`, onde a Fase 3 não roda de novo) sem the coordinator precisar rastrear se
+// já rodou. Nunca sobrescreve um `opencode.json` existente às cegas — mescla preservando outras
+// chaves (ex.: `mcp`, outras regras de `permission.external_directory`) e recusa (código 1) se o
+// arquivo existente não for JSON válido, em vez de arriscar destruir configuração do usuário.
+//
+// Contrato de stdin:
+//   { cwd?: string }
+// Sem `cwd`, usa `Deno.cwd()`.
+//
+// Códigos de saída:
+//   0 - regra presente (criada, mesclada, ou já estava correta) — stdout traz o path do
+//       opencode.json.
+//   1 - opencode.json existente não é JSON válido; nada foi escrito.
+
+import { normalizeCwd, readJson } from "./lib/project.ts";
+import { resolveWorktree } from "./lib/status.ts";
+
+interface Payload {
+  cwd?: string;
+}
+
+interface OpencodeConfig {
+  "$schema"?: string;
+  permission?: {
+    external_directory?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const raw = new TextDecoder().decode(await new Response(Deno.stdin.readable).arrayBuffer());
+
+  let input: Payload;
+  try {
+    input = raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    input = {};
+  }
+
+  const cwd = normalizeCwd(input.cwd ?? Deno.cwd());
+  const worktree = await resolveWorktree(cwd);
+  const root = worktree?.root ?? cwd;
+
+  const configPath = `${root}/opencode.json`;
+  const rulePath = `${root}/.claude/vetor/**`;
+
+  let config: OpencodeConfig;
+  if (exists(configPath)) {
+    try {
+      config = readJson(configPath) as OpencodeConfig;
+    } catch {
+      console.error(
+        `${configPath} existe mas não é JSON válido — recuse sobrescrever. Adicione manualmente ` +
+          `"permission.external_directory": { "${rulePath}": "allow" } a esse arquivo.`,
+      );
+      Deno.exit(1);
+    }
+  } else {
+    config = { "$schema": "https://opencode.ai/config.json" };
+  }
+
+  const currentRule = config.permission?.external_directory?.[rulePath];
+  if (currentRule === "allow") {
+    return;
+  }
+
+  config.permission = {
+    ...config.permission,
+    external_directory: {
+      ...config.permission?.external_directory,
+      [rulePath]: "allow",
+    },
+  };
+
+  await Deno.writeTextFile(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+await main();