@apicircle/cli 1.0.2 → 1.0.4

package/README.md

@@ -166,6 +166,10 @@ apicircle run "Nightly" --secrets ./secrets.json --no-save
 Resolves a plan by name or id, runs each step through the **real** request
 engine (same auth, same retries, same assertions as the desktop app),
 evaluates assertions, and carries extracted context forward between steps.
+If a request or linked-workspace step needs Global Assets file bytes that are
+missing on this machine, the CLI downloads the attachment blobs from GitHub,
+verifies their checksums, and only then starts the request. A checksum mismatch
+fails closed instead of sending a partial upload.
 
 **Flags:**
 

package/dist/index.cjs

@@ -141,7 +141,7 @@ async function ensureWorkspace(dir) {
       linkedWorkspaces: {},
       linkedOverrides: { requests: {}, environmentVars: {} },
       releases: { self: null, perLink: {} },
-      globalAssets: { schemas: {}, graphql: {} },
+      globalAssets: { schemas: {}, graphql: {}, files: {} },
       mockServers: {},
       meta: { createdAt: now, updatedAt: now, appVersion: "1.0.0" }
     },
@@ -158,13 +158,14 @@ async function ensureWorkspace(dir) {
       retiredBranch: null,
       sync: { lastPulledSnapshot: null, lastPulledSha: null, lastPulledAt: null, dirtyKeys: [] },
       linkedCollections: {},
+      attachmentCache: {},
       globalContext: {},
       mockRuntime: { active: {} },
       ui: {
         activeRequestId: null,
         sidebarExpandedSections: [],
-        themeId: "studio-dark",
-        fontId: "system-mono",
+        themeId: "one-dark-pro",
+        fontId: "system-sans",
         fontSizePercent: import_shared2.FONT_SIZE_PERCENT_DEFAULT
       },
       settings: { validateOnSend: true, monacoConsumesWheel: false },
@@ -362,7 +363,7 @@ function buildEmptyState(workspaceId, now, withSample) {
       linkedWorkspaces: {},
       linkedOverrides: { requests: {}, environmentVars: {} },
       releases: { self: null, perLink: {} },
-      globalAssets: { schemas: {}, graphql: {} },
+      globalAssets: { schemas: {}, graphql: {}, files: {} },
       mockServers: {},
       meta: { createdAt: now, updatedAt: now, appVersion: "1.0.0" }
     },
@@ -379,13 +380,14 @@ function buildEmptyState(workspaceId, now, withSample) {
       retiredBranch: null,
       sync: { lastPulledSnapshot: null, lastPulledSha: null, lastPulledAt: null, dirtyKeys: [] },
       linkedCollections: {},
+      attachmentCache: {},
       globalContext: {},
       mockRuntime: { active: {} },
       ui: {
         activeRequestId: sample?.id ?? null,
         sidebarExpandedSections: [],
-        themeId: "studio-dark",
-        fontId: "system-mono",
+        themeId: "one-dark-pro",
+        fontId: "system-sans",
         fontSizePercent: 100
       },
       settings: { validateOnSend: true, monacoConsumesWheel: false },
@@ -552,13 +554,13 @@ function registerImportCommand(program) {
 }
 async function readInput(p) {
   if (p === "-") {
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       let data = "";
       process.stdin.setEncoding("utf-8");
       process.stdin.on("data", (chunk) => {
         data += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
       });
-      process.stdin.on("end", () => resolve6(data));
+      process.stdin.on("end", () => resolve7(data));
       process.stdin.on("error", reject);
     });
   }
@@ -585,7 +587,7 @@ function blankRequest(partial) {
 // src/commands/run.ts
 var os2 = __toESM(require("os"), 1);
 var import_kleur4 = __toESM(require("kleur"), 1);
-var import_core2 = require("@apicircle/core");
+var import_core3 = require("@apicircle/core");
 var import_file_backed4 = require("@apicircle/core/workspace/file-backed");
 
 // src/util/secrets.ts
@@ -620,6 +622,272 @@ async function buildSecretsFromCli(options = {}) {
   return { byId };
 }
 
+// src/util/executionAttachments.ts
+var import_node_crypto = require("crypto");
+var import_node_fs6 = require("fs");
+var path6 = __toESM(require("path"), 1);
+var import_core2 = require("@apicircle/core");
+var ATTACHMENTS_DIR = path6.join(".apicircle", "attachments");
+async function prepareExecutionAttachments(workspaceDir, state, plan) {
+  const cacheDir = path6.resolve(workspaceDir, ATTACHMENTS_DIR);
+  const requirements = collectExecutionAttachmentRequirements(state, plan);
+  await import_node_fs6.promises.mkdir(cacheDir, { recursive: true });
+  let downloaded = 0;
+  let alreadyPresent = 0;
+  let failed = 0;
+  const cache = {
+    ...state.local.attachmentCache ?? {}
+  };
+  const entries = [];
+  for (const requirement of requirements) {
+    const localPath = path6.join(cacheDir, encodeURIComponent(requirement.slotId));
+    const present = await hasExpectedFile(localPath, requirement.sha256);
+    if (present) {
+      alreadyPresent++;
+    } else {
+      try {
+        const bytes = await downloadAttachment(requirement);
+        if (!bytes) {
+          throw new Error(
+            `Attachment ${attachmentLabel(requirement)} was not found in ${sourceLabel(requirement)}.`
+          );
+        }
+        if (requirement.sha256 && sha256Hex(bytes) !== requirement.sha256) {
+          throw new Error(
+            `Attachment ${attachmentLabel(requirement)} failed checksum verification.`
+          );
+        }
+        await import_node_fs6.promises.writeFile(localPath, bytes, { mode: 384 });
+        downloaded++;
+      } catch (err) {
+        failed++;
+        throw new Error(
+          `Attachment ${attachmentLabel(requirement)} is required by ${requiredByLabel(
+            requirement
+          )} but could not be downloaded from ${sourceLabel(requirement)}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    cache[requirement.slotId] = {
+      slotId: requirement.slotId,
+      filename: requirement.filename ?? requirement.slotId,
+      mimeType: requirement.mimeType ?? "application/octet-stream",
+      size: requirement.size ?? await fileSize(localPath),
+      sha256: requirement.sha256,
+      localPath,
+      storage: "filesystem",
+      source: requirement.source,
+      ...requirement.linkedWorkspaceId ? { linkedWorkspaceId: requirement.linkedWorkspaceId } : {},
+      requiredBy: requirement.requiredBy,
+      downloadedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    entries.push({
+      slotId: requirement.slotId,
+      filename: requirement.filename ?? requirement.slotId,
+      localPath,
+      source: requirement.source,
+      ...requirement.linkedWorkspaceId ? { linkedWorkspaceId: requirement.linkedWorkspaceId } : {},
+      requiredBy: requirement.requiredBy
+    });
+  }
+  const nextState = {
+    ...state,
+    local: {
+      ...state.local,
+      attachmentCache: cache
+    }
+  };
+  return {
+    state: nextState,
+    resolveAttachment: createFileAttachmentResolver(nextState),
+    summary: {
+      total: requirements.length,
+      downloaded,
+      alreadyPresent,
+      failed,
+      cacheDir,
+      entries
+    }
+  };
+}
+function createFileAttachmentResolver(state) {
+  return async (slotId) => {
+    const meta = state.local.attachmentCache?.[slotId];
+    if (!meta) return null;
+    const bytes = await import_node_fs6.promises.readFile(meta.localPath);
+    const view = new Uint8Array(bytes);
+    const body = view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+    return {
+      blob: new Blob([body], { type: meta.mimeType }),
+      filename: meta.filename
+    };
+  };
+}
+function collectExecutionAttachmentRequirements(state, plan) {
+  const seen = /* @__PURE__ */ new Map();
+  const localRequestFilter = requestFilterForPlan(plan, null);
+  const localCollections = localRequestFilter ? {
+    ...state.synced.collections,
+    requests: Object.fromEntries(
+      Object.entries(state.synced.collections.requests).filter(
+        ([id]) => localRequestFilter.has(id)
+      )
+    )
+  } : state.synced.collections;
+  const workspaceSlots = (0, import_core2.collectAttachmentSlots)({ ...state.synced, collections: localCollections });
+  for (const slot of workspaceSlots) {
+    const requiredBy = collectRequiredBy(localCollections.requests, slot.slotId);
+    if (requiredBy.length === 0) continue;
+    addRequirement(seen, {
+      ...slot,
+      source: "workspace",
+      repoFullName: state.local.connectedRepo?.fullName ?? void 0,
+      branch: state.local.workingBranch?.name ?? void 0,
+      publicRepo: state.local.connectedRepo ? !state.local.connectedRepo.isPrivate : false,
+      requiredBy
+    });
+  }
+  for (const [linkedWorkspaceId, snapshot] of Object.entries(state.local.linkedCollections)) {
+    const link = state.synced.linkedWorkspaces[linkedWorkspaceId];
+    if (!link) continue;
+    const linkedRequestFilter = requestFilterForPlan(plan, linkedWorkspaceId);
+    if (plan && linkedRequestFilter && linkedRequestFilter.size === 0) continue;
+    const linkedCollections = linkedRequestFilter ? {
+      ...snapshot.collections,
+      requests: Object.fromEntries(
+        Object.entries(snapshot.collections.requests).filter(
+          ([id]) => linkedRequestFilter.has(id)
+        )
+      )
+    } : snapshot.collections;
+    const linkedSynced = {
+      ...state.synced,
+      collections: linkedCollections,
+      environments: snapshot.environments,
+      globalAssets: snapshot.globalAssets ?? state.synced.globalAssets
+    };
+    for (const slot of (0, import_core2.collectAttachmentSlots)(linkedSynced)) {
+      const requiredBy = collectRequiredBy(linkedCollections.requests, slot.slotId);
+      if (requiredBy.length === 0) continue;
+      addRequirement(seen, {
+        ...slot,
+        source: "linked-workspace",
+        linkedWorkspaceId,
+        repoFullName: link.source.repoFullName,
+        branch: link.source.branch,
+        publicRepo: link.kind === "public",
+        requiredBy
+      });
+    }
+  }
+  return [...seen.values()];
+}
+function requestFilterForPlan(plan, linkedWorkspaceId) {
+  if (!plan) return null;
+  const ids = /* @__PURE__ */ new Set();
+  for (const step of plan.steps) {
+    if (step.enabled === false) continue;
+    if ((step.linkedWorkspaceId ?? null) === linkedWorkspaceId) ids.add(step.requestId);
+  }
+  return ids;
+}
+function addRequirement(seen, requirement) {
+  const existing = seen.get(requirement.slotId);
+  if (!existing) {
+    seen.set(requirement.slotId, requirement);
+    return;
+  }
+  for (const usage of requirement.requiredBy) {
+    if (!existing.requiredBy.some((item) => item.requestId === usage.requestId)) {
+      existing.requiredBy.push(usage);
+    }
+  }
+}
+function collectRequiredBy(requests, slotId) {
+  const requiredBy = [];
+  for (const request of Object.values(requests)) {
+    if (bodyReferencesSlot(request.body, slotId)) {
+      requiredBy.push({ requestId: request.id, requestName: request.name });
+    }
+  }
+  return requiredBy;
+}
+function bodyReferencesSlot(body, slotId) {
+  if (body.type === "binary") return body.attachment?.slotId === slotId;
+  if (body.type !== "form-data") return false;
+  return (body.formRows ?? []).some((row) => row.kind === "file" && row.slotId === slotId);
+}
+async function hasExpectedFile(localPath, sha256) {
+  try {
+    const bytes = await import_node_fs6.promises.readFile(localPath);
+    if (!sha256) return true;
+    return sha256Hex(bytes) === sha256;
+  } catch {
+    return false;
+  }
+}
+async function fileSize(localPath) {
+  try {
+    return (await import_node_fs6.promises.stat(localPath)).size;
+  } catch {
+    return 0;
+  }
+}
+async function downloadAttachment(requirement) {
+  if (!requirement.repoFullName || !requirement.branch) return null;
+  const [owner, repo] = requirement.repoFullName.split("/", 2);
+  if (!owner || !repo) return null;
+  const token = resolveGitHubToken(requirement);
+  if (!token && !requirement.publicRepo) {
+    throw new Error(
+      "private linked attachments need a GitHub token (set APICIRCLE_GITHUB_TOKEN or GITHUB_TOKEN)"
+    );
+  }
+  const apiPath = [".apicircle", "attachments", requirement.slotId].map(encodeURIComponent).join("/");
+  const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(
+    repo
+  )}/contents/${apiPath}?ref=${encodeURIComponent(requirement.branch)}`;
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "apicircle-cli",
+    "X-GitHub-Api-Version": "2022-11-28"
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(url, { headers, cache: "no-store" });
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`GitHub returned ${res.status}: ${await res.text()}`);
+  }
+  const json = await res.json();
+  if (json.type !== "file" || typeof json.content !== "string") {
+    throw new Error("GitHub response was not a file");
+  }
+  if (json.encoding !== "base64") {
+    throw new Error(`GitHub response used unsupported encoding ${json.encoding ?? "(missing)"}`);
+  }
+  return new Uint8Array(Buffer.from(json.content.replace(/\n/g, ""), "base64"));
+}
+function resolveGitHubToken(requirement) {
+  if (requirement.source === "linked-workspace") {
+    return process.env.APICIRCLE_E2E_BOT_PAT_LINK_DEDICATED ?? process.env.APICIRCLE_GITHUB_TOKEN ?? process.env.GITHUB_TOKEN ?? process.env.APICIRCLE_E2E_GITHUB_PAT ?? process.env.APICIRCLE_E2E_BOT_PAT ?? "";
+  }
+  return process.env.APICIRCLE_GITHUB_TOKEN ?? process.env.GITHUB_TOKEN ?? process.env.APICIRCLE_E2E_GITHUB_PAT ?? process.env.APICIRCLE_E2E_BOT_PAT ?? "";
+}
+function sha256Hex(bytes) {
+  return (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+}
+function attachmentLabel(requirement) {
+  return `${requirement.filename ?? requirement.slotId} (${requirement.slotId})`;
+}
+function sourceLabel(requirement) {
+  const repo = requirement.repoFullName ?? "local workspace";
+  const branch = requirement.branch ? `@${requirement.branch}` : "";
+  return `${repo}${branch}`;
+}
+function requiredByLabel(requirement) {
+  return requirement.requiredBy.map((item) => item.requestName).join(", ") || "a request";
+}
+
 // src/commands/run.ts
 var REPORTERS = ["text", "json", "junit"];
 function registerRunCommand(program) {
@@ -661,7 +929,7 @@ function registerRunCommand(program) {
       fail(`no workspace found at ${dir} (expected workspace.synced.json)`);
       return;
     }
-    const ref = (0, import_core2.resolvePlanRef)(state.synced, planRef);
+    const ref = (0, import_core3.resolvePlanRef)(state.synced, planRef);
     if (!ref.ok) {
       fail(ref.error);
       if (ref.available.length > 0) {
@@ -693,21 +961,33 @@ function registerRunCommand(program) {
     const onSigint = () => controller.abort(new Error("aborted by SIGINT"));
     process.on("SIGINT", onSigint);
     if (text) process.stdout.write(formatHeader(ref.plan, actor, withAssertions, opts));
+    let prepared;
+    try {
+      prepared = await prepareExecutionAttachments(dir, state, ref.plan);
+    } catch (err) {
+      process.off("SIGINT", onSigint);
+      fail(err instanceof Error ? err.message : String(err), 1, "attachment");
+      return;
+    }
+    if (text && prepared.summary.total > 0) {
+      process.stdout.write(formatAttachmentPreparation(prepared.summary));
+    }
     let result;
     try {
-      result = await (0, import_core2.runPlan)(state, ref.id, {
+      result = await (0, import_core3.runPlan)(prepared.state, ref.id, {
         withAssertions,
         bail: opts.bail === true,
         env: opts.env,
         secretsById,
         actor,
         signal: controller.signal,
+        resolveAttachment: prepared.resolveAttachment,
         authorize: checkRunPermission,
         onStep: text ? (step) => process.stdout.write(formatStepLine(step)) : void 0
       });
     } catch (err) {
       process.off("SIGINT", onSigint);
-      if (err instanceof import_core2.PlanRunDeniedError) {
+      if (err instanceof import_core3.PlanRunDeniedError) {
         fail(err.message, 3, "denied");
         return;
       }
@@ -720,7 +1000,7 @@ function registerRunCommand(program) {
     if (reporter === "json") {
       process.stdout.write(
         JSON.stringify(
-          buildJsonReport(dir, ref.id, ref.plan, actor, result, saved, aborted),
+          buildJsonReport(dir, ref.id, ref.plan, actor, result, saved, aborted, prepared.summary),
           null,
           2
         ) + "\n"
@@ -746,7 +1026,7 @@ function resolveActor(local, override) {
     if (username) return { kind: "os", name: username };
   } catch {
   }
-  return import_core2.ANONYMOUS_ACTOR;
+  return import_core3.ANONYMOUS_ACTOR;
 }
 function checkRunPermission(_ctx) {
 }
@@ -762,6 +1042,26 @@ function formatHeader(plan, actor, withAssertions, opts) {
   )}
 ${import_kleur4.default.dim("Run by")} ${actor.name} ${import_kleur4.default.dim(`(${actor.kind})`)}
 
+`;
+}
+function formatAttachmentPreparation(summary) {
+  const status = `${summary.downloaded} downloaded, ${summary.alreadyPresent} already local`;
+  const lines = [
+    `${import_kleur4.default.bold("Attachments")} ${summary.total} required ${import_kleur4.default.dim(
+      `(${status} - ${summary.cacheDir})`
+    )}`
+  ];
+  for (const entry2 of summary.entries) {
+    const source = entry2.source === "linked-workspace" ? `linked:${entry2.linkedWorkspaceId ?? "unknown"}` : "workspace";
+    const requiredBy = entry2.requiredBy.map((item) => item.requestName).join(", ");
+    lines.push(
+      `  ${import_kleur4.default.dim("file")} ${entry2.filename} ${import_kleur4.default.dim(
+        `${source} - ${requiredBy} - ${entry2.localPath}`
+      )}`
+    );
+  }
+  return `${lines.join("\n")}
+
 `;
 }
 function formatStepLine(step) {
@@ -831,7 +1131,7 @@ ${verdict}  ${parts.join(import_kleur4.default.dim(" \xB7 "))}  ${import_kleur4.
   out += saved ? import_kleur4.default.dim("Plan run saved to workspace history.\n") : import_kleur4.default.dim("Plan run not saved (--no-save).\n");
   return out;
 }
-function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted) {
+function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted, attachments) {
   return {
     workspace,
     plan: { id: planId, name: plan.name },
@@ -841,6 +1141,7 @@ function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted)
     aborted,
     durationMs: result.planRun.durationMs,
     saved,
+    attachments,
     counts: tally(result),
     steps: result.steps.map((s) => ({
       step: s.stepIndex + 1,