@zaip-ai/cli 1.0.7 → 1.3.0

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

@@ -1,23 +1,30 @@
 import { EventEmitter } from "node:events";
 import { mkdir, mkdtemp, readFile, rm, utimes } from "node:fs/promises";
-import { createServer } from "node:net";
+import { connect, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
+  assertDashboardPrerequisites,
   browserLaunchCommands,
   findAvailablePort,
   findAvailablePortWithFallback,
   findReusableDashboardSession,
   formatLauncherError,
   host,
+  isAncestorProcess,
+  isProcessAlive,
   openBrowser,
+  previousDashboardSessions,
   probeDashboardPort,
   readPortRegistry,
   recordPortStatus,
+  registeredListenerMatches,
   runtimeKind,
   startDashboardLaunchPage,
+  stopOwnedDashboardProcess,
   stripTerminalControlCodes,
+  teardownWarning,
   withLauncherLock,
   workspaceKey,
   workspaceRoot,
@@ -33,12 +40,33 @@ afterEach(async () => {
 });
 
 describe("dashboard executable session", () => {
+  it("imports teardown bindings for the launcher implementation", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain("stopProcessTree,");
+    expect(source).toContain("teardownWarning,");
+    expect(source).toContain('from "./start-dashboard-processes.mjs";');
+  });
+
   it("removes terminal control sequences from launcher diagnostics", () => {
     const colored = "\u001B[31mMissing export\u001B[0m\r\n";
 
     expect(stripTerminalControlCodes(colored)).toBe("Missing export");
   });
 
+  it("shows preparation before validating a Node runtime that can import node:sqlite", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain("export async function assertDashboardPrerequisites()");
+    expect(source).toContain('await import("node:sqlite")');
+    expect(source).not.toContain('builtinModules.includes("node:sqlite")');
+    expect(source).toContain("Node.js 22 ou superior");
+    expect(source.indexOf("await openBrowser(dashboardUrl(launchPort, token))")).toBeLessThan(
+      source.indexOf("await assertDashboardPrerequisites();"),
+    );
+    await expect(assertDashboardPrerequisites()).resolves.toBeUndefined();
+  });
+
   it("keeps the beginning and end of an oversized launcher error", () => {
     const message = `imported-symbol${"x".repeat(100)}missing-export`;
 
@@ -46,44 +74,133 @@ describe("dashboard executable session", () => {
     expect(formatLauncherError(message, 40)).toContain("missing-export");
   });
 
-  it("starts a new runtime instead of reusing a healthy session", async () => {
+  it("reuses a healthy runtime only when its build signature remains compatible", async () => {
     const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
-    expect(source).not.toContain("const reusable = await findReusableDashboardSession");
-    expect(source).toContain("const previousSessions = await previousDashboardSessions();");
+    expect(source).toContain("expectedBuildSignature: buildSignature,");
+    expect(source).toContain('expectedSnapshotState: "current",');
+    expect(source).toContain(
+      "Reused healthy compatible dashboard session on port ${reusable.port}",
+    );
     expect(source).toContain(
-      "const excludedPorts = new Set([...previousSessions.map((session) => session.port), launchPort]);",
+      "await redirectLaunchPage(launchPage, dashboardUrl(reusable.port, reusable.token));",
+    );
+    expect(source).toContain("const previousSessions = await previousDashboardSessions();");
+    const excludedPorts = source.slice(
+      source.indexOf("const excludedPorts = new Set(["),
+      source.indexOf("const serverPath = await assertRuntimeReady();"),
     );
+    expect(excludedPorts).toContain("...previousSessions.map((session) => session.port),");
+    expect(excludedPorts).toContain("launchPort,");
   });
 
   it("opens preparation before checking freshness and keeps it through server health", async () => {
     const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
     const lock = source.indexOf("await withLauncherLock(async () => {");
-    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(launchPort);");
+    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const freshness = source.indexOf("const buildSignature = await ensureFreshDashboardBuild();");
     const server = source.indexOf(
-      "const { child, port } = await startDashboardServer(serverPath, token, excludedPorts);",
-    );
-    const redirectAfterServer = source.indexOf(
-      "await redirectLaunchPage(launchPage, dashboardUrl(port, token));",
+      "const { child, port, dbPath, snapshotCache } = await startDashboardServer(",
     );
+    const redirectAfterServer = source.indexOf("await redirectLaunchPage(", server);
 
     expect(lock).toBeGreaterThan(-1);
-    expect(preparation).toBeGreaterThan(lock);
+    expect(preparation).toBeLessThan(lock);
     expect(preparation).toBeLessThan(freshness);
     expect(server).toBeGreaterThan(freshness);
     expect(redirectAfterServer).toBeGreaterThan(server);
   });
 
+  it("reports readiness failures as actionable without retrying a build storm", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const wait = source.slice(
+      source.indexOf("async function waitForDashboard"),
+      source.indexOf("function exists"),
+    );
+    expect(wait).toContain("Dashboard data readiness returned ${readiness.status}");
+    expect(wait).toContain("unavailable.retryable = false;");
+    expect(wait).toContain("if (error?.retryable === false) throw error;");
+    expect(wait).toContain("await delay(100);");
+  });
+
+  it("streams complete structured rebuild progress records even when stderr chunks split a line", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain('let startupTelemetryBuffer = "";');
+    expect(source).toContain(
+      "startupTelemetryBuffer = `${startupTelemetryBuffer}${String(chunk)}`;",
+    );
+    expect(source).toContain('event?.event === "dashboard_sqlite_rebuild_progress"');
+    expect(source).toContain('ZAIP_DASHBOARD_LAUNCH_PROGRESS: "1"');
+  });
+
+  it("uses one durable cache and an append-only worker log for a stale snapshot refresh", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain(
+      'const sqliteSnapshotCacheDirectory = join(sqliteReadModelDirectory, "cache");',
+    );
+    expect(source).toContain("ZAIP_SQLITE_CACHE_DIR: sqliteSnapshotCacheDirectory,");
+    expect(source).toContain(
+      'const refreshLogPath = join(sessionDirectory, "dashboard-sqlite-refresh.log");',
+    );
+    expect(source).toContain('stdio: ["ignore", refreshLogDescriptor, refreshLogDescriptor]');
+    expect(source).toContain("worker log ${refreshLogPath}");
+  });
+
+  it("keeps a visible, actionable handoff watchdog instead of closing the preparation page before navigation", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+
+    expect(source).toContain('id="handoff-link"');
+    expect(source).toContain("function showHandoff(target)");
+    expect(source).toContain("setTimeout(()=>location.replace(next.target),0)");
+    expect(source).toContain("closeAfterHandoffGrace: (graceMs = 12_000)");
+    expect(source).toContain("launchPage.closeAfterHandoffGrace();");
+    expect(source).not.toContain("await launchPage.close();\n  if (!redirected");
+  });
+
   it("tears down prior owned sessions only after the new browser handoff", async () => {
     const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
-    const redirect = source.indexOf(
-      "await redirectLaunchPage(launchPage, dashboardUrl(port, token));",
+    const server = source.indexOf(
+      "const { child, port, dbPath, snapshotCache } = await startDashboardServer(",
     );
+    const redirect = source.indexOf("await redirectLaunchPage(", server);
     const teardown = source.indexOf("for (const previous of previousSessions)");
 
     expect(redirect).toBeGreaterThan(-1);
     expect(teardown).toBeGreaterThan(redirect);
-    expect(source).toContain("const stopped = await stopOwnedDashboard(previous);");
+    expect(source).toContain("const status = await stopOwnedDashboard(previous);");
+  });
+
+  it("does not mark an owned prior session closed while its registered listener remains", async () => {
+    const source = await readFile(
+      new URL("./start-dashboard-processes.mjs", import.meta.url),
+      "utf8",
+    );
+
+    expect(source).toContain("const listenerStillMatches = registeredListenerMatches(");
+    expect(source).toContain("!listenerStillMatches");
+    expect(source).toContain("await stopProcessTreeImpl(session.serverPid);");
+  });
+
+  it("keeps a failed health probe with a foreign listener out of the closed registry state", async () => {
+    const stopCalls = [];
+    const status = await stopOwnedDashboardProcess(
+      { port: 4317, rootPid: 1234, serverPid: 5678 },
+      {
+        probeDashboardPort: async () => false,
+        workspaceKey,
+        fetchImpl: fetch,
+        host,
+        packageRoot: "unused",
+        delay: async () => {},
+        listeningProcessIdImpl: async () => 9999,
+        isProcessAliveImpl: async () => true,
+        stopProcessTreeImpl: async (pid) => stopCalls.push(pid),
+      },
+    );
+
+    expect(status).toBe("skipped_unowned");
+    expect(stopCalls).toEqual([]);
   });
 
   it("does not force a rebuild from the Windows executable", async () => {
@@ -95,6 +212,60 @@ describe("dashboard executable session", () => {
     expect(source).not.toContain("ZAIP_DASHBOARD_FORCE_REBUILD");
   });
 
+  it("accepts a healthy new same-workspace port without scanning historical active ports", async () => {
+    const source = await readFile(
+      new URL("../windows-launcher/Program.cs", import.meta.url),
+      "utf8",
+    );
+
+    expect(source).toContain("The new same-workspace healthy port is definitive success.");
+    expect(source).not.toContain("dashboard-ports.json");
+    expect(source).not.toContain("porta anterior reconhecida");
+    expect(source).toContain("return true;");
+  });
+
+  it("treats the Node-confirmed handoff as definitive instead of rediscovering mutable session state", async () => {
+    const source = await readFile(
+      new URL("../windows-launcher/Program.cs", import.meta.url),
+      "utf8",
+    );
+
+    const ok = source.indexOf('if (status.StartsWith("ok", StringComparison.OrdinalIgnoreCase))');
+    const warning = source.indexOf(
+      'if (status.StartsWith("warning", StringComparison.OrdinalIgnoreCase))',
+    );
+    const okBranch = source.slice(ok, warning);
+
+    expect(ok).toBeGreaterThan(-1);
+    expect(okBranch).toContain("return 0;");
+    expect(okBranch).not.toContain("VerifyDashboardLaunch");
+  });
+
+  it("publishes ok only after Node observed both health and readiness", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const wait = source.slice(
+      source.indexOf("async function waitForDashboard"),
+      source.indexOf("function exists"),
+    );
+
+    expect(wait).toContain("dashboardHealthUrl(port)");
+    expect(wait).toContain("/api/v2/ready");
+    expect(source.indexOf('await writeLauncherStatus("ok");')).toBeGreaterThan(
+      source.indexOf("await waitForDashboard(port, child);"),
+    );
+  });
+
+  it("records prior-port cleanup warnings while still publishing an ok handoff", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const cleanup = source.indexOf("const status = await stopOwnedDashboard(previous);");
+    const warning = source.indexOf("Dashboard launched on port ${port}; prior-port cleanup:");
+    const success = source.indexOf('await writeLauncherStatus("ok");', cleanup);
+
+    expect(cleanup).toBeGreaterThan(-1);
+    expect(warning).toBeGreaterThan(cleanup);
+    expect(success).toBeGreaterThan(warning);
+  });
+
   it("dispatches Windows URLs through the registered protocol handler", () => {
     const target = "http://127.0.0.1:4317/?token=local-session-token";
     const commands = browserLaunchCommands(target, "win32", {
@@ -122,14 +293,25 @@ describe("dashboard executable session", () => {
     expect(calls).toBe(2);
   });
 
-  it("serves an immediate dashboard skeleton while the runtime starts", async () => {
+  it("serves a viewport-covering centered progress overlay while the runtime starts", async () => {
     const launchPage = await startDashboardLaunchPage(0);
     try {
       const page = await fetch(`http://${host}:${launchPage.port}/?token=temporary`);
       const health = await fetch(`http://${host}:${launchPage.port}/api/v2/health`);
 
       expect(page.status).toBe(200);
-      await expect(page.text()).resolves.toContain("Pronto para Executar");
+      const html = await page.text();
+      expect(html).toContain('class="launch-overlay"');
+      expect(html).toContain("position:fixed;inset:0;width:100vw;height:100vh");
+      expect(html).toContain("display:grid;place-items:center");
+      expect(html).toContain('aria-live="polite" role="status"');
+      expect(html).toContain("abra o dashboard agora");
+      expect(html).toContain("function showHandoff(target)");
+      const progress = await fetch(`http://${host}:${launchPage.port}/api/v2/progress`);
+      await expect(progress.json()).resolves.toMatchObject({
+        phase: "Iniciando o launcher local",
+        percent: expect.any(Number),
+      });
       expect(health.status).toBe(503);
       await expect(health.json()).resolves.toEqual({
         kind: "zaip-dashboard-launcher",
@@ -147,6 +329,22 @@ describe("dashboard executable session", () => {
     }
   });
 
+  it("bounds launch-page shutdown when a browser connection never finishes polling", async () => {
+    const launchPage = await startDashboardLaunchPage(0);
+    const connection = connect({ host, port: launchPage.port });
+    await new Promise((resolveConnected, rejectConnected) => {
+      connection.once("connect", resolveConnected);
+      connection.once("error", rejectConnected);
+    });
+    const closed = new Promise((resolveClosed) => connection.once("close", resolveClosed));
+    const startedAt = Date.now();
+    await launchPage.close({ forceAfterMs: 20 });
+    await closed;
+
+    expect(Date.now() - startedAt).toBeLessThan(500);
+    expect(connection.destroyed).toBe(true);
+  });
+
   it("reuses a healthy session owned by the same workspace", async () => {
     const directory = await temporaryDirectory();
     const path = join(directory, "dashboard-session.json");
@@ -155,19 +353,24 @@ describe("dashboard executable session", () => {
       workspace: workspaceRoot,
       workspaceKey,
       rootPid: 1234,
+      serverPid: 5678,
       port: 4317,
       token: "local-session-token",
+      buildSignature: "compatible-build",
+      snapshotState: "current",
       createdAt: new Date().toISOString(),
     };
     await writeDashboardSession(session, path);
 
     const reusable = await findReusableDashboardSession({
       path,
+      expectedBuildSignature: "compatible-build",
       fetchImpl: async () =>
         new Response(JSON.stringify({ kind: runtimeKind, workspaceKey }), { status: 200 }),
     });
 
     expect(reusable).toEqual(session);
+    expect(reusable).toMatchObject({ port: 4317, serverPid: 5678 });
   });
 
   it("does not claim a health endpoint from another workspace", async () => {
@@ -222,6 +425,35 @@ describe("dashboard executable session", () => {
     ).resolves.toBeNull();
   });
 
+  it("does not reuse an updating stale snapshot after its background refresh", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-session.json");
+    await writeDashboardSession(
+      {
+        kind: runtimeKind,
+        workspace: workspaceRoot,
+        workspaceKey,
+        rootPid: 1234,
+        serverPid: 5678,
+        port: 4317,
+        token: "stale-session-token",
+        buildSignature: "compatible-build",
+        snapshotState: "updating",
+      },
+      path,
+    );
+
+    await expect(
+      findReusableDashboardSession({
+        path,
+        expectedBuildSignature: "compatible-build",
+        expectedSnapshotState: "current",
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ kind: runtimeKind, workspaceKey }), { status: 200 }),
+      }),
+    ).resolves.toBeNull();
+  });
+
   it("recognizes an unavailable runtime only for safe cleanup", async () => {
     const fetchImpl = async () =>
       new Response(JSON.stringify({ kind: runtimeKind, workspaceKey, status: "unavailable" }), {
@@ -254,6 +486,34 @@ describe("dashboard executable session", () => {
     expect(selectedPort).not.toBe(previousPort);
   });
 
+  it("does not report invalid or departed launcher PIDs as live", async () => {
+    await expect(isProcessAlive(0)).resolves.toBe(false);
+    await expect(isProcessAlive(-1)).resolves.toBe(false);
+  });
+
+  it("does not authorize teardown when a registry server PID was reused", () => {
+    const session = { rootPid: 1234, serverPid: 5678, port: 4317 };
+    expect(registeredListenerMatches(session, 9999)).toBe(false);
+    expect(registeredListenerMatches(session, null)).toBe(false);
+    expect(registeredListenerMatches(session, 5678)).toBe(true);
+  });
+
+  it("keeps skipped unowned listeners auditable without failing a healthy launch", () => {
+    expect(teardownWarning("skipped_unowned")).toBe(false);
+    expect(teardownWarning("close_failed")).toBe(true);
+  });
+
+  it("requires the recorded launcher root to be an ancestor of the server", async () => {
+    const parentOf = async (pid) =>
+      new Map([
+        [30, 20],
+        [20, 10],
+        [10, null],
+      ]).get(pid) ?? null;
+    await expect(isAncestorProcess(10, 30, parentOf)).resolves.toBe(true);
+    await expect(isAncestorProcess(99, 30, parentOf)).resolves.toBe(false);
+  });
+
   it("persists active and closed dashboard ports per workspace", async () => {
     const directory = await temporaryDirectory();
     const path = join(directory, "dashboard-ports.json");
@@ -275,6 +535,27 @@ describe("dashboard executable session", () => {
     ]);
   });
 
+  it("rechecks a closed registry entry that still has this workspace runtime listening", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "dashboard-ports.json");
+    const session = {
+      rootPid: 1234,
+      serverPid: 5678,
+      port: 4317,
+      createdAt: "2026-07-15T00:00:00.000Z",
+    };
+    await recordPortStatus(session, "active", path);
+    await recordPortStatus(session, "closed", path);
+
+    await expect(
+      previousDashboardSessions({
+        sessionPath: join(directory, "missing-session.json"),
+        registryPath: path,
+        probe: async () => true,
+      }),
+    ).resolves.toEqual([expect.objectContaining({ port: 4317, rootPid: 1234, status: "closed" })]);
+  });
+
   it("recovers an abandoned launcher lock", async () => {
     const directory = await temporaryDirectory();
     const path = join(directory, "dashboard-launcher.lock");
@@ -346,20 +627,39 @@ describe("dashboard executable session", () => {
     await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]);
   });
 
-  it("coalesces a click that observes a newly handed-off healthy session", async () => {
+  it("opens preparation before waiting and only reuses after checking the current build", async () => {
     const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
-    const observed = source.indexOf("const observedRootPid = observedSession?.rootPid ?? null;");
+    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
     const lock = source.indexOf("await withLauncherLock(async () => {");
-    const coalesced = source.indexOf("Coalesced dashboard launcher request");
-    const preparation = source.indexOf("launchPage = await startDashboardLaunchPage(launchPort);");
+    const buildSignature = source.indexOf(
+      "const buildSignature = await ensureFreshDashboardBuild();",
+    );
+    const reusable = source.indexOf("const reusable = await findReusableDashboardSession({");
 
-    expect(observed).toBeGreaterThan(-1);
-    expect(observed).toBeLessThan(lock);
-    expect(coalesced).toBeGreaterThan(lock);
-    expect(preparation).toBeGreaterThan(coalesced);
+    expect(preparation).toBeLessThan(lock);
+    expect(buildSignature).toBeGreaterThan(lock);
+    expect(reusable).toBeGreaterThan(buildSignature);
+    expect(source).toContain(
+      "await redirectLaunchPage(launchPage, dashboardUrl(reusable.port, reusable.token));",
+    );
+    expect(source).toContain(
+      'snapshotState: snapshotCache === "stale_seed" ? "updating" : "current",',
+    );
+    expect(source).toContain("if (launchPage !== null) await launchPage.close().catch(() => {});");
     expect(source).toContain('await writeLauncherStatus("ok");');
   });
 
+  it("binds preparation atomically instead of reserving a probe-selected port", async () => {
+    const source = await readFile(new URL("./start-dashboard.mjs", import.meta.url), "utf8");
+    const preparationStart = source.indexOf("launchPage = await startDashboardLaunchPage(0);");
+    const lock = source.indexOf("await withLauncherLock(async () => {");
+    const beforeLock = source.slice(preparationStart, lock);
+
+    expect(preparationStart).toBeGreaterThan(-1);
+    expect(source).toContain("const launchPort = launchPage.port;");
+    expect(beforeLock).not.toContain("findAvailablePortWithFallback(");
+  });
+
   it("gives the Windows wrapper margin beyond the bounded Node launcher wait", async () => {
     const source = await readFile(
       new URL("../windows-launcher/Program.cs", import.meta.url),

package/templates/.agents/dashboard/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-ui",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "private": true,
   "type": "module",
   "exports": {