@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/design/design-system-maker/runtime/request-contracts.mjs

@@ -0,0 +1,121 @@
+import {
+  normalizeUrlInput,
+  replayableUrl,
+  safeText,
+  url,
+} from "../../../tools/visual-url/policy.mjs";
+import { identifier } from "./io.mjs";
+
+export function browserTraffic(value) {
+  if (
+    !value ||
+    Object.keys(value).sort().join() !== "page,proxy" ||
+    !value.proxy ||
+    Object.keys(value.proxy).sort().join() !== "connections,hosts,wire_bytes" ||
+    ![value.proxy.wire_bytes, value.proxy.connections].every(
+      (n) => Number.isSafeInteger(n) && n >= 0,
+    ) ||
+    !Array.isArray(value.proxy.hosts) ||
+    value.proxy.hosts.length > 32 ||
+    !Array.isArray(value.page) ||
+    value.page.length > 64
+  )
+    throw new Error("Invalid bounded browser traffic");
+  for (const [rows, keys, types] of [
+    [value.proxy.hosts, ["connections", "host", "scope", "type", "wire_bytes"], ["HTTP", "TLS"]],
+    [
+      value.page,
+      ["blocked", "host", "received_bytes", "requests", "scope", "type"],
+      [
+        "Document",
+        "Stylesheet",
+        "Script",
+        "Font",
+        "Image",
+        "Media",
+        "XHR",
+        "Fetch",
+        "WebSocket",
+        "Other",
+      ],
+    ],
+  ])
+    for (const row of rows) {
+      if (
+        !row ||
+        Object.keys(row).sort().join() !== keys.sort().join() ||
+        typeof row.host !== "string" ||
+        row.host.length > 253 ||
+        !/^[a-z0-9.:[\]-]+$/i.test(row.host) ||
+        !["target", "other-public"].includes(row.scope) ||
+        !types.includes(row.type) ||
+        Object.entries(row).some(
+          ([key, n]) =>
+            !["host", "scope", "type"].includes(key) && (!Number.isSafeInteger(n) || n < 0),
+        )
+      )
+        throw new Error("Invalid host/type-only browser counter");
+    }
+  return value;
+}
+
+export function generate(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some(
+      (key) => !["url", "name", "id", "expected_revision", "mode", "operation_id"].includes(key),
+    ) ||
+    !Object.hasOwn(value, "url")
+  )
+    throw new Error("Generate accepts only url/name/id/expected_revision");
+  const target = url(replayableUrl(normalizeUrlInput(value.url)));
+  if (!["http", "browser"].includes(value.mode ?? "http"))
+    throw new Error("Unknown extraction mode");
+  const name = safeText(value.name ?? target.hostname, 128).trim();
+  if (!name) throw new Error("Extraction name missing");
+  if (value.id !== undefined) identifier(value.id);
+  if (value.operation_id !== undefined) {
+    identifier(value.operation_id);
+    if (value.operation_id.length > 40) throw new Error("Operation ID exceeds40 characters");
+  }
+  if (
+    value.expected_revision !== undefined &&
+    (!Number.isInteger(value.expected_revision) || value.expected_revision < 0)
+  )
+    throw new Error("Expected revision invalid");
+  return {
+    url: target.href,
+    name,
+    id: value.id ?? null,
+    expected_revision: value.expected_revision ?? 0,
+    mode: value.mode ?? "http",
+    ...(value.operation_id === undefined ? {} : { operation_id: value.operation_id }),
+  };
+}
+
+export function revisionRequest(value, allowUrl = false) {
+  const keys = allowUrl
+    ? ["expected_revision", "url", "mode", "operation_id"]
+    : ["expected_revision", "expected_trash_revision"];
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some((key) => !keys.includes(key)) ||
+    !Number.isInteger(value.expected_revision) ||
+    value.expected_revision < 1 ||
+    (!allowUrl &&
+      (!Number.isInteger(value.expected_trash_revision) || value.expected_trash_revision < 0))
+  )
+    throw new Error("Explicit current entry/trash revisions required");
+  if (value.url !== undefined) replayableUrl(normalizeUrlInput(value.url));
+  if (value.mode !== undefined && !["http", "browser"].includes(value.mode))
+    throw new Error("Unknown extraction mode");
+  if (value.operation_id !== undefined) {
+    identifier(value.operation_id);
+    if (value.operation_id.length > 40) throw new Error("Operation ID exceeds40 characters");
+  }
+  return value;
+}

package/templates/.agents/design/design-system-maker/runtime/serve.mjs

@@ -0,0 +1,53 @@
+import { realpath } from "node:fs/promises";
+import { read } from "./io.mjs";
+import { startServer } from "./server.mjs";
+
+try {
+  const args = process.argv.slice(2);
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    if (
+      !["--workspace", "--host-config"].includes(args[index]) ||
+      !args[index + 1] ||
+      Object.hasOwn(options, args[index])
+    )
+      throw new Error("Invalid/duplicate Maker server option");
+    options[args[index]] = args[index + 1];
+  }
+  if (!options["--workspace"]) throw new Error("Explicit workspace required");
+  const workspace = await realpath(options["--workspace"]);
+  if (options["--host-config"] && !options["--host-config"].startsWith(".local/"))
+    throw new Error("Explicit host configuration must be local project-owned data");
+  const configuration = options["--host-config"]
+    ? JSON.parse((await read(workspace, options["--host-config"], 65536)).toString("utf8"))
+    : {};
+  if (Object.keys(configuration).some((key) => !["fixture_origins", "captures"].includes(key)))
+    throw new Error("Unsupported host configuration key");
+  const server = await startServer({ workspace, host_configuration: configuration });
+  process.stdout.write(
+    `${JSON.stringify({ ok: true, ...server.identity, origin: server.origin })}\n`,
+  );
+  let stopping = false;
+  async function stop() {
+    if (stopping) return;
+    stopping = true;
+    await server.close();
+  }
+  process.once("SIGINT", () => {
+    stop().catch((error) => {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+    });
+  });
+  process.once("SIGTERM", () => {
+    stop().catch((error) => {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+    });
+  });
+} catch (error) {
+  process.stdout.write(
+    `${JSON.stringify({ ok: false, error: error.code ? `Maker I/O ${error.code}` : error.message })}\n`,
+  );
+  process.exitCode = 1;
+}

package/templates/.agents/design/design-system-maker/runtime/server.mjs

@@ -0,0 +1,363 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { extname } from "node:path";
+import { iconFormat } from "../../../tools/visual-url/icon.mjs";
+import { design } from "../../../tools/visual-url/proposal.mjs";
+import { chatCommands, chatProtocol } from "./chat-contract.mjs";
+import { bytes, identifier, json, read, relativePath, remove, write } from "./io.mjs";
+import { createService } from "./service.mjs";
+
+const mime = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".svg": "image/svg+xml",
+};
+export async function startServer({ workspace, host_configuration = {}, launch_control = null }) {
+  const service = await createService(workspace, host_configuration);
+  const installedBuild = await json(workspace, ".agents/design/design-system-maker/build.json");
+  const buildId = launch_control?.identity?.build_id ?? installedBuild?.build_id ?? null;
+  const nonce = randomBytes(32).toString("hex");
+  let origin;
+  const server = createServer({ maxHeaderSize: 8192 }, async (request, response) => {
+    const finish = (status, content, type = "application/json; charset=utf-8") => {
+      response.writeHead(status, {
+        "Content-Type": type,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Cross-Origin-Resource-Policy": "same-origin",
+        "Content-Security-Policy":
+          "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'",
+      });
+      response.end(
+        typeof content === "string" || Buffer.isBuffer(content) ? content : JSON.stringify(content),
+      );
+    };
+    try {
+      if (
+        request.headers.host !== origin.slice(7) ||
+        (request.headers.origin && request.headers.origin !== origin) ||
+        request.headers["sec-fetch-site"] === "cross-site"
+      ) {
+        finish(403, { error: "Host/Origin boundary rejected" });
+        return;
+      }
+      if (!["GET", "POST", "DELETE"].includes(request.method)) {
+        finish(405, { error: "Method unavailable" });
+        return;
+      }
+      const target = new URL(request.url, origin);
+      const route = decodeURIComponent(target.pathname);
+      if (request.method === "POST" && route === "/.zaip-maker/control") {
+        const operation = request.headers["x-maker-operation"];
+        if (
+          !launch_control?.authenticate(request.headers) ||
+          !["probe", "stop"].includes(operation) ||
+          request.headers["content-length"] !== "0" ||
+          request.headers["transfer-encoding"]
+        ) {
+          finish(403, { error: "Authenticated launcher control required" });
+          return;
+        }
+        finish(200, { ...service.identity, ...launch_control.identity, origin });
+        if (operation === "stop")
+          setImmediate(() =>
+            close().catch(() => {
+              process.exitCode = 1;
+            }),
+          );
+        return;
+      }
+      if (["POST", "DELETE"].includes(request.method)) {
+        const supplied = request.headers["x-maker-nonce"];
+        if (
+          request.headers.origin !== origin ||
+          typeof supplied !== "string" ||
+          supplied.length !== nonce.length ||
+          !timingSafeEqual(Buffer.from(supplied), Buffer.from(nonce))
+        ) {
+          finish(403, { error: "Mutation requires exact origin and session nonce" });
+          return;
+        }
+        const reprocess = /^\/api\/extracts\/([a-zA-Z0-9_-]+)\/reprocess$/.exec(route);
+        const trash = /^\/api\/extracts\/([a-zA-Z0-9_-]+)$/.exec(route);
+        const restore = /^\/api\/trash\/([a-zA-Z0-9_-]+)\/restore$/.exec(route);
+        const cancel = /^\/api\/jobs\/([a-zA-Z0-9_-]+)\/cancel$/.exec(route);
+        if (
+          !(
+            request.method === "POST" &&
+            (route === "/api/generate" ||
+              route === "/api/local-sources" ||
+              reprocess ||
+              restore ||
+              cancel)
+          ) &&
+          !(request.method === "DELETE" && trash)
+        ) {
+          finish(404, { error: "Unknown mutation route" });
+          return;
+        }
+        if (
+          !/^application\/json(?:;|$)/i.test(request.headers["content-type"] ?? "") ||
+          Number(request.headers["content-length"] ?? 0) > 65536
+        ) {
+          finish(413, { error: "Bounded JSON request required" });
+          return;
+        }
+        const chunks = [];
+        let size = 0;
+        const timer = setTimeout(() => request.destroy(), 2000);
+        try {
+          for await (const chunk of request) {
+            size += chunk.length;
+            if (size > 65536) {
+              finish(413, { error: "Request byte bound exceeded" });
+              request.destroy();
+              return;
+            }
+            chunks.push(chunk);
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+        let input;
+        try {
+          input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        } catch {
+          finish(400, { error: "Invalid JSON request" });
+          return;
+        }
+        if (route === "/api/local-sources") finish(202, await service.local(input));
+        else if (cancel) finish(200, await service.cancel(identifier(cancel[1]), input));
+        else if (request.method === "DELETE")
+          finish(200, await service.changeTrash(identifier(trash[1]), input, "trashed"));
+        else if (restore)
+          finish(200, await service.changeTrash(identifier(restore[1]), input, "active"));
+        else
+          finish(
+            202,
+            reprocess
+              ? await service.reprocess(identifier(reprocess[1]), input)
+              : await service.enqueue(input),
+          );
+        return;
+      }
+      if (route === "/.zaip-maker/health") {
+        finish(200, { ...service.identity, ...launch_control?.identity, origin });
+        return;
+      }
+      if (route === "/api/session") {
+        finish(200, {
+          ...service.identity,
+          build_id: buildId,
+          origin,
+          nonce,
+          capabilities: {
+            chat: { protocol: chatProtocol, commands: chatCommands },
+            extraction: "static reader with optional host configuration",
+            previews: false,
+            central_promotion: false,
+            browser: service.browser,
+          },
+        });
+        return;
+      }
+      if (route === "/api/extracts" || route === "/api/trash") {
+        const offset = Number(target.searchParams.get("offset") ?? 0);
+        const limit = Number(target.searchParams.get("limit") ?? 100);
+        if (
+          !Number.isInteger(offset) ||
+          offset < 0 ||
+          !Number.isInteger(limit) ||
+          limit < 1 ||
+          limit > 100
+        )
+          throw new Error("Invalid collection pagination");
+        finish(200, {
+          ...(await service.list(offset, limit, route === "/api/trash")),
+          schema_version: 1,
+        });
+        return;
+      }
+      const jobMatch = /^\/api\/jobs\/([a-zA-Z0-9_-]+)$/.exec(route);
+      if (jobMatch) {
+        const job = await service.job(identifier(jobMatch[1]));
+        finish(job ? 200 : 404, job ?? { error: "Unknown job" });
+        return;
+      }
+      const entryMatch =
+        /^\/api\/extracts\/([a-zA-Z0-9_-]+)(?:\/(proposal|design|screenshot|report|report-markdown|favicon))?$/.exec(
+          route,
+        );
+      if (entryMatch) {
+        const id = identifier(entryMatch[1]);
+        const revision = target.searchParams.has("revision")
+          ? Number(target.searchParams.get("revision"))
+          : null;
+        if (revision !== null && (!Number.isInteger(revision) || revision < 1))
+          throw new Error("Revision must be positive integer");
+        const historyOffset = Number(target.searchParams.get("history_offset") ?? 0);
+        const historyLimit = Number(target.searchParams.get("history_limit") ?? 20);
+        if (
+          !Number.isInteger(historyOffset) ||
+          historyOffset < 0 ||
+          !Number.isInteger(historyLimit) ||
+          historyLimit < 1 ||
+          historyLimit > 100
+        )
+          throw new Error("Invalid history pagination");
+        const detail = await service.detail(id, revision, historyOffset, historyLimit);
+        if (!detail) {
+          finish(404, { error: "Unknown extraction" });
+          return;
+        }
+        if (entryMatch[2]) {
+          if (entryMatch[2] === "favicon") {
+            const icon = detail.artifacts.find((item) =>
+              ["favicon.png", "favicon.jpg", "favicon.ico"].includes(item.name),
+            );
+            if (!icon) {
+              finish(404, { error: "Favicon unavailable for this revision" });
+              return;
+            }
+            const data = await service.artifact(id, detail.revision, icon.name);
+            const format = iconFormat(data);
+            if (format.name !== icon.name) throw new Error("Favicon artifact format mismatch");
+            finish(200, data, format.mime);
+            return;
+          }
+          const name = {
+            proposal: "proposal.json",
+            design: "DESIGN.md",
+            screenshot: "screenshot.png",
+            report: "report.json",
+            "report-markdown": "REPORT.md",
+          }[entryMatch[2]];
+          if (!detail.artifacts.some((item) => item.name === name)) {
+            finish(404, { error: "Artifact unavailable for this revision" });
+            return;
+          }
+          if (
+            entryMatch[2] === "design" &&
+            target.searchParams.get("format") === "compact" &&
+            detail.proposal
+          ) {
+            finish(200, design(detail.proposal), "text/plain; charset=utf-8");
+            return;
+          }
+          finish(
+            200,
+            await service.artifact(id, detail.revision, name),
+            entryMatch[2] === "screenshot"
+              ? "image/png"
+              : ["design", "report-markdown"].includes(entryMatch[2])
+                ? "text/plain; charset=utf-8"
+                : "application/json; charset=utf-8",
+          );
+          return;
+        }
+        finish(200, detail);
+        return;
+      }
+      if (route === "/assets/zaip-icon.png") {
+        finish(
+          200,
+          await read(service.store.workspace, ".agents/config/src/icon_zaip.png", 2097152),
+          "image/png",
+        );
+        return;
+      }
+      const mapped =
+        route === "/" || route === "/catalog" || route === "/catalog/"
+          ? "catalog/index.html"
+          : route === "/viewer" || route === "/viewer/"
+            ? "viewer/index.html"
+            : route === "/advanced" || route === "/advanced/"
+              ? "advanced/index.html"
+              : route === "/generate"
+                ? "generate.html"
+                : route.slice(1);
+      relativePath(mapped);
+      if (
+        !mime[extname(mapped)] ||
+        !/^(?:catalog\/|viewer\/|advanced\/|shared\/|styles\/|assets\/|generate\.(?:html|js)$)/.test(
+          mapped,
+        )
+      ) {
+        finish(404, { error: "Route unavailable; external previews never served" });
+        return;
+      }
+      finish(
+        200,
+        await read(
+          service.store.workspace,
+          `.agents/design/design-system-maker/frontend/${mapped}`,
+          2097152,
+        ),
+        mime[extname(mapped)],
+      );
+    } catch (error) {
+      if (!response.headersSent)
+        finish(
+          error.status ??
+            (error.code === "ENOENT"
+              ? 404
+              : /revision conflict|already collecting/.test(error.message)
+                ? 409
+                : 400),
+          { error: error.code ? `Maker I/O ${error.code}` : error.message },
+        );
+    }
+  });
+  server.maxConnections = 32;
+  server.headersTimeout = 3000;
+  server.requestTimeout = 5000;
+  server.keepAliveTimeout = 1000;
+  server.maxRequestsPerSocket = 100;
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+  } catch (error) {
+    await service.close();
+    throw error;
+  }
+  origin = `http://127.0.0.1:${server.address().port}`;
+  const discoveryPath = ".local/zaip-maker-session.json";
+  await write(
+    workspace,
+    discoveryPath,
+    bytes({
+      schema_version: 1,
+      app: service.identity.app,
+      origin,
+      workspace_hash: service.identity.workspace_hash,
+      pid: process.pid,
+      build_id: buildId,
+    }),
+  );
+  let closing;
+  function close() {
+    closing ??= (async () => {
+      await new Promise((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+      await service.close();
+      const pointer = await json(workspace, discoveryPath);
+      if (pointer?.origin === origin && pointer?.pid === process.pid)
+        await remove(workspace, discoveryPath);
+    })();
+    return closing;
+  }
+  return {
+    origin,
+    service,
+    identity: service.identity,
+    close,
+  };
+}

package/templates/.agents/design/design-system-maker/runtime/service-actions.mjs

@@ -0,0 +1,59 @@
+import { revisionRequest } from "./contracts.mjs";
+import { reprocessMode } from "./reprocess-mode.mjs";
+export function serviceActions({ store, serialize, enqueue, browserJobs }) {
+  return {
+    async cancel(id, input) {
+      if (
+        !input ||
+        Object.keys(input).join() !== "expected_revision" ||
+        !Number.isInteger(input.expected_revision) ||
+        input.expected_revision < 1
+      )
+        throw new Error("Cancel requires exact current entry revision");
+      return serialize(async () => {
+        const job = await store.readJob(id);
+        if (job?.mode !== "browser" || !["queued", "running"].includes(job.status))
+          throw new Error("Active own browser job required");
+        const entry = await store.get(job.entry_id);
+        if (
+          !entry ||
+          entry.revision !== input.expected_revision ||
+          entry.job_id !== id ||
+          entry.status !== "collecting"
+        )
+          throw new Error("Entry revision conflict");
+        const signal = browserJobs.get(id);
+        if (!signal) throw new Error("Own browser job unavailable");
+        signal.cancel();
+        return { id, cancel_requested: true, expected_revision: entry.revision };
+      });
+    },
+    async reprocess(id, input) {
+      revisionRequest(input, true);
+      const previous = await serialize(() => store.get(id));
+      if (!previous) throw new Error("Unknown extraction");
+      if (previous.source)
+        throw new Error(
+          "Local reference requires rebuild-document with exact DESIGN revision/hash; URL reprocess is separate",
+        );
+      const target = input.url ?? previous.request_url;
+      if (!target)
+        throw new Error("Saved exact request URL unavailable; provide a safe URL explicitly");
+      const mode = await serialize(() => reprocessMode(store, previous, input.mode));
+      return enqueue({
+        id,
+        url: target,
+        name: previous.name,
+        expected_revision: input.expected_revision,
+        mode,
+        ...(input.operation_id === undefined ? {} : { operation_id: input.operation_id }),
+      });
+    },
+    async changeTrash(id, input, state) {
+      revisionRequest(input);
+      return serialize(() =>
+        store.changeTrash(id, input.expected_revision, input.expected_trash_revision, state),
+      );
+    },
+  };
+}

package/templates/.agents/design/design-system-maker/runtime/service-host.mjs

@@ -0,0 +1,32 @@
+// Validate the explicit host boundary before opening persistent collection state.
+export function validateServiceHost(host) {
+  if (
+    !host ||
+    typeof host !== "object" ||
+    Array.isArray(host) ||
+    Object.keys(host).some((key) => !["fixture_origins", "captures", "checkpoint"].includes(key)) ||
+    !Array.isArray(host.fixture_origins ?? []) ||
+    (host.fixture_origins ?? []).length > 16 ||
+    (host.captures !== undefined &&
+      (!host.captures ||
+        typeof host.captures !== "object" ||
+        Array.isArray(host.captures) ||
+        Object.keys(host.captures).length > 16)) ||
+    (host.checkpoint !== undefined && typeof host.checkpoint !== "function")
+  )
+    throw new Error("Invalid explicit host configuration");
+}
+
+export function serviceIdentity(workspaceHash) {
+  return {
+    app: "zaip-design-system-maker",
+    schema_version: 1,
+    data_schema_version: 1,
+    workspace_hash: workspaceHash,
+    runtime_identity: "maker-collection-v1",
+    chat_protocol: "maker-chat-v1",
+    pid: process.pid,
+    concurrency: 2,
+    queue_capacity: 5,
+  };
+}