@getmagical/cli 0.3.0 → 0.3.2

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";
 
@@ -14592,8 +14596,8 @@ var automationRunStartConfigSchema = automationRunConfigBaseSchema.omit({
 });
 
 // ../common/dist/src/utils/custom-instructions-command.util.js
-var MAX_CUSTOM_COMMAND_COUNT = 1;
-var MAX_CUSTOM_INSTRUCTIONS_LENGTH = 280;
+var MAX_CUSTOM_COMMAND_COUNT = 3;
+var MAX_CUSTOM_INSTRUCTIONS_LENGTH = 560;
 var STANDARD_COMMAND_NAMES = [
   "callSpecializedAgent",
   "checkpoint",
@@ -14633,22 +14637,20 @@ function assertCustomInstructionsCommand({ commands, path: path9 }) {
     return;
   }
   if (customCommands.length > MAX_CUSTOM_COMMAND_COUNT) {
-    throw createInvalidValueError(`${path9} contains ${customCommands.length.toString()} custom commands. Use at most one short custom command per agent. Split policy, decision, outreach, and multi-step work into catalog commands or child agents instead.`);
-  }
-  const [customCommand] = customCommands;
-  if (!customCommand) {
-    return;
-  }
-  const instructions = getCustomInstructions(customCommand.command);
-  if (instructions.length === 0) {
-    throw createInvalidValueError(`${customCommand.path}.arguments.instructions must be a non-empty string for custom commands.`);
+    throw createInvalidValueError(`${path9} contains ${customCommands.length.toString()} custom commands. Use at most ${MAX_CUSTOM_COMMAND_COUNT.toString()} short custom commands per agent. Split policy, decision, outreach, and multi-step work into catalog commands or child agents instead.`);
   }
-  if (instructions.length > MAX_CUSTOM_INSTRUCTIONS_LENGTH) {
-    throw createInvalidValueError(`${customCommand.path}.arguments.instructions is ${instructions.length.toString()} characters. Custom commands must be short single-action instructions (max ${MAX_CUSTOM_INSTRUCTIONS_LENGTH.toString()} chars). Move policy/template/context text into description, inputSchema, or child agents, and express executable work with catalog commands.`);
-  }
-  const mentionedCommand = getMentionedStandardCommand(instructions);
-  if (mentionedCommand !== null) {
-    throw createInvalidValueError(`${customCommand.path}.arguments.instructions mentions "${mentionedCommand}". Use the "${mentionedCommand}" catalog command directly instead of wrapping it in custom prose.`);
+  for (const customCommand of customCommands) {
+    const instructions = getCustomInstructions(customCommand.command);
+    if (instructions.length === 0) {
+      throw createInvalidValueError(`${customCommand.path}.arguments.instructions must be a non-empty string for custom commands.`);
+    }
+    if (instructions.length > MAX_CUSTOM_INSTRUCTIONS_LENGTH) {
+      throw createInvalidValueError(`${customCommand.path}.arguments.instructions is ${instructions.length.toString()} characters. Custom commands must be short single-action instructions (max ${MAX_CUSTOM_INSTRUCTIONS_LENGTH.toString()} chars). Move policy/template/context text into description, inputSchema, or child agents, and express executable work with catalog commands.`);
+    }
+    const mentionedCommand = getMentionedStandardCommand(instructions);
+    if (mentionedCommand !== null) {
+      throw createInvalidValueError(`${customCommand.path}.arguments.instructions mentions "${mentionedCommand}". Use the "${mentionedCommand}" catalog command directly instead of wrapping it in custom prose.`);
+    }
   }
 }
 
@@ -14997,6 +14999,60 @@ var agentLimitationsSelection = `      limitations {
         maxToolCalls
         allowedUrlRegexes
       }`;
+var automationRunsInputSchema = z27.object({
+  automationId: z27.string().min(1).optional(),
+  from: z27.string().min(1).optional(),
+  status: z27.array(z27.string().min(1)).optional(),
+  invocationType: z27.array(z27.string().min(1)).optional(),
+  limit: z27.number().int().positive().optional(),
+  orderBy: z27.enum(["createdAtAsc", "createdAtDesc", "random"]).optional(),
+  page: z27.number().int().nonnegative().optional(),
+  to: z27.string().min(1).optional()
+}).refine(({ orderBy, page }) => orderBy !== "random" || (page ?? 0) === 0, {
+  message: "Random ordering reshuffles on every call, so --page cannot be combined with --order-by random."
+});
+var automationRunsCliOptions = [
+  stringOption({
+    inputKey: "automationId",
+    flagName: "automation-id",
+    description: "Optional automation ID."
+  }),
+  stringOption({
+    inputKey: "from",
+    flagName: "from",
+    description: "Optional inclusive createdAt lower bound ISO timestamp."
+  }),
+  stringArrayOption({
+    inputKey: "status",
+    flagName: "status",
+    description: "Optional run statuses."
+  }),
+  stringArrayOption({
+    inputKey: "invocationType",
+    flagName: "invocation-type",
+    description: "Optional invocation types."
+  }),
+  numberOption({
+    inputKey: "limit",
+    flagName: "limit",
+    description: "Maximum number of runs to return."
+  }),
+  stringOption({
+    inputKey: "orderBy",
+    flagName: "order-by",
+    description: "Run ordering. Use random for sampling; it reshuffles on every call."
+  }),
+  numberOption({
+    inputKey: "page",
+    flagName: "page",
+    description: "Zero-based page number."
+  }),
+  stringOption({
+    inputKey: "to",
+    flagName: "to",
+    description: "Optional inclusive createdAt upper bound ISO timestamp."
+  })
+];
 var operationSpecs = [
   createOperationSpec({
     operationName: "GetCaptureContext",
@@ -15344,12 +15400,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({
@@ -15361,9 +15419,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
@@ -15686,57 +15745,13 @@ query InspectPausedAutomationStep($runId: ID!) {
   createOperationSpec({
     operationName: "GetAutomationRuns",
     kind: "query",
-    inputSchema: z27.object({
-      automationId: z27.string().min(1).optional(),
-      from: z27.string().min(1).optional(),
-      status: z27.array(z27.string().min(1)).optional(),
-      invocationType: z27.array(z27.string().min(1)).optional(),
-      limit: z27.number().int().positive().optional(),
-      page: z27.number().int().nonnegative().optional(),
-      to: z27.string().min(1).optional()
-    }),
+    inputSchema: automationRunsInputSchema,
     cli: {
       name: "get-automation-runs",
       path: ["automation-runs", "list"],
       description: "Fetch automation run history.",
       resultKey: "automationRuns",
-      options: [
-        stringOption({
-          inputKey: "automationId",
-          flagName: "automation-id",
-          description: "Optional automation ID."
-        }),
-        stringOption({
-          inputKey: "from",
-          flagName: "from",
-          description: "Optional inclusive createdAt lower bound ISO timestamp."
-        }),
-        stringArrayOption({
-          inputKey: "status",
-          flagName: "status",
-          description: "Optional run statuses."
-        }),
-        stringArrayOption({
-          inputKey: "invocationType",
-          flagName: "invocation-type",
-          description: "Optional invocation types."
-        }),
-        numberOption({
-          inputKey: "limit",
-          flagName: "limit",
-          description: "Maximum number of runs to return."
-        }),
-        numberOption({
-          inputKey: "page",
-          flagName: "page",
-          description: "Zero-based page number."
-        }),
-        stringOption({
-          inputKey: "to",
-          flagName: "to",
-          description: "Optional inclusive createdAt upper bound ISO timestamp."
-        })
-      ]
+      options: automationRunsCliOptions
     },
     mcp: { fileName: "automationRuns.graphql" },
     document: `# Query automation run history with optional automation and time-window filters
@@ -15746,6 +15761,7 @@ query GetAutomationRuns(
   $status: [RunStatus!]
   $invocationType: [InvocationType!]
   $limit: Int
+  $orderBy: AutomationRunOrderBy
   $page: Int
   $to: String
 ) {
@@ -15755,6 +15771,7 @@ query GetAutomationRuns(
     status: $status
     invocationType: $invocationType
     limit: $limit
+    orderBy: $orderBy
     page: $page
     to: $to
   ) {
@@ -15770,6 +15787,59 @@ query GetAutomationRuns(
     pausedAt
     finishedAt
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationRunsPage",
+    kind: "query",
+    inputSchema: automationRunsInputSchema,
+    cli: {
+      name: "get-automation-runs-page",
+      path: ["automation-runs", "list-page"],
+      description: "Fetch automation run history with bounded total metadata. When isTotalTruncated is true, total is a lower bound.",
+      resultKey: "automationRunsPage",
+      options: automationRunsCliOptions
+    },
+    mcp: { fileName: "automationRunsPage.graphql" },
+    document: `# Query automation run history with optional filters and a bounded total
+query GetAutomationRunsPage(
+  $automationId: ID
+  $from: String
+  $status: [RunStatus!]
+  $invocationType: [InvocationType!]
+  $limit: Int
+  $orderBy: AutomationRunOrderBy
+  $page: Int
+  $to: String
+) {
+  automationRunsPage(
+    automationId: $automationId
+    from: $from
+    status: $status
+    invocationType: $invocationType
+    limit: $limit
+    orderBy: $orderBy
+    page: $page
+    to: $to
+  ) {
+    items {
+      id
+      automationId
+      parentAutomationRunId
+      status
+      statusDetail
+      invocationType
+      summary
+      createdAt
+      startedAt
+      pausedAt
+      finishedAt
+    }
+    total
+    page
+    pageSize
+    isTotalTruncated
+  }
 }`
   }),
   createOperationSpec({
@@ -15912,7 +15982,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",
@@ -15947,10 +16017,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",
@@ -16011,8 +16084,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",
@@ -16043,14 +16116,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({
@@ -18523,7 +18596,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),
@@ -19401,6 +19474,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}`;
@@ -21840,6 +21939,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(
@@ -21848,6 +21948,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
@@ -22835,26 +22942,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);