@getmagical/cli 0.3.1 → 0.4.0

package/README.md

@@ -129,20 +129,25 @@ mgcl --branch-id <branch-id> workbench patch readiness --target-draft-automation
 Branch creation defaults to main. Use `--source-branch-id` and optionally
 `--source-version-id` to fork from another branch or an older version in that
 branch's history. Names must use lowercase letters or numbers separated by
-single dashes, such as `release-2`. Spaces, underscores, slashes, backslashes,
-punctuation, uppercase letters, leading or trailing dashes, and repeated dashes
-are rejected before an API request. Branch IDs, not names, identify targets.
+single dashes, such as `release-2`, and must be 100 characters or fewer.
+Spaces, underscores, slashes, backslashes, punctuation, uppercase letters,
+leading or trailing dashes, repeated dashes, and over-length names are
+rejected before an API request. Branch IDs, not names, identify targets, and
+every automation or branch ID must be a UUID; malformed IDs are rejected
+before an API request.
 Merge previews the same change set as the web UI. A conflict returns
-`status: "conflict"` and does not change main or delete the branch. A
-conflict-free merge returns `status: "merged"`, the saved-main result, and
-deletes the source branch. Rename, delete, compare, and publish are
-intentionally deferred.
+`status: "conflict"`, does not change main or delete the branch, and exits
+nonzero so scripts gating on the exit code never mistake it for an applied
+merge. A conflict-free merge returns `status: "merged"`, the saved-main
+result, and deletes the source branch. Rename, delete, compare, and publish
+are intentionally deferred.
 
 The global branch target is accepted by `automations update`, `automations
-run-draft`, `workbench diagnostics`, `workbench schema-suggestions`, and
-`workbench patch preview`, `readiness`, and `apply`. It is required by
-`automations branches get` and `merge`. Other commands reject `--branch-id`
-before making an API request. Branch-aware responses identify the selected
+run-draft`, `automations diff-from-published`, `workbench diagnostics`,
+`workbench schema-suggestions`, and `workbench patch preview`, `readiness`,
+and `apply`. It is required by `automations branches get` and `merge`. Other
+commands reject `--branch-id` before making an API request, and
+`mgcl --help` lists the branch-aware commands. Branch-aware responses identify the selected
 target with `branchId` and `headVersionId`. Merge returns `branchId`, its exact
 preview and conflicts, plus the new main head as `applyResult.draftVersionId`
 when successful. Branch inspection excludes workspace authentication records

package/dist/index.js

@@ -7764,6 +7764,10 @@ function safeJsonParseWithoutLogging(json) {
   }
 }
 
+// ../common/dist/src/constants/automation.js
+var AUTOMATION_BRANCH_NAME_MAX_LENGTH = 100;
+var AUTOMATION_BRANCH_NAME_MAX_LENGTH_MESSAGE = `Branch name must be ${AUTOMATION_BRANCH_NAME_MAX_LENGTH} characters or fewer.`;
+
 // ../common/dist/src/constants/tool-declarations.js
 import { z as z15 } from "zod";
 
@@ -15336,6 +15340,7 @@ query DiffAgentVersion(
 query GetAgentRun($id: ID!) {
   agentRun(id: $id) {
     id
+    agentId
     agentVersionId
     agentName
     status
@@ -15396,12 +15401,14 @@ query GetAutomationAgents($ids: [ID!]!) {
     operationName: "GetAutomationDiffFromPublished",
     kind: "query",
     inputSchema: z27.object({
-      automationId: z27.string().min(1)
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      branchId: z27.uuid("--branch-id must be a UUID.").optional()
     }),
     cli: {
+      branchContext: "optional",
       name: "get-automation-diff-from-published",
       path: ["automations", "diff-from-published"],
-      description: "Fetch draft-vs-published automation JSON Patch.",
+      description: "Fetch draft-vs-published automation JSON Patch for main or one branch.",
       resultKey: "automationDiffFromPublished",
       options: [
         stringOption({
@@ -15413,9 +15420,10 @@ query GetAutomationAgents($ids: [ID!]!) {
       ]
     },
     mcp: { fileName: "automationDiffFromPublished.graphql" },
-    document: `# Query JSON Patch changes from published automation JSON to draft automation JSON
-query GetAutomationDiffFromPublished($automationId: ID!) {
-  automationDiffFromPublished(automationId: $automationId) {
+    document: `# Query JSON Patch changes from published automation JSON to draft automation JSON.
+# Pass branchId to diff a branch head against published instead of the main draft.
+query GetAutomationDiffFromPublished($automationId: ID!, $branchId: ID) {
+  automationDiffFromPublished(automationId: $automationId, branchId: $branchId) {
     automationId
     automationName
     mode
@@ -15559,12 +15567,15 @@ query GetAutomationRun($id: ID!) {
   automationRun(id: $id) {
     id
     automationId
+    automationVersionId
     parentAutomationRunId
     status
     statusDetail
     summary
     invocationType
     input
+    initialStore
+    currentStore
     additionalPrompt
     debugUrl
     createdAt
@@ -15599,6 +15610,7 @@ query GetAutomationRun($id: ID!) {
 query GetAutomationRunAgentRuns($automationRunId: ID!) {
   automationRunAgentRuns(automationRunId: $automationRunId) {
     id
+    agentId
     agentVersionId
     agentName
     status
@@ -15618,6 +15630,7 @@ query GetAutomationRunAgentRuns($automationRunId: ID!) {
       automationRunId: z27.string().min(1),
       agentRunId: z27.string().min(1).optional(),
       limit: z27.number().int().positive().optional(),
+      page: z27.number().int().nonnegative().optional(),
       reverse: z27.boolean().optional()
     }),
     cli: {
@@ -15642,6 +15655,11 @@ query GetAutomationRunAgentRuns($automationRunId: ID!) {
           flagName: "limit",
           description: "Maximum number of iterations to return."
         }),
+        numberOption({
+          inputKey: "page",
+          flagName: "page",
+          description: "Zero-based page number."
+        }),
         booleanOption({
           inputKey: "reverse",
           flagName: "reverse",
@@ -15655,18 +15673,21 @@ query GetAutomationRunIterations(
   $automationRunId: ID!
   $agentRunId: ID
   $limit: Int
+  $page: Int
   $reverse: Boolean
 ) {
   automationRunIterations(
     automationRunId: $automationRunId
     agentRunId: $agentRunId
     limit: $limit
+    page: $page
     reverse: $reverse
   ) {
     id
     sequence
     agentRunId
     metadata
+    store
     startedAt
     finishedAt
     totalDurationMs
@@ -15682,6 +15703,42 @@ query GetAutomationRunIterations(
       screenshotMimeType
     }
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetIterationScreenshot",
+    kind: "query",
+    inputSchema: z27.object({
+      iterationId: z27.string().min(1),
+      hasMarks: z27.boolean().default(false)
+    }),
+    cli: {
+      name: "get-iteration-screenshot",
+      path: ["automation-runs", "iteration-screenshot"],
+      description: "Fetch a fresh screenshot URL for an iteration.",
+      resultKey: "iterationScreenshot",
+      options: [
+        stringOption({
+          inputKey: "iterationId",
+          flagName: "iteration-id",
+          description: "Automation run iteration ID.",
+          required: true
+        }),
+        booleanOption({
+          inputKey: "hasMarks",
+          flagName: "with-marks",
+          description: "Fetch the marked screenshot instead of the base screenshot."
+        })
+      ]
+    },
+    mcp: { fileName: "iterationScreenshot.graphql" },
+    document: `# Fetch a fresh screenshot URL for an automation run iteration
+query GetIterationScreenshot($iterationId: ID!, $hasMarks: Boolean = false) {
+  iterationScreenshot(iterationId: $iterationId, hasMarks: $hasMarks) {
+    status
+    url
+    mimeType
+  }
 }`
   }),
   createOperationSpec({
@@ -15770,6 +15827,7 @@ query GetAutomationRuns(
   ) {
     id
     automationId
+    automationVersionId
     parentAutomationRunId
     status
     statusDetail
@@ -15818,6 +15876,7 @@ query GetAutomationRunsPage(
     items {
       id
       automationId
+      automationVersionId
       parentAutomationRunId
       status
       statusDetail
@@ -15975,7 +16034,7 @@ query ViewAutomationReview($automationId: ID!) {
     operationName: "ListAutomationBranches",
     kind: "query",
     inputSchema: z27.object({
-      automationId: z27.string().min(1)
+      automationId: z27.uuid("--automation-id must be a UUID.")
     }),
     cli: {
       name: "list-automation-branches",
@@ -16010,10 +16069,13 @@ query ListAutomationBranches($automationId: ID!) {
     operationName: "CreateAutomationBranch",
     kind: "mutation",
     inputSchema: z27.object({
-      automationId: z27.string().min(1),
-      name: z27.string().regex(AUTOMATION_BRANCH_NAME_PATTERN, AUTOMATION_BRANCH_NAME_MESSAGE),
-      sourceBranchId: z27.string().min(1).optional(),
-      sourceVersionId: z27.string().min(1).optional()
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      name: z27.string().regex(AUTOMATION_BRANCH_NAME_PATTERN, AUTOMATION_BRANCH_NAME_MESSAGE).max(
+        AUTOMATION_BRANCH_NAME_MAX_LENGTH,
+        AUTOMATION_BRANCH_NAME_MAX_LENGTH_MESSAGE
+      ),
+      sourceBranchId: z27.uuid("--source-branch-id must be a UUID.").optional(),
+      sourceVersionId: z27.uuid("--source-version-id must be a UUID.").optional()
     }),
     cli: {
       name: "create-automation-branch",
@@ -16074,8 +16136,8 @@ mutation CreateAutomationBranch(
     operationName: "GetAutomationBranch",
     kind: "query",
     inputSchema: z27.object({
-      automationId: z27.string().min(1),
-      branchId: z27.string().min(1)
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      branchId: z27.uuid("--branch-id must be a UUID.")
     }),
     cli: {
       branchContext: "required",
@@ -16106,14 +16168,14 @@ query GetAutomationBranch($automationId: ID!, $branchId: ID!) {
     operationName: "MergeAutomationBranch",
     kind: "mutation",
     inputSchema: z27.object({
-      automationId: z27.string().min(1),
-      branchId: z27.string().min(1)
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      branchId: z27.uuid("--branch-id must be a UUID.")
     }),
     cli: {
       branchContext: "required",
       name: "merge-automation-branch",
       path: ["automations", "branches", "merge"],
-      description: "Preview and merge a branch into main when every change is conflict-free.",
+      description: "Preview and merge a branch into main when every change is conflict-free. Exits nonzero when conflicts block the merge.",
       resultKey: "mergeAutomationBranch",
       options: [
         stringOption({
@@ -18586,7 +18648,7 @@ var pathwayRegressionAgentVersionRegressionRunResponseSchema = z28.object({
   automationVersionId: z28.string().min(1),
   baselineAgentVersionId: z28.string().min(1),
   baselineAutomationVersionId: z28.string().min(1),
-  baselineContractId: z28.string().min(1),
+  baselineContractId: z28.string().min(1).nullable(),
   candidateContractId: z28.string().min(1),
   contractId: z28.string().min(1),
   paths: z28.array(pathwayRegressionAgentVersionRunPathSchema),
@@ -19464,6 +19526,32 @@ function configureCommandPresentation(command) {
   command.createHelp = () => new MagicalHelp();
   return command;
 }
+function formatBranchAwareCommandsHelp() {
+  const branchAwareCommandLines = operationSpecs.flatMap((operationSpec) => {
+    const { branchContext } = operationSpec.cli;
+    if (branchContext === void 0) {
+      return [];
+    }
+    return [
+      `mgcl ${operationSpec.cli.path.join(" ")} (--branch-id ${branchContext})`
+    ];
+  }).toSorted();
+  return formatExamples("Branch-aware commands", branchAwareCommandLines);
+}
+function formatRootAfterHelpText() {
+  return `
+${formatExamples("Quick start", [
+    "mgcl auth login",
+    "mgcl org list",
+    "mgcl automations list --limit 10",
+    "mgcl automation-runs get --id <run-id>",
+    "mgcl update"
+  ])}
+
+${formatBranchAwareCommandsHelp()}
+
+${formatOutputModesNote()}`;
+}
 function createOperationHelpExamples(operationSpec) {
   const commandPath = operationSpec.cli.path.join(" ");
   const baseCommand = operationSpec.cli.branchContext === "required" ? `mgcl --branch-id <branch-id> ${commandPath}` : `mgcl ${commandPath}`;
@@ -21903,6 +21991,7 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     json: commandOptions.json,
     result
   });
+  assertBranchMergeApplied(operationSpec, result);
   if (operationSpec.operationName === "ViewAutomationReview" && commandOptions["open"] && isRecord5(result) && typeof result["reportUrl"] === "string") {
     await dependencies.openExternalUrl(result["reportUrl"]).catch((error) => {
       dependencies.io.error(
@@ -21911,6 +22000,13 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     });
   }
 }
+function assertBranchMergeApplied(operationSpec, result) {
+  if (operationSpec.operationName === "MergeAutomationBranch" && (!isRecord5(result) || result["status"] !== "merged")) {
+    throw new CliError(
+      "Merge not applied. Review the merge output, resolve any conflicts, then merge again."
+    );
+  }
+}
 function getOperation(operationName) {
   const operationSpec = operationSpecs.find(
     (candidate) => candidate.operationName === operationName
@@ -22898,26 +22994,14 @@ function buildProgram(dependencies) {
   ).addOption(new Option3("--json", "Render JSON output.")).addOption(
     new Option3(
       "--branch-id <id>",
-      "Target a supported automation command at one branch; omit it to target main."
+      'Target a supported automation command at one branch; omit it to target main. "Branch-aware commands" below lists the commands that accept it.'
     )
   ).version(CLI_VERSION, "--version", `Display mgcl version (${CLI_VERSION}).`).addOption(
     new Option3(
       "--update",
       "Update mgcl to the latest published npm release."
     )
-  ).showHelpAfterError().showSuggestionAfterError().addHelpText(
-    "after",
-    `
-${formatExamples("Quick start", [
-      "mgcl auth login",
-      "mgcl org list",
-      "mgcl automations list --limit 10",
-      "mgcl automation-runs get --id <run-id>",
-      "mgcl update"
-    ])}
-
-${formatOutputModesNote()}`
-  );
+  ).showHelpAfterError().showSuggestionAfterError().addHelpText("after", formatRootAfterHelpText());
   program2.hook("preAction", (_thisCommand, actionCommand) => {
     const options = actionCommand.optsWithGlobals();
     const branchContext = commandBranchContexts.get(actionCommand);