fix(snapshot): follow main's CLI with a snapshot subcommand over the shared parser

Main's CLI (#152) is total over the parsed modes: its dispatcher and per-mode flag split are typed over RunConfig and MODES, so the snapshot arm needs a home. The dispatcher concludes a snapshot config the way the action does, inputsForMode derives each mode's flags from the exported per-mode input lists (MERGE_ONLY_INPUTS and SNAPSHOT_ONLY_INPUTS now exported), and the program gains the snapshot subcommand with its guide row.

Author: Vivswan

docs/start/cli.md

@@ -33,6 +33,7 @@ The package needs Node 22.14 or newer; `bunx` fetches it the same way and honors
 | `check` | Report drift between a settings file and the live repository; exits 1 on any drift | yes |
 | `apply` | Apply a settings file to the repository | yes |
 | `merge` | Fold an ordered list of settings files into one document | no |
+| `snapshot` | Write a repository's live settings as a settings file, or one file per multi-repo target | yes |
 | `validate <file>` | Validate a settings file against the schema | no |
 | `permissions <file>` | Print the PAT grant each section the file declares needs | no |
 
@@ -65,6 +66,15 @@ gsac merge --settings-file fleet.yml --settings-file team.yml --merged-file merg
 
 A repeated `--settings-file` builds the layer list, lowest first; a comma-separated value does the same. The merged file is exactly what `apply` would run ([layering](../operate/layering.md)).
 
+### snapshot
+
+```bash
+gsac snapshot --token "$ADMIN_TOKEN" --repository octocat/hello-world --snapshot-file settings.snapshot.yml
+gsac snapshot --token "$FLEET_TOKEN" --repos "*" --snapshot-dir snapshots
+```
+
+Exactly one of `--snapshot-file` (one repository) and `--snapshot-dir` (one `<owner>/<name>.yml` per target) is required; the fleet flags are the multi-repo ones. The written file is what `check` reads clean against the repository it came from ([snapshot mode](../operate/snapshot.md)).
+
 ### validate
 
 ```bash
@@ -114,7 +124,7 @@ With `--json` the outputs are one object instead, and stdout carries nothing els
 {"skipped-sections":"","result":"clean"}
 ```
 
-The exit codes are the action's: `check` exits 1 on drift or failure, `apply` and `merge` exit 1 on failure only, `validate` exits 1 on an invalid file, `permissions` exits 0 for a valid file.
+The exit codes are the action's: `check` exits 1 on drift or failure, `apply`, `merge`, and `snapshot` exit 1 on failure only, `validate` exits 1 on an invalid file, `permissions` exits 0 for a valid file.
 A flag the mode does not read is unknown to that subcommand and exits 1 with the parser's message, where the action rejects the same input by name;
 a value the mode refuses (a filter without `--repos "*"`, a `--repository` that is not a slug) fails with the action's own message, reworded where the action's remedy names the workflow step.
 The token passed on the command line is masked as `***` wherever a line would echo it.

src/cli/commands.ts

@@ -8,6 +8,7 @@
 import {
   concludeMerge,
   concludeRun,
+  concludeSnapshot,
   describeProblem,
   failRun,
   type GithubClient,
@@ -20,6 +21,7 @@ import {
   runMerge,
   runMulti,
   runSingle,
+  runSnapshot,
   SECTIONS,
   type SectionModule,
   sectionGrant,
@@ -49,6 +51,12 @@ export async function runConfig(cfg: RunConfig, io: Io, host: CliHost): Promise<
     );
   }
   const api = host.createClient(cfg.token, io, cfg.apiVersion);
+  if (cfg.kind === "snapshot") {
+    return runSnapshot(api, cfg, io).match(
+      (finished) => concludeSnapshot(io, finished),
+      (problem) => failRun(io, problem),
+    );
+  }
   if (cfg.kind === "multi") {
     return runMulti(api, cfg, io).match(
       (targets) => concludeRun(io, { kind: "multi", mode: cfg.mode, targets }),

src/cli/inputs.ts

@@ -14,8 +14,11 @@ import {
   type InputName,
   type InputReader,
   MERGE_INPUTS,
+  MERGE_ONLY_INPUTS,
   MODES,
   type Mode,
+  SNAPSHOT_INPUTS,
+  SNAPSHOT_ONLY_INPUTS,
 } from "../index.js";
 
 /** Declaration order is the help order, as on the inputs reference page. */
@@ -30,19 +33,22 @@ const PROGRAM_INPUTS = ["mode", "token"] as const satisfies readonly InputName[]
  */
 export const CLI_UNSUPPORTED_INPUTS = ["report-public-key"] as const satisfies readonly InputName[];
 
-/**
- * The flags a mode's subcommand takes: the inputs its mode reads. `settings-file`
- * is the one input both the merge and the engine modes read.
- */
+/** The flags a mode's subcommand takes: the inputs its mode reads, in declaration order. */
 export function inputsForMode(mode: Mode): InputName[] {
-  const mergeReads = (name: InputName): boolean =>
-    (MERGE_INPUTS as readonly InputName[]).includes(name);
   const hidden: readonly InputName[] = [...PROGRAM_INPUTS, ...CLI_UNSUPPORTED_INPUTS];
-  return INPUT_NAMES.filter(
-    (name) =>
-      !hidden.includes(name) &&
-      (mode === "merge" ? mergeReads(name) : !mergeReads(name) || name === "settings-file"),
-  );
+  const modeOnly: readonly InputName[] = [...MERGE_ONLY_INPUTS, ...SNAPSHOT_ONLY_INPUTS];
+  const reads = (name: InputName): boolean => {
+    switch (mode) {
+      case "merge":
+        return (MERGE_INPUTS as readonly InputName[]).includes(name);
+      case "snapshot":
+        return (SNAPSHOT_INPUTS as readonly InputName[]).includes(name);
+      case "apply":
+      case "check":
+        return !modeOnly.includes(name);
+    }
+  };
+  return INPUT_NAMES.filter((name) => !hidden.includes(name) && reads(name));
 }
 
 /** Every input some subcommand or the program exposes; the mode is the subcommand itself. */

src/cli/program.ts

@@ -1,5 +1,5 @@
 /**
- * The command tree: check, apply, and merge mirror the action's modes with
+ * The command tree: check, apply, merge, and snapshot mirror the action's modes with
  * INPUT_DECLS as their flags; validate and permissions read a file alone.
  * `--token`, `--json`, `--summary`, and `--verbose` are global. main() runs
  * argv to its exit code without touching the process.
@@ -29,22 +29,34 @@ import { argvReader, inputOption, inputsForMode, once, tokenValues } from "./inp
 import { type CliStreams, cliIo, type MaskedStreams, maskedStreams } from "./io.js";
 
 /** Every subcommand, in help order; the package smoke asserts the installed help names each. */
-export const CLI_COMMANDS = ["check", "apply", "merge", "validate", "permissions"] as const;
+export const CLI_COMMANDS = [
+  "check",
+  "apply",
+  "merge",
+  "snapshot",
+  "validate",
+  "permissions",
+] as const;
 
 type CliCommand = (typeof CLI_COMMANDS)[number];
 
 const DESCRIPTION: Readonly<Record<CliCommand, string>> = {
   check: "Report drift between a settings file and the live repository; exits 1 on any drift",
   apply: "Apply a settings file to the repository",
   merge: "Fold an ordered list of settings files into one document, with no token and no API call",
+  snapshot:
+    "Write a repository's live settings as a settings file, or one file per multi-repo target under a directory",
   validate: "Validate a settings file against the schema; no token, no API call",
   permissions: "Print the PAT grant each section a settings file declares needs",
 };
 
 /** The subcommands that run the engine or the merge, each under its mode. */
-const MODE_COMMANDS = { check: "check", apply: "apply", merge: "merge" } as const satisfies Partial<
-  Record<CliCommand, Mode>
->;
+const MODE_COMMANDS = {
+  check: "check",
+  apply: "apply",
+  merge: "merge",
+  snapshot: "snapshot",
+} as const satisfies Partial<Record<CliCommand, Mode>>;
 
 interface Globals {
   readonly token?: string;

src/flows/inputs.ts

@@ -405,8 +405,11 @@ type _UnlistedLayering = MustBeNever<Exclude<Layering, (typeof LAYERINGS)[number
  * Their declared defaults are empty so "explicitly set" is detectable, as with the discovery filters; apply and check
  * reject a set one instead of silently ignoring it.
  */
-const MERGE_ONLY_INPUTS = ["merged-file", "layering"] as const satisfies readonly InputName[];
-const SNAPSHOT_ONLY_INPUTS = [
+export const MERGE_ONLY_INPUTS = [
+  "merged-file",
+  "layering",
+] as const satisfies readonly InputName[];
+export const SNAPSHOT_ONLY_INPUTS = [
   "snapshot-file",
   "snapshot-dir",
 ] as const satisfies readonly InputName[];

src/index.ts

@@ -69,12 +69,14 @@ export {
   type InputName,
   type InputReader,
   MERGE_INPUTS,
+  MERGE_ONLY_INPUTS,
   MERGE_REJECTED_INPUTS,
   MODES,
   type Mode,
   parseConfig,
   type RunConfig,
   SNAPSHOT_INPUTS,
+  SNAPSHOT_ONLY_INPUTS,
   SNAPSHOT_REJECTED_INPUTS,
 } from "./flows/inputs.js";
 export { foldLayers, readLayerFiles } from "./flows/layers.js";

test/cli/inputs.test.ts

@@ -70,6 +70,71 @@ function cases(): Case[] {
       inputs: { mode: "check", repository: "o/r", "settings-file": "s.yml" },
       env: { GITHUB_TOKEN: "ghp_env" },
     },
+    {
+      name: "snapshot, one repository to a file with an allowlist",
+      argv: [
+        "snapshot",
+        "--token",
+        "ghp_flag",
+        "--repository",
+        "o/r",
+        "--snapshot-file",
+        "snap.yml",
+        "--sections",
+        "labels",
+        "--on-missing-permission",
+        "warn",
+      ],
+      inputs: {
+        mode: "snapshot",
+        token: "ghp_flag",
+        repository: "o/r",
+        "snapshot-file": "snap.yml",
+        sections: "labels",
+        "on-missing-permission": "warn",
+      },
+    },
+    {
+      name: "snapshot, the fleet to a directory with a discovery filter",
+      argv: [
+        "snapshot",
+        "--token",
+        "ghp_flag",
+        "--repos",
+        "*",
+        "--snapshot-dir",
+        "snaps",
+        "--forks",
+        "exclude",
+      ],
+      inputs: {
+        mode: "snapshot",
+        token: "ghp_flag",
+        repos: "*",
+        "snapshot-dir": "snaps",
+        forks: "exclude",
+      },
+      env: { GITHUB_REPOSITORY: "o/admin" },
+    },
+    {
+      name: "snapshot, a merge-only flag is unknown to the subcommand",
+      argv: [
+        "snapshot",
+        "--token",
+        "ghp_flag",
+        "--snapshot-file",
+        "snap.yml",
+        "--layering",
+        "replace",
+      ],
+      inputs: {
+        mode: "snapshot",
+        token: "ghp_flag",
+        "snapshot-file": "snap.yml",
+        layering: "replace",
+      },
+      unknownFlag: "layering",
+    },
     {
       name: "check, the workflow's own repository from GITHUB_REPOSITORY",
       argv: ["check", "--token", "ghp_flag"],
@@ -294,7 +359,7 @@ describe("argv -> config equals env -> config", () => {
         envToken++;
       }
     }
-    expect([...kinds].sort()).toEqual(["merge", "multi", "single"]);
+    expect([...kinds].sort()).toEqual(["merge", "multi", "single", "snapshot"]);
     expect(envToken).toBeGreaterThan(0);
     expect(rejected).toBeGreaterThanOrEqual(5);
   });
@@ -305,6 +370,8 @@ const VALID: Record<Exclude<InputName, "mode" | "token">, string> = {
   repository: "o/r",
   "settings-file": "s.yml",
   "merged-file": "out.yml",
+  "snapshot-file": "snap.yml",
+  "snapshot-dir": "snaps",
   "on-missing-permission": "warn",
   "required-sections": "labels",
   sections: "labels",
@@ -338,7 +405,39 @@ const COMPANIONS: Partial<Record<InputName, Inputs>> = {
 
 /** The smallest input set each mode accepts. */
 function base(mode: Mode): Inputs {
-  return mode === "merge" ? { mode, "merged-file": "out.yml" } : { mode, token: "ghp" };
+  switch (mode) {
+    case "merge":
+      return { mode, "merged-file": "out.yml" };
+    case "snapshot":
+      return { mode, token: "ghp", "snapshot-file": "snap.yml" };
+    default:
+      return { mode, token: "ghp" };
+  }
+}
+
+/**
+ * The snapshot's fleet inputs need the directory form: they unset the base's
+ * snapshot-file (an empty value reads as unset) and name a snapshot-dir.
+ */
+const SNAPSHOT_FLEET: Inputs = { "snapshot-file": "", "snapshot-dir": "snaps", repos: "*" };
+const SNAPSHOT_FLEET_INPUTS = new Set<InputName>([
+  "snapshot-dir",
+  "repos",
+  "repos-dir",
+  "visibility",
+  "archived",
+  "forks",
+  "exclude",
+  "topics",
+  "affiliation",
+]);
+
+/** The inputs a flag needs beside it under `mode`, on top of that mode's base. */
+function companions(mode: Mode, name: InputName): Inputs {
+  if (mode === "snapshot" && SNAPSHOT_FLEET_INPUTS.has(name)) {
+    return name === "repos-dir" ? { ...SNAPSHOT_FLEET, repos: "" } : SNAPSHOT_FLEET;
+  }
+  return COMPANIONS[name] ?? {};
 }
 
 describe("the per-mode flag split", () => {
@@ -350,7 +449,7 @@ describe("the per-mode flag split", () => {
         const value = name === "report-public-key" ? recipient : VALID[name];
         if (exposed.has(name)) {
           const result = parseConfig(
-            recordReader({ ...base(mode), ...COMPANIONS[name], [name]: value }),
+            recordReader({ ...base(mode), ...companions(mode, name), [name]: value }),
             env,
           );
           expect(
@@ -366,7 +465,9 @@ describe("the per-mode flag split", () => {
               (problem) => problem.code,
             ),
             `${mode} --${name}`,
-          ).toMatch(/^input-(merge-only|rejected-in-merge|report-key-unused)$/);
+          ).toMatch(
+            /^input-(merge-only|snapshot-only|rejected-in-merge|rejected-in-snapshot|report-key-unused)$/,
+          );
         }
       }
     }
@@ -397,6 +498,8 @@ describe("the per-mode flag split", () => {
     },
     mode: "single",
     "merged-file": "single",
+    "snapshot-file": "single",
+    "snapshot-dir": "single",
     "on-missing-permission": "single",
     "required-sections": {
       argv: check,
@@ -458,8 +561,14 @@ describe("the per-mode flag split", () => {
         if (!exposed.has(name)) {
           continue; // the mode is the subcommand; an unsupported input has no flag
         }
-        // The base argv minus this flag, so the two repeats below are its only occurrences.
-        const base = inputsForMode("check").includes(name) || name === "token" ? check : ["merge"];
+        // The base argv of the first subcommand exposing the flag, minus this flag, so the two
+        // repeats below are its only occurrences.
+        const base =
+          inputsForMode("check").includes(name) || name === "token"
+            ? check
+            : inputsForMode("merge").includes(name)
+              ? ["merge"]
+              : ["snapshot", "--token", "ghp"];
         const flag = base.filter((argument, index) => {
           const value = index > 0 && base[index - 1] === `--${name}`;
           return argument !== `--${name}` && !value;