@asteroidai/cli 1.9.4 → 1.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.4",
+  "version": "1.9.12",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,8 @@
     "tsx": "^4.23.12",
     "typescript": "5.9.3",
     "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@asteroid/workflow-files": "0.1.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts && pnpm exec prettier --write src/generated/commands.ts",

package/src/commands.ts

@@ -0,0 +1,13 @@
+import { COMMANDS } from "./generated/commands";
+import { SYNC_COMMANDS } from "./sync/commands";
+import type { CliCommand } from "./types";
+
+export function withSyncCommands(
+  commands: readonly CliCommand[],
+): CliCommand[] {
+  return [...commands, ...SYNC_COMMANDS].sort((a, b) =>
+    a.command.localeCompare(b.command),
+  );
+}
+
+export const ALL_COMMANDS = withSyncCommands(COMMANDS);

package/src/core.ts

@@ -8,3 +8,34 @@ export {
 } from "./program";
 export { type BuiltRequest, buildRequest, type InputReader } from "./request";
 export type { CliCommand, Option } from "./types";
+export { ALL_COMMANDS, withSyncCommands } from "./commands";
+export { type Activity, formatActivitiesMarkdown } from "./sync/activities";
+export {
+  type Execution,
+  type ExecutionPullOptions,
+  type ExecutionPullResult,
+  formatExecutionPull,
+  pullExecution,
+} from "./sync/execution-pull";
+export { matchesGlob } from "./sync/paths";
+export { runSync, type SyncDeps, SYNC_COMMANDS } from "./sync/run";
+export {
+  type FileEntry,
+  type FileTree,
+  type LocalFiles,
+  MANIFEST,
+  type Manifest,
+  type Remote,
+  type Sync,
+} from "./sync/types";
+export {
+  formatWorkflowPull,
+  pullWorkflow,
+  type WorkflowPullOptions,
+  type WorkflowPullResult,
+} from "./sync/workflow-pull";
+export {
+  formatWorkflowPush,
+  pushWorkflow,
+  type WorkflowPushResult,
+} from "./sync/workflow-push";

package/src/generated/commands.ts

@@ -128,6 +128,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "context",
@@ -1092,6 +1093,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "execution resume",
@@ -1113,6 +1115,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "insight get",
@@ -2004,6 +2007,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schedule delete",
@@ -2031,6 +2035,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: true,
+    capability: "run_execution",
   },
   {
     command: "schedule get",
@@ -2222,6 +2227,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution cancel",
@@ -2243,6 +2249,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution create",
@@ -2315,6 +2322,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution list",
@@ -2421,6 +2429,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schema validate",
@@ -3621,6 +3630,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "workflow execute-sync",
@@ -3731,119 +3741,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow file list",
-    tool: "workflow_files_list",
-    title: "List workflow files",
-    description:
-      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
-  },
-  {
-    command: "workflow file patch",
-    tool: "workflow_files_patch",
-    title: "Write workflow files",
-    description:
-      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
-    method: "PATCH",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [],
-    binary: false,
-    readOnly: false,
-    destructive: true,
-    body: {
-      required: true,
-      contentType: "application/json",
-      fields: [
-        {
-          name: "baseRev",
-          flag: "base-rev",
-          type: "integer",
-          required: true,
-          description:
-            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
-        },
-        {
-          name: "writes",
-          flag: "writes",
-          type: "json",
-          required: true,
-          description: "Files to upsert.",
-        },
-        {
-          name: "deletes",
-          flag: "deletes",
-          type: "string[]",
-          required: true,
-        },
-      ],
-      files: [],
-      credentialOrganization: false,
-    },
+    capability: "run_execution",
   },
   {
     command: "workflow get",
@@ -3894,6 +3792,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
   },
   {
     command: "workflow head revert",
@@ -4024,6 +3923,121 @@ export const COMMANDS: CliCommand[] = [
     readOnly: true,
     destructive: false,
   },
+  {
+    command: "workflow pull",
+    tool: "workflow_files_list",
+    title: "List workflow files",
+    description:
+      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
+  },
+  {
+    command: "workflow push",
+    tool: "workflow_files_patch",
+    title: "Write workflow files",
+    description:
+      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
+    method: "PATCH",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [],
+    binary: false,
+    readOnly: false,
+    destructive: true,
+    body: {
+      required: true,
+      contentType: "application/json",
+      fields: [
+        {
+          name: "baseRev",
+          flag: "base-rev",
+          type: "integer",
+          required: true,
+          description:
+            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
+        },
+        {
+          name: "writes",
+          flag: "writes",
+          type: "json",
+          required: true,
+          description: "Files to upsert.",
+        },
+        {
+          name: "deletes",
+          flag: "deletes",
+          type: "string[]",
+          required: true,
+        },
+      ],
+      files: [],
+      credentialOrganization: false,
+    },
+    files: "push",
+  },
   {
     command: "workflow rename",
     tool: "workflow_rename",
@@ -4449,75 +4463,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow version file list",
-    tool: "workflow_version_files_list",
-    title: "List workflow version files",
-    description:
-      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-      {
-        name: "versionId",
-        flag: "version-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
+    capability: "run_execution",
   },
   {
     command: "workflow version file url",
@@ -4680,6 +4626,77 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
+  },
+  {
+    command: "workflow version pull",
+    tool: "workflow_version_files_list",
+    title: "List workflow version files",
+    description:
+      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+      {
+        name: "versionId",
+        flag: "version-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
   },
   {
     command: "workflow version validate",

package/src/main.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 
+import { ALL_COMMANDS } from "./commands";
 import { readEnv } from "./config";
-import { COMMANDS } from "./generated/commands";
 import { runCompletion } from "./program";
 import { BUILTINS } from "./reference";
 import { run } from "./run";
@@ -27,7 +27,7 @@ function openUrl(url: string) {
 
 const argv = process.argv.slice(2);
 if (argv[0] === "complete") {
-  await runCompletion(argv, { commands: COMMANDS, builtins: BUILTINS });
+  await runCompletion(argv, { commands: ALL_COMMANDS, builtins: BUILTINS });
   process.exit(0);
 }
 

package/src/program.test.ts

@@ -133,4 +133,23 @@ describe("parseInvocation", () => {
       "expected [workflow-id] <schedule-id>, got 0 argument(s)",
     );
   });
+
+  it("prints the version only as the first argument", async () => {
+    const options = {
+      commands: COMMANDS,
+      builtins: BUILTINS,
+      version: "1.2.3",
+    };
+
+    const version = await parseInvocation(["--version"], options);
+    const create = await parseInvocation(
+      ["workflow", "create", "--name", "W", "--version", "{}"],
+      options,
+    );
+
+    expect(version).toMatchObject({ kind: "exit", code: 0, stdout: "1.2.3\n" });
+    expect(create.kind).toBe("command");
+    if (create.kind === "command")
+      expect(create.parsed.flags.get("version")).toEqual(["{}"]);
+  });
 });

package/src/program.ts

@@ -85,10 +85,22 @@ function leafOptions(leaf: Command, command: CliCommand) {
       optionText(option),
       collect,
     );
+    if (option.negatable)
+      leaf.option(`--no-${option.flag}`, `Skip ${option.flag}.`);
   }
   for (const file of command.body?.files ?? []) {
     leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
   }
+  if (command.files === "pull")
+    leaf.option(
+      "--out <dir>",
+      "Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead.",
+    );
+  if (command.files === "push")
+    leaf.option(
+      "--from <dir>",
+      "The pulled head folder to push. Defaults to the current folder.",
+    );
 }
 
 function toParsed(
@@ -122,7 +134,11 @@ export function defineCommands(
   onInvocation: (invocation: Invocation) => void = () => undefined,
 ): Command {
   if (options.description) root.description(options.description);
-  if (options.version) root.version(options.version, "-v, --version");
+  if (options.version)
+    root.addHelpText(
+      "after",
+      "\nRun `asteroid --version` to print the CLI version.",
+    );
   for (const [flags, text] of GLOBAL_FLAGS) {
     if (!flags.startsWith("-h")) root.option(flags, text);
   }
@@ -224,6 +240,14 @@ export async function parseInvocation(
   let stderr = "";
   let result: Invocation | undefined;
 
+  if (options.version && (argv[0] === "-v" || argv[0] === "--version")) {
+    return {
+      kind: "exit",
+      code: 0,
+      stdout: `${options.version}\n`,
+      stderr: "",
+    };
+  }
   const { argv: rest, dotted } = splitDotted(argv);
   const root = new Command("asteroid")
     .exitOverride()

package/src/reference.ts

@@ -75,7 +75,11 @@ export const GLOBAL_FLAGS: [string, string][] = [
 ];
 
 export function usage(command: CliCommand): string {
-  const args = command.args.map((arg) => `<${arg.flag}>`).join(" ");
+  const args = command.args
+    .map((arg) =>
+      command.files === "push" ? `[${arg.flag}]` : `<${arg.flag}>`,
+    )
+    .join(" ");
   return `asteroid ${command.command}${args ? ` ${args}` : ""} [flags]`;
 }
 
@@ -109,6 +113,14 @@ export function flagLines(command: CliCommand): string[] {
   for (const file of command.body?.files ?? []) {
     lines.push(`--${file} <path>  File to upload (repeatable)`);
   }
+  if (command.files === "pull")
+    lines.push(
+      "--out <dir>  Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead",
+    );
+  if (command.files === "push")
+    lines.push(
+      "--from <dir>  The pulled head folder to push. Defaults to the current folder",
+    );
   return lines;
 }