fix(cli): name the program, refuse repeated single-value flags, tighten the README cap

The help usage line names github-settings-as-code (gsac in the description) instead of commander's default "cli". A repeated flag now accumulates only for the inputs parseConfig splits (LIST_INPUTS, pinned against the library's own reading of each pair); every other value flag, --token and --summary included, rejects a second value with commander's message naming the flag, so no argv can form a joined value the action never receives. The README line budget is 101, one over the file.

Author: settings-as-code-release

docs/start/cli.md

@@ -88,7 +88,7 @@ One line per declared section: the grant its declaration names, the same words a
 
 The subcommand is the action's `mode` input. Every other input of that mode is a flag named `--<input>`, taking the value the action's `with:` key takes;
 the [inputs reference](../reference/inputs.md) lists each one with its default and meaning, and `gsac <command> --help` prints the same descriptions.
-A list input (`--settings-file` under merge, `--repos`, `--exclude`, `--topics`, `--affiliation`, `--sections`, `--required-sections`) takes a comma-separated value or the flag repeated.
+A list input (`--settings-file` under merge, `--repos`, `--exclude`, `--topics`, `--affiliation`, `--sections`, `--required-sections`) takes a comma-separated value or the flag repeated; repeating any other value flag, `--token` and `--summary` included, is an error naming it.
 
 Four flags are the command line's own:
 

src/cli/inputs.ts

@@ -7,7 +7,7 @@
  * here does.
  */
 
-import { Option } from "commander";
+import { InvalidArgumentError, Option } from "commander";
 import {
   INPUT_DECLS,
   type InputName,
@@ -43,14 +43,40 @@ export function exposedInputs(): InputName[] {
   return INPUT_NAMES.filter((name) => flags.has(name));
 }
 
-/** A repeated flag accumulates as a newline-separated list, the form parseConfig splits. */
+/**
+ * The inputs parseConfig splits on newlines and commas (its splitList calls),
+ * so a repeated flag may accumulate into one list. Pinned to parseConfig in
+ * test/cli/inputs.test.ts: every name here accepts a newline-joined pair.
+ */
+export const LIST_INPUTS = [
+  "settings-file",
+  "required-sections",
+  "sections",
+  "repos",
+  "exclude",
+  "topics",
+  "affiliation",
+] as const satisfies readonly InputName[];
+
+/** A repeated list flag accumulates as a newline-separated list, the form parseConfig splits. */
 function accumulate(value: string, previous?: string): string {
   return previous === undefined ? value : `${previous}\n${value}`;
 }
 
+/** A repeated single-value flag is refused: joined, it would form a value the action cannot receive. */
+export function once(flag: string): (value: string, previous?: string) => string {
+  return (value, previous) => {
+    if (previous !== undefined) {
+      throw new InvalidArgumentError(`--${flag} takes one value and was given more than once`);
+    }
+    return value;
+  };
+}
+
 /** The commander option for one input: `--<name> <value>` with the action's description. */
 export function inputOption(name: InputName): Option {
-  return new Option(`--${name} <value>`, INPUT_DECLS[name].description).argParser(accumulate);
+  const parse = (LIST_INPUTS as readonly InputName[]).includes(name) ? accumulate : once(name);
+  return new Option(`--${name} <value>`, INPUT_DECLS[name].description).argParser(parse);
 }
 
 /** Commander's attribute for each flag (camelCase of the name), read from commander itself. */

src/cli/program.ts

@@ -6,7 +6,7 @@
  * argv to its exit code without touching the process.
  */
 
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option } from "commander";
 import pc from "picocolors";
 import {
   failRun,
@@ -25,7 +25,7 @@ import {
   unavailable,
   validateFile,
 } from "./commands.js";
-import { argvReader, inputOption, inputsForMode, tokenValues } from "./inputs.js";
+import { argvReader, inputOption, inputsForMode, once, tokenValues } from "./inputs.js";
 import { type CliStreams, cliIo, type MaskedStreams, maskedStreams } from "./io.js";
 
 /** Every subcommand, in help order; the package smoke asserts the installed help names each. */
@@ -101,10 +101,22 @@ export function buildProgram(options: ProgramOptions): {
   }
   let exitCode = 0;
   const program = new Command()
-    .description("Apply, check, merge, and validate declarative GitHub repository settings")
-    .option("--token <value>", `${INPUT_DECLS.token.description} Falls back to GITHUB_TOKEN.`)
+    .name("github-settings-as-code")
+    .description(
+      "Apply, check, merge, and validate declarative GitHub repository settings (also installed as gsac)",
+    )
+    .addOption(
+      new Option(
+        "--token <value>",
+        `${INPUT_DECLS.token.description} Falls back to GITHUB_TOKEN.`,
+      ).argParser(once("token")),
+    )
     .option("--json", "Print the outputs as one JSON object on stdout; log lines move to stderr")
-    .option("--summary <file>", "Append the run's markdown summary to this file")
+    .addOption(
+      new Option("--summary <file>", "Append the run's markdown summary to this file").argParser(
+        once("summary"),
+      ),
+    )
     .option("--verbose", "Show the debug trace on stderr")
     .exitOverride()
     .configureOutput({

test/cli/inputs.test.ts

@@ -10,7 +10,7 @@
 
 import { beforeAll, describe, expect, test } from "bun:test";
 import { generateX25519Identity, identityToRecipient } from "age-encryption";
-import { exposedInputs, inputsForMode } from "../../src/cli/inputs.js";
+import { exposedInputs, inputsForMode, LIST_INPUTS } from "../../src/cli/inputs.js";
 import { maskedStreams } from "../../src/cli/io.js";
 import { buildProgram, CLI_COMMANDS, main } from "../../src/cli/program.js";
 import {
@@ -21,6 +21,7 @@ import {
   MODES,
   type Mode,
   parseConfig,
+  parseReposInput,
   type RunConfig,
 } from "../../src/index.js";
 import { MockApi } from "../mock-api.js";
@@ -348,6 +349,66 @@ describe("the per-mode flag split", () => {
     }
   });
 
+  test("every LIST_INPUTS entry is one parseConfig splits: a newline-joined pair is accepted whole", () => {
+    // Two entries per list input, each valid alone; the pair must come out of the
+    // parse as those two values, which only the library's own splitting can prove
+    // (repos is split downstream by parseReposInput, so that is what reads it).
+    const engine: Inputs = { mode: "check", token: "ghp" };
+    const discovery: Inputs = { ...engine, repos: "*" };
+    const cases: Record<
+      (typeof LIST_INPUTS)[number],
+      [Inputs, [string, string], (cfg: RunConfig) => readonly string[]]
+    > = {
+      "settings-file": [
+        { mode: "merge", "merged-file": "out.yml" },
+        ["a.yml", "b.yml"],
+        (cfg) => (cfg.kind === "merge" ? cfg.settingsFiles : []),
+      ],
+      "required-sections": [
+        engine,
+        ["labels", "milestones"],
+        (cfg) => (cfg.kind === "merge" ? [] : [...cfg.sections.required]),
+      ],
+      sections: [
+        engine,
+        ["labels", "milestones"],
+        (cfg) => (cfg.kind === "merge" ? [] : [...cfg.sections.only]),
+      ],
+      repos: [
+        engine,
+        ["o/a", "o/b"],
+        (cfg) =>
+          cfg.kind === "multi"
+            ? parseReposInput(cfg.reposInput)
+                .map((r) => r.slugs)
+                .unwrapOr([])
+            : [],
+      ],
+      exclude: [
+        discovery,
+        ["x/*", "tmp-*"],
+        (cfg) => (cfg.kind === "multi" ? cfg.discoveryFilters.exclude : []),
+      ],
+      topics: [
+        discovery,
+        ["a", "b"],
+        (cfg) => (cfg.kind === "multi" ? cfg.discoveryFilters.topics : []),
+      ],
+      affiliation: [
+        discovery,
+        ["owner", "collaborator"],
+        (cfg) => (cfg.kind === "multi" ? cfg.discoveryFilters.affiliation : []),
+      ],
+    };
+    const env: ConfigEnv = { GITHUB_REPOSITORY: "o/self" };
+    for (const name of LIST_INPUTS) {
+      const [companions, pair, kept] = cases[name];
+      const result = parseConfig(recordReader({ ...companions, [name]: pair.join("\n") }), env);
+      expect(result.isOk(), `${name}: ${result.match(() => "", describeProblem)}`).toBe(true);
+      expect(result.map(kept).unwrapOr([]), name).toEqual(pair);
+    }
+  });
+
   test("every declared input is the mode, the global token, or a flag of some subcommand", () => {
     expect(new Set([...exposedInputs(), "mode"])).toEqual(new Set(Object.keys(INPUT_DECLS)));
   });

test/cli/program.test.ts

@@ -276,14 +276,49 @@ describe("the commands this build cannot run", () => {
 });
 
 describe("commander's own exits", () => {
-  test("--help exits 0 and names every subcommand", async () => {
+  test("--help exits 0, prints the bin name, and names every subcommand", async () => {
     const result = await cli(["--help"]);
     expect(result.code).toBe(0);
+    expect(result.stdout).toStartWith("Usage: github-settings-as-code [options] [command]");
+    expect(result.stdout).toContain("gsac");
     for (const command of CLI_COMMANDS) {
       expect(result.stdout).toContain(`  ${command}`);
     }
   });
 
+  test("a repeated single-value flag exits 1 naming the flag; a repeated list flag accumulates", async () => {
+    const repeated = await cli(
+      ["check", "--token", TOKEN, "--repository", "a/b", "--repository", "c/d"],
+      new MockApi({}),
+    );
+    expect(repeated.code).toBe(1);
+    expect(repeated.stderr).toBe(
+      "error: option '--repository <value>' argument 'c/d' is invalid. --repository takes one value and was given more than once\n",
+    );
+    // Both unknown names must be reported: a last-wins parser would name only the second.
+    const list = await cli([
+      "check",
+      "--token",
+      TOKEN,
+      "--repository",
+      "o/r",
+      "--sections",
+      "nope",
+      "--sections",
+      "also",
+    ]);
+    expect(list.code).toBe(1);
+    expect(list.stderr).toStartWith(
+      'error: unknown sections "nope", "also" in the "sections" input',
+    );
+    // Both token values were registered before the parse, so the echo is masked.
+    const token = await cli(["check", "--token", "first", "--token", "second"]);
+    expect(token.code).toBe(1);
+    expect(token.stderr).toBe(
+      "error: option '--token <value>' argument '***' is invalid. --token takes one value and was given more than once\n",
+    );
+  });
+
   test("an unknown flag exits 1 with commander's line on stderr", async () => {
     const result = await cli(["check", "--tokn", "x"]);
     expect(result.code).toBe(1);

test/docs/readme.test.ts

@@ -117,7 +117,7 @@ describe("README front door", () => {
   test("stays a front door in size", () => {
     // The budget is the tripwire against the reference tables growing back; the full
     // reference is docs/. The Library section's package and command pointers sit inside it.
-    expect(readme.split("\n").length).toBeLessThanOrEqual(105);
+    expect(readme.split("\n").length).toBeLessThanOrEqual(101);
   });
 });