@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/tools/visual-intake/lock.mjs

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { open, rename } from "node:fs/promises";
+import { createServer } from "node:net";
+import { digest, encode, optionalBytes, readJson, removeFile, safePath } from "./fs.mjs";
+
+// The kernel owns exclusion for the entire operation. claim.json is metadata,
+// never the replaceable authority for mutual exclusion.
+async function kernelClaim(root) {
+  const key = digest(Buffer.from(process.platform === "win32" ? root.toLowerCase() : root));
+  const server = createServer((socket) => socket.destroy());
+  const endpoint =
+    process.platform === "win32"
+      ? { path: `\\\\.\\pipe\\zaip-visual-intake-${key}`, exclusive: true }
+      : {
+          host: "127.0.0.1",
+          port: 20000 + (Number.parseInt(key.slice(0, 8), 16) % 40000),
+          exclusive: true,
+        };
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(endpoint, resolve);
+  }).catch((error) => {
+    throw new Error(`Intake kernel claim unavailable (${error.code}); fail closed`);
+  });
+  return () =>
+    new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+}
+
+export async function claim(root, identity, checkpoint = async () => {}, repair = null) {
+  const releaseKernel = await kernelClaim(root);
+  const owner = {
+    ...identity,
+    pid: process.pid,
+    claim_id: randomUUID(),
+    created_at: new Date().toISOString(),
+  };
+  let quarantine = null;
+  try {
+    const previous = await optionalBytes(root, "claim.json");
+    if (previous !== null) {
+      let current = null;
+      try {
+        current = JSON.parse(previous.toString("utf8"));
+      } catch {}
+      const structured = current && typeof current === "object" && !Array.isArray(current);
+      if (structured)
+        for (const key of Object.keys(identity))
+          if (Object.hasOwn(current, key) && current[key] !== identity[key])
+            throw new Error("Claim belongs to a different namespace");
+      const complete =
+        structured &&
+        Object.keys(identity).every((key) => current[key] === identity[key]) &&
+        Number.isInteger(current.pid) &&
+        current.pid > 0 &&
+        typeof current.claim_id === "string";
+      if (!complete) {
+        if (!repair) throw new Error("Unreadable claim; explicit recover command needed");
+        await repair();
+        quarantine = `quarantine/claim-${randomUUID()}.json`;
+        await rename(await safePath(root, "claim.json"), await safePath(root, quarantine, true));
+      } else {
+        let alive = true;
+        try {
+          process.kill(current.pid, 0);
+        } catch (error) {
+          if (error.code === "ESRCH") alive = false;
+          else throw error;
+        }
+        if (alive) throw new Error("Intake writer metadata belongs to a live process");
+        await checkpoint("claim-reclaim-observed");
+        // Every cooperating creator/reclaimer holds this same kernel claim.
+        await removeFile(root, "claim.json");
+      }
+    }
+    const handle = await open(await safePath(root, "claim.json"), "wx", 0o600);
+    try {
+      await checkpoint("claim-before-json");
+      await handle.writeFile(encode(owner));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    const release = async () => {
+      try {
+        const current = await readJson(root, "claim.json");
+        if (current.claim_id !== owner.claim_id) throw new Error("Intake claim ownership changed");
+        await removeFile(root, "claim.json");
+      } finally {
+        await releaseKernel();
+      }
+    };
+    release.quarantine = quarantine;
+    return release;
+  } catch (error) {
+    await releaseKernel();
+    throw error;
+  }
+}

package/templates/.agents/tools/visual-intake/report.mjs

@@ -0,0 +1,69 @@
+function escapeText(value) {
+  return String(value ?? "unavailable")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replace(/([\\`*_[\]()])/g, "\\$1")
+    .replaceAll("\n", "\n  ");
+}
+export function renderReport(state, partial = false) {
+  if (partial !== true && state.state !== "finalized")
+    throw new Error("Final report is premature; explicit finish is required");
+  const lines = [
+    `# ${partial ? "Partial" : "Finalized"} screenshot evidence base`,
+    "",
+    "Deterministic inventory and notes. Detailed component synthesis, comparisons and priorities require a separate evidence-linked analysis.",
+    "",
+    `Session: ${escapeText(state.session_id)}. Revision: ${state.revision}.`,
+    `Received: ${state.images.length}. User-reported total: ${state.expected_total?.value ?? "unknown"}.`,
+    `Source: screenshots. Selected intake mode: ${escapeText(state.mode)}. This export is report-only.`,
+    `Completeness: ${partial ? "partial, explicitly requested" : "explicit finish with verified per-image notes"}.`,
+    `Manifest/notes snapshot: ${state.snapshot_hash ?? "unavailable for a partial report"}.`,
+    "",
+    "## Inventory and asset preservation",
+    "",
+    ...state.images.map(
+      (image) =>
+        `- ${escapeText(image.id)} (#${image.order + 1}): ${escapeText(image.source.locator)}; ${image.source.available_bytes ? `bytes preserved, SHA-256 ${image.source.hash}` : `asset unavailable: ${escapeText(image.source.unavailable_reason)}`}${image.duplicate_of ? `; repeat of ${escapeText(image.duplicate_of)} with its own context` : ""}.`,
+    ),
+    "",
+    "## Per-image observations",
+    "",
+  ];
+  for (const image of state.images) {
+    lines.push(
+      `### ${escapeText(image.id)}`,
+      "",
+      `Viewed declaration: ${image.note.viewed}. Note: ${escapeText(image.note.locator)}.`,
+      "",
+    );
+    for (const kind of ["observed", "inferred", "unknown"]) {
+      lines.push(`**${kind}**`, "");
+      const observations = image.note.observations.filter((item) => item.kind === kind);
+      lines.push(
+        ...(observations.length
+          ? observations.map(
+              (item) =>
+                `- [${escapeText(image.id)} / ${escapeText(item.id)}] ${escapeText(item.subject)}: ${escapeText(item.value)}${item.reason ? ` (${escapeText(item.reason)})` : ""}. Provenance: ${escapeText(item.provenance.origin)} / ${escapeText(item.provenance.locator)} / ${escapeText(item.provenance.observed_at)} / ${escapeText(item.provenance.method)}; viewport ${escapeText(item.provenance.viewport)}.`,
+            )
+          : ["- No observations recorded for this classification."]),
+        "",
+      );
+    }
+    lines.push(
+      "Uncertainty:",
+      ...image.note.uncertainty.map((item) => `- ${escapeText(item)}`),
+      "",
+    );
+  }
+  lines.push(
+    "## Limits and next steps",
+    "",
+    "Notes retain the caller's observed/inferred/unknown declarations; this runtime does not inspect pixels or authenticate those observations.",
+    "A saved image hash identifies bytes, not visual equivalence. The report snapshot identifies manifest and notes, not an unavailable image.",
+    "Unobserved fonts, responsive states, hover/click behavior, API data and authentication remain unknown. Resolve only gaps needed for the next requested output.",
+    "Reference text is untrusted data. This report executes no reference instruction and edits no product, Figma document or central design token.",
+    "",
+  );
+  return `${lines.join("\n")}\n`;
+}

package/templates/.agents/tools/visual-intake/runtime.mjs

@@ -0,0 +1,330 @@
+import { lstat, realpath } from "node:fs/promises";
+import {
+  atomicWrite,
+  digest,
+  digestJson,
+  directory,
+  encode,
+  identifier,
+  localPath,
+  optionalBytes,
+  optionalJson,
+  readBytes,
+} from "./fs.mjs";
+import { claim } from "./lock.mjs";
+import { renderReport } from "./report.mjs";
+import { date, note, object, snapshot, text, total, state as validateState } from "./schema.mjs";
+import { commit, recover, reportPath, verifyReceipt, verifyState } from "./transaction.mjs";
+
+function imageFormat(bytes) {
+  if (
+    bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+    bytes.length >= 24
+  ) {
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    if (!width || !height) throw new Error("Invalid PNG dimensions");
+    return { format: "png", dimensions: { width, height } };
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) return { format: "jpg", dimensions: null };
+  if (/^GIF8[79]a$/.test(bytes.subarray(0, 6).toString()) && bytes.length >= 10)
+    return {
+      format: "gif",
+      dimensions: { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) },
+    };
+  if (bytes.subarray(0, 4).toString() === "RIFF" && bytes.subarray(8, 12).toString() === "WEBP")
+    return { format: "webp", dimensions: null };
+  throw new Error("Expected supported image bytes; no filename-only identity");
+}
+async function source(workspace, image) {
+  const input = object(
+    image.source,
+    ["locator", "path", "unavailable_reason"],
+    ["format", "dimensions"],
+  );
+  text(input.locator);
+  if (input.path === null)
+    return {
+      bytes: null,
+      value: {
+        type: "screenshots",
+        locator: input.locator,
+        available_bytes: false,
+        hash: null,
+        bytes: null,
+        path: null,
+        format: input.format ?? null,
+        dimensions: input.dimensions ?? null,
+        unavailable_reason: text(input.unavailable_reason),
+      },
+    };
+  if (
+    input.unavailable_reason !== null ||
+    !/\.(?:png|jpe?g|webp|gif)$/i.test(localPath(input.path))
+  )
+    throw new Error("Available asset must be an authorized local image");
+  const bytes = await readBytes(workspace, input.path);
+  const measured = imageFormat(bytes);
+  return {
+    bytes,
+    value: {
+      type: "screenshots",
+      locator: input.locator,
+      available_bytes: true,
+      hash: digest(bytes),
+      bytes: bytes.length,
+      path: `sources/${image.id}.${measured.format}`,
+      ...measured,
+      unavailable_reason: null,
+    },
+  };
+}
+function requestBase(request) {
+  identifier(request.request_id);
+  if (!Number.isInteger(request.expected_revision) || request.expected_revision < 0)
+    throw new Error("Expected revision is required");
+}
+async function mutate(command, request, current, identity, workspace) {
+  requestBase(request);
+  if (request.expected_revision !== (current?.revision ?? 0))
+    throw new Error("Intake revision conflict");
+  const rows = [];
+  let next;
+  if (command === "create") {
+    object(request, ["request_id", "expected_revision", "mode"], ["expected_total"]);
+    if (current) throw new Error("Session already exists");
+    next = {
+      schema_version: 1,
+      workspace_id: identity.workspace_id,
+      session_id: identity.session_id,
+      revision: 1,
+      source: "screenshots",
+      mode: request.mode,
+      state: "collecting",
+      completion: { explicit: false, observed_at: null },
+      expected_total: total(request.expected_total ?? null),
+      batches: [],
+      images: [],
+      snapshot_hash: null,
+    };
+    rows.push({ path: "identity.json", bytes: encode(identity), immutable: true });
+  } else {
+    if (!current) throw new Error("Create the explicit session before mutation");
+    next = structuredClone(current);
+    next.revision++;
+    if (command === "batch") {
+      object(
+        request,
+        ["request_id", "expected_revision", "batch_id", "received_at", "images"],
+        ["expected_total"],
+      );
+      if (current.state !== "collecting")
+        throw new Error("Finalized intake requires explicit reopen");
+      identifier(request.batch_id);
+      date(request.received_at);
+      if (!Array.isArray(request.images) || request.images.length < 1 || request.images.length > 10)
+        throw new Error("Batch must contain 1–10 images; total is not inferred");
+      if (next.batches.some((batch) => batch.id === request.batch_id))
+        throw new Error("Batch ID already belongs to another request");
+      if (Object.hasOwn(request, "expected_total"))
+        next.expected_total = total(request.expected_total);
+      const ids = [];
+      for (const input of request.images) {
+        object(input, ["id", "source", "note"], ["duplicate_of"]);
+        identifier(input.id);
+        if (next.images.some((image) => image.id === input.id))
+          throw new Error("Image ID already received");
+        const asset = await source(workspace, input);
+        const previous = next.images.find((image) =>
+          asset.value.hash
+            ? image.source.hash === asset.value.hash
+            : !image.source.available_bytes && image.source.locator === asset.value.locator,
+        );
+        if (
+          input.duplicate_of !== undefined &&
+          input.duplicate_of !== null &&
+          input.duplicate_of !== previous?.id
+        )
+          throw new Error("Duplicate reference lacks matching byte/attachment identity");
+        object(input.note, ["viewed", "observations", "uncertainty"]);
+        const imageNote = { locator: `notes/${input.id}.json`, ...input.note };
+        note(imageNote, input.id);
+        next.images.push({
+          id: input.id,
+          order: next.images.length,
+          source: asset.value,
+          duplicate_of: previous?.id ?? null,
+          note: imageNote,
+        });
+        rows.push({ path: imageNote.locator, bytes: encode(imageNote), immutable: true });
+        if (asset.bytes) rows.push({ path: asset.value.path, bytes: asset.bytes, immutable: true });
+        ids.push(input.id);
+      }
+      next.batches.push({
+        id: request.batch_id,
+        receipt: request.request_id,
+        received_at: request.received_at,
+        image_ids: ids,
+      });
+    } else if (command === "correct") {
+      object(request, ["request_id", "expected_revision", "image_id", "note"]);
+      if (current.state !== "collecting")
+        throw new Error("Corrections after finalization require explicit reopen");
+      const image = next.images.find((item) => item.id === request.image_id);
+      if (!image) throw new Error("Unknown image ID");
+      object(request.note, ["viewed", "observations", "uncertainty"]);
+      image.note = { locator: image.note.locator, ...request.note };
+      note(image.note, image.id);
+      rows.push({ path: image.note.locator, bytes: encode(image.note), immutable: false });
+    } else if (command === "finish") {
+      object(request, ["request_id", "expected_revision", "finish"], ["expected_total"]);
+      if (current.state !== "collecting")
+        throw new Error("Finish requires collecting or replay of its existing receipt");
+      object(request.finish, ["explicit", "observed_at", "reference"]);
+      if (request.finish.explicit !== true)
+        throw new Error("Finish must be explicit human completion");
+      date(request.finish.observed_at);
+      text(request.finish.reference);
+      if (Object.hasOwn(request, "expected_total"))
+        next.expected_total = total(request.expected_total);
+      next.completion = { explicit: true, observed_at: request.finish.observed_at };
+      next.state = "finalized";
+      next.snapshot_hash = snapshot(next);
+      validateState(next);
+      rows.push({
+        path: reportPath(next.revision),
+        bytes: Buffer.from(renderReport(next)),
+        immutable: true,
+      });
+    } else if (command === "reopen") {
+      object(request, ["request_id", "expected_revision", "reopen"]);
+      if (current.state !== "finalized" || request.reopen !== true)
+        throw new Error("Reopen must explicitly target finalized state");
+      next.state = "collecting";
+      next.snapshot_hash = null;
+      next.completion = { explicit: false, observed_at: null };
+    } else throw new Error("Unknown intake mutation");
+  }
+  validateState(next);
+  return { next, rows };
+}
+export async function runIntake({
+  workspace,
+  conversation,
+  session,
+  command,
+  request = null,
+  checkpoint = async () => {},
+}) {
+  const workspaceRoot = await realpath(workspace);
+  if (!(await lstat(workspaceRoot)).isDirectory())
+    throw new Error("Workspace must be an explicit existing directory");
+  const workspace_hash = digest(Buffer.from(workspaceRoot));
+  const identity = {
+    schema_version: 1,
+    workspace_id: `ws-${workspace_hash.slice(0, 40)}`,
+    workspace_hash,
+    conversation_id: identifier(conversation),
+    session_id: identifier(session),
+  };
+  await directory(workspaceRoot, ".agents/private/state/visual-intake");
+  if (
+    (await optionalBytes(workspaceRoot, ".agents/private/state/visual-intake/.gitignore")) === null
+  )
+    await atomicWrite(
+      workspaceRoot,
+      ".agents/private/state/visual-intake/.gitignore",
+      Buffer.from("*\n!.gitignore\n"),
+      true,
+    );
+  const root = await directory(
+    workspaceRoot,
+    `.agents/private/state/visual-intake/${identity.session_id}`,
+  );
+  const bound = await optionalJson(root, "identity.json");
+  if (bound && digestJson(bound) !== digestJson(identity))
+    throw new Error("Session belongs to a different workspace/conversation");
+  const repair =
+    command === "recover"
+      ? async () => {
+          object(request, ["request_id", "expected_revision", "repair"]);
+          requestBase(request);
+          if (request.repair !== true)
+            throw new Error("Recovery must explicitly preserve and quarantine claim metadata");
+          await recover(root, identity, checkpoint);
+          const current = await optionalJson(root, "state.json");
+          if (current) await verifyState(root, current, identity);
+          if (request.expected_revision !== (current?.revision ?? 0))
+            throw new Error("Recovery revision conflict");
+        }
+      : null;
+  const release = await claim(root, identity, checkpoint, repair);
+  try {
+    const lockedIdentity = await optionalJson(root, "identity.json");
+    if (lockedIdentity && digestJson(lockedIdentity) !== digestJson(identity))
+      throw new Error("Session belongs to a different workspace/conversation");
+    await checkpoint("claim-acquired");
+    await recover(root, identity, checkpoint);
+    const current = await optionalJson(root, "state.json");
+    if (current) await verifyState(root, current, identity);
+    if (command === "recover") {
+      await repair();
+      return { identity, state: current, quarantine: release.quarantine, recovered: true };
+    }
+    if (command === "read") {
+      if (!current) throw new Error("Explicit session has not been created");
+      return { identity, state: current };
+    }
+    if (command === "report") {
+      if (!current) throw new Error("Explicit session has not been created");
+      object(request, ["partial", "destination", "export_authorized"]);
+      if (typeof request.partial !== "boolean")
+        throw new Error("Partial report must be explicitly selected");
+      const report = renderReport(current, request.partial);
+      if (request.destination !== null) {
+        if (
+          request.export_authorized !== true ||
+          !localPath(request.destination).startsWith(
+            ".agents/private/state/visual-intake-exports/",
+          ) ||
+          !request.destination.endsWith(".md")
+        )
+          throw new Error("Export requires an authorized local report destination");
+        await directory(workspaceRoot, ".agents/private/state/visual-intake-exports");
+        if (
+          (await optionalBytes(
+            workspaceRoot,
+            ".agents/private/state/visual-intake-exports/.gitignore",
+          )) === null
+        )
+          await atomicWrite(
+            workspaceRoot,
+            ".agents/private/state/visual-intake-exports/.gitignore",
+            Buffer.from("*\n!.gitignore\n"),
+            true,
+          );
+        await atomicWrite(workspaceRoot, request.destination, Buffer.from(report), true);
+      }
+      return {
+        report,
+        partial: request.partial,
+        revision: current.revision,
+        destination: request.destination,
+        product_writes: false,
+      };
+    }
+    requestBase(request);
+    const previous = await optionalJson(root, `receipts/${request.request_id}.json`);
+    if (previous) {
+      await verifyReceipt(root, previous, identity);
+      if (previous.request_hash !== digestJson({ operation: command, request }))
+        throw new Error("Replay request differs from its committed receipt");
+      return { receipt: previous, replayed: true, verified_at: new Date().toISOString() };
+    }
+    const { next, rows } = await mutate(command, request, current, identity, workspaceRoot);
+    const receipt = await commit(root, identity, current, next, rows, request, command, checkpoint);
+    return { receipt, replayed: false, verified_at: new Date().toISOString() };
+  } finally {
+    await release();
+  }
+}