@getmagical/cli 0.3.1 → 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";
 
@@ -15396,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({
@@ -15413,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
@@ -15975,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",
@@ -16010,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",
@@ -16074,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",
@@ -16106,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({
@@ -18586,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),
@@ -19464,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}`;
@@ -21903,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(
@@ -21911,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
@@ -22898,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);