@spec-wave/cli 0.14.0 → 0.16.0

package/src/agent/tools.mjs

@@ -0,0 +1,452 @@
+// Implementações in-process de Read / Write / Glob / Grep.
+//
+// Porte de `agent-cli/src/tools.ts` (TypeScript) para ESM puro — este pacote
+// não tem etapa de build, então tipos viram JSDoc e nada mais muda.
+//
+// Servem o backend OpenRouter, que não tem subprocesso do Claude Code para
+// executar tools por ele. O backend anthropic usa as tools do próprio SDK
+// dentro do subprocesso e só consome o `ENV_FILE_PATTERN` daqui.
+//
+// Toda garantia que o subprocesso dá de graça é reimplementada aqui: `.env*` é
+// ilegível e inescrevível, caminhos ficam confinados às roots do run, e o Write
+// obedece à allowlist. O modelo nunca recebe um caminho que passou por fora
+// dessas checagens.
+
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+// Casa ".env", ".env.local", ".env.production" em qualquer ponto do caminho,
+// mas não arquivos que apenas contenham ".env" como substring ("envelope.ts").
+export const ENV_FILE_PATTERN = /(^|[\\/])\.env(\.|$)/;
+
+const MAX_READ_LINES = 2_000;
+const MAX_LINE_CHARS = 2_000;
+const MAX_OUTPUT_CHARS = 60_000;
+const MAX_GLOB_RESULTS = 200;
+const MAX_GREP_RESULTS = 200;
+const MAX_GREP_LINE_CHARS = 300;
+const MAX_GREP_FILE_BYTES = 2_000_000;
+const MAX_WALK_FILES = 20_000;
+const MAX_WALK_DEPTH = 12;
+
+// Diretórios que nunca valem a caminhada e dominariam qualquer resultado.
+// Deliberadamente curto — o resto é jogo justo.
+const SKIP_DIRS = new Set([
+  '.cache', '.git', '.next', '.venv', '__pycache__',
+  'build', 'coverage', 'dist', 'node_modules', 'vendor',
+]);
+
+/**
+ * @typedef {object} ToolContext
+ * @property {string} cwd base dos caminhos relativos e root primária
+ * @property {string[]} tools superfície de tools do run — validada na EXECUÇÃO,
+ *   não só no que o modelo vê: chamada alucinada a tool fora da lista é negada
+ * @property {string[]|null} allowedWritePaths null = qualquer caminho gravável
+ *   dentro de `roots`; senão o Write só passa nos caminhos listados
+ * @property {string[]} roots roots absolutas; todo caminho resolve dentro de uma
+ * @property {number} denials contador de chamadas recusadas
+ */
+
+/**
+ * @typedef {object} ToolResult
+ * @property {string} output
+ * @property {boolean} isError
+ */
+
+/** Forma de comparação: absoluto resolvido, minúsculo no win32 (NTFS ignora caixa). */
+function normalize(p) {
+  const resolved = path.resolve(p);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * @param {{ tools: string[], cwd?: string, allowedWritePaths?: string[] }} config
+ * @returns {ToolContext}
+ */
+export function createToolContext(config) {
+  const cwd = path.resolve(config.cwd ?? process.cwd());
+  const allowed = config.allowedWritePaths?.map(p => path.resolve(p)) ?? null;
+  // Um alvo de escrita pode ficar fora do cwd; nesse caso o diretório pai dele
+  // também precisa ser root, espelhando `additionalDirectories` no anthropic.
+  const roots = [...new Set([cwd, ...(allowed ?? []).map(p => path.dirname(p))])];
+  return {
+    cwd,
+    tools: [...config.tools],
+    allowedWritePaths: allowed === null ? null : allowed.map(normalize),
+    roots,
+    denials: 0,
+  };
+}
+
+// "denied" é recusa de política (conta em ctx.denials); "invalid" é só argumento
+// malformado — a diferença importa para o relatório do run.
+function resolveToolPath(ctx, raw, param) {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    return { ok: false, reason: 'invalid', error: `${param} must be a non-empty string` };
+  }
+  const abs = path.resolve(ctx.cwd, raw);
+  if (ENV_FILE_PATTERN.test(abs)) {
+    return { ok: false, reason: 'denied', error: 'Access to .env files is blocked' };
+  }
+  if (!ctx.roots.some(root => isInside(abs, root))) {
+    return {
+      ok: false,
+      reason: 'denied',
+      error: `Path is outside the allowed working directory (${ctx.roots.join(', ')})`,
+    };
+  }
+  return { ok: true, abs };
+}
+
+function pathFailure(ctx, check) {
+  return check.reason === 'denied' ? deny(ctx, check.error) : fail(check.error);
+}
+
+function deny(ctx, message) {
+  ctx.denials += 1;
+  return { output: message, isError: true };
+}
+
+function fail(message) {
+  return { output: message, isError: true };
+}
+
+function truncate(text, limit) {
+  return text.length > limit ? `${text.slice(0, limit)}… [truncated]` : text;
+}
+
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Suporta `**` (qualquer profundidade), `*` e `?` (dentro de um segmento) e
+ * alternância simples não-aninhada `{a,b}`. Casado contra um caminho separado
+ * por "/" relativo à raiz da busca (função PURA).
+ */
+export function globToRegExp(pattern) {
+  let source = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i++;
+        if (pattern[i + 1] === '/') {
+          i++;
+          source += '(?:[^/]+/)*';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+    } else if (ch === '?') {
+      source += '[^/]';
+    } else if (ch === '{') {
+      const close = pattern.indexOf('}', i);
+      if (close === -1) {
+        source += '\\{';
+      } else {
+        source += `(?:${pattern.slice(i + 1, close).split(',').map(escapeRegExp).join('|')})`;
+        i = close;
+      }
+    } else {
+      source += escapeRegExp(ch);
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** Caminhada limitada por profundidade, contagem e skip-list. Nunca produz `.env*`. */
+function* iterFiles(root) {
+  const stack = [{ dir: root, depth: 0 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) break;
+    let entries;
+    try {
+      entries = readdirSync(current.dir, { withFileTypes: true });
+    } catch {
+      continue; // diretório ilegível — pula, não derruba a tool inteira
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const abs = path.join(current.dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || current.depth >= MAX_WALK_DEPTH) continue;
+        stack.push({ dir: abs, depth: current.depth + 1 });
+      } else if (entry.isFile()) {
+        if (ENV_FILE_PATTERN.test(abs)) continue;
+        if (++seen > MAX_WALK_FILES) return;
+        yield { abs, rel: path.relative(root, abs).split(path.sep).join('/') };
+      }
+    }
+  }
+}
+
+function readTool(ctx, input) {
+  const checked = resolveToolPath(ctx, input.file_path, 'file_path');
+  if (!checked.ok) return pathFailure(ctx, checked);
+
+  let stat;
+  try {
+    stat = statSync(checked.abs);
+  } catch (err) {
+    return fail(`Could not read ${checked.abs}: ${errorMessage(err)}`);
+  }
+  if (stat.isDirectory()) {
+    return fail(`${checked.abs} is a directory — use Glob to list its files`);
+  }
+
+  let content;
+  try {
+    content = readFileSync(checked.abs, 'utf8');
+  } catch (err) {
+    return fail(`Could not read ${checked.abs}: ${errorMessage(err)}`);
+  }
+  if (content.includes('\0')) return fail(`${checked.abs} looks like a binary file`);
+
+  const offset = typeof input.offset === 'number' && input.offset >= 1
+    ? Math.floor(input.offset)
+    : 1;
+  const limit = typeof input.limit === 'number' && input.limit >= 1
+    ? Math.min(Math.floor(input.limit), MAX_READ_LINES)
+    : MAX_READ_LINES;
+
+  const lines = content.split('\n');
+  const slice = lines.slice(offset - 1, offset - 1 + limit);
+  if (slice.length === 0) {
+    return fail(`offset ${offset} is past the end of the file (${lines.length} lines)`);
+  }
+  const numbered = slice
+    .map((line, i) => `${offset + i}\t${truncate(line, MAX_LINE_CHARS)}`)
+    .join('\n');
+  const remaining = lines.length - (offset - 1 + slice.length);
+  const footer = remaining > 0 ? `\n… ${remaining} more line(s); re-read with offset` : '';
+  return { output: truncate(numbered, MAX_OUTPUT_CHARS) + footer, isError: false };
+}
+
+function writeTool(ctx, input) {
+  const checked = resolveToolPath(ctx, input.file_path, 'file_path');
+  if (!checked.ok) return pathFailure(ctx, checked);
+  if (ctx.allowedWritePaths !== null && !ctx.allowedWritePaths.includes(normalize(checked.abs))) {
+    return deny(ctx, `Writes are allowed only to: ${ctx.allowedWritePaths.join(', ')}`);
+  }
+  if (typeof input.content !== 'string') return fail('content must be a string');
+  try {
+    mkdirSync(path.dirname(checked.abs), { recursive: true });
+    writeFileSync(checked.abs, input.content, 'utf8');
+  } catch (err) {
+    return fail(`Could not write ${checked.abs}: ${errorMessage(err)}`);
+  }
+  return {
+    output: `Wrote ${Buffer.byteLength(input.content, 'utf8')} bytes to ${checked.abs}`,
+    isError: false,
+  };
+}
+
+function globTool(ctx, input) {
+  if (typeof input.pattern !== 'string' || input.pattern.trim() === '') {
+    return fail('pattern must be a non-empty string');
+  }
+  const baseCheck = resolveToolPath(ctx, input.path ?? ctx.cwd, 'path');
+  if (!baseCheck.ok) return pathFailure(ctx, baseCheck);
+  try {
+    if (!statSync(baseCheck.abs).isDirectory()) return fail(`${baseCheck.abs} is not a directory`);
+  } catch (err) {
+    return fail(`Could not search ${baseCheck.abs}: ${errorMessage(err)}`);
+  }
+
+  const matcher = globToRegExp(input.pattern);
+  const matches = [];
+  let truncated = false;
+  for (const file of iterFiles(baseCheck.abs)) {
+    if (!matcher.test(file.rel)) continue;
+    if (matches.length >= MAX_GLOB_RESULTS) {
+      truncated = true;
+      break;
+    }
+    matches.push(file.abs);
+  }
+  if (matches.length === 0) return { output: `No files matched ${input.pattern}`, isError: false };
+  const footer = truncated ? `\n… more matches omitted (showing first ${MAX_GLOB_RESULTS})` : '';
+  return { output: matches.join('\n') + footer, isError: false };
+}
+
+function grepTool(ctx, input) {
+  if (typeof input.pattern !== 'string' || input.pattern === '') {
+    return fail('pattern must be a non-empty string');
+  }
+  let regex;
+  try {
+    regex = new RegExp(input.pattern, input.case_insensitive === true ? 'i' : '');
+  } catch (err) {
+    return fail(`Invalid regular expression: ${errorMessage(err)}`);
+  }
+
+  const baseCheck = resolveToolPath(ctx, input.path ?? ctx.cwd, 'path');
+  if (!baseCheck.ok) return pathFailure(ctx, baseCheck);
+  let baseIsDir;
+  try {
+    baseIsDir = statSync(baseCheck.abs).isDirectory();
+  } catch (err) {
+    return fail(`Could not search ${baseCheck.abs}: ${errorMessage(err)}`);
+  }
+
+  const fileFilter = typeof input.glob === 'string' && input.glob.trim() !== ''
+    ? globToRegExp(input.glob)
+    : null;
+  const files = baseIsDir
+    ? iterFiles(baseCheck.abs)
+    : [{ abs: baseCheck.abs, rel: path.basename(baseCheck.abs) }];
+
+  const hits = [];
+  let truncated = false;
+  for (const file of files) {
+    if (fileFilter && !fileFilter.test(file.rel)) continue;
+    try {
+      if (statSync(file.abs).size > MAX_GREP_FILE_BYTES) continue;
+    } catch {
+      continue;
+    }
+    let content;
+    try {
+      content = readFileSync(file.abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (content.slice(0, 8_000).includes('\0')) continue; // binário
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (!regex.test(lines[i])) continue;
+      if (hits.length >= MAX_GREP_RESULTS) {
+        truncated = true;
+        break;
+      }
+      hits.push(`${file.abs}:${i + 1}:${truncate(lines[i].trim(), MAX_GREP_LINE_CHARS)}`);
+    }
+    if (truncated) break;
+  }
+
+  if (hits.length === 0) return { output: `No matches for ${input.pattern}`, isError: false };
+  const footer = truncated ? `\n… more matches omitted (showing first ${MAX_GREP_RESULTS})` : '';
+  return { output: hits.join('\n') + footer, isError: false };
+}
+
+const IMPLEMENTATIONS = { Read: readTool, Write: writeTool, Glob: globTool, Grep: grepTool };
+
+const DEFINITIONS = {
+  Read: {
+    type: 'function',
+    function: {
+      name: 'Read',
+      description:
+        'Read a text file from the local filesystem. Returns the content with 1-based line numbers. Use offset/limit to page through large files.',
+      parameters: {
+        type: 'object',
+        properties: {
+          file_path: { type: 'string', description: 'Path to the file (absolute, or relative to the working directory).' },
+          offset: { type: 'integer', description: '1-based line number to start from. Defaults to 1.' },
+          limit: { type: 'integer', description: `Maximum number of lines to return (cap ${MAX_READ_LINES}).` },
+        },
+        required: ['file_path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  Write: {
+    type: 'function',
+    function: {
+      name: 'Write',
+      description:
+        'Write text to a file, creating it (and any missing parent directories) or overwriting it completely. Prefer reading a file before overwriting it.',
+      parameters: {
+        type: 'object',
+        properties: {
+          file_path: { type: 'string', description: 'Path to the file (absolute, or relative to the working directory).' },
+          content: { type: 'string', description: 'Full content to write.' },
+        },
+        required: ['file_path', 'content'],
+        additionalProperties: false,
+      },
+    },
+  },
+  Glob: {
+    type: 'function',
+    function: {
+      name: 'Glob',
+      description:
+        "Find files by path pattern. Supports ** (any depth), * and ? (within a path segment) and {a,b} alternation, e.g. '**/*.{ts,tsx}'. Returns absolute paths.",
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Glob pattern, matched against paths relative to the search directory.' },
+          path: { type: 'string', description: 'Directory to search. Defaults to the working directory.' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+      },
+    },
+  },
+  Grep: {
+    type: 'function',
+    function: {
+      name: 'Grep',
+      description:
+        "Search file contents with a JavaScript regular expression. Returns matching lines as 'path:line:text'.",
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Regular expression to search for.' },
+          path: { type: 'string', description: 'File or directory to search. Defaults to the working directory.' },
+          glob: { type: 'string', description: "Only search files whose relative path matches this glob, e.g. '**/*.ts'." },
+          case_insensitive: { type: 'boolean', description: 'Match case-insensitively. Defaults to false.' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+      },
+    },
+  },
+};
+
+export const KNOWN_TOOL_NAMES = Object.keys(DEFINITIONS);
+
+/** Definições em formato OpenAI para a superfície pedida; nomes desconhecidos caem fora. */
+export function toolDefinitionsFor(names) {
+  return names.map(name => DEFINITIONS[name]).filter(def => def !== undefined);
+}
+
+/**
+ * Roda UMA chamada de tool. Nunca lança: toda falha — caminho negado, argumento
+ * ruim, erro de filesystem — volta como `{ isError: true }` para o modelo ver e
+ * se adaptar.
+ *
+ * @param {string} name
+ * @param {unknown} input
+ * @param {ToolContext} ctx
+ * @returns {ToolResult}
+ */
+export function executeTool(name, input, ctx) {
+  const impl = IMPLEMENTATIONS[name];
+  if (!impl || !ctx.tools.includes(name)) {
+    return deny(ctx, `Tool "${name}" is not available in this run. Available: ${ctx.tools.join(', ')}`);
+  }
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    return fail('Tool arguments must be a JSON object');
+  }
+  try {
+    return impl(ctx, input);
+  } catch (err) {
+    return fail(`${name} failed: ${errorMessage(err)}`);
+  }
+}

package/src/agent/tracing.mjs

@@ -0,0 +1,106 @@
+// Fachada sobre `@langfuse/tracing`, para que o tracing seja OPCIONAL.
+//
+// No agent-cli a telemetria é premissa: o binário existe para ser observado.
+// Aqui não — `generate-spec` roda dentro de um GitHub Action de quem talvez
+// nunca tenha ouvido falar de Langfuse, e a geração do documento não pode
+// depender disso. Sem chaves configuradas, tudo aqui vira no-op e os backends
+// seguem idênticos.
+//
+// O contrato dos backends fica limpo: eles chamam `withTrace`/`observe` sem
+// nunca perguntar se há telemetria.
+
+import { telemetryConfigured } from './telemetry.mjs';
+
+// Observação nula: mesma superfície do objeto do Langfuse, sem efeito.
+const NOOP_OBSERVATION = {
+  update() {},
+  end() {},
+  startObservation: () => NOOP_OBSERVATION,
+};
+
+let tracingModule;
+
+// Import dinâmico: sem telemetria configurada o pacote nem é carregado, o que
+// tira ~centenas de ms do arranque de todo comando que não gera documento.
+async function loadTracing() {
+  if (!telemetryConfigured()) return null;
+  if (tracingModule === undefined) {
+    try {
+      tracingModule = await import('@langfuse/tracing');
+    } catch {
+      tracingModule = null;
+    }
+  }
+  return tracingModule;
+}
+
+/**
+ * Roda `fn` dentro de uma observação raiz, propagando os atributos da trace.
+ *
+ * Sem telemetria, chama `fn` com uma observação nula — o backend não muda de
+ * caminho de código, então a versão instrumentada e a não-instrumentada não
+ * divergem em comportamento.
+ *
+ * @param {object} params
+ * @param {string} params.name nome da observação raiz
+ * @param {string} params.sessionId
+ * @param {string} params.userId
+ * @param {string[]} params.tags
+ * @param {object} [params.metadata]
+ * @param {boolean} [params.nested] herda o contexto ambiente em vez de abrir trace
+ * @param {(span: object) => Promise<any>} fn
+ */
+export async function withTrace(params, fn) {
+  const lf = await loadTracing();
+  if (!lf) return fn(NOOP_OBSERVATION);
+
+  const execute = () =>
+    lf.startActiveObservation(params.name, span => fn(span), { asType: 'agent' });
+
+  if (params.nested === true) return execute();
+
+  return lf.propagateAttributes(
+    {
+      sessionId: params.sessionId,
+      userId: params.userId,
+      tags: params.tags,
+      ...(params.metadata ? { metadata: params.metadata } : {}),
+    },
+    execute,
+  );
+}
+
+/**
+ * Abre uma observação filha sem nunca lançar.
+ *
+ * A telemetria não pode quebrar o run — é a invariante que o agent-cli mantém
+ * com try/catch em cada hook. Centralizando aqui, o corpo dos backends fica sem
+ * try/catch de tracing espalhado.
+ *
+ * @returns {{ update: Function, end: Function }} observação (real ou nula)
+ */
+export function startObservation(span, name, body, asType) {
+  try {
+    return span.startObservation(name, body, { asType }) ?? NOOP_OBSERVATION;
+  } catch {
+    return NOOP_OBSERVATION;
+  }
+}
+
+/** `span.update` que nunca lança. */
+export function updateSpan(span, body) {
+  try {
+    span.update(body);
+  } catch {
+    // telemetria nunca derruba o run
+  }
+}
+
+/** `observation.end` que nunca lança. */
+export function endObservation(observation) {
+  try {
+    observation?.end();
+  } catch {
+    // telemetria nunca derruba o run
+  }
+}