fix(snapshot): never write the staging file through a leftover link, and pin the mode subcommands

A stale symlink at <path>.tmp (out/s.yml.tmp -> s.yml) was written through and then installed as the destination, so the run printed "snapshot written" while the destination became a self-pointing link and both the old and the new content were gone. The staging path is unlinked before the write (a directory there still fails loudly) and created exclusively, and a test runs the link case. The Windows note on the helper now says what Node's rename is there, a single replace call, rather than claiming atomicity.

Beside it: the staging tests assert the full outputs record and lines array like the rest of the file; the CLI's mode subcommands gain the lockstep type that fails when a Mode has no subcommand; the snapshot fleet-input set in the CLI test spreads FILTER_INPUTS instead of hand-listing them; and the README's snapshot pointer moves from step 3's check-mode bullet to step 2's settings-file line, where starting from a snapshot belongs.

Author: Vivswan

README.md

@@ -6,7 +6,7 @@ Apply declarative repository settings from `.github/settings.yml`: a loud, state
 
 1. Create a [fine-grained PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) from the [pre-filled token form][pat-form] and save it as the `ADMIN_TOKEN` repository secret. The form starts with every repository permission the action can need (an organization owner adds Members: read by hand); the default `GITHUB_TOKEN` can never hold them.
 
-2. Add `.github/settings.yml`. The first line gives editor autocomplete and hover docs:
+2. Add `.github/settings.yml` (or start from a [snapshot](docs/operate/snapshot.md) of the live settings). The first line gives editor autocomplete and hover docs:
 
    ```yaml
    # yaml-language-server: $schema=https://raw.githubusercontent.com/Vivswan/github-settings-as-code/v2/lib/settings.schema.json # x-release-please-major
@@ -23,7 +23,7 @@ Apply declarative repository settings from `.github/settings.yml`: a loud, state
 3. Add the workflow and run it from the Actions tab.
    - Keep `mode: check` for the first run: the drift report lists everything an apply would change or delete, and nothing is written.
    - Read the report. An apply deletes undeclared labels, autolinks, collaborators, Actions variables, and Copilot agents variables.
-   - Drop the `mode: check` line once the report says what you expect. The [getting started guide](docs/start/getting-started.md) explains the drift output; [Snapshot mode](docs/operate/snapshot.md) writes an existing repository's live settings as the file to start from.
+   - Drop the `mode: check` line once the report says what you expect. The [getting started guide](docs/start/getting-started.md) explains the drift output.
 
    ```yaml
    # .github/workflows/settings.yml

src/cli/program.ts

@@ -13,6 +13,7 @@ import {
   INPUT_DECLS,
   type Io,
   type Mode,
+  type MustBeNever,
   parseConfig,
   type RunConfig,
 } from "../index.js";
@@ -58,6 +59,9 @@ const MODE_COMMANDS = {
   snapshot: "snapshot",
 } as const satisfies Partial<Record<CliCommand, Mode>>;
 
+/** Compile-time lockstep: a Mode without a subcommand fails here. */
+type _UnlistedMode = MustBeNever<Exclude<Mode, (typeof MODE_COMMANDS)[keyof typeof MODE_COMMANDS]>>;
+
 interface Globals {
   readonly token?: string;
   readonly json?: boolean;

src/flows/snapshot.ts

@@ -256,14 +256,15 @@ async function snapshotTarget(ctx: {
  * Write `text` to `path` through a sibling staging file renamed into place, so
  * a write that fails partway (disk full, an interrupted run) leaves the
  * previous snapshot at `path` intact instead of a truncated one; the rename is
- * atomic for a regular file on POSIX and Windows alike. The staging file is
- * removed when the write fails.
+ * atomic on POSIX and a single replace call on Windows. A leftover staging
+ * file or link is unlinked first, never written through.
  */
 function writeReplacing(path: string, text: string): void {
   mkdirSync(dirname(path), { recursive: true });
   const staging = `${path}.tmp`;
   try {
-    writeFileSync(staging, text);
+    rmSync(staging, { force: true });
+    writeFileSync(staging, text, { flag: "wx" });
     renameSync(staging, path);
   } catch (error) {
     // The write's error is the one reported: a directory at the staging path fails both the write and this rm.

test/cli/inputs.test.ts

@@ -23,6 +23,7 @@ import { buildProgram, CLI_COMMANDS, main } from "../../src/cli/program.js";
 import {
   type ConfigEnv,
   describeProblem,
+  FILTER_INPUTS,
   INPUT_DECLS,
   type InputDecl,
   type InputName,
@@ -424,12 +425,7 @@ const SNAPSHOT_FLEET_INPUTS = new Set<InputName>([
   "snapshot-dir",
   "repos",
   "repos-dir",
-  "visibility",
-  "archived",
-  "forks",
-  "exclude",
-  "topics",
-  "affiliation",
+  ...FILTER_INPUTS,
 ]);
 
 /** The inputs a flag needs beside it under `mode`, on top of that mode's base. */

test/flows/snapshot.test.ts

@@ -8,7 +8,16 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { parse as parseYaml } from "yaml";
@@ -244,7 +253,7 @@ function disjointRefusal(snapshotDir: string, reposDir: string): string {
 describe("runSnapshot writes through a staging file", () => {
   const unwritable = (path: string, input: "snapshot-file" | "snapshot-dir", os: string) => ({
     level: "error" as const,
-    line: `cannot write the snapshot to ${path}: Error: ${os}. Check that the "${input}" input names a writable path`,
+    line: `cannot write the snapshot to ${path}: ${os}. Check that the "${input}" input names a writable path`,
   });
 
   test("a staging write that fails leaves the previous snapshot intact and reports the write's error", async () => {
@@ -253,25 +262,45 @@ describe("runSnapshot writes through a staging file", () => {
     const staging = `${cfg.snapshotFile}.tmp`;
     mkdirSync(dirname(cfg.snapshotFile), { recursive: true });
     writeFileSync(cfg.snapshotFile, "labels: []\n");
-    // A directory at the staging path fails the write before the rename; the run must not remove it either.
+    // A directory at the staging path fails the run before the rename; the run must not remove it either.
     mkdirSync(staging);
     const collected = collectingIo();
     expect(await run(api, cfg, collected.io)).toBe(1);
-    expect(collected.outputs.result).toBe("failed");
-    expect(collected.lines[0]).toEqual(
+    expect(collected.outputs).toEqual({ "skipped-sections": "", result: "failed" });
+    expect(collected.lines).toEqual([
       unwritable(
         cfg.snapshotFile,
         "snapshot-file",
-        `EISDIR: illegal operation on a directory, open '${staging}'`,
+        `SystemError [ERR_FS_EISDIR]: Path is a directory: rm returned EISDIR (is a directory) ${staging}`,
       ),
-    );
+      { line: "result: failed" },
+    ]);
     expect(readFileSync(cfg.snapshotFile, "utf8")).toBe("labels: []\n");
     rmSync(staging, { recursive: true });
     expect(await run(api, cfg, collectingIo().io)).toBe(0);
     expect(parseYaml(readFileSync(cfg.snapshotFile, "utf8"))).toEqual(doc(BUG));
     expect(existsSync(staging)).toBe(false);
   });
 
+  test("a leftover link at the staging path is unlinked, never written through: the destination becomes a regular file", async () => {
+    const api = new MockApi(labelsRoute("o/r", [BUG]));
+    const cfg = fileCfg();
+    const staging = `${cfg.snapshotFile}.tmp`;
+    mkdirSync(dirname(cfg.snapshotFile), { recursive: true });
+    writeFileSync(cfg.snapshotFile, "labels: []\n");
+    symlinkSync("snapshot.yml", staging);
+    const collected = collectingIo();
+    expect(await run(api, cfg, collected.io)).toBe(0);
+    expect(collected.outputs).toEqual({ "skipped-sections": "", result: "snapshot" });
+    expect(collected.lines).toEqual([
+      { line: `snapshot written to ${cfg.snapshotFile}` },
+      { line: "result: snapshot" },
+    ]);
+    expect(lstatSync(cfg.snapshotFile).isSymbolicLink()).toBe(false);
+    expect(parseYaml(readFileSync(cfg.snapshotFile, "utf8"))).toEqual(doc(BUG));
+    expect(existsSync(staging)).toBe(false);
+  });
+
   test("a rename that fails removes the staging file, fails only that target, and leaves the destination as it was", async () => {
     const api = new MockApi({
       "GET /repos/o/a": { data: { private: false } },
@@ -298,9 +327,13 @@ describe("runSnapshot writes through a staging file", () => {
     const { level, line } = unwritable(
       fileA,
       "snapshot-dir",
-      `EISDIR: illegal operation on a directory, rename '${fileA}.tmp' -> '${fileA}'`,
+      `Error: EISDIR: illegal operation on a directory, rename '${fileA}.tmp' -> '${fileA}'`,
     );
-    expect(collected.lines[0]).toEqual({ level, line: `o/a: ${line}` });
+    expect(collected.lines).toEqual([
+      { level, line: `o/a: ${line}` },
+      { line: `o/b: snapshot written to ${fileB}` },
+      { line: "result: failed" },
+    ]);
     expect(existsSync(`${fileA}.tmp`)).toBe(false);
     expect(readFileSync(join(fileA, "keep"), "utf8")).toBe("authored\n");
     expect(parseYaml(readFileSync(fileB, "utf8"))).toEqual(doc(DOCS));