@zaip-ai/cli 2.2.0 → 3.0.0

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

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { formatLauncherError } from "./start-dashboard-logging.mjs";
+import {
+  dashboardBuildTargets,
+  frontendRoot,
+  installedServer,
+  packageRoot,
+  sourceServer,
+  workspaceRoot,
+} from "./start-dashboard-paths.mjs";
+import {
+  assertInstalledDashboardArtifacts,
+  isDashboardSourceWorkspace as hasDashboardSourceWorkspace,
+  dashboardServerPathForWorkspace as selectDashboardServerPath,
+} from "./start-dashboard-runtime-selection.mjs";
+export async function latestModifiedAt(paths, excludedSourcePaths = []) {
+  let latest = 0;
+  for (const path of paths) {
+    const details = await stat(path).catch(() => null);
+    if (details === null) continue;
+    if (!details.isDirectory()) {
+      if (isBuildInputPath(path, excludedSourcePaths)) latest = Math.max(latest, details.mtimeMs);
+      continue;
+    }
+    // Retain included directory mtimes so removing or renaming a source file
+    // after a build still invalidates its artifact. Excluded trees stay out.
+    if (isBuildInputPath(path, excludedSourcePaths)) latest = Math.max(latest, details.mtimeMs);
+    const entries = await readdir(path, { withFileTypes: true }).catch(() => []);
+    latest = Math.max(
+      latest,
+      await latestModifiedAt(
+        entries
+          .filter((entry) => isBuildInputPath(join(path, entry.name), excludedSourcePaths))
+          .map((entry) => join(path, entry.name)),
+        excludedSourcePaths,
+      ),
+    );
+  }
+  return latest;
+}
+export function isBuildInputPath(path, excludedSourcePaths) {
+  const normalized = path.replaceAll("\\", "/");
+  const name = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (new Set(["dist", "node_modules", ".turbo"]).has(name)) return false;
+  if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(name)) return false;
+  return !excludedSourcePaths.some(
+    (excluded) => normalized.includes(excluded) || normalized.endsWith(excluded.slice(0, -1)),
+  );
+}
+export async function runSqliteBuild(target) {
+  const frontend = target === "frontend";
+  const command = process.execPath;
+  const args = frontend
+    ? [resolve(workspaceRoot, "node_modules/vite/bin/vite.js"), "build"]
+    : [
+        resolve(
+          workspaceRoot,
+          ".agents/dashboard/packages/local-runtime/scripts/build-sqlite-runtime.mjs",
+        ),
+      ];
+  const output = await new Promise((resolveBuild, rejectBuild) => {
+    const child = spawn(command, args, {
+      cwd: frontend ? resolve(workspaceRoot, ".agents/dashboard/apps/frontend") : packageRoot,
+      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(
+            `SQLite dashboard ${target} build failed (${code}): ${formatLauncherError(outputText)}`,
+          ),
+        );
+    });
+  });
+  return output;
+}
+export async function inspectDashboardBuildTarget(target) {
+  const artifactStats = await Promise.all(
+    target.artifacts.map(async (path) => ({ path, details: await stat(path).catch(() => null) })),
+  );
+  const missingArtifacts = artifactStats
+    .filter(({ details }) => details === null)
+    .map(({ path }) => path);
+  const artifactsModifiedAt = Math.min(
+    ...artifactStats.map(({ details }) => details?.mtimeMs ?? 0),
+  );
+  const sourcesModifiedAt = await latestModifiedAt(target.sourceRoots, target.excludedSourcePaths);
+  return { artifactsModifiedAt, missingArtifacts, sourcesModifiedAt };
+}
+export function buildProgress(onProgress, percent, phase, detail) {
+  onProgress({ percent, phase, detail });
+}
+export async function refreshDashboardBuildTargets({
+  targets = dashboardBuildTargets,
+  forceRebuild = process.env.ZAIP_DASHBOARD_FORCE_REBUILD === "1",
+  inspectTarget = inspectDashboardBuildTarget,
+  runBuild = runSqliteBuild,
+  onProgress = () => {},
+} = {}) {
+  const builtTargets = [];
+  for (const [name, target] of Object.entries(targets)) {
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 30 : 35,
+      `Verificando ${name === "frontend" ? "a interface" : "o runtime local"}`,
+      "Conferindo somente as dependências que geram este artefato.",
+    );
+    const state = await inspectTarget(target);
+    const needsBuild =
+      forceRebuild ||
+      state.missingArtifacts.length > 0 ||
+      state.artifactsModifiedAt < state.sourcesModifiedAt;
+    if (!needsBuild) {
+      buildProgress(
+        onProgress,
+        name === "frontend" ? 33 : 39,
+        `${name === "frontend" ? "Interface" : "Runtime local"} já está atualizado`,
+        "O artefato existente corresponde às dependências verificadas.",
+      );
+      continue;
+    }
+    const reason = forceRebuild
+      ? "A atualização foi solicitada explicitamente."
+      : state.missingArtifacts.length > 0
+        ? "Um artefato necessário está ausente."
+        : "Uma dependência deste artefato foi modificada.";
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 33 : 39,
+      `Atualizando ${name === "frontend" ? "a interface" : "o runtime local"}`,
+      reason,
+    );
+    await runBuild(name);
+    builtTargets.push(name);
+    buildProgress(
+      onProgress,
+      name === "frontend" ? 35 : 42,
+      `${name === "frontend" ? "Interface" : "Runtime local"} atualizado`,
+      "O artefato foi gerado com as dependências atuais.",
+    );
+  }
+  return { artifacts: Object.values(targets).flatMap((target) => target.artifacts), builtTargets };
+}
+export async function ensureFreshDashboardBuild(onProgress = () => {}) {
+  if (!(await hasDashboardSourceWorkspace(workspaceRoot))) {
+    const packagedArtifacts = [installedServer, resolve(frontendRoot, "index.html")];
+    await assertInstalledDashboardArtifacts(packagedArtifacts);
+    buildProgress(
+      onProgress,
+      39,
+      "Usando runtime empacotado",
+      "O pacote npm já inclui o dashboard pronto; nenhuma instalação de desenvolvimento é necessária.",
+    );
+    const signature = await Promise.all(
+      [...packagedArtifacts, resolve(packageRoot, "start-dashboard.mjs")].map(async (path) => {
+        const details = await stat(path);
+        return `${path}:${details.size}:${details.mtimeMs}`;
+      }),
+    );
+    return createHash("sha256").update(signature.join("|")).digest("hex");
+  }
+  const { artifacts } = await refreshDashboardBuildTargets({ onProgress });
+  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 isDashboardSourceWorkspace(root = workspaceRoot) {
+  return hasDashboardSourceWorkspace(root);
+}
+export async function dashboardServerPathForWorkspace({
+  root = workspaceRoot,
+  sourcePath = sourceServer,
+  installedPath = installedServer,
+} = {}) {
+  return selectDashboardServerPath({ root, sourcePath, installedPath });
+}

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

@@ -36,7 +36,7 @@ describe("dashboard launcher lifecycle", () => {
     expect(presentLaunchFailure(null, "unused", () => "unused")).toBeNull();
   });
 
-  it("waits for the child exit before clearing the owned session", async () => {
+  it("waits for child exit and preserves the persistent SQLite snapshot", async () => {
     const child = new EventEmitter();
     const processRef = new EventEmitter();
     const calls = [];
@@ -55,12 +55,7 @@ describe("dashboard launcher lifecycle", () => {
     child.emit("exit", null);
 
     await expect(completion).resolves.toBe(0);
-    expect(calls).toEqual([
-      ["kill", "SIGINT"],
-      ["clear"],
-      ["status", "closed"],
-      ["remove", "C:/tmp/dashboard.sqlite"],
-    ]);
+    expect(calls).toEqual([["kill", "SIGINT"], ["clear"], ["status", "closed"]]);
   });
 
   it("records launcher phase timing with the same process identity", () => {

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

@@ -0,0 +1,35 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { launcherLogPath, sessionDirectory } from "./start-dashboard-paths.mjs";
+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) {
+  const escapeCode = String.fromCharCode(27);
+  const bell = String.fromCharCode(7);
+  const operatingSystemCommand = new RegExp(
+    `${escapeCode}\\][^${bell}]*(?:${bell}|${escapeCode}\\\\)`,
+    "g",
+  );
+  const controlSequenceIntroducer = new RegExp(`${escapeCode}\\[[0-?]*[ -/]*[@-~]`, "g");
+  return String(value)
+    .replace(operatingSystemCommand, "")
+    .replace(controlSequenceIntroducer, "")
+    .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)}`;
+}

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

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { win32 } from "node:path";
+import process from "node:process";
+import { appendLauncherLog } from "./start-dashboard-logging.mjs";
+import { defaultPort, healthPath, host, maxPortAttempts } from "./start-dashboard-paths.mjs";
+import { isPortFree } from "./start-dashboard-server.mjs";
+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, snapshotUpdating = false) {
+  return `http://${host}:${port}/?token=${encodeURIComponent(token)}${snapshotUpdating ? "&snapshot=updating" : ""}`;
+}
+export async function findAvailablePort(startPort = preferredPort()) {
+  for (let port = startPort; port < Math.min(startPort + maxPortAttempts, 65_536); port += 1) {
+    if (await isPortFree(host, 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(host, 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",
+  );
+}
+export 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", [target]]]
+    : [
+        ["xdg-open", [target]],
+        ["gio", ["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;
+}

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

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const host = "127.0.0.1";
+export const defaultPort = 4417;
+export const maxPortAttempts = 25;
+export const runtimeKind = "zaip-dashboard-sqlite-runtime";
+export const packageRoot = dirname(fileURLToPath(import.meta.url));
+export const workspaceRoot = resolve(packageRoot, "../../../..");
+export const workspaceKey = createHash("sha256")
+  .update(`${workspaceRoot}:dashboard-sqlite`)
+  .digest("hex")
+  .slice(0, 16);
+export const sessionDirectory = join(tmpdir(), "zaip-aios", `dashboard-sqlite-${workspaceKey}`);
+export const sessionPath = join(sessionDirectory, "dashboard-sqlite-session.json");
+export const launchPath = join(sessionDirectory, "dashboard-sqlite-launch.json");
+export const claimLockPath = join(sessionDirectory, "dashboard-sqlite-claim.lock");
+export const claimLockTimeoutMs = 5_000;
+export const claimLockStaleMs = 30_000;
+export const portRegistryPath = join(sessionDirectory, "dashboard-sqlite-ports.json");
+export const lockPath = join(sessionDirectory, "dashboard-sqlite-launcher.lock");
+export const launcherLogPath = join(sessionDirectory, "dashboard-sqlite-launcher.log");
+export const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend/dist");
+export const sqliteReadModelDirectory = resolve(workspaceRoot, ".local", "sqlite");
+export const sqliteReadModelPath = join(sqliteReadModelDirectory, "zaip-aios-dashboard.sqlite");
+export const nodeCompileCacheDirectory = join(sessionDirectory, "node-compile-cache");
+export const installedServer = resolve(packageRoot, "server.mjs");
+export const sourceServer = resolve(packageRoot, "dist/server.cjs");
+export const healthPath = "/api/v2/health";
+export const lockTimeoutMs = 210_000;
+export const staleLockMs = 30_000;
+export const lockHeartbeatFloorMs = 10;
+export const maxServerStartAttempts = 4;
+export const maxPortHistory = 50;
+export const dashboardBuildTargets = {
+  frontend: {
+    artifacts: [resolve(frontendRoot, "index.html")],
+    sourceRoots: [
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/src"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/public"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/index.html"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src/contracts.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/contracts/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/ui/src"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/vite.config.ts"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/package.json"),
+      resolve(workspaceRoot, ".agents/dashboard/apps/frontend/tsconfig.json"),
+      resolve(workspaceRoot, "tsconfig.base.json"),
+      resolve(workspaceRoot, "pnpm-lock.yaml"),
+      resolve(workspaceRoot, "README.md"),
+    ],
+    excludedSourcePaths: ["/server/"],
+  },
+  runtime: {
+    artifacts: [
+      sourceServer,
+      resolve(packageRoot, "dist/server.js"),
+      resolve(packageRoot, "dist/sqlite-read-model.cjs"),
+      installedServer,
+    ],
+    sourceRoots: [
+      resolve(packageRoot, "src"),
+      resolve(packageRoot, "scripts"),
+      resolve(packageRoot, "package.json"),
+      resolve(packageRoot, "tsconfig.json"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/operations/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/cost-monitor/src"),
+      resolve(workspaceRoot, ".agents/dashboard/modules/traceability/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/contracts/src"),
+      resolve(workspaceRoot, ".agents/dashboard/packages/data-export/src"),
+      resolve(workspaceRoot, "packages/core/src"),
+      resolve(workspaceRoot, "packages/costs/src"),
+      resolve(workspaceRoot, "packages/decisions/src"),
+      resolve(workspaceRoot, "packages/lifecycle-manifests/src"),
+      resolve(workspaceRoot, "packages/specs/src"),
+      resolve(workspaceRoot, "packages/tasks/src"),
+      resolve(workspaceRoot, "package.json"),
+      resolve(workspaceRoot, "pnpm-workspace.yaml"),
+      resolve(workspaceRoot, "pnpm-lock.yaml"),
+      resolve(workspaceRoot, "tsconfig.base.json"),
+    ],
+    excludedSourcePaths: ["/react/"],
+  },
+};