@zaip-ai/cli 4.5.0 → 4.7.0

package/templates/.agents/dashboard/packages/local-runtime/DIAGNOSTICS.md

@@ -0,0 +1,42 @@
+# Diagnóstico local do dashboard
+
+Logs persistentes ficam em `.local/dashboard-logs/`, na raiz do projeto servido.
+Cada linha é JSON (JSONL), com `occurred_at` em UTC, `event`, `component`,
+`pid` e `correlation_id`. O clique no executável gera um ID herdado pelo
+launcher e pelo runtime. Cada reconciliação tem `job_id`; cada POST tem
+`request_id`, inclusive pedidos simultâneos que compartilham um job.
+
+Arquivos `native-*.jsonl` registram o clique, início do Node, entrega ao navegador
+e falha anterior ao Node. Se a raiz não puder ser localizada, esse erro inicial
+fica em `%TEMP%/zaip-dashboard-logs/`. Arquivos `launcher-*.jsonl` registram
+preparo e stdout/stderr do runtime. `runtime-*.jsonl` registram requisição,
+fila, resultado e promoção/falha do snapshot. `reconciliation-*.jsonl`
+registram a execução da CLI, stdout/stderr sanitizados e resultado/erro.
+
+Para analisar um incidente, procure o `job_id` do diálogo ou o
+`request_id` da resposta de erro. Relacione `reconciliation_queued`,
+`reconciliation_started`, `cli_output|cli_error` e o desfecho do job.
+A conclusão do comando e `projection_refresh_completed` são eventos separados:
+o segundo só é registrado após a atualização da projeção. Uma falha assíncrona
+tem `projection_refresh_failed`; a resposta imediata pode preceder esse erro.
+Timeouts podem ter alterações parciais; nunca deduza entrega concluída.
+
+Strings têm limite de 16 mil caracteres, coleções de 200 itens e profundidade
+de seis níveis. Credenciais, cookies, tokens de acesso e códigos de terminal
+são removidos; IDs, motivos e horários de coleta de tokens são preservados.
+Saídas truncadas são diagnóstico resumido; o resultado completo permanece nos
+registros canônicos. Cada log Node gira após 2 MiB, mantendo uma geração
+`.1`. No início de um escritor, logs dos componentes próprios acima são
+limitados a 60 arquivos e 14 dias; o executável também limita seus logs nativos
+a 60 arquivos e 14 dias, inclusive se o Node não iniciar. Outros arquivos
+na pasta são preservados. Erro de gravação é avisado no stderr sem esconder
+a falha original. A pasta é local e segue o ignore de `.local`.
+
+O cabeçalho exibe somente “Última Atualização”, baseada em
+`projection_updated_at`, o horário do snapshot exibido. `latest_token_collected_at`
+continua representando a coleta mais recente de tokens positivos materializados,
+sem aparecer como uma segunda data no cabeçalho. O diálogo mostra
+`completed_at` do job. Reconciliar estados sem novos tokens pode atualizar
+os dois últimos horários e conservar o primeiro. Horários são exibidos no fuso
+do navegador; os logs usam UTC. A reconciliação preserva invocações ativas e
+registra interrupções/falhas sem fabricar sucesso ou cancelamento.

package/templates/.agents/dashboard/packages/local-runtime/dashboard-diagnostics.d.mts

@@ -0,0 +1,10 @@
+export function sanitizeDiagnostic(value: unknown, depth?: number): unknown;
+export function createDashboardDiagnostics(
+  workspaceRoot: string,
+  component: string,
+  options?: { maxBytes?: number },
+): {
+  log(event: string, data?: Record<string, unknown>): boolean;
+  path: string;
+  correlationId: string;
+};

package/templates/.agents/dashboard/packages/local-runtime/dashboard-diagnostics.mjs

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+const secretKey =
+  /^(?:(?:access|refresh|session|ui|auth)[_-]?)?token$|authorization|cookie|password|secret|credential|api[_-]?key/i;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI OSC sequences contain escape and bell controls.
+const oscEscapePattern = /\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI CSI sequences contain escape controls.
+const csiEscapePattern = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+export function sanitizeDiagnostic(value, depth = 0) {
+  if (depth > 6) return "[depth limited]";
+  if (typeof value === "string") {
+    let text = value.replace(oscEscapePattern, "").replace(csiEscapePattern, "");
+    for (const secret of [process.env.ZAIP_UI_TOKEN, process.env.ZAIP_SESSION_TOKEN])
+      if (secret) text = text.replaceAll(secret, "[redacted]");
+    return text
+      .replace(/(Bearer\s+)[^\s"']+/gi, "$1[redacted]")
+      .replace(
+        /((?:token|authorization|cookie|password|secret|api[_-]?key)["']?\s*[:=]\s*["']?)[^\s"',};&]+/gi,
+        "$1[redacted]",
+      )
+      .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@")
+      .slice(0, 16_000);
+  }
+  if (value instanceof Error) {
+    return sanitizeDiagnostic(
+      {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+        ...Object.fromEntries(Object.entries(value)),
+      },
+      depth + 1,
+    );
+  }
+  if (Array.isArray(value))
+    return value.slice(0, 200).map((item) => sanitizeDiagnostic(item, depth + 1));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value)
+        .slice(0, 100)
+        .map(([key, item]) => [
+          key,
+          secretKey.test(key) ? "[redacted]" : sanitizeDiagnostic(item, depth + 1),
+        ]),
+    );
+  return typeof value === "bigint" ? String(value) : value;
+}
+
+export function createDashboardDiagnostics(workspaceRoot, component, options = {}) {
+  const inherited = process.env.ZAIP_DASHBOARD_LAUNCH_ID;
+  const correlationId = /^[a-zA-Z0-9-]{1,80}$/.test(inherited ?? "") ? inherited : randomUUID();
+  const directory = join(workspaceRoot, ".local", "dashboard-logs");
+  const path = join(directory, `${component}-${correlationId}-${process.pid}.jsonl`);
+  const maxBytes = options.maxBytes ?? 2 * 1024 * 1024;
+  let prepared = false;
+  let failed = false;
+  const log = (event, data = {}) => {
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      if (!prepared) {
+        prepared = true;
+        const files = readdirSync(directory)
+          .filter((name) =>
+            /^(?:native|launcher|runtime|reconciliation)-[a-zA-Z0-9-]+\.jsonl(?:\.1)?$/.test(name),
+          )
+          .map((name) => ({ name, modified: statSync(join(directory, name)).mtimeMs }))
+          .sort((a, b) => b.modified - a.modified);
+        for (const [index, file] of files.entries())
+          if (index >= 60 || Date.now() - file.modified > 14 * 86400_000)
+            unlinkSync(join(directory, file.name));
+      }
+      if (statSync(path, { throwIfNoEntry: false })?.size >= maxBytes) {
+        const rotated = `${path}.1`;
+        if (statSync(rotated, { throwIfNoEntry: false })) unlinkSync(rotated);
+        renameSync(path, rotated);
+      }
+      appendFileSync(
+        path,
+        `${JSON.stringify({
+          ...sanitizeDiagnostic(data),
+          schema_version: 1,
+          occurred_at: new Date().toISOString(),
+          component,
+          event,
+          correlation_id: correlationId,
+          pid: process.pid,
+        })}\n`,
+        { encoding: "utf8", mode: 0o600 },
+      );
+      return true;
+    } catch {
+      if (!failed)
+        process.stderr.write("Dashboard diagnostic log unavailable in .local/dashboard-logs\n");
+      failed = true;
+      return false;
+    }
+  };
+  return { log, path, correlationId };
+}

package/templates/.agents/dashboard/packages/local-runtime/dashboard-diagnostics.test.mjs

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readdir, readFile, rm, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { test } from "node:test";
+import { createDashboardDiagnostics, sanitizeDiagnostic } from "./dashboard-diagnostics.mjs";
+
+test("persistent JSONL redacts credentials, bounds streams and preserves token collection time", async () => {
+  const base = new URL("../../../../.tmp/dashboard-diagnostic-tests/", import.meta.url);
+  await mkdir(base, { recursive: true });
+  const root = await mkdtemp(new URL("fixture-", base));
+  try {
+    const diagnostics = createDashboardDiagnostics(root, "reconciliation", { maxBytes: 400 });
+    const time = "2026-09-29T13:46:11.000Z";
+    assert.equal(
+      diagnostics.log("cli_error", {
+        job_id: "JOB-X",
+        latest_token_collected_at: time,
+        error: Object.assign(new Error("Bearer topsecret"), { stderr: "password=secret" }),
+        stdout: '{"access_token":"private"}',
+        cookie: "private",
+      }),
+      true,
+    );
+    const original = await readFile(diagnostics.path, "utf8");
+    const event = JSON.parse(original);
+    assert.equal(event.latest_token_collected_at, time);
+    assert.equal(event.job_id, "JOB-X");
+    assert.ok(event.occurred_at);
+    assert.equal(/topsecret|private|password=secret/.test(original), false);
+    diagnostics.log("next", { stdout: "x".repeat(20_000) });
+    assert.equal(JSON.parse(await readFile(diagnostics.path, "utf8")).stdout.length, 16_000);
+    assert.equal(await readFile(diagnostics.path + ".1", "utf8"), original);
+    assert.equal(sanitizeDiagnostic("\x1b[31mBearer secret\x1b[0m"), "Bearer [redacted]");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("retains recent owned logs and removes aged owned logs only", async () => {
+  const base = new URL("../../../../.tmp/dashboard-diagnostic-tests/", import.meta.url);
+  await mkdir(base, { recursive: true });
+  const root = await mkdtemp(new URL("fixture-", base));
+  try {
+    const directory = join(root, ".local", "dashboard-logs");
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, "runtime-old-123.jsonl"), "{}\n");
+    await writeFile(join(directory, "unrelated.jsonl"), "{}\n");
+    const old = new Date(Date.now() - 15 * 86400_000);
+    await utimes(join(directory, "runtime-old-123.jsonl"), old, old);
+    await utimes(join(directory, "unrelated.jsonl"), old, old);
+    assert.equal(createDashboardDiagnostics(root, "launcher").log("start"), true);
+    const files = await readdir(directory);
+    assert.equal(files.includes("runtime-old-123.jsonl"), false);
+    assert.equal(files.includes("unrelated.jsonl"), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});