@asteroidai/cli 1.9.2 → 1.9.11

package/src/sync/execution-pull.ts

@@ -0,0 +1,273 @@
+import { type Activity, formatActivitiesMarkdown } from "./activities";
+import {
+  executionDirName,
+  isContained,
+  join,
+  matchesGlob,
+  workflowRoot,
+} from "./paths";
+import { get, type Sync } from "./types";
+
+export interface Execution {
+  id: string;
+  status: string;
+  workflowId: string;
+  workflowVersionId?: string;
+  workflowName?: string;
+  inputs?: unknown;
+  executionResult?: { outcome?: string; reasoning?: string } | null;
+  createdAt: string;
+  terminalAt?: string | null;
+  duration?: number | null;
+  scriptFailures?: { nodeName?: string; error?: string }[] | null;
+  purgedAt?: string | null;
+}
+
+interface ExecutionFile {
+  id: string;
+  fileName: string;
+  filePath: string;
+  fileSize: number;
+  directory: string;
+}
+
+const DIRECTORIES = ["workspace", "downloads", "shared"] as const;
+
+export interface ExecutionPullOptions {
+  executionId: string;
+  root: string;
+  dir?: (execution: Execution) => string | undefined;
+  files?: boolean;
+  activities?: boolean;
+  glob?: string;
+  maxFileBytes?: number;
+}
+
+export interface ExecutionPullResult {
+  execution: Execution;
+  dir: string;
+  written: string[];
+  downloaded: number;
+  candidates: number;
+  skipped: string[];
+  failed: string[];
+  skippedBy?: string;
+}
+
+export function relativeFilePath(
+  file: Pick<ExecutionFile, "filePath" | "directory">,
+): string {
+  const at = file.filePath.indexOf(`/${file.directory}/`);
+  if (at === -1)
+    return `${file.directory}/${file.filePath.split("/").pop() ?? "unknown"}`;
+  return file.filePath
+    .slice(at + 1)
+    .replace(/^workspace\/\.execution-context\//, "");
+}
+
+function executionDir(
+  options: ExecutionPullOptions,
+  execution: Execution,
+): string {
+  const chosen = options.dir?.(execution);
+  if (chosen) return chosen;
+  const root = workflowRoot(
+    options.root,
+    execution.workflowName ?? execution.workflowId,
+  );
+  return join(root, "executions", executionDirName(execution.id));
+}
+
+async function writeText(sync: Sync, path: string, text: string) {
+  await sync.files.write(path, Buffer.from(text, "utf8"));
+}
+
+async function writeActivities(sync: Sync, dir: string, execution: Execution) {
+  try {
+    const activities = (await sync.remote.json(
+      get(`/agents/v2/executions/${execution.id}/activities`, { order: "asc" }),
+    )) as Activity[];
+    if (activities.length === 0) return false;
+    const markdown = formatActivitiesMarkdown(
+      activities,
+      execution.status,
+      execution.createdAt,
+    );
+    await writeText(sync, join(dir, "activities.md"), markdown);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listFiles(
+  sync: Sync,
+  executionId: string,
+): Promise<ExecutionFile[]> {
+  const listing = (await sync.remote.json(
+    get(`/agents/v2/executions/${executionId}/files`),
+  )) as {
+    directories: Partial<Record<string, ExecutionFile[]>>;
+  };
+  return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
+}
+
+async function download(sync: Sync, executionId: string, file: ExecutionFile) {
+  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+  const { url } = (await sync.remote.json(get(path))) as { url: string };
+  return sync.remote.download(url);
+}
+
+function selectFiles(
+  files: ExecutionFile[],
+  options: ExecutionPullOptions,
+  skipped: string[],
+) {
+  return files.filter((file) => {
+    const path = relativeFilePath(file);
+    if (!isContained(path)) skipped.push(`${path} (unsafe path)`);
+    else if (options.glob !== undefined && !matchesGlob(path, options.glob))
+      skipped.push(`${path} (excluded by --files)`);
+    else if (
+      options.maxFileBytes !== undefined &&
+      file.fileSize > options.maxFileBytes
+    )
+      skipped.push(`${path} (${file.fileSize} bytes, over the size limit)`);
+    else return true;
+    return false;
+  });
+}
+
+async function pullFiles(
+  sync: Sync,
+  dir: string,
+  options: ExecutionPullOptions,
+) {
+  const skipped: string[] = [];
+  const failed: string[] = [];
+  let files: ExecutionFile[];
+  try {
+    files = await listFiles(sync, options.executionId);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      downloaded: 0,
+      candidates: 0,
+      skipped,
+      failed: [`file listing (${reason})`],
+    };
+  }
+  let downloaded = 0;
+  await Promise.all(
+    selectFiles(files, options, skipped).map(async (file) => {
+      try {
+        const bytes = await download(sync, options.executionId, file);
+        await sync.files.write(join(dir, relativeFilePath(file)), bytes);
+        downloaded++;
+      } catch (error) {
+        failed.push(
+          `${file.fileName} (${error instanceof Error ? error.message : String(error)})`,
+        );
+      }
+    }),
+  );
+  return { downloaded, candidates: files.length, skipped, failed };
+}
+
+export async function pullExecution(
+  sync: Sync,
+  options: ExecutionPullOptions,
+): Promise<ExecutionPullResult> {
+  const execution = (await sync.remote.json(
+    get(`/agents/v2/executions/${options.executionId}`),
+  )) as Execution;
+  const dir = executionDir(options, execution);
+  await writeText(
+    sync,
+    join(dir, "summary.json"),
+    JSON.stringify(execution, null, 2),
+  );
+  const result = {
+    execution,
+    dir,
+    written: ["summary.json"],
+    downloaded: 0,
+    candidates: 0,
+    skipped: [],
+    failed: [],
+  };
+  if (execution.purgedAt) return result;
+  if (
+    options.activities !== false &&
+    (await writeActivities(sync, dir, execution))
+  )
+    result.written.push("activities.md");
+  if (options.files === false) {
+    return {
+      ...result,
+      skippedBy: options.activities === false ? "--summary-only" : "--no-files",
+    };
+  }
+  return { ...result, ...(await pullFiles(sync, dir, options)) };
+}
+
+function filesLine(result: ExecutionPullResult): string {
+  const parts = [...result.written];
+  if (result.downloaded > 0) parts.push(`${result.downloaded} downloaded`);
+  const counted = `Files: ${result.written.length + result.downloaded} written (${parts.join(", ")})`;
+  if (result.skippedBy)
+    return `${counted}; downloads skipped (${result.skippedBy})`;
+  if (result.candidates === 0) return `${counted}; no execution files matched`;
+  return counted;
+}
+
+function failures(execution: Execution): string | null {
+  const list = execution.scriptFailures ?? [];
+  if (list.length === 0) return null;
+  const lines = list.map(
+    (f) =>
+      `  - ${f.nodeName ?? "(unknown node)"}: ${(f.error ?? "").split("\n")[0]}`,
+  );
+  return `Script failures: ${list.length}\n${lines.join("\n")}`;
+}
+
+function purged(result: ExecutionPullResult): string {
+  const { execution } = result;
+  return [
+    `Execution: ${execution.id}`,
+    `Status: ${execution.status}`,
+    `Purged: ${execution.purgedAt}`,
+    "This run was retention-purged. Activities, files, inputs and result are gone. Do not diagnose it.",
+    `Written to: ${result.dir}/`,
+  ].join("\n");
+}
+
+export function formatExecutionPull(result: ExecutionPullResult): string {
+  const { execution } = result;
+  if (execution.purgedAt) return purged(result);
+  const outcome = execution.executionResult;
+  return [
+    `Execution: ${execution.id}`,
+    `Status: ${execution.status}`,
+    `Workflow: ${execution.workflowName ?? execution.workflowId}`,
+    execution.workflowVersionId
+      ? `Workflow version: ${execution.workflowVersionId}`
+      : null,
+    execution.inputs ? `Inputs: ${JSON.stringify(execution.inputs)}` : null,
+    outcome ? `Result: ${outcome.outcome}: ${outcome.reasoning}` : null,
+    `Created: ${execution.createdAt}`,
+    execution.terminalAt ? `Completed: ${execution.terminalAt}` : null,
+    execution.duration != null
+      ? `Duration: ${execution.duration.toFixed(1)}s`
+      : null,
+    failures(execution),
+    filesLine(result),
+    result.skipped.length > 0
+      ? `Skipped:\n${result.skipped.map((s) => `  - ${s}`).join("\n")}`
+      : null,
+    result.failed.length > 0 ? `Failed: ${result.failed.join(", ")}` : null,
+    `Written to: ${result.dir}/`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/sync/node-files.ts

@@ -0,0 +1,47 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+
+import type { LocalFiles } from "./types";
+
+function missing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+async function walk(root: string, dir: string, out: string[]): Promise<void> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = resolve(dir, entry.name);
+    if (entry.isDirectory()) await walk(root, path, out);
+    else if (entry.isFile())
+      out.push(relative(root, path).split(sep).join("/"));
+  }
+}
+
+export function nodeFiles(cwd: string): LocalFiles {
+  const at = (path: string) => resolve(cwd, path);
+  return {
+    async read(path) {
+      try {
+        return new Uint8Array(await readFile(at(path)));
+      } catch (error) {
+        if (missing(error)) return undefined;
+        throw error;
+      }
+    },
+    async write(path, bytes) {
+      await mkdir(dirname(at(path)), { recursive: true });
+      await writeFile(at(path), bytes);
+    },
+    async remove(path) {
+      await rm(at(path), { force: true });
+    },
+    async list(dir) {
+      const out: string[] = [];
+      try {
+        await walk(at(dir), at(dir), out);
+      } catch (error) {
+        if (!missing(error)) throw error;
+      }
+      return out.sort();
+    },
+  };
+}

package/src/sync/paths.ts

@@ -0,0 +1,45 @@
+import { agentDirName } from "@asteroid/workflow-files/names";
+import { createHash } from "node:crypto";
+
+export {
+  agentDirName,
+  executionDirName,
+  workflowDirName,
+} from "@asteroid/workflow-files/names";
+
+export function join(...parts: string[]): string {
+  return parts
+    .filter((part) => part !== "")
+    .join("/")
+    .replace(/\/{2,}/g, "/");
+}
+
+export function workflowRoot(root: string, workflowName: string): string {
+  return join(root, agentDirName(workflowName));
+}
+
+export function isContained(path: string): boolean {
+  if (path === "" || path.startsWith("/") || path.includes("\\")) return false;
+  return path.split("/").every((segment) => segment !== ".." && segment !== "");
+}
+
+export function sha256(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function matchesGlob(path: string, pattern: string): boolean {
+  let source = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "*" && pattern[i + 1] === "*" && pattern[i + 2] === "/") {
+      source += "(?:.*/)?";
+      i += 2;
+    } else if (ch === "*" && pattern[i + 1] === "*") {
+      source += ".*";
+      i += 1;
+    } else if (ch === "*") source += "[^/]*";
+    else if (ch === "?") source += "[^/]";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`).test(path);
+}

package/src/sync/run.ts

@@ -0,0 +1,102 @@
+import { type Parsed, UsageError } from "../args";
+import type { CliCommand } from "../types";
+import {
+  type ExecutionPullOptions,
+  formatExecutionPull,
+  pullExecution,
+} from "./execution-pull";
+import { nodeFiles } from "./node-files";
+import type { LocalFiles, Remote, Sync } from "./types";
+import {
+  formatWorkflowPull,
+  pullWorkflow,
+  type WorkflowPullOptions,
+} from "./workflow-pull";
+import { formatWorkflowPush, pushWorkflow } from "./workflow-push";
+
+export { SYNC_COMMANDS } from "./commands";
+
+export interface SyncDeps {
+  cwd: string;
+  remote: Remote;
+  files?: LocalFiles;
+  stdout: (text: string) => void;
+  root?: string;
+  workflowPull?: Partial<WorkflowPullOptions>;
+  executionPull?: Partial<ExecutionPullOptions>;
+}
+
+function flag(parsed: Parsed, name: string): string | undefined {
+  return parsed.flags.get(name)?.at(-1);
+}
+
+function integer(parsed: Parsed, name: string): number | undefined {
+  const raw = flag(parsed, name);
+  if (raw === undefined) return undefined;
+  if (!/^\d+$/.test(raw))
+    throw new UsageError(`--${name} must be a whole number`);
+  return Number(raw);
+}
+
+function executionOptions(parsed: Parsed): Omit<ExecutionPullOptions, "root"> {
+  const summaryOnly = flag(parsed, "summary-only") === "true";
+  const glob = flag(parsed, "files");
+  const dir = flag(parsed, "dir");
+  return {
+    executionId: parsed.positionals[0],
+    activities: !summaryOnly,
+    files: !summaryOnly && glob !== "false",
+    glob: glob === "false" ? undefined : glob,
+    maxFileBytes: integer(parsed, "max-file-size"),
+    dir: dir ? () => dir : undefined,
+  };
+}
+
+async function execute(
+  command: CliCommand,
+  parsed: Parsed,
+  sync: Sync,
+  deps: SyncDeps,
+) {
+  const root = deps.root ?? "";
+  switch (command.command) {
+    case "workflow pull": {
+      const result = await pullWorkflow(sync, {
+        workflowId: parsed.positionals[0],
+        versionId: flag(parsed, "version-id"),
+        dir: flag(parsed, "dir"),
+        root,
+        ...deps.workflowPull,
+      });
+      return { result, text: formatWorkflowPull(result) };
+    }
+    case "workflow push": {
+      const result = await pushWorkflow(sync, flag(parsed, "dir") ?? ".");
+      return { result, text: formatWorkflowPush(result) };
+    }
+    case "execution pull": {
+      const result = await pullExecution(sync, {
+        ...executionOptions(parsed),
+        root,
+        ...deps.executionPull,
+      });
+      return { result, text: formatExecutionPull(result) };
+    }
+    default:
+      throw new UsageError(`unknown command ${command.command}`);
+  }
+}
+
+export async function runSync(
+  command: CliCommand,
+  parsed: Parsed,
+  deps: SyncDeps,
+) {
+  const sync = {
+    remote: deps.remote,
+    files: deps.files ?? nodeFiles(deps.cwd),
+  };
+  const { result, text } = await execute(command, parsed, sync, deps);
+  deps.stdout(`${parsed.json ? JSON.stringify(result, null, 2) : text}\n`);
+  return 0;
+}