@zaip-ai/cli 1.3.8 → 1.4.1

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-snapshot-cache.ts

@@ -1,45 +1,18 @@
-import { randomUUID } from "node:crypto";
-import { copyFile, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
-export async function pruneSnapshotCache(directory: string, activePath: string): Promise<void> {
-  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
-  const stale = await Promise.all(
-    entries
-      .filter(
-        (entry) =>
-          entry.isFile() &&
-          entry.name.endsWith(".sqlite") &&
-          resolve(directory, entry.name) !== activePath,
-      )
-      .map(async (entry) => ({
-        path: resolve(directory, entry.name),
-        mtime: (await stat(resolve(directory, entry.name))).mtimeMs,
-      })),
-  );
-  for (const entry of stale.sort((a, b) => b.mtime - a.mtime).slice(1))
-    await rm(entry.path, { force: true }).catch(() => {});
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.includes(".sqlite.") || !entry.name.includes(".tmp"))
-      continue;
-    const candidate = resolve(directory, entry.name);
-    if (Date.now() - (await stat(candidate)).mtimeMs > 60_000)
-      await rm(candidate, { force: true }).catch(() => {});
-  }
-}
-
 export function readSnapshotFileCount(
   path: string,
   fingerprint: string,
   schemaVersion: string,
   hasRequiredPayloads: (database: DatabaseSync) => boolean,
 ): number | null {
+  let database: DatabaseSync | undefined;
   try {
-    const database = new DatabaseSync(path, { readOnly: true });
+    database = new DatabaseSync(path, { readOnly: true });
+    const reader = database;
     const value = (key: string) =>
       (
-        database.prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key = ?").get(key) as
+        reader.prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key = ?").get(key) as
           | { value?: string }
           | undefined
       )?.value;
@@ -50,58 +23,11 @@ export function readSnapshotFileCount(
       hasRequiredPayloads(database)
         ? files
         : null;
-    database.close();
-    return result;
-  } catch {
-    return null;
-  }
-}
-
-export async function mostRecentCompatibleSnapshot(
-  directory: string,
-  schemaVersion: string,
-  hasRequiredPayloads: (database: DatabaseSync) => boolean,
-): Promise<{ path: string; files: number } | null> {
-  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
-  const candidates = await Promise.all(
-    entries
-      .filter((entry) => entry.isFile() && entry.name.endsWith(".sqlite"))
-      .map(async (entry) => ({
-        path: join(directory, entry.name),
-        mtime: (await stat(join(directory, entry.name))).mtimeMs,
-      })),
-  );
-  for (const candidate of candidates.sort((left, right) => right.mtime - left.mtime)) {
-    const files = readCompatibleSnapshotFileCount(
-      candidate.path,
-      schemaVersion,
-      hasRequiredPayloads,
-    );
-    if (files !== null) return { path: candidate.path, files };
-  }
-  return null;
-}
-
-function readCompatibleSnapshotFileCount(
-  path: string,
-  schemaVersion: string,
-  hasRequiredPayloads: (database: DatabaseSync) => boolean,
-): number | null {
-  try {
-    const database = new DatabaseSync(path, { readOnly: true });
-    const value = (key: string) =>
-      (
-        database.prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key = ?").get(key) as
-          | { value?: string }
-          | undefined
-      )?.value;
-    const files = Number(value("source_file_count") ?? 0);
-    const result =
-      value("schema_version") === schemaVersion && hasRequiredPayloads(database) ? files : null;
-    database.close();
     return result;
   } catch {
     return null;
+  } finally {
+    database?.close();
   }
 }
 
@@ -112,18 +38,13 @@ export function installLegacyViewAliases(database: DatabaseSync): void {
   for (const { name } of views) {
     const alias = name.slice("zaip_vw_".length);
     const quoted = (identifier: string) => `"${identifier.replaceAll('"', '""')}"`;
+    // A transaction may still have a staging table with a legacy public name.
+    // The table is already the intended source in that connection, so a TEMP
+    // alias would collide and make the complete transaction impossible.
+    const existing = database
+      .prepare("SELECT 1 FROM sqlite_temp_master WHERE name=? LIMIT 1")
+      .get(alias);
+    if (existing !== undefined) continue;
     database.exec(`CREATE TEMP VIEW ${quoted(alias)} AS SELECT * FROM main.${quoted(name)}`);
   }
 }
-
-export async function materializeSnapshot(source: string, destination: string): Promise<void> {
-  await mkdir(dirname(destination), { recursive: true });
-  const temporaryPath = `${destination}.${process.pid}.${randomUUID()}.tmp`;
-  await copyFile(source, temporaryPath);
-  try {
-    await rename(temporaryPath, destination);
-  } catch (error) {
-    await rm(temporaryPath, { force: true });
-    throw error;
-  }
-}

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-launch-claims.test.mjs

@@ -0,0 +1,79 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  claimDashboardLaunch,
+  host,
+  requestBackgroundProjectionRefresh,
+  workspaceKey,
+} from "./start-dashboard.mjs";
+
+const temporaryDirectories = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+describe("dashboard launch claims", () => {
+  it("blocks the new launch before SQLite when the superseded launcher will not exit", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-launch.json");
+    await writeFile(
+      path,
+      JSON.stringify({ kind: "zaip-dashboard-sqlite-launch", workspaceKey, launcherPid: 1234 }),
+    );
+    const stops = [];
+    await expect(
+      claimDashboardLaunch(
+        { launchPort: 4317, token: "newest-token" },
+        {
+          path,
+          stopProcessTreeImpl: async (pid) => stops.push(pid),
+          isKnownDashboardLauncherImpl: async () => true,
+          isProcessAliveImpl: async () => true,
+          delayImpl: async () => {},
+        },
+      ),
+    ).rejects.toThrow("Could not stop the superseded dashboard launcher");
+    expect(stops).toEqual([1234]);
+  });
+
+  it("recovers a recent claim lock immediately when its owner PID is dead", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "launch.json");
+    const lockPath = join(directory, "claim.lock");
+    await mkdir(lockPath);
+    await writeFile(join(lockPath, "owner"), "999999", "utf8");
+    await claimDashboardLaunch(
+      { launchPort: 4317, token: "new-token" },
+      { path, lockPath, isProcessAliveImpl: async () => false },
+    );
+    await expect(readFile(path, "utf8")).resolves.toContain('"launchPort": 4317');
+  });
+
+  it("requests a coalesced projection refresh after reusing a warm session", async () => {
+    const calls = [];
+    await requestBackgroundProjectionRefresh(
+      { port: 4417, token: "warm-token" },
+      async (url, init) => calls.push({ url, init }),
+    );
+    expect(calls).toEqual([
+      {
+        url: `http://${host}:4417/api/v2/refresh-projection`,
+        init: expect.objectContaining({
+          method: "POST",
+          headers: { "x-zaip-session": "warm-token" },
+        }),
+      },
+    ]);
+  });
+});
+
+async function temporaryDirectory() {
+  const path = await mkdtemp(join(tmpdir(), "zaip-dashboard-launch-claims-"));
+  temporaryDirectories.push(path);
+  return path;
+}

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-launch-page.mjs

@@ -9,6 +9,18 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
     detail: "Abrindo a página de preparação.",
   };
   let progressSteps = [{ phase: progress.phase, detail: progress.detail }];
+  const browserLeases = new Set();
+  let resolveBrowserDeparture;
+  const browserDeparture = new Promise((resolve) => {
+    resolveBrowserDeparture = resolve;
+  });
+  const browserLeaseGraceMs = 12_000;
+  let browserDepartureTimer = null;
+  const scheduleBrowserDeparture = () => {
+    if (browserLeases.size > 0 || browserDepartureTimer !== null) return;
+    browserDepartureTimer = setTimeout(() => resolveBrowserDeparture(), browserLeaseGraceMs);
+    browserDepartureTimer.unref?.();
+  };
   progress = { ...progress, steps: progressSteps };
   const connections = new Set();
   let resolveRedirectObserved;
@@ -36,6 +48,18 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
       response.end(JSON.stringify({ ...progress, failure }));
       return;
     }
+    if (request.url?.startsWith("/api/v2/browser-lease")) {
+      if (browserDepartureTimer !== null) clearTimeout(browserDepartureTimer);
+      browserDepartureTimer = null;
+      browserLeases.add(response);
+      response.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-store" });
+      response.write("event: lease\ndata: active\n\n");
+      response.once("close", () => {
+        browserLeases.delete(response);
+        scheduleBrowserDeparture();
+      });
+      return;
+    }
     if (request.url?.startsWith(healthPath)) {
       response.writeHead(503, { "Content-Type": "application/json; charset=utf-8" });
       response.end(JSON.stringify({ kind: "zaip-dashboard-launcher", status: "starting" }));
@@ -70,6 +94,7 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
     function setProgressBar(percent,phase){lastProgressPercent=percent;document.getElementById("bar").style.width=percent+"%";document.getElementById("track").setAttribute("aria-valuenow",String(percent));document.getElementById("track").setAttribute("aria-valuetext",phase)}
     function showHandoff(target){handoffTarget=target;stopCompilationTicker();setProgressBar(100,"Dashboard pronto");document.querySelector(".launch-overlay").setAttribute("aria-busy","false");document.getElementById("handoff").style.display="block";document.getElementById("phase").textContent="Dashboard pronto";document.getElementById("detail").textContent="Concluindo a abertura da tela principal.";document.getElementById("activity").textContent="Preparação concluída."}
     function showFailure(next,percent=lastProgressPercent){terminalFailure=true;clearInterval(progressPoll);stopCompilationTicker();document.querySelector(".launch-overlay").setAttribute("aria-busy","false");document.getElementById("phase").textContent=next.phase;document.getElementById("detail").textContent="A preparação não foi concluída. Consulte a mensagem abaixo para agir.";setProgressBar(percent,next.phase);document.getElementById("handoff").style.display="none";document.getElementById("failure").textContent=next.detail;document.getElementById("failure").style.display="block";document.querySelector(".progress").classList.add("terminal-failure")}
+    const browserLease=new EventSource("/api/v2/browser-lease");
     async function updateProgress(){if(progressRequestInFlight||terminalFailure)return terminalFailure;progressRequestInFlight=true;try{const r=await fetch("/api/v2/progress",{cache:"no-store",signal:AbortSignal.timeout(1000)});const p=await r.json();if(terminalFailure)return true;const percent=Math.max(4,Math.min(100,Number(p.percent)||4));if(p.failure){showFailure(p.failure,percent);return true}if(!handoffTarget){for(const step of Array.isArray(p.steps)?p.steps:[p])recordStep(step);const nextStepKey=p.phase+"\\u0000"+(p.detail??"");if(nextStepKey!==activeStepKey){activeStepKey=nextStepKey;activeStepStartedAt=Date.now()}document.getElementById("phase").textContent=p.phase;const compiling=p.phase.startsWith("Atualizando ");if(compiling){if(compilationStartedAt===null){compilationStartedAt=Date.now();compilationDetail=p.detail;if(!reducedMotion)compilationTicker=setInterval(renderCompilationElapsed,1000)}renderCompilationElapsed()}else{stopCompilationTicker();document.getElementById("detail").textContent=p.detail}renderActivityElapsed()}if(!terminalFailure&&!handoffTarget)setProgressBar(percent,p.phase)}catch{}finally{progressRequestInFlight=false}return terminalFailure}
     const progressPoll=setInterval(updateProgress,250);
     async function waitForDashboard(){try{if(await updateProgress())return;const ready=await fetch("/api/v2/ready",{cache:"no-store",signal:AbortSignal.timeout(1000)});const next=await ready.json();if(next.failure){showFailure(next.failure);return}if(next.target){showHandoff(next.target);clearInterval(progressPoll);setTimeout(()=>location.replace(next.target),0);return}const response=await fetch("${healthPath}",{cache:"no-store",signal:AbortSignal.timeout(1000)});const payload=await response.json();if(response.ok&&payload.kind==="${runtimeKind}"){clearInterval(progressPoll);location.reload();return}}catch{}setTimeout(waitForDashboard,250)}
@@ -120,6 +145,7 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
     },
     waitForRedirect: async (timeoutMs = 1_500) =>
       Promise.race([redirectObserved, delay(timeoutMs).then(() => false)]),
+    waitForBrowserDeparture: () => browserDeparture,
     closeAfterHandoffGrace: (graceMs = 12_000) => {
       const timer = setTimeout(() => {
         void server.close();
@@ -153,6 +179,7 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
           if (error) rejectClose(error);
           else resolveClose();
         };
+        if (browserDepartureTimer !== null) clearTimeout(browserDepartureTimer);
         server.close(finish);
         forceTimer = setTimeout(() => {
           server.closeAllConnections?.();

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-lifecycle.mjs

@@ -39,20 +39,20 @@ export async function awaitOwnedDashboardExit({
   currentSession,
   clearOwnedDashboardSession,
   recordPortStatus,
-  removeGeneratedReadModel,
   processRef = process,
 }) {
   for (const signal of ["SIGINT", "SIGTERM"]) {
     processRef.once(signal, () => child.kill(signal));
   }
-  const exitCode = await new Promise((resolveExit, rejectExit) => {
-    child.once("error", rejectExit);
-    child.once("exit", (code) => resolveExit(code ?? 0));
-  });
+  const exitCode =
+    child.exitCode ??
+    (await new Promise((resolveExit, rejectExit) => {
+      child.once("error", rejectExit);
+      child.once("exit", (code) => resolveExit(code ?? 0));
+    }));
   await clearOwnedDashboardSession();
   if (currentSession !== null) {
     await recordPortStatus(currentSession, "closed");
-    await removeGeneratedReadModel(currentSession.dbPath);
   }
   return exitCode;
 }

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-prerequisites.mjs

@@ -2,7 +2,7 @@ import { access, mkdir } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import process from "node:process";
 
-async function exists(path) {
+export async function exists(path) {
   return access(path).then(
     () => true,
     () => false,

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-refresh.mjs

@@ -40,12 +40,10 @@ async function acquireRefreshLock(lockPath, isProcessAlive) {
 export async function startSeedRefresh(options) {
   const {
     appendLog,
-    cacheDirectory,
     isRunning,
     isProcessAlive,
     lockPath,
     packageRoot,
-    randomBytes,
     refreshLogPath,
     refreshStatusPath,
     sqliteDirectory,
@@ -62,10 +60,7 @@ export async function startSeedRefresh(options) {
       appendLog("Skipped duplicate background SQLite seed refresh; a worker is already running.");
       return;
     }
-    const refreshPath = resolve(
-      sqliteDirectory,
-      `refresh-${process.pid}-${randomBytes(4).toString("hex")}.sqlite`,
-    );
+    const refreshPath = resolve(sqliteDirectory, "zaip-aios-dashboard.sqlite");
     mkdirSync(dirname(refreshStatusPath), { recursive: true });
     const descriptor = openSync(refreshLogPath, "a");
     let worker;
@@ -81,8 +76,6 @@ export async function startSeedRefresh(options) {
             ZAIP_SQLITE_DB_PATH: refreshPath,
             ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
             ZAIP_DASHBOARD_LAUNCH_PROGRESS: "0",
-            ZAIP_SQLITE_REFRESH_CLEANUP: "1",
-            ZAIP_SQLITE_CACHE_DIR: cacheDirectory,
           },
           stdio: ["ignore", descriptor, descriptor],
           detached: true,
@@ -101,7 +94,6 @@ export async function startSeedRefresh(options) {
         status: "running",
         pid: worker.pid,
         path: refreshPath,
-        cacheDirectory,
         startedAt: new Date().toISOString(),
       });
     } catch (error) {
@@ -130,7 +122,7 @@ export async function startSeedRefresh(options) {
     });
     worker.unref();
     appendLog(
-      `Started background SQLite seed refresh at ${refreshPath}; cache ${cacheDirectory}; worker log ${refreshLogPath}.`,
+      `Started transactional refresh of the persistent SQLite database at ${refreshPath}; worker log ${refreshLogPath}.`,
     );
   } finally {
     try {

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-server.mjs

@@ -0,0 +1,142 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import process from "node:process";
+
+export function isPortFree(host, port) {
+  return new Promise((resolvePort) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", () => resolvePort(false));
+    server.listen({ host, port }, () => server.close(() => resolvePort(true)));
+  });
+}
+
+export async function startDashboardServer({
+  serverPath,
+  token,
+  excludedPorts,
+  initialPort = null,
+  onProgress = () => {},
+  onChildStarted = () => {},
+  maxAttempts,
+  dbPath,
+  packageRoot,
+  workspaceRoot,
+  frontendRoot,
+  compileCacheDirectory,
+  findPort,
+  waitForDashboard,
+  stopProcessTree,
+  sanitize,
+  formatError,
+  appendLog,
+}) {
+  const failures = [];
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const port =
+      attempt === 1 && Number.isInteger(initialPort)
+        ? initialPort
+        : await findPort({ excludedPorts: [...excludedPorts] });
+    excludedPorts.add(port);
+    let stderr = "";
+    let startupTelemetryBuffer = "";
+    let snapshotCache = null;
+    const child = spawn(process.execPath, [serverPath], {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        ZAIP_WORKSPACE: workspaceRoot,
+        ZAIP_UI_ROOT: frontendRoot,
+        ZAIP_UI_TOKEN: token,
+        ZAIP_SERVER_PORT: String(port),
+        NODE_COMPILE_CACHE: compileCacheDirectory,
+        NODE_NO_WARNINGS: "1",
+        ZAIP_DASHBOARD_LAUNCH_PROGRESS: "1",
+        ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
+        ZAIP_SQLITE_DB_PATH: dbPath,
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true,
+    });
+    onChildStarted(child);
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-4_000);
+      startupTelemetryBuffer = `${startupTelemetryBuffer}${String(chunk)}`;
+      const lines = startupTelemetryBuffer.split("\n");
+      startupTelemetryBuffer = lines.pop() ?? "";
+      for (const line of lines)
+        reportStartupProgress(line, onProgress, (value) => {
+          snapshotCache = value;
+        });
+    });
+    try {
+      await waitForDashboard(port, child);
+      for (const timing of sanitize(stderr)
+        .split("\n")
+        .filter(
+          (line) =>
+            line.includes('"event":"dashboard_sqlite_read_model"') ||
+            line.includes('"event":"dashboard_sqlite_startup_phase"'),
+        ))
+        appendLog(timing);
+      return { child, port, dbPath, snapshotCache };
+    } catch (error) {
+      await stopProcessTree(child.pid);
+      const detail = sanitize(stderr)
+        .split("\n")
+        .filter(
+          (line) =>
+            !line.includes("ExperimentalWarning") && !line.includes("node --trace-warnings"),
+        )
+        .join("\n")
+        .trim();
+      failures.push(
+        `porta ${port}: ${error.message}${detail ? ` — ${formatError(detail, 600)}` : ""}`,
+      );
+      appendLog(`Dashboard start attempt ${attempt} failed on port ${port}: ${error.message}`);
+      if (error.retryable === false) break;
+    }
+  }
+  throw new Error(
+    `Não foi possível iniciar o dashboard após os fallbacks. ${failures.join(" | ")}`,
+  );
+}
+
+function reportStartupProgress(line, onProgress, setSnapshotCache) {
+  try {
+    const event = JSON.parse(line);
+    if (event?.event === "dashboard_sqlite_rebuild_progress")
+      onProgress({
+        percent: event.percent,
+        phase: "Configurando o banco SQLite local",
+        detail:
+          "Esta é a instalação/atualização da cópia local descartável; nenhum servidor externo é instalado.",
+      });
+    if (event?.event === "dashboard_sqlite_startup_phase" && event.phase === "main_entered")
+      onProgress({
+        percent: 50,
+        phase: "Lendo os registros do projeto",
+        detail: "Preparando o read model SQLite local.",
+      });
+    if (event?.event === "dashboard_sqlite_read_model") {
+      setSnapshotCache(event.cache);
+      onProgress({
+        percent: 82,
+        phase: "Banco local pronto",
+        detail:
+          event.cache === "rebuilt"
+            ? "O read model SQLite foi reconstruído para os dados atuais."
+            : "Uma cópia local do read model foi preparada.",
+      });
+    }
+    if (event?.event === "dashboard_sqlite_startup_phase" && event.phase === "listening")
+      onProgress({
+        percent: 88,
+        phase: "Iniciando a interface",
+        detail: "Verificando saúde e disponibilidade dos dados.",
+      });
+  } catch {
+    // Only structured startup telemetry affects user-facing progress.
+  }
+}