fix(cli): restore unknown-option errors swallowed by positional args

Cliffy 1.2 parses an unrecognized `--flag` into the next free positional
slot instead of raising an unknown-option error. Since the dependency bump,
`deno deploy --prd` was silently treated as `deno deploy <root-path=--prd>`,
so a typo'd flag ran the deploy action (and reported an auth error) instead
of exiting 2 with a VALIDATION_ERROR envelope. Two CLI-contract tests have
been failing on main because of this.

Reject flag-like positionals in `actionHandler`, except for slots that
forward their value verbatim (a shell command, an env var value, a SQL
query), which are identified by their declared argument name.

Also gives the hidden `tunnel-login` command the one-line description every
other command has.

Author: crowlbot

config.ts

@@ -167,6 +167,42 @@ export interface ConfigContext {
   noCreate(): void;
 }
 
+/**
+ * Positional slots that legitimately receive flag-like values: they are
+ * forwarded verbatim (a shell command, an env var value, a SQL query) rather
+ * than interpreted by this CLI.
+ */
+const PASSTHROUGH_ARGUMENTS = new Set(["command", "value", "query"]);
+
+interface ArgumentDef {
+  name: string;
+  variadic?: boolean;
+}
+
+/**
+ * Cliffy >= 1.2 fills the next positional slot with an unrecognized `--flag`
+ * instead of raising an unknown-option error, so `deno deploy --prd` would
+ * silently deploy a directory literally named `--prd`. Restore the usage error
+ * for every slot that isn't a passthrough.
+ */
+function assertNoFlagLikeArgs(command: unknown, args: unknown[]): void {
+  const defs: ArgumentDef[] =
+    (command as { getArguments?(): ArgumentDef[] } | undefined)
+      ?.getArguments?.() ?? [];
+  const last = defs.at(-1);
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (typeof arg !== "string" || arg.length < 2 || !arg.startsWith("-")) {
+      continue;
+    }
+    // A trailing variadic slot absorbs every remaining argument.
+    const def = defs[i] ?? (last?.variadic ? last : undefined);
+    if (def && PASSTHROUGH_ARGUMENTS.has(def.name)) continue;
+    throw new ValidationError(`Unknown option "${arg}".`);
+  }
+}
+
 export function actionHandler<
   O extends GlobalContext,
   A extends unknown[] = unknown[],
@@ -181,6 +217,7 @@ export function actionHandler<
   rootPath?: (...args: A) => string | undefined,
 ): (options: O, ...args: A) => Promise<void> {
   return async function (this: unknown, context: O, ...args: A) {
+    assertNoFlagLikeArgs(this, args);
     try {
       const root = rootPath?.(...args) ?? Deno.cwd();
       // Discover the config file only (cheap). The deploy file manifest is a

deploy/mod.ts

@@ -107,6 +107,7 @@ const setupGCPCommand = new Command<GlobalContext>()
   }));
 
 const tunnelLoginCommand = new Command<GlobalContext>()
+  .description("Resolve org, app and token for `deno tunnel` (internal)")
   .option("--really-no-config", "really no config")
   .option("--out <file:string>", "out file")
   .hidden()

tests/cli_contract.test.ts

@@ -48,6 +48,31 @@ Deno.test("combined short flag -jy is detected as JSON mode for the error envelo
   assertEquals(envelope.error.code, "VALIDATION_ERROR");
 });
 
+Deno.test("an unknown flag is not swallowed by the root's [root-path] argument", async () => {
+  const res = await runCli(["--json", "--prd"]);
+  assertEquals(res.code, 2, `stderr: ${res.stderr}`);
+  const envelope = JSON.parse(res.stderr.trim().split("\n").pop()!);
+  assertEquals(envelope.error.code, "VALIDATION_ERROR");
+  assert(
+    envelope.error.message.includes("--prd"),
+    `message should name the flag: ${envelope.error.message}`,
+  );
+});
+
+Deno.test("flag-like positional values are still passed through", async () => {
+  // `env add FOO -bar` must reach the action (which then requires auth) rather
+  // than being rejected as an unknown option.
+  const res = await runCli(
+    ["env", "add", "FOO", "-bar", "--json", "--non-interactive"],
+    { DENO_DEPLOY_TOKEN: "" }, // never reach the backend, whatever the runner has
+  );
+  const envelope = JSON.parse(res.stderr.trim().split("\n").pop()!);
+  assert(
+    envelope.error.code !== "VALIDATION_ERROR",
+    `unexpected usage error: ${res.stderr}`,
+  );
+});
+
 Deno.test("--help exits 0", async () => {
   const res = await runCli(["--help"]);
   assertEquals(res.code, 0, `stderr: ${res.stderr}`);