feat(cli): add usage diff for spec compatibility checking

cli/assets/fig.ts

@@ -161,6 +161,45 @@ const completionSpec: Fig.Spec = {
         isVariadic: true,
       },
     },
+    {
+      name: "diff",
+      description:
+        "Compare two usage specs and report what changed about the interface",
+      options: [
+        {
+          name: ["-f", "--format"],
+          description: "Output format",
+          isRepeatable: false,
+          args: {
+            name: "format",
+            suggestions: ["text", "json"],
+          },
+        },
+        {
+          name: ["-b", "--breaking"],
+          description: "Report only breaking changes",
+          isRepeatable: false,
+        },
+        {
+          name: "--exit-zero",
+          description: "Exit 0 even when there are breaking changes",
+          isRepeatable: false,
+        },
+      ],
+      args: [
+        {
+          name: "old",
+          description:
+            'The spec as it was, typically the released one, use "-" to read from stdin',
+          template: "filepaths",
+        },
+        {
+          name: "new",
+          description: 'The spec as it is now, use "-" to read from stdin',
+          template: "filepaths",
+        },
+      ],
+    },
     {
       name: ["exec", "x"],
       description:

cli/assets/usage.1

@@ -26,6 +26,9 @@ Generate shell completion candidates for a partial command line
 \fIAliases: \fRcw
 .RE
 .TP
+\fBdiff\fR
+Compare two usage specs and report what changed about the interface
+.TP
 \fBexec\fR
 Execute a script, parsing args and exposing them as environment variables
 .RS
@@ -155,6 +158,46 @@ Current word index
 .TP
 \fB<WORDS>\fR
 User's input from the command line
+.SH "USAGE DIFF"
+Compare two usage specs and report what changed about the interface
+
+Findings are grouped into breaking changes (a command line that used to work
+now fails, binds differently, or resolves to a different value), compatible
+changes (the interface gained something or relaxed a rule), and metadata
+changes (help text, effect, deprecation — nothing about parsing).
+
+Exits 1 when there is a breaking change, so a release job can gate on it, and
+either spec may be "\-":
+
+  mycli \-\-usage\-spec | usage diff released.usage.kdl \-
+
+`version` is ignored on purpose: a release bumps it, and a check that fires
+every release does not get left switched on.
+.PP
+\fBUsage:\fR usage diff [OPTIONS] <OLD> <NEW>
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-f, \-\-format\fR \fI<FORMAT>\fR
+Output format
+.RS
+\fIDefault: \fRtext
+.RE
+.TP
+\fB\-b, \-\-breaking\fR
+Report only breaking changes
+.TP
+\fB\-\-exit\-zero\fR
+Exit 0 even when there are breaking changes
+\fBArguments:\fR
+.PP
+.TP
+\fB<OLD>\fR
+The spec as it was, typically the released one, use "\-" to read from stdin
+.TP
+\fB<NEW>\fR
+The spec as it is now, use "\-" to read from stdin
 .SH "USAGE EXEC"
 Execute a script, parsing args and exposing them as environment variables
 .PP