@plannotator/pi-extension 0.26.0 → 0.26.1

package/generated/gitbutler-core.ts

@@ -43,6 +43,32 @@ const VERSION_TIMEOUT_MS = 5_000;
 const OBJECT_ID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
 const STATUS_CACHE_MS = 1_000;
 
+/**
+ * GitButler has shipped two spellings of the global JSON output flag:
+ * 0.21.x accepts only `--format json` (gitbutlerapp/gitbutler#14061) while
+ * 0.22.0+ accepts only `--json` (gitbutlerapp/gitbutler#15026), and each
+ * release rejects the other spelling as an unknown argument. The primary
+ * spelling matches GITBUTLER_MIN_VERSION; when a status call fails with
+ * clap's unexpected-argument rejection for the exact flag we passed, the
+ * other spelling is tried once. Any other failure propagates unchanged.
+ */
+interface GitButlerStatusSyntax {
+  args: readonly string[];
+  /** The flag clap names in its unexpected-argument rejection. */
+  flag: string;
+  label: string;
+}
+
+const GITBUTLER_STATUS_SYNTAXES: readonly [GitButlerStatusSyntax, GitButlerStatusSyntax] = [
+  { args: ["--format", "json", "status"], flag: "--format", label: "but --format json status" },
+  { args: ["--json", "status"], flag: "--json", label: "but --json status" },
+];
+
+/** Narrow sniff for clap rejecting exactly the JSON flag this syntax passed. */
+function isUnexpectedArgumentRejection(result: GitCommandResult, flag: string): boolean {
+  return result.exitCode !== 0 && result.stderr.includes(`unexpected argument '${flag}'`);
+}
+
 /** Runtime operations needed by the shared GitButler provider. */
 export interface ReviewGitButlerRuntime extends ReviewGitRuntime {
   runBut(args: string[], options?: GitCommandOptions): Promise<GitCommandResult>;
@@ -68,7 +94,7 @@ export interface GitButlerStack {
   branches: GitButlerBranch[];
 }
 
-/** Validated subset of `but --format json status`. */
+/** Validated subset of `but --format json status` (0.21.x) / `but --json status` (0.22.0+). */
 export interface GitButlerStatus {
   mergeBase: GitButlerCommit;
   stacks: GitButlerStack[];
@@ -154,12 +180,15 @@ function parseStack(value: unknown, path: string): GitButlerStack {
 }
 
 /** Parse and validate the status fields Plannotator relies on. Unknown fields are allowed. */
-export function parseGitButlerStatus(output: string): GitButlerStatus {
+export function parseGitButlerStatus(
+  output: string,
+  commandLabel = GITBUTLER_STATUS_SYNTAXES[0].label,
+): GitButlerStatus {
   let decoded: unknown;
   try {
     decoded = JSON.parse(output);
   } catch {
-    throw new GitButlerContractError("GitButler returned invalid JSON from `but --format json status`.");
+    throw new GitButlerContractError(`GitButler returned invalid JSON from \`${commandLabel}\`.`);
   }
 
   const root = requireRecord(decoded, "root");
@@ -203,6 +232,8 @@ function versionAtLeast(actual: ParsedVersion, minimum: ParsedVersion): boolean
 }
 
 const versionChecks = new WeakMap<ReviewGitButlerRuntime, Promise<void>>();
+/** Index into GITBUTLER_STATUS_SYNTAXES of the spelling this runtime's CLI last accepted. */
+const statusSyntaxPreferences = new WeakMap<ReviewGitButlerRuntime, 0 | 1>();
 const statusCaches = new WeakMap<
   ReviewGitButlerRuntime,
   Map<string, { expiresAt: number; inFlight: boolean; status: Promise<GitButlerStatus> }>
@@ -256,17 +287,42 @@ async function loadStatus(runtime: ReviewGitButlerRuntime, cwd: string): Promise
   if (existing && (existing.inFlight || existing.expiresAt > now)) return existing.status;
 
   const status = (async () => {
-    const result = await runtime.runBut(["--format", "json", "status"], {
+    const preferredIndex = statusSyntaxPreferences.get(runtime) ?? 0;
+    let syntaxIndex = preferredIndex;
+    let syntax = GITBUTLER_STATUS_SYNTAXES[syntaxIndex];
+    let result = await runtime.runBut([...syntax.args], {
       cwd,
       timeoutMs: STATUS_TIMEOUT_MS,
     });
+    if (isUnexpectedArgumentRejection(result, syntax.flag)) {
+      // This CLI does not know this spelling of the JSON flag; try the other
+      // spelling exactly once. Only clap's unexpected-argument rejection for
+      // the flag we passed triggers the retry — a real status failure must
+      // keep failing loudly below.
+      syntaxIndex = preferredIndex === 0 ? 1 : 0;
+      const fallback = GITBUTLER_STATUS_SYNTAXES[syntaxIndex];
+      const retried = await runtime.runBut([...fallback.args], {
+        cwd,
+        timeoutMs: STATUS_TIMEOUT_MS,
+      });
+      if (isUnexpectedArgumentRejection(retried, fallback.flag)) {
+        throw new GitButlerContractError(
+          `GitButler rejected both \`${syntax.label}\` and \`${fallback.label}\`; ` +
+          `Plannotator requires GitButler ${GITBUTLER_MIN_VERSION} or newer.`,
+        );
+      }
+      syntax = fallback;
+      result = retried;
+    }
     if (result.exitCode !== 0) {
       const detail = result.stderr.trim();
       throw new GitButlerContractError(
-        `GitButler status failed${detail ? `: ${detail}` : ` with exit code ${result.exitCode}`}`,
+        `GitButler status (\`${syntax.label}\`) failed${detail ? `: ${detail}` : ` with exit code ${result.exitCode}`}`,
       );
     }
-    return parseGitButlerStatus(result.stdout);
+    const parsed = parseGitButlerStatus(result.stdout, syntax.label);
+    statusSyntaxPreferences.set(runtime, syntaxIndex);
+    return parsed;
   })();
   const entry = { expiresAt: 0, inFlight: true, status };
   cache.set(cwd, entry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/pi-extension",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "type": "module",
   "description": "Plannotator Pi extension - interactive plan review with annotations, annotate agent messages, and review code/PRs",
   "author": "backnotprop",