@zaip-ai/cli 0.1.0 → 1.0.2

package/templates/.zaip-aios/dashboard/packages/local-runtime/start-dashboard.mjs

@@ -0,0 +1,726 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { access, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createServer as createHttpServer } from "node:http";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, win32 } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+export const host = "127.0.0.1";
+export const defaultPort = 4317;
+export const maxPortAttempts = 25;
+export const runtimeKind = "zaip-dashboard-local-runtime";
+
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+export const workspaceRoot = resolve(packageRoot, "../../../..");
+export const workspaceKey = createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
+export const sessionDirectory = join(tmpdir(), "zaip-aios", workspaceKey);
+export const sessionPath = join(sessionDirectory, "dashboard-session.json");
+export const portRegistryPath = join(sessionDirectory, "dashboard-ports.json");
+export const lockPath = join(sessionDirectory, "dashboard-launcher.lock");
+export const launcherLogPath = join(sessionDirectory, "dashboard-launcher.log");
+
+const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend/dist");
+const installedServer = resolve(packageRoot, "server.mjs");
+const sourceServer = resolve(packageRoot, "dist/server.js");
+const healthPath = "/api/v2/health";
+const lockTimeoutMs = 10_000;
+const staleLockMs = 30_000;
+const startupTimeoutMs = 12_000;
+const maxServerStartAttempts = 4;
+const maxPortHistory = 50;
+const dashboardSourceRoots = [
+  resolve(workspaceRoot, ".agents/dashboard/apps/frontend/src"),
+  resolve(workspaceRoot, ".agents/dashboard/modules"),
+  resolve(workspaceRoot, ".agents/dashboard/packages/ui/src"),
+  resolve(packageRoot, "src"),
+];
+
+export function preferredPort(value = process.env.ZAIP_SERVER_PORT) {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : defaultPort;
+}
+
+export function dashboardHealthUrl(port) {
+  return `http://${host}:${port}${healthPath}`;
+}
+
+export function dashboardUrl(port, token) {
+  return `http://${host}:${port}/?token=${encodeURIComponent(token)}`;
+}
+
+export function appendLauncherLog(message) {
+  try {
+    mkdirSync(sessionDirectory, { recursive: true });
+    appendFileSync(
+      launcherLogPath,
+      `[${new Date().toISOString()}] ${stripTerminalControlCodes(message)}\n`,
+      "utf8",
+    );
+  } catch {
+    // Best-effort diagnostics must not hide the launcher failure.
+  }
+}
+
+export function stripTerminalControlCodes(value) {
+  return String(value)
+    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/g, "")
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\r/g, "")
+    .trim();
+}
+
+export function formatLauncherError(value, maximumLength = 3_600) {
+  const message = stripTerminalControlCodes(value);
+  if (message.length <= maximumLength) return message;
+
+  const firstHalf = Math.floor(maximumLength / 2);
+  const lastHalf = maximumLength - firstHalf;
+  return `${message.slice(0, firstHalf)}\n\n… detalhes reduzidos; consulte o log temporário …\n\n${message.slice(-lastHalf)}`;
+}
+
+export async function readDashboardSession(path = sessionPath) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeDashboardSession(session, path = sessionPath) {
+  await writeJsonAtomic(path, session);
+}
+
+async function writeJsonAtomic(path, value) {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await rename(temporaryPath, path);
+}
+
+export async function readPortRegistry(path = portRegistryPath) {
+  try {
+    const registry = JSON.parse(await readFile(path, "utf8"));
+    if (
+      registry?.workspace !== workspaceRoot ||
+      registry?.workspaceKey !== workspaceKey ||
+      !Array.isArray(registry?.ports)
+    ) {
+      return [];
+    }
+    return registry.ports;
+  } catch {
+    return [];
+  }
+}
+
+export async function recordPortStatus(session, status, path = portRegistryPath) {
+  const entries = await readPortRegistry(path);
+  const now = new Date().toISOString();
+  const matchingIndex = entries.findIndex(
+    (entry) => entry.rootPid === session.rootPid && entry.port === session.port,
+  );
+  const nextEntry = {
+    port: session.port,
+    rootPid: session.rootPid,
+    serverPid: session.serverPid ?? null,
+    openedAt: session.createdAt ?? session.openedAt ?? now,
+    status,
+    closedAt: status === "active" ? null : now,
+  };
+  if (matchingIndex >= 0) entries[matchingIndex] = { ...entries[matchingIndex], ...nextEntry };
+  else entries.push(nextEntry);
+  await writeJsonAtomic(path, {
+    schemaVersion: 1,
+    workspace: workspaceRoot,
+    workspaceKey,
+    updatedAt: now,
+    ports: entries.slice(-maxPortHistory),
+  });
+}
+
+export async function clearOwnedDashboardSession(rootPid = process.pid, path = sessionPath) {
+  const session = await readDashboardSession(path);
+  if (session?.rootPid === rootPid) await rm(path, { force: true });
+}
+
+export async function probeDashboardPort(
+  port,
+  fetchImpl = fetch,
+  expectedWorkspaceKey = workspaceKey,
+  requireHealthy = true,
+) {
+  try {
+    const response = await fetchImpl(dashboardHealthUrl(port), {
+      signal: AbortSignal.timeout(500),
+    });
+    const payload = await response.json();
+    const owned = payload?.kind === runtimeKind && payload.workspaceKey === expectedWorkspaceKey;
+    return owned && (!requireHealthy || response.ok);
+  } catch {
+    return false;
+  }
+}
+
+export async function findReusableDashboardSession({
+  path = sessionPath,
+  startPort = preferredPort(),
+  fetchImpl = fetch,
+  expectedWorkspaceKey = workspaceKey,
+  expectedBuildSignature = null,
+} = {}) {
+  const session = await readDashboardSession(path);
+  if (
+    session?.kind !== runtimeKind ||
+    session?.workspace !== workspaceRoot ||
+    session?.workspaceKey !== expectedWorkspaceKey ||
+    typeof session?.token !== "string" ||
+    session.token.length === 0 ||
+    (expectedBuildSignature !== null && session?.buildSignature !== expectedBuildSignature)
+  ) {
+    return null;
+  }
+  if (
+    Number.isInteger(session.port) &&
+    (await probeDashboardPort(session.port, fetchImpl, expectedWorkspaceKey))
+  ) {
+    return session;
+  }
+
+  const ports = Array.from({ length: maxPortAttempts }, (_, index) => startPort + index).filter(
+    (port) => port <= 65_535 && port !== session.port,
+  );
+  const matches = await Promise.all(
+    ports.map(async (port) =>
+      (await probeDashboardPort(port, fetchImpl, expectedWorkspaceKey)) ? port : null,
+    ),
+  );
+  const port = matches.find((candidate) => candidate !== null);
+  return port === undefined ? null : { ...session, port };
+}
+
+async function latestModifiedAt(paths) {
+  let latest = 0;
+  for (const path of paths) {
+    const details = await stat(path).catch(() => null);
+    if (details === null) continue;
+    latest = Math.max(latest, details.mtimeMs);
+    if (!details.isDirectory()) continue;
+    const entries = await readdir(path, { withFileTypes: true }).catch(() => []);
+    latest = Math.max(
+      latest,
+      await latestModifiedAt(
+        entries
+          .filter((entry) => !new Set(["dist", "node_modules", ".turbo"]).has(entry.name))
+          .map((entry) => join(path, entry.name)),
+      ),
+    );
+  }
+  return latest;
+}
+
+async function runWorkspaceBuild(filter) {
+  const command = process.platform === "win32" ? (process.env.ComSpec ?? "cmd.exe") : "corepack";
+  const args =
+    process.platform === "win32"
+      ? ["/d", "/s", "/c", `corepack pnpm --filter ${filter} build`]
+      : ["pnpm", "--filter", filter, "build"];
+  const output = await new Promise((resolveBuild, rejectBuild) => {
+    const child = spawn(command, args, { cwd: workspaceRoot, windowsHide: true, stdio: "pipe" });
+    let outputText = "";
+    const appendOutput = (chunk) => {
+      outputText = `${outputText}${chunk}`.slice(-8_000);
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", appendOutput);
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", appendOutput);
+    child.once("error", rejectBuild);
+    child.once("exit", (code) => {
+      if (code === 0) resolveBuild();
+      else rejectBuild(new Error(`Build ${filter} failed (${code}): ${formatLauncherError(outputText)}`));
+    });
+  });
+  return output;
+}
+
+async function ensureFreshDashboardBuild() {
+  const artifacts = [resolve(frontendRoot, "index.html"), sourceServer];
+  const [sourcesModifiedAt, artifactsModifiedAt] = await Promise.all([
+    latestModifiedAt(dashboardSourceRoots),
+    latestModifiedAt(artifacts),
+  ]);
+  const forceRebuild = process.env.ZAIP_DASHBOARD_FORCE_REBUILD === "1";
+  if (forceRebuild || artifactsModifiedAt < sourcesModifiedAt) {
+    await runWorkspaceBuild("@zaip-ai/dashboard-frontend");
+    await runWorkspaceBuild("@zaip-ai/dashboard-local-runtime");
+  }
+  const artifactFingerprint = await Promise.all(
+    [...artifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
+      const details = await stat(path);
+      return `${path}:${details.size}:${details.mtimeMs}`;
+    }),
+  );
+  return createHash("sha256").update(artifactFingerprint.join("|")).digest("hex");
+}
+
+export async function withLauncherLock(
+  action,
+  {
+    directory = sessionDirectory,
+    path = lockPath,
+    timeoutMs = lockTimeoutMs,
+    staleAfterMs = staleLockMs,
+  } = {},
+) {
+  await mkdir(directory, { recursive: true });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await mkdir(path);
+      try {
+        return await action();
+      } finally {
+        await rm(path, { recursive: true, force: true });
+      }
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const lockStat = await stat(path).catch(() => null);
+      if (lockStat !== null && Date.now() - lockStat.mtimeMs > staleAfterMs) {
+        await rm(path, { recursive: true, force: true });
+        continue;
+      }
+      await delay(100);
+    }
+  }
+  throw new Error("Timed out waiting for the ZAIP dashboard launcher lock");
+}
+
+export async function findAvailablePort(startPort = preferredPort()) {
+  for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error(
+    `No free dashboard port found between ${startPort} and ${Math.min(startPort + maxPortAttempts - 1, 65_535)}`,
+  );
+}
+
+export async function findAvailablePortWithFallback({
+  preferred = preferredPort(),
+  excludedPorts = [],
+} = {}) {
+  const excluded = new Set(excludedPorts.filter(Number.isInteger));
+  const fallbackStarts = [preferred, defaultPort + 1_000, defaultPort + 4_000].filter(
+    (port, index, ports) => port <= 65_535 && ports.indexOf(port) === index,
+  );
+  for (const startPort of fallbackStarts) {
+    for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
+      if (!excluded.has(port) && (await isPortFree(port))) return port;
+    }
+  }
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const ephemeralPort = await findEphemeralPort();
+    if (!excluded.has(ephemeralPort)) return ephemeralPort;
+  }
+  throw new Error(
+    "No free dashboard port was found in the preferred, fallback, or ephemeral ranges",
+  );
+}
+
+async function findEphemeralPort() {
+  return new Promise((resolvePort, rejectPort) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", rejectPort);
+    server.listen({ host, port: 0 }, () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : null;
+      server.close(() => {
+        if (Number.isInteger(port)) resolvePort(port);
+        else rejectPort(new Error("The operating system did not allocate an ephemeral port"));
+      });
+    });
+  });
+}
+
+export function browserLaunchCommands(
+  target,
+  platform = process.platform,
+  environment = process.env,
+) {
+  if (platform === "win32") {
+    const systemRoot = environment.SystemRoot ?? "C:\\Windows";
+    return [
+      [
+        win32.resolve(systemRoot, "System32", "rundll32.exe"),
+        ["url.dll,FileProtocolHandler", target],
+      ],
+      [
+        environment.ComSpec ?? win32.resolve(systemRoot, "System32", "cmd.exe"),
+        ["/d", "/c", "start", "", target],
+      ],
+    ];
+  }
+  return [[platform === "darwin" ? "open" : "xdg-open", [target]]];
+}
+
+export async function openBrowser(target, spawnImpl = spawn) {
+  if (process.env.ZAIP_UI_NO_BROWSER === "1") return true;
+  const commands = browserLaunchCommands(target);
+  for (const [command, args] of commands) {
+    const launched = await new Promise((resolveLaunch) => {
+      let settled = false;
+      const settle = (value) => {
+        if (settled) return;
+        settled = true;
+        resolveLaunch(value);
+      };
+      try {
+        const browser = spawnImpl(command, args, {
+          detached: true,
+          stdio: "ignore",
+          windowsHide: true,
+        });
+        browser.once("spawn", () => settle(true));
+        browser.once("error", () => settle(false));
+        browser.unref();
+      } catch {
+        settle(false);
+      }
+    });
+    if (launched) return true;
+  }
+  appendLauncherLog(`Could not dispatch the dashboard URL to the default browser: ${target}`);
+  return false;
+}
+
+export async function startDashboardLaunchPage(port) {
+  const server = createHttpServer((request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    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" }));
+      return;
+    }
+    response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    response.end(`<!doctype html>
+<html lang="pt-BR">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Dashboard Zaip AIOS</title>
+  <style>
+    :root{color-scheme:dark;font-family:Inter,system-ui,sans-serif;background:#010610;color:#f1f5f9}
+    *{box-sizing:border-box}body{margin:0;min-height:100vh;background:radial-gradient(circle at 50% 0,rgba(0,176,240,.07),transparent 42%),#010610}
+    main{padding:clamp(18px,2.4vw,38px)}header{display:flex;align-items:center;justify-content:space-between;margin-bottom:24px}h1{font-size:clamp(1.45rem,2.4vw,2.25rem);margin:8px 0 0}
+    .eyebrow,.line,.value,.action,.chart,.pill{display:block;position:relative;overflow:hidden;border-radius:999px;background:#172033}.eyebrow{width:110px;height:10px}.actions{display:flex;gap:10px}.action{width:48px;height:42px;border-radius:12px}
+    .kpis,.panels,.board{display:grid;gap:14px}.kpis{grid-template-columns:repeat(4,minmax(0,1fr))}.kpis article,.panels article,.board article{border:1px solid rgba(255,255,255,.08);border-radius:16px;background:linear-gradient(145deg,rgba(17,24,39,.86),rgba(10,14,23,.92))}
+    .kpis article{min-height:138px;padding:18px}.line{width:86%;height:10px;margin-top:12px}.value{width:42%;height:30px;margin-top:18px}.panels{grid-template-columns:1.7fr 1fr;margin-top:14px}.panels article{padding:18px}.chart{height:156px;margin-top:22px;border-radius:12px;background:repeating-linear-gradient(to bottom,rgba(51,65,85,.3) 0,rgba(51,65,85,.3) 1px,transparent 1px,transparent 38px)}
+    .board{grid-template-columns:repeat(5,minmax(210px,1fr));margin-top:18px;overflow:hidden}.board article{min-height:220px;padding:14px}.board h2{min-height:34px;margin:0 0 12px;color:#cbd5e1;font-size:.82rem}.card{min-height:92px;border:1px solid rgba(255,255,255,.06);border-radius:12px;padding:10px;background:rgba(2,6,23,.56)}.pill{width:52px;height:15px;margin-top:14px}
+    .eyebrow:after,.line:after,.value:after,.action:after,.chart:after,.pill:after{content:"";position:absolute;inset:0;background:linear-gradient(90deg,transparent,rgba(125,211,252,.12),transparent);animation:shine 1.35s ease-in-out infinite;transform:translateX(-100%)}
+    @keyframes shine{to{transform:translateX(100%)}}@media(max-width:860px){.kpis{grid-template-columns:repeat(2,1fr)}.panels{grid-template-columns:1fr}.board{overflow-x:auto}}
+  </style>
+</head>
+<body>
+  <main aria-label="Preparando dashboard">
+    <header><div><span class="eyebrow"></span><h1>Dashboard Zaip AIOS</h1></div><div class="actions"><span class="action"></span><span class="action"></span><span class="action"></span></div></header>
+    <section class="kpis">${Array.from({ length: 4 }, () => '<article><span class="line"></span><span class="value"></span><span class="line"></span></article>').join("")}</section>
+    <section class="panels"><article><span class="line"></span><div class="chart"></div></article><article><span class="line"></span><div class="chart"></div></article></section>
+    <section class="board">${["Definição", "Planejamento", "Pronto para Executar", "Execução", "Verificação"].map((label) => `<article><h2>${label}</h2><div class="card"><span class="line"></span><span class="line"></span><span class="pill"></span></div></article>`).join("")}</section>
+  </main>
+  <script>
+    async function waitForDashboard(){
+      try{
+        const response=await fetch("${healthPath}",{cache:"no-store"});
+        const payload=await response.json();
+        if(response.ok&&payload.kind==="${runtimeKind}"){location.reload();return}
+      }catch{}
+      setTimeout(waitForDashboard,250)
+    }
+    setTimeout(waitForDashboard,100)
+  </script>
+</body>
+</html>`);
+  });
+  await new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen({ host, port }, resolveListen);
+  });
+  server.unref();
+  const address = server.address();
+  const listeningPort = typeof address === "object" && address !== null ? address.port : port;
+  return {
+    port: listeningPort,
+    close: () =>
+      new Promise((resolveClose, rejectClose) => {
+        server.close((error) => (error ? rejectClose(error) : resolveClose()));
+      }),
+  };
+}
+
+async function assertRuntimeReady() {
+  const serverPath = (await exists(sourceServer)) ? sourceServer : installedServer;
+  if (!(await exists(serverPath))) {
+    throw new Error(
+      "Dashboard server bundle is missing; run the ZAIP release build or reinstall ZAIP-AIOS",
+    );
+  }
+  if (!(await exists(resolve(frontendRoot, "index.html")))) {
+    throw new Error(
+      "Dashboard frontend bundle is missing; run the ZAIP release build or reinstall ZAIP-AIOS",
+    );
+  }
+  return serverPath;
+}
+
+async function stopOwnedDashboard(session) {
+  if (!(await probeDashboardPort(session?.port, fetch, workspaceKey, false))) return true;
+  if (!Number.isInteger(session?.rootPid) || session.rootPid <= 0) return false;
+  await stopProcessTree(session.rootPid);
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    if (!(await probeDashboardPort(session.port))) return true;
+    await delay(100);
+  }
+  return false;
+}
+
+async function stopProcessTree(pid) {
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return;
+  if (process.platform === "win32") {
+    await new Promise((resolveStop) => {
+      const killer = spawn("taskkill", ["/pid", String(pid), "/t", "/f"], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      killer.once("error", () => resolveStop());
+      killer.once("exit", () => resolveStop());
+    });
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // A stale recorded PID is already stopped.
+  }
+}
+
+async function previousDashboardSessions() {
+  const session = await readDashboardSession();
+  const registryEntries = (await readPortRegistry()).filter((entry) => entry.status === "active");
+  const candidates = [session, ...registryEntries].filter(Boolean);
+  return candidates.filter(
+    (candidate, index) =>
+      Number.isInteger(candidate.port) &&
+      candidates.findIndex(
+        (entry) => entry.port === candidate.port && entry.rootPid === candidate.rootPid,
+      ) === index,
+  );
+}
+
+async function startDashboardServer(serverPath, token, excludedPorts, initialPort = null) {
+  const failures = [];
+  for (let attempt = 1; attempt <= maxServerStartAttempts; attempt += 1) {
+    const port =
+      attempt === 1 && Number.isInteger(initialPort)
+        ? initialPort
+        : await findAvailablePortWithFallback({ excludedPorts: [...excludedPorts] });
+    excludedPorts.add(port);
+    let stderr = "";
+    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),
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true,
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-4_000);
+    });
+    try {
+      await waitForDashboard(port, child);
+      return { child, port };
+    } catch (error) {
+      await stopProcessTree(child.pid);
+      const detail = stderr.trim();
+      failures.push(`porta ${port}: ${error.message}${detail ? ` — ${detail}` : ""}`);
+      appendLauncherLog(
+        `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(" | ")}`,
+  );
+}
+
+async function writeLauncherStatus(status, message = "") {
+  const path = process.env.ZAIP_LAUNCH_STATUS;
+  if (!path) return;
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  await writeFile(temporaryPath, `${status}\n${message}`.trimEnd(), "utf8");
+  await rename(temporaryPath, path);
+}
+
+async function main() {
+  let ownedChild = null;
+  let currentSession = null;
+  let launchPage = null;
+
+  await withLauncherLock(async () => {
+    const buildSignature = await ensureFreshDashboardBuild();
+    const reusable = await findReusableDashboardSession({ expectedBuildSignature: buildSignature });
+    if (reusable !== null) {
+      await writeDashboardSession(reusable);
+      await recordPortStatus(reusable, "active");
+      if (!(await openBrowser(dashboardUrl(reusable.port, reusable.token)))) {
+        throw new Error(
+          "O dashboard está saudável, mas nenhuma opção conseguiu abrir o navegador padrão.",
+        );
+      }
+      await writeLauncherStatus("ok");
+      return;
+    }
+
+    const previousSessions = await previousDashboardSessions();
+    const excludedPorts = new Set(previousSessions.map((session) => session.port));
+    const token = process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
+    const launchPort = await findAvailablePortWithFallback({ excludedPorts: [...excludedPorts] });
+    launchPage = await startDashboardLaunchPage(launchPort);
+    if (!(await openBrowser(dashboardUrl(launchPort, token)))) {
+      await launchPage.close();
+      launchPage = null;
+      throw new Error("Não foi possível abrir a preparação do dashboard no navegador padrão.");
+    }
+
+    const serverPath = await assertRuntimeReady();
+    await launchPage.close();
+    launchPage = null;
+    const { child, port } = await startDashboardServer(
+      serverPath,
+      token,
+      excludedPorts,
+      launchPort,
+    );
+    ownedChild = child;
+    try {
+      if (port !== launchPort && !(await openBrowser(dashboardUrl(port, token)))) {
+        throw new Error(
+          "O dashboard iniciou em uma porta alternativa, mas não foi possível abrir essa URL.",
+        );
+      }
+      currentSession = {
+        kind: runtimeKind,
+        workspace: workspaceRoot,
+        workspaceKey,
+        rootPid: process.pid,
+        serverPid: child.pid,
+        port,
+        token,
+        buildSignature,
+        createdAt: new Date().toISOString(),
+      };
+      await writeDashboardSession(currentSession);
+      await recordPortStatus(currentSession, "active");
+      const warnings = [];
+      for (const previous of previousSessions) {
+        const stopped = await stopOwnedDashboard(previous);
+        await recordPortStatus(previous, stopped ? "closed" : "close_failed");
+        if (!stopped) warnings.push(`não foi possível fechar a porta anterior ${previous.port}`);
+      }
+      await writeLauncherStatus(warnings.length > 0 ? "warning" : "ok", warnings.join("; "));
+    } catch (error) {
+      await stopProcessTree(child.pid);
+      if (currentSession !== null) await recordPortStatus(currentSession, "failed");
+      await clearOwnedDashboardSession();
+      throw error;
+    }
+  });
+
+  if (ownedChild === null) return;
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => ownedChild?.kill(signal));
+  }
+  const exitCode = await new Promise((resolveExit, rejectExit) => {
+    ownedChild.once("error", rejectExit);
+    ownedChild.once("exit", (code) => resolveExit(code ?? 0));
+  });
+  await clearOwnedDashboardSession();
+  if (currentSession !== null) await recordPortStatus(currentSession, "closed");
+  process.exitCode = exitCode;
+}
+
+function isPortFree(port) {
+  return new Promise((resolvePort) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", () => resolvePort(false));
+    server.listen({ host, port }, () => server.close(() => resolvePort(true)));
+  });
+}
+
+async function waitForDashboard(port, child) {
+  const deadline = Date.now() + startupTimeoutMs;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Dashboard server exited before becoming healthy (${child.exitCode})`);
+    }
+    try {
+      const response = await fetch(dashboardHealthUrl(port), { signal: AbortSignal.timeout(750) });
+      const payload = await response.json().catch(() => null);
+      if (response.ok && payload?.kind === runtimeKind && payload?.workspaceKey === workspaceKey) {
+        return;
+      }
+      if (response.status >= 500) {
+        const unavailable = new Error(
+          `Dashboard health returned ${response.status}: ${payload?.error ?? "service unavailable"}`,
+        );
+        unavailable.retryable = false;
+        throw unavailable;
+      }
+    } catch (error) {
+      if (error?.retryable === false) throw error;
+    }
+    await delay(250);
+  }
+  throw new Error(`Timed out waiting for ${dashboardHealthUrl(port)}`);
+}
+
+function exists(path) {
+  return access(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+function delay(milliseconds) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+
+const isMain = process.argv[1]
+  ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  : false;
+
+if (isMain) {
+  main().catch(async (error) => {
+    const logMessage = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    const userMessage = formatLauncherError(error instanceof Error ? error.message : String(error));
+    appendLauncherLog(logMessage);
+    await writeLauncherStatus("error", userMessage).catch(() => {});
+    process.exitCode = 1;
+  });
+}