second-read 0.1.0 → 0.1.1

package/README.md

@@ -36,7 +36,8 @@ It isn't a secrets scanner. Tools like gitleaks find keys and tokens, and second
 ## Where it runs
 
 - **git hooks:** commit messages, and the lines a push adds.
-- **A `gh` shim:** the title and body of `gh issue`, `gh pr` and comment commands, before the real `gh` sends them.
+- **A `gh` shim:** the text of issues, pull requests, comments, releases, gists, labels and repositories, and the
+  names they're given, before the real `gh` sends it.
 - **Agent adapters**, for posts that don't go through `git` or `gh`, such as a GitHub tool an agent calls directly.
   Claude Code comes first. Other agents follow, each written from its tool's own hook docs.
 - **A sweep** of what's already posted to a repository, edit histories included.
@@ -106,7 +107,7 @@ exempt_files = ["src/**/*.test.ts", "fixtures/"]
 repository: `*` and `?` stay within one folder, `**` takes in any number of them, and a trailing `/` takes in a
 whole folder. A glob made only of wildcards and dots, such as `**` or `**/*.*`, is an error, since it takes in nearly
 every file; one for dotfiles, such as `**/.*`, is fine. Commit and tag messages, branch and tag names, and everything
-the `gh` shim sends are still checked in full.
+the `gh` shim sends are still checked in full, a gist's files included: a gist is a post of its own.
 
 ## The guards
 
@@ -126,8 +127,11 @@ second-read shim install     # writes a gh shim, and says which folder to put ah
   `SECOND_READ_ALLOWLIST_REVIEWED="<id>"`. An id covers only that change, so a later one is refused again.
 - **The `gh` shim** checks `--title`, `--body`, `--body-file` and a body read from stdin, for `gh issue` and
   `gh pr` `create`, `edit` and `comment`, and `gh pr review`. It also checks the `--comment` that `close` and
-  `reopen` leave, and the `--subject` and body of `gh pr merge`'s merge commit. Then it runs the real `gh` with the
-  same arguments and input. Every other command, `gh api` included, passes straight through.
+  `reopen` leave, and the `--subject` and body of `gh pr merge`'s merge commit. It checks a release's title,
+  notes and tag, a gist's description and the files it uploads, stdin included, with the name each is uploaded
+  under, a label's name and description, and a repository's name and description, on `gh repo rename` too. A name
+  is checked as a branch name is, and only the new one, so a leaked name can be renamed away. Then it runs the real
+  `gh` with the same arguments and input. Every other command, `gh api` included, passes straight through.
 
 Each guard refuses on a finding, and also when the check itself fails. A hook that was already in place is set aside
 and still runs after the check; `second-read hooks uninstall` removes only second-read's hooks and puts it back. The
@@ -166,9 +170,8 @@ the call and gives Claude the report as the reason, so Claude can fix the text a
 
 It checks:
 
-- **Bash commands that post through `gh`:** the same `gh issue` and `gh pr` commands as the shim, behind `env`,
-  `sudo` and the like, and `gh api` calls
-  that send fields (`-f`, `-F`, including `@file`) or an `--input` body, unless they're `GET`. A GraphQL query
+- **Bash commands that post through `gh`:** the same `gh` commands as the shim, behind `env`, `sudo` and the like,
+  and `gh api` calls that send fields (`-f`, `-F`, including `@file`) or an `--input` body, unless they're `GET`. A GraphQL query
   is checked when it's a mutation.
 - **`git commit` and `git tag` messages**, from `-m`, `-F` and `--trailer`. What a push sends is the `pre-push`
   hook's to check.

package/dist/claude.js

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { KIND_NAMES } from "./checks.js";
-import { parseGh, postTexts } from "./gh.js";
+import { parseGh, postNames, postTexts, shortFlag } from "./gh.js";
 import { output, parseShell, UNKNOWN, UNKNOWN_END, unknown } from "./shell.js";
 // The texts each command in a Bash tool call would post, read against the folder each one runs in.
 export function bashPosts(command, cwd, home) {
@@ -148,8 +148,12 @@ function ghPosts(args, stdin, dir, written) {
     const post = parseGh(args);
     if (!post)
         return [];
-    return postTexts(post, reader(stdin, dir, written)).map(([where, text]) => ({ where, kind: post.kind, text, cwd: dir }));
+    return [
+        ...postNames(post).map(([where, text]) => ({ where, kind: post.kind, text, cwd: dir, name: true })),
+        ...postTexts(post, reader(stdin, dir, written)).map(([where, text]) => ({ where, kind: post.kind, text, cwd: dir })),
+    ];
 }
+// gh api's flags that take a value, as gh 2.92 has them. The rest are switches, -i among them.
 const GH_API_VALUE_FLAGS = new Set(["-X", "--method", "-f", "--raw-field", "-F", "--field", "-H", "--header", "-q",
     "--jq", "-t", "--template", "-p", "--preview", "--hostname", "--cache", "--input"]);
 // gh api sends its fields, or the --input file, and switches to POST when it has either. A GraphQL query that
@@ -170,9 +174,10 @@ function ghApiPosts(args, read, dir) {
                 value = arg.slice(eq + 1);
         }
         else if (arg.startsWith("-") && arg.length > 1) {
-            name = arg.slice(0, 2);
-            if (arg.length > 2)
-                value = arg.slice(arg[2] === "=" ? 3 : 2);
+            const flag = shortFlag(arg, (f) => GH_API_VALUE_FLAGS.has(f));
+            if (flag === undefined)
+                continue;
+            ({ name, value } = flag);
         }
         else {
             endpoint ??= arg;

package/dist/cli.js

@@ -46,6 +46,7 @@ process.exitCode = await main({
     identity: systemIdentity,
     command: [process.execPath, fileURLToPath(import.meta.url)],
     readStdin,
+    stdinIsTTY: process.stdin.isTTY === true,
     out: (text) => process.stdout.write(text),
     err: (text) => process.stderr.write(text),
 });

package/dist/gh.js

@@ -1,5 +1,5 @@
 import { accessSync, closeSync, constants, openSync, readSync, realpathSync, statSync } from "node:fs";
-import { delimiter, join, resolve } from "node:path";
+import { basename, delimiter, join, resolve } from "node:path";
 import { KIND_NAMES } from "./checks.js";
 import { shQuote } from "./git.js";
 export const SHIM_MARKER = "# Added by second-read: the gh shim.";
@@ -22,26 +22,166 @@ const MERGE_FLAGS = {
     "--body-file": "bodyFile",
     "-F": "bodyFile",
 };
-const text = (kind) => ({ kind, flags: TEXT_FLAGS });
-const comment = { kind: "comment", flags: COMMENT_FLAGS };
+const RELEASE_FLAGS = {
+    "--title": "title",
+    "-t": "title",
+    "--notes": "body",
+    "-n": "body",
+    "--notes-file": "bodyFile",
+    "-F": "bodyFile",
+};
+const DESCRIPTION_FLAGS = { "--description": "body", "-d": "body" };
+const text = (kind, valued = []) => ({ kind, flags: TEXT_FLAGS, valued });
+const comment = (valued = []) => ({ kind: "comment", flags: COMMENT_FLAGS, valued });
+const ISSUE_CREATE = ["--assignee", "-a", "--label", "-l", "--milestone", "-m", "--project", "-p", "--recover",
+    "--template", "-T"];
+const ISSUE_EDIT = ["--add-assignee", "--add-label", "--add-project", "--milestone", "-m", "--remove-assignee",
+    "--remove-label", "--remove-project"];
+const PR_CREATE = [...ISSUE_CREATE, "--base", "-B", "--head", "-H", "--reviewer", "-r"];
+const PR_EDIT = [...ISSUE_EDIT, "--add-reviewer", "--base", "-B", "--remove-reviewer"];
+// A post's kind only picks how it's checked, and these check like a comment; each has its own noun.
+const release = (posting) => ({
+    kind: "comment",
+    flags: RELEASE_FLAGS,
+    valued: ["--discussion-category", "--target"],
+    noun: "this release",
+    bodyName: "notes",
+    nameName: "tag",
+    ...posting,
+});
+// gh release create [<tag>] [<asset>...]
+const releaseCreate = release({
+    valued: ["--discussion-category", "--notes-start-tag", "--target"],
+    args: (post, [tag]) => {
+        if (tag !== undefined)
+            post.names.push(tag);
+    },
+});
+// A repository's name, from gh repo create [<name>] or gh repo rename [<new name>].
+const repository = (posting) => ({
+    kind: "comment",
+    flags: DESCRIPTION_FLAGS,
+    valued: [],
+    noun: "this repository",
+    bodyName: "description",
+    ...posting,
+});
+const repoName = (post, [name]) => {
+    if (name !== undefined)
+        post.names.push(name);
+};
+const repoCreate = repository({
+    valued: ["--gitignore", "-g", "--homepage", "-h", "--license", "-l", "--remote", "-r", "--source", "-s", "--team",
+        "-t", "--template", "-p"],
+    args: repoName,
+});
+// A gist's files are a new post of their own, not lines added to the repository's files, so exempt_files never
+// applies to them.
+const gist = (posting) => ({
+    kind: "comment",
+    flags: { "--desc": "body", "-d": "body" },
+    valued: [],
+    noun: "this gist",
+    bodyName: "description",
+    fileName: "contents",
+    nameName: "file name",
+    ...posting,
+});
+// Each argument is a file to upload, "-" being stdin. With none, it uploads stdin when it's piped in. A file is
+// uploaded under its own name, and stdin under the name --filename gives.
+const gistCreate = gist({
+    flags: { "--desc": "body", "-d": "body", "--filename": "name", "-f": "name" },
+    args: (post, files) => {
+        const named = post.names.at(-1);
+        post.names = [];
+        if (files.length === 0) {
+            files = ["-"];
+            post.stdinIfPiped = true;
+        }
+        post.bodyFiles.push(...files);
+        for (const file of files) {
+            if (file !== "-")
+                post.names.push(basename(file));
+            else if (named !== undefined)
+                post.names.push(named);
+        }
+    },
+});
+const label = (posting) => ({
+    kind: "comment",
+    flags: DESCRIPTION_FLAGS,
+    valued: ["--color", "-c"],
+    noun: "this label",
+    titleName: "name",
+    bodyName: "description",
+    ...posting,
+});
 const POSTS = {
     issue: {
-        create: text("issue"),
-        new: text("issue"),
-        edit: text("issue"),
+        create: text("issue", ISSUE_CREATE),
+        new: text("issue", ISSUE_CREATE),
+        edit: text("issue", ISSUE_EDIT),
         comment: text("comment"),
-        close: comment,
-        reopen: comment,
+        close: comment(["--duplicate-of", "--reason", "-r"]),
+        reopen: comment(),
     },
     pr: {
-        create: text("pr"),
-        new: text("pr"),
-        edit: text("pr"),
+        create: text("pr", PR_CREATE),
+        new: text("pr", PR_CREATE),
+        edit: text("pr", PR_EDIT),
         comment: text("comment"),
         review: text("review"),
-        close: comment,
-        reopen: comment,
-        merge: { kind: "commit", flags: MERGE_FLAGS, noun: "this merge commit", titleName: "subject" },
+        close: comment(),
+        reopen: comment(),
+        merge: {
+            kind: "commit",
+            flags: MERGE_FLAGS,
+            valued: ["--author-email", "-A", "--match-head-commit"],
+            noun: "this merge commit",
+            titleName: "subject",
+        },
+    },
+    release: {
+        create: releaseCreate,
+        new: releaseCreate,
+        // The tag it's given now is checked, not the one it had, so a release's tag can be renamed.
+        edit: release({ flags: { ...RELEASE_FLAGS, "--tag": "name" } }),
+    },
+    gist: {
+        create: gistCreate,
+        new: gistCreate,
+        // gh gist edit <gist> [<file>]: the file replaces the one --filename picks, or is uploaded under the name --add
+        // gives. Without it, --add uploads the file it names.
+        edit: gist({
+            flags: { "--desc": "body", "-d": "body", "--add": "bodyFile", "-a": "bodyFile" },
+            valued: ["--filename", "-f", "--remove", "-r"],
+            args: (post, [, file]) => {
+                const added = post.bodyFiles.at(-1);
+                if (added !== undefined)
+                    post.names.push(basename(added));
+                if (file !== undefined)
+                    post.bodyFiles = [file];
+            },
+        }),
+    },
+    label: {
+        create: label({
+            args: (post, [name]) => {
+                if (name !== undefined)
+                    post.title.push(name);
+            },
+        }),
+        // The name it's given now is checked, not the one it had, so a label can be renamed.
+        edit: label({ flags: { ...DESCRIPTION_FLAGS, "--name": "title", "-n": "title" } }),
+    },
+    repo: {
+        create: repoCreate,
+        new: repoCreate,
+        edit: repository({
+            valued: ["--add-topic", "--default-branch", "--homepage", "-h", "--remove-topic",
+                "--squash-merge-commit-message", "--visibility"],
+        }),
+        rename: repository({ flags: {}, args: repoName }),
     },
 };
 // The text a posting gh command sends, or undefined for any other command, which passes straight through.
@@ -64,17 +204,22 @@ export function parseGh(args) {
         kind: posting.kind,
         noun: posting.noun ?? KIND_NAMES[posting.kind],
         titleName: posting.titleName ?? "title",
+        bodyName: posting.bodyName ?? "body",
+        fileName: posting.fileName ?? posting.bodyName ?? "body",
+        nameName: posting.nameName ?? "name",
         title: [],
         body: [],
         bodyFiles: [],
+        names: [],
     };
+    const takesValue = (flag) => flag in posting.flags || posting.valued.includes(flag) || flag === "-R" || flag === "--repo";
+    // The arguments, the command words first.
+    const positional = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (arg === "--")
+        if (arg === "--") {
+            positional.push(...args.slice(i + 1));
             break;
-        if (arg === "-R" || arg === "--repo") {
-            i++;
-            continue;
         }
         let name;
         let value;
@@ -85,40 +230,66 @@ export function parseGh(args) {
                 value = arg.slice(eq + 1);
         }
         else if (arg.startsWith("-") && arg.length > 1) {
-            // A short flag takes its value from the next argument, or joined: "-tTitle" or "-t=Title".
-            name = arg.slice(0, 2);
-            if (arg.length > 2)
-                value = arg.slice(arg[2] === "=" ? 3 : 2);
+            const flag = shortFlag(arg, takesValue);
+            if (flag === undefined)
+                continue;
+            ({ name, value } = flag);
         }
         else {
+            positional.push(arg);
             continue;
         }
         const field = posting.flags[name];
-        if (field === undefined)
+        if (field === undefined) {
+            if (value === undefined && takesValue(name))
+                i++;
             continue;
+        }
         if (value === undefined)
             value = args[++i];
         if (value === undefined)
             continue;
         if (field === "bodyFile")
             post.bodyFiles.push(value);
+        else if (field === "name")
+            post.names.push(value);
         else
             post[field].push(value);
     }
+    posting.args?.(post, positional.slice(2));
     return post;
 }
+// A group of short flags, read as gh reads them: the first that takes a value takes the rest of the argument, past
+// an "=", or the next argument, which `value` is left undefined for. Those before it are switches, and a switch
+// given "=" takes the rest as its own. Undefined when the group is all switches.
+export function shortFlag(arg, takesValue) {
+    let j = 1;
+    for (; j < arg.length && !takesValue(`-${arg[j]}`); j++) {
+        if (arg[j + 1] === "=" && j + 2 < arg.length)
+            return undefined;
+    }
+    if (j === arg.length)
+        return undefined;
+    if (j + 1 === arg.length)
+        return { name: `-${arg[j]}`, value: undefined };
+    return { name: `-${arg[j]}`, value: arg.slice(arg[j + 1] === "=" && j + 2 < arg.length ? j + 2 : j + 1) };
+}
 // Each text a posting gh command sends, with where it goes. `read` gives a body file's text, "-" being stdin.
 export function postTexts(post, read) {
     const noun = post.noun;
     return [
         ...post.title.map((t) => [`the ${post.titleName} of ${noun}`, t]),
-        ...post.body.map((t) => [`the body of ${noun}`, t]),
+        ...post.body.map((t) => [`the ${post.bodyName} of ${noun}`, t]),
         ...post.bodyFiles.map((f) => [
-            f === "-" ? `the body of ${noun}` : `the body of ${noun}, from ${f}`,
+            f === "-" ? `the ${post.fileName} of ${noun}` : `the ${post.fileName} of ${noun}, from ${f}`,
             read(f),
         ]),
     ];
 }
+// Each name a posting gh command gives, with where it goes. A name is checked as a branch name is.
+export function postNames(post) {
+    return post.names.map((n) => [`the ${post.nameName} of ${post.noun}`, n]);
+}
 export function shimScript(command) {
     return `#!/bin/sh
 ${SHIM_MARKER} It checks what gh is about to post, then runs the real gh.

package/dist/main.js

@@ -4,7 +4,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { check, checkTerms, KIND_NAMES, KINDS, } from "./checks.js";
 import { configDir, exemptMatcher, findRepoConfig, loadRepoConfig, loadUserConfig, mergeRules, USER_FILE, USER_FILE_TEMPLATE, } from "./config.js";
 import { bashPosts, firstUnknown, isGithubTool, mcpPosts } from "./claude.js";
-import { findRealGh, isShim, parseGh, postTexts, shimScript } from "./gh.js";
+import { findRealGh, isShim, parseGh, postNames, postTexts, shimScript } from "./gh.js";
 import { allowlistChanges, commitMessage, exitStatus, HOOKS, hooksDir, hooksInWorkTree, installHooks, installManaged, isManagedDir, pushRange, readPushed, refreshManaged, runPrevious, uninstallHooks, uninstallManaged, } from "./git.js";
 import { UNKNOWN } from "./shell.js";
 export const EXIT = { clean: 0, findings: 1, failed: 2 };
@@ -336,13 +336,14 @@ async function runShim(io, args) {
     let input;
     if (post) {
         const { identity, rules } = loadRules(io);
-        if (post.bodyFiles.includes("-"))
+        if (post.bodyFiles.includes("-") && !(post.stdinIfPiped && io.stdinIsTTY))
             input = await io.readStdin();
         const stdin = input?.toString("utf8") ?? "";
         const texts = postTexts(post, (file) => (file === "-" ? stdin : readFileSync(resolve(io.cwd, file), "utf8")));
-        const sections = texts
-            .map(([where, text]) => ({ where, findings: check(text, { identity, rules, kind: post.kind }) }))
-            .filter((s) => s.findings.length > 0);
+        const sections = [
+            ...postNames(post).map(([where, name]) => ({ where, findings: checkName(name, identity, rules) })),
+            ...texts.map(([where, text]) => ({ where, findings: check(text, { identity, rules, kind: post.kind }) })),
+        ].filter((s) => s.findings.length > 0);
         if (sections.length > 0) {
             io.err(report(sections, FIX_TEXT));
             return EXIT.findings;
@@ -412,6 +413,8 @@ function claudeRefusal(io, call) {
         const { identity, rules: merged, exemptFiles } = rules.get(post.cwd);
         const exempt = post.file !== undefined && exemptMatcher(exemptFiles)(post.file);
         const options = { identity, rules: merged, kind: post.kind };
+        if (post.name)
+            return { where: post.where, findings: checkName(post.text, identity, merged) };
         return { where: post.where, findings: exempt ? checkTerms(post.text, options) : check(post.text, options) };
     })
         .filter((s) => s.findings.length > 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "second-read",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A privacy check on agent-written commits, issues, PRs and comments, for any coding agent.",
   "license": "MIT",
   "type": "module",