fix(cli): derive list flags from the input declarations, refuse the artifact channel, drop the snapshot placeholders

Which inputs are lists is now one declaration: InputDecl gains `list`, parseConfig reads such inputs only through its list() port (a name without the attribute cannot be split), and the CLI lets exactly those flags repeat. A complete Record over every input runs one repeated-argv case per name, so a new list input cannot be missed.

The snapshot and init subcommands are gone until the snapshot mode exists; no build could run them. `--private-report artifact` is refused before parsing (the upload needs the Actions runner) and report-public-key is not a flag. The no-token and not-a-slug problems name --token, --repository, and the environment variables; the --repository help says the flag is required outside Actions.

Tests assert whole outcomes: exact option sets and descriptions per subcommand, the fold's own shape in the merged file, the whole --json object with exit code and stderr, and where an unnamed summary goes. The package smoke gains a failing control (validate on an invalid file exits 1). The redacting stream honors the target's backpressure, with a guard test seen failing on the old code; the bin's empty declaration file is removed after the build; docs and AGENTS.md trimmed to what the code cannot show.

Author: settings-as-code-release

.github/scripts/package-smoke.ts

@@ -12,7 +12,7 @@
  * directory is removed on every path, failure included.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -43,12 +43,26 @@ export const ok: boolean = result.isOk() && first === "repository";
 /** The settings file the installed CLI validates: one section, valid as written. */
 const SETTINGS_FILE = "labels:\n  - name: bug\n    color: d73a4a\n";
 
+/** The control: a label without its name, which the validator refuses. */
+const INVALID_SETTINGS_FILE = "labels:\n  - color: d73a4a\n";
+
 /** Run a command to completion in `cwd`, streaming its output; a non-zero exit throws. */
 function run(command: string, args: string[], cwd: string): void {
   console.log(`$ ${[command, ...args].join(" ")}`);
   execFileSync(command, args, { cwd, stdio: "inherit" });
 }
 
+/** Run a command expected to fail; any other exit code, zero included, throws. */
+function expectExit(code: number, command: string, args: string[], cwd: string): void {
+  console.log(`$ ${[command, ...args].join(" ")}  # expecting exit ${code}`);
+  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  if (result.status !== code) {
+    throw new Error(
+      `${[command, ...args].join(" ")} exited ${result.status ?? "by signal"}, expected ${code}`,
+    );
+  }
+}
+
 /** Run a command and return its stdout. */
 function capture(command: string, args: string[], cwd: string): string {
   console.log(`$ ${[command, ...args].join(" ")}`);
@@ -130,6 +144,9 @@ async function main(): Promise<void> {
     }
     writeFileSync(join(consumerDir, "settings.yml"), SETTINGS_FILE);
     run("node", [bin, "validate", "settings.yml"], consumerDir);
+    // The failing control: a bin that swallowed its exit code would pass the line above.
+    writeFileSync(join(consumerDir, "invalid.yml"), INVALID_SETTINGS_FILE);
+    expectExit(1, "node", [bin, "validate", "invalid.yml"], consumerDir);
     writeFileSync(join(consumerDir, "main.ts"), TS_CONSUMER);
     run(
       join(REPO_ROOT, "node_modules", ".bin", "tsc"),

AGENTS.md

@@ -36,8 +36,7 @@ GitHub Settings as Code: GitHub Action applying declarative repository settings:
 
 - `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on a packaged child of the release commit, which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
 - `lib/pkg/` is the npm library build: `bun run build:lib` (tsdown, configured in `tsdown.config.ts`) bundles `src/index.ts` into one ESM `index.js` plus one `index.d.ts` with the runtime dependencies external; like `lib/index.js` it is built, never committed. `package.json` publishes it as `@vivswan/github-settings-as-code` through its `exports` map (`.` to the build, `./settings.schema.json` to the committed schema, `./package.json` to itself; `files` ships only those plus LICENSE.md and README.md), and `test/package-json.test.ts` pins the manifest's field set and holds its `version` equal to `.release-please-manifest.json` (release-please's json extra-file rewrites it). The package-smoke job in `checks.yml` (`bun .github/scripts/package-smoke.ts`) builds the library, runs publint and attw, installs the packed tarball into a fresh consumer, and imports it under Node and under tsc with skipLibCheck off, so a declaration that leaks a devDependency type or a type the emitter cannot name fails there; a type a section module exposes must therefore be exported from its home module. The library reference is docs/reference/library.md.
-- `src/cli.ts` and `src/cli/` are the command line, a second CONSUMER of the public entry with the action's one edge, `../index.js`:
-  a capability the CLI needs is exported from `src/index.ts` first, and `test/cli/inputs.test.ts` pins its argv-to-config equal to the action's env-to-config. Guide: docs/start/cli.md.
+- `src/cli/` is the command line, a consumer of the public entry like the action: a capability it needs is exported from `src/index.ts` first, never imported across. Guide: docs/start/cli.md.
 - The import layering of `src/` is declared in `architecture.yml` and enforced by `bun run lint:arch`, so a new cross-layer import is a deliberate edit to that file; the module map in `docs/reference/architecture.md` is generated from it.
 - The apply/check engine layout: `src/main.ts` is the thin bundled entrypoint; `src/index.ts` is the public entry (declaration-only re-exports, pinned by test/library/public-surface.test.ts); `src/action/` is the GitHub Actions layer and a CONSUMER of that entry: its only import outside itself is `../index.js`, the one edge `architecture.yml` grants it; `src/flows/` holds the run flows the action and a library caller share (single, multi, merge, delivery, redaction); `src/io.ts` is the import-free Io output port; `src/types.ts` holds the leaf type vocabulary; `src/engine/` is the per-repo pipeline (orchestrate, validate, merge, diff, secret references); `src/github/` is the REST client, pagination, and repo-file fetch; `src/discovery/` resolves multi-repo targets; `src/report/` composes and delivers the private report. Under `src/sections/`, each settings section is one self-contained DIRECTORY `src/sections/<key>/`: `index.ts` (the `SectionModule` - key, PAT grant advice, the loose shape derived from the slice, handler), `schema.ts` (the zod slice), `mock.ts` (the e2e mock fragment), `generators.ts` (the fuzz fragment; the secret and variable factory families share theirs in `test/e2e/generators.ts` instead), `<key>.test.ts` (absent where a shared factory's suite under `test/sections/` covers the section), and `scenarios/`. Beside the section directories sit `contract/` (the layered section contract: permissions/endpoints/graphql/module/errors/requests/live), `shared/` (the cross-section engines and factories, plus the schema helpers), and `registry.ts` (the single registration point). All GitHub API list calls must go through `listAll()` (bare-array endpoints) or `listAllEnveloped()` (endpoints that wrap the list in a `{total_count, <key>: []}` envelope), both backed by the single page loop in `src/github/paginate.ts`; errors through `call()`/`throwFor()` so the permission policy (`on-missing-permission`, `required-sections`) works.
 - Adding a section: create `src/sections/<key>/` with the six pieces above plus its `<key>.docs.yml` (the Sections table cells for docs/reference/sections.md, the COVERAGE.md prose, and the schema descriptions the generators render; the docs loader fails without it), compose the `SettingsFile` property from the slice and add the key to `SECTION_KEYS` in `src/schema.ts`, and add one line in `src/sections/registry.ts` - the compiler flags each forgotten step (the registry's mapped type, the mock fragment registration, the slice composition pin, and the generator aggregation are all keyed by SectionKey).

docs/start/cli.md

@@ -5,8 +5,8 @@ order: 40
 # Command line
 
 The engine behind the action is also a command in the npm package `@vivswan/github-settings-as-code`: `github-settings-as-code`, or `gsac` for short.
-It runs the same checks, applies, and merges the action runs, from a terminal or any CI, plus three file-only commands the action has no step for:
-validate a settings file, print the PAT grant it needs, and (in a build that carries the snapshot mode) write a repository's live settings as a file.
+It runs the same checks, applies, and merges the action runs, from a terminal or any CI, plus two file-only commands the action has no step for:
+validate a settings file, and print the PAT grant it needs.
 
 ## Install
 
@@ -35,10 +35,6 @@ The package needs Node 22.14 or newer; `bunx` fetches it the same way and honors
 | `merge` | Fold an ordered list of settings files into one document | no |
 | `validate <file>` | Validate a settings file against the schema | no |
 | `permissions <file>` | Print the PAT grant each section the file declares needs | no |
-| `snapshot` | Write the live repository settings as a settings file | yes |
-| `init` | Snapshot into `.github/settings.yml` and print the PAT grant that file needs | yes |
-
-`snapshot` and `init` need a build of the package whose library carries `mode: snapshot`; a build without it exits 1 naming the missing mode.
 
 ### check
 
@@ -58,7 +54,8 @@ The defaults are the action's, redaction included: a private repository's lines
 gsac apply --repository octo-org/api --settings-file .github/settings.yml --on-missing-permission warn
 ```
 
-Every flag of the action's `apply` and `check` inputs is a flag here, spelled the same way; `--repos`, `--repos-dir`, and `--defaults-file` switch to [multi-repo mode](../operate/multi-repo.md), and the discovery filters follow.
+Every flag of the action's `apply` and `check` inputs is a flag here, spelled the same way, with two exceptions below. `--repos` or `--repos-dir` switches to [multi-repo mode](../operate/multi-repo.md); `--defaults-file` and the discovery filters apply there, as in the action.
+Outside GitHub Actions there is no `GITHUB_REPOSITORY`, so single-repo runs need `--repository`.
 
 ### merge
 
@@ -90,6 +87,8 @@ The subcommand is the action's `mode` input. Every other input of that mode is a
 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; repeating any other value flag, `--token` and `--summary` included, is an error naming it.
 
+Two inputs have no command-line form: `--private-report artifact` is refused (the artifact upload needs the Actions runner; `issue`, `issue-on-failure`, and `none` work), and `report-public-key`, which only that channel reads, is not a flag.
+
 Four flags are the command line's own:
 
 | Flag | Does |
@@ -117,5 +116,5 @@ With `--json` the outputs are one object instead, and stdout carries nothing els
 
 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.
 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.
+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

@@ -12,6 +12,7 @@ import {
   failRun,
   type GithubClient,
   type Io,
+  type Problem,
   type RunConfig,
   readSettingsFile,
   runMerge,
@@ -117,12 +118,31 @@ export function permissionsFor(file: string, io: Io, bold: (text: string) => str
   );
 }
 
-/** A command whose mode this build's library does not carry: one error line, exit 1. */
-export function unavailable(command: string, io: Io): number {
-  io.annotate(
-    "error",
-    `${command} needs mode: snapshot, which this build of github-settings-as-code does not include. ` +
-      "Upgrade to a release whose inputs reference lists snapshot among the modes",
-  );
+/**
+ * The action's wording for a problem, except where the remedy names the
+ * workflow step: from a terminal the fix is a flag or an environment variable.
+ */
+export function describeCliProblem(problem: Problem): string {
+  switch (problem.code) {
+    case "input-token-missing":
+      return "cannot call the GitHub API: no token was provided. Pass --token, or export GITHUB_TOKEN";
+    case "input-repository-not-slug":
+      return `cannot target a repository: "${problem.value}" is not an owner/name slug. Pass --repository owner/name (inside GitHub Actions, GITHUB_REPOSITORY supplies it)`;
+    default:
+      return describeProblem(problem);
+  }
+}
+
+/** The one report channel a terminal cannot serve: the artifact upload needs the Actions runner. */
+export const ARTIFACT_UNSUPPORTED =
+  '"--private-report artifact" uploads through the Actions artifact service, which the command line has no access to. ' +
+  'Use "--private-report issue" or "issue-on-failure" (a report on each private target repository), or "none"';
+
+/** End a run on a problem the library has no code for, exactly as failRun ends one. */
+export function failCli(io: Io, message: string): number {
+  io.annotate("error", message);
+  io.output("skipped-sections", "");
+  io.output("result", "failed");
+  io.log("result: failed");
   return 1;
 }

src/cli/inputs.ts

@@ -10,6 +10,7 @@
 import { InvalidArgumentError, Option } from "commander";
 import {
   INPUT_DECLS,
+  type InputDecl,
   type InputName,
   type InputReader,
   MERGE_INPUTS,
@@ -23,16 +24,23 @@ const INPUT_NAMES = Object.keys(INPUT_DECLS) as InputName[];
 /** The two inputs that are not subcommand flags: the mode is the subcommand, the token is global. */
 const PROGRAM_INPUTS = ["mode", "token"] as const satisfies readonly InputName[];
 
+/**
+ * Inputs no subcommand exposes: the artifact report channel needs the Actions
+ * artifact service, which a terminal has no upload for, so its key has no use.
+ */
+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.
  */
 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) =>
-      !(PROGRAM_INPUTS as readonly InputName[]).includes(name) &&
+      !hidden.includes(name) &&
       (mode === "merge" ? mergeReads(name) : !mergeReads(name) || name === "settings-file"),
   );
 }
@@ -43,20 +51,29 @@ export function exposedInputs(): InputName[] {
   return INPUT_NAMES.filter((name) => flags.has(name));
 }
 
-/**
- * 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[];
+/** The sentence the action's `repository` description spends on a default a terminal never has. */
+const ACTIONS_DEFAULT_SENTENCE = "Defaults to the current repository.";
+const CLI_REPOSITORY_SENTENCE =
+  "Required unless repos or repos-dir is set (inside GitHub Actions, GITHUB_REPOSITORY supplies it).";
+if (!INPUT_DECLS.repository.description.includes(ACTIONS_DEFAULT_SENTENCE)) {
+  throw new Error(
+    `BUG: the repository input's description no longer says "${ACTIONS_DEFAULT_SENTENCE}"; reword the CLI's replacement with it`,
+  );
+}
+
+/** The flag's help text: the declaration's, reworded where it assumes the Actions runner. */
+export function inputDescription(name: InputName): string {
+  const description = INPUT_DECLS[name].description;
+  return name === "repository"
+    ? description.replace(ACTIONS_DEFAULT_SENTENCE, CLI_REPOSITORY_SENTENCE)
+    : description;
+}
+
+/** Whether the declaration is a list; read through InputDecl since only the list members carry the field. */
+export function isList(name: InputName): boolean {
+  const decl: InputDecl = INPUT_DECLS[name];
+  return decl.list === true;
+}
 
 /** A repeated list flag accumulates as a newline-separated list, the form parseConfig splits. */
 function accumulate(value: string, previous?: string): string {
@@ -73,10 +90,10 @@ export function once(flag: string): (value: string, previous?: string) => string
   };
 }
 
-/** The commander option for one input: `--<name> <value>` with the action's description. */
+/** The commander option for one input: `--<name> <value>`, repeatable when the declaration is a list. */
 export function inputOption(name: InputName): Option {
-  const parse = (LIST_INPUTS as readonly InputName[]).includes(name) ? accumulate : once(name);
-  return new Option(`--${name} <value>`, INPUT_DECLS[name].description).argParser(parse);
+  const parse = isList(name) ? accumulate : once(name);
+  return new Option(`--${name} <value>`, inputDescription(name)).argParser(parse);
 }
 
 /** Commander's attribute for each flag (camelCase of the name), read from commander itself. */

src/cli/io.ts

@@ -1,11 +1,6 @@
 /**
- * The CLI's output boundary and its Io. maskedStreams() wraps stdout and
- * stderr so every write, the parser's messages included, passes one mask
- * registry (no runner masks for a terminal); cliIo() is the Io the flows
- * write through over those streams: annotations and the debug trace on
- * stderr as `level: message`, log lines on stdout, the summary appended to a
- * file when one is named, and the outputs collected for flush() to print as
- * `name=value` lines or one JSON object.
+ * The CLI's output boundary and its Io. No runner masks for a terminal, so
+ * every writer, the parser included, goes through maskedStreams().
  */
 
 import { appendFileSync } from "node:fs";
@@ -47,8 +42,12 @@ class RedactingStream extends Writable {
   }
 
   override _write(chunk: unknown, _encoding: BufferEncoding, callback: () => void): void {
-    this.target.write(this.redact(String(chunk)));
-    callback();
+    // A full target holds the next chunk until it drains, so backpressure reaches the writer.
+    if (this.target.write(this.redact(String(chunk)))) {
+      callback();
+    } else {
+      this.target.once("drain", callback);
+    }
   }
 }