vouchington-tooling 0.8.1 → 0.9.0

package/README.md

@@ -208,8 +208,21 @@ import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-tr
 import { appendJournal, probeBlackboard } from 'vouchington-tooling/agent-blackboard'
 import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
 import { createPullRequest, getDiffAgainstBase, runGh, runGit } from 'vouchington-tooling/gh-cli'
+import {
+  shellScriptViolations,
+  workflowYamlViolations,
+} from 'vouchington-tooling/gh-api-shell-quoting'
 ```
 
+`shellScriptViolations`/`workflowYamlViolations` flag a `gh api` call whose argument carries an
+unquoted `?` or `&`: an unquoted `&` silently backgrounds the command and truncates the query
+(the call still exits 0), and an unquoted `?` fails loudly under zsh glob-nomatch but passes
+through unexpanded under bash. `workflowYamlViolations` decodes quoted and folded YAML `run:`
+scalars before scanning, so a hazard hidden by YAML's own quote-stripping is still caught; it
+throws on a `run:` value that is a YAML alias or a multiline PLAIN scalar, shapes it cannot yet
+scan safely. Both functions scan already-in-scope source text — deciding which files count as a
+shell script or a workflow/action YAML file is left to the caller.
+
 `checkWorkspaceGatesPolicy` rejects tracked test assertions that hard-code the exact version of a
 dependency declared by a non-fixture package manifest. Assert dependency membership or placement,
 or derive a configuration or documentation package spec from that manifest instead.

package/dist/gh-api-shell-quoting/index.d.mts

@@ -0,0 +1,5 @@
+import type { ShellQuotingViolation } from './yaml.mts';
+export type { ShellQuotingViolation } from './yaml.mts';
+export { workflowYamlViolations } from './yaml.mts';
+/** For a plain shell script: `source` is the whole file, so hit offsets are already absolute. */
+export declare function shellScriptViolations(source: string): ShellQuotingViolation[];

package/dist/gh-api-shell-quoting/index.mjs

@@ -0,0 +1,17 @@
+// Detects `gh api <arg>` invocations, in a shell script or a workflow/composite-action `run:`
+// block, where the argument carries an unquoted `?` or `&`. An unquoted `&` backgrounds the
+// command and drops every argument after it — the truncated call still exits 0, so CI can report
+// success on a silently short-circuited query. An unquoted `?` fails loudly under zsh
+// glob-nomatch but passes through unexpanded under bash.
+//
+// This module only scans already-in-scope source text; deciding which files count as a shell
+// script or a workflow/action YAML file is repo-layout policy left to the caller.
+import { ghApiShellQuotingHits, lineNumberAt } from './scan.mjs';
+export { workflowYamlViolations } from './yaml.mjs';
+/** For a plain shell script: `source` is the whole file, so hit offsets are already absolute. */
+export function shellScriptViolations(source) {
+    return ghApiShellQuotingHits(source).map((hit) => ({
+        line: lineNumberAt(source, hit.offset),
+        excerpt: hit.excerpt,
+    }));
+}

package/dist/gh-api-shell-quoting/scan.d.mts

@@ -0,0 +1,7 @@
+export type ShellQuotingHit = {
+    offset: number;
+    excerpt: string;
+};
+export declare function lineNumberAt(source: string, offset: number): number;
+/** Hits in `text` with offsets relative to `text` itself, not any enclosing document. */
+export declare function ghApiShellQuotingHits(text: string): ShellQuotingHit[];

package/dist/gh-api-shell-quoting/scan.mjs

@@ -0,0 +1,181 @@
+// Pure `gh api` shell-argument scanner: detects an unquoted `?` or `&` in a `gh api` call's
+// argument list. An unquoted `&` backgrounds the command and drops every argument after it — the
+// truncated call still exits 0, so CI can report success on a silently short-circuited query. An
+// unquoted `?` fails loudly under zsh glob-nomatch but passes through unexpanded under bash. See
+// ./yaml.mts and ./index.mts for what feeds this and how it maps hits back to source locations.
+//
+// This is a small heuristic scanner, not a shell parser: it tracks quote state, backslash
+// escapes, and `$(...)` command-substitution nesting per logical line (physical lines joined
+// across a trailing, unescaped `\`). It stops once it finds the first unsafe character in a
+// call's argument list. A general-purpose shell tokenizer whose "expandable" notion conflates
+// glob metacharacters with `$`/backtick expansion would false-positive on a quoted
+// `"…${VAR}…?per_page=1"`, so this scanner tracks its own narrower quote-state machine instead.
+const GH_API_BOUNDARY = /[\s;|&(){}]/;
+const GH_API_HEAD = /^gh[ \t]+api\b/;
+function matchGhApiHead(text, index) {
+    if (index > 0 && !GH_API_BOUNDARY.test(text[index - 1]))
+        return 0;
+    const match = GH_API_HEAD.exec(text.slice(index));
+    return match ? match[0].length : 0;
+}
+function excerptAround(text, index) {
+    return text.slice(Math.max(0, index - 24), Math.min(text.length, index + 12)).trim();
+}
+function newFrame() {
+    return { inSingleQuote: false, inDoubleQuote: false, scanningArgs: false, parenDepth: 0 };
+}
+function pushSubstitutionFrame(stack) {
+    const frame = newFrame();
+    frame.parenDepth = 1;
+    stack.push(frame);
+}
+// Scans one already-joined logical line for `gh api` calls and returns at most one hit per call —
+// the first unquoted `?` or `&`, whichever comes first. `offsets[k]` maps character k of `text`
+// back to its absolute offset in the original source, so callers can report real line numbers.
+function scanLogicalLine(text, offsets) {
+    const hits = [];
+    const stack = [newFrame()];
+    let i = 0;
+    while (i < text.length) {
+        const frame = stack[stack.length - 1];
+        const char = text[i];
+        if (frame.inSingleQuote) {
+            if (char === "'")
+                frame.inSingleQuote = false;
+            i += 1;
+            continue;
+        }
+        if (char === '\\') {
+            i += 2;
+            continue;
+        }
+        if (frame.inDoubleQuote) {
+            if (char === '"') {
+                frame.inDoubleQuote = false;
+                i += 1;
+                continue;
+            }
+            if (char === '$' && text[i + 1] === '(') {
+                pushSubstitutionFrame(stack);
+                i += 2;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if (char === '#' && (i === 0 || /\s/.test(text[i - 1])))
+            break;
+        if (char === "'") {
+            frame.inSingleQuote = true;
+            i += 1;
+            continue;
+        }
+        if (char === '"') {
+            frame.inDoubleQuote = true;
+            i += 1;
+            continue;
+        }
+        if (char === '$' && text[i + 1] === '(') {
+            pushSubstitutionFrame(stack);
+            i += 2;
+            continue;
+        }
+        if (stack.length > 1 && (char === '(' || char === ')')) {
+            frame.parenDepth += char === '(' ? 1 : -1;
+            i += 1;
+            if (frame.parenDepth === 0)
+                stack.pop();
+            continue;
+        }
+        if (frame.scanningArgs) {
+            if (char === ';' || char === '|') {
+                frame.scanningArgs = false;
+                i += 1;
+                continue;
+            }
+            if (char === '&') {
+                if (text[i + 1] === '&') {
+                    frame.scanningArgs = false;
+                    i += 2;
+                    continue;
+                }
+                // `2>&1`/`>&2`/`<&3` fd-duplication redirects don't end the argument list; whitespace-
+                // preceded `&` is Bash's background operator and does. Only an `&` embedded in an
+                // unquoted argument is unsafe.
+                if (i > 0 && /[><]/.test(text[i - 1])) {
+                    i += 1;
+                    continue;
+                }
+                if (!(i > 0 && /[ \t]/.test(text[i - 1])))
+                    hits.push({ offset: offsets[i], excerpt: excerptAround(text, i) });
+                frame.scanningArgs = false;
+                i += 1;
+                continue;
+            }
+            if (char === '?') {
+                hits.push({ offset: offsets[i], excerpt: excerptAround(text, i) });
+                frame.scanningArgs = false;
+                i += 1;
+                continue;
+            }
+        }
+        const headLength = frame.scanningArgs ? 0 : matchGhApiHead(text, i);
+        if (headLength > 0) {
+            frame.scanningArgs = true;
+            i += headLength;
+            continue;
+        }
+        i += 1;
+    }
+    return hits;
+}
+// A logical line joins physical lines across a trailing, unescaped `\` — bash line continuation —
+// so a `gh api \` / URL-on-next-line split (common in multi-line `run:` steps) is scanned as one
+// command instead of two truncated fragments.
+function endsWithLineContinuation(line) {
+    let backslashRun = 0;
+    for (let i = line.length - 1; i >= 0 && line[i] === '\\'; i -= 1)
+        backslashRun += 1;
+    return backslashRun % 2 === 1;
+}
+function joinLogicalLines(source) {
+    const lines = [];
+    let position = 0;
+    while (position <= source.length) {
+        let text = '';
+        const offsets = [];
+        for (;;) {
+            const newlineIndex = source.indexOf('\n', position);
+            const lineEnd = newlineIndex === -1 ? source.length : newlineIndex;
+            const physical = source.slice(position, lineEnd);
+            const continues = endsWithLineContinuation(physical);
+            const contentEnd = continues ? physical.length - 1 : physical.length;
+            for (let i = 0; i < contentEnd; i += 1) {
+                text += physical[i];
+                offsets.push(position + i);
+            }
+            position = lineEnd + 1;
+            if (!continues || newlineIndex === -1)
+                break;
+        }
+        lines.push({ text, offsets });
+        if (position > source.length)
+            break;
+    }
+    return lines;
+}
+export function lineNumberAt(source, offset) {
+    let line = 1;
+    for (let i = 0; i < offset; i += 1)
+        if (source[i] === '\n')
+            line += 1;
+    return line;
+}
+/** Hits in `text` with offsets relative to `text` itself, not any enclosing document. */
+export function ghApiShellQuotingHits(text) {
+    const hits = [];
+    for (const logicalLine of joinLogicalLines(text)) {
+        hits.push(...scanLogicalLine(logicalLine.text, logicalLine.offsets));
+    }
+    return hits;
+}

package/dist/gh-api-shell-quoting/yaml.d.mts

@@ -0,0 +1,6 @@
+export type ShellQuotingViolation = {
+    line: number;
+    excerpt: string;
+};
+/** For a workflow/composite-action YAML file: scans every `run:` block's effective shell text. */
+export declare function workflowYamlViolations(source: string): ShellQuotingViolation[];

package/dist/gh-api-shell-quoting/yaml.mjs

@@ -0,0 +1,95 @@
+// Extracts and scans `run:` step bodies from a GitHub Actions workflow or composite-action YAML
+// document for the same unquoted `?`/`&` hazard `./scan.mts` detects in a plain shell script. See
+// ./index.mts for the exported entry points.
+import { isAlias, isScalar, parseDocument, visit } from 'yaml';
+import { ghApiShellQuotingHits, lineNumberAt } from './scan.mjs';
+// Any `run:` scalar anywhere in the document is a shell step body — workflow job steps and
+// composite-action steps both use the same key. This module does not resolve YAML aliases: a
+// `run:` value has no reason to be shared via an anchor, so instead of silently skipping an
+// aliased `run:` (which would let an unsafe invocation bypass detection undetected), `runBlocks`
+// throws when it finds one — see below.
+//
+// A folded scalar (`run: >-`) joins its source lines with spaces before the shell ever sees it, so
+// `gh api` on one physical line and an unquoted `repos/x/y?a=1&b=2` on the next form one unsafe
+// command at runtime even though they are two lines in the file. A quoted flow scalar
+// (`run: 'gh api …?a=1&b=2'` or `run: "gh api …?a=1&b=2"`) has its outer quotes stripped by YAML
+// before the shell ever sees it too, so scanning the raw source slice — which still includes those
+// quotes — makes the shell scanner mistake them for argument quoting and miss a real violation.
+// `text` is the already-decoded string for these shapes (`pair.value.value`, not the raw source
+// slice, which still carries the block header or quote delimiters) so the scanner sees exactly
+// what the shell would; `decoded` tells the caller that per-hit offsets inside `text` no longer
+// correspond 1:1 to source byte offsets, since decoding discards those delimiters (and, for folded
+// scalars, the original line breaks). `BLOCK_LITERAL` (`run: |`) and single-line `PLAIN` scalars
+// keep their raw source slice: both scan identically decoded or not, so precise per-hit offsets
+// stay correct and existing per-line assertions are unaffected. A *multiline* `PLAIN` scalar folds
+// its line breaks the same way a folded scalar does, so its raw slice is not equivalent to what
+// the shell sees either — worse, the raw slice's un-joined `\n` (with no trailing backslash) makes
+// `ghApiShellQuotingHits` treat the continuation as an unrelated logical line, silently missing a
+// `gh api` call split across it (see below). `runBlocks` throws on this shape below rather than
+// decode it, mirroring the alias handling above.
+const DECODED_SCALAR_TYPES = new Set([
+    'BLOCK_FOLDED',
+    'QUOTE_SINGLE',
+    'QUOTE_DOUBLE',
+]);
+function runBlocks(source) {
+    const document = parseDocument(source);
+    if (document.errors.length > 0)
+        throw document.errors[0];
+    const blocks = [];
+    visit(document, {
+        Pair(_key, pair) {
+            if (!isScalar(pair.key) || pair.key.value !== 'run')
+                return;
+            if (isAlias(pair.value)) {
+                const resolved = pair.value.resolve(document);
+                if (isScalar(resolved) && typeof resolved.value === 'string') {
+                    throw new Error('run: value is a YAML alias to a string scalar — this guard does not resolve ' +
+                        'aliases, so an aliased shell body could bypass it undetected. Write the run: ' +
+                        'value inline, or extend runBlocks() to resolve aliases before adding one.');
+                }
+                return;
+            }
+            if (!isScalar(pair.value) || typeof pair.value.value !== 'string')
+                return;
+            /* v8 ignore next -- parseDocument always assigns a range to a scalar it parsed from source;
+               this only guards the type narrowing above, not a reachable runtime state. */
+            if (!pair.value.range)
+                throw new Error('run: scalar has no source range');
+            const raw = source.slice(pair.value.range[0], pair.value.range[1]);
+            if (pair.value.type === 'PLAIN' && raw.includes('\n')) {
+                throw new Error('run: value is a multiline PLAIN scalar — its raw source slice does not match the ' +
+                    'decoded shell text (YAML folds a PLAIN line break into a single space), and this ' +
+                    'guard only decodes BLOCK_FOLDED/QUOTE_SINGLE/QUOTE_DOUBLE scalars, so scanning the ' +
+                    'raw slice can silently miss a call split across the fold. Rewrite the run: value as ' +
+                    'a quoted or block scalar, or extend DECODED_SCALAR_TYPES and runBlocks() to decode ' +
+                    'multiline PLAIN scalars before adding one.');
+            }
+            const decoded = pair.value.type !== undefined && DECODED_SCALAR_TYPES.has(pair.value.type);
+            blocks.push({
+                offset: pair.value.range[0],
+                text: decoded ? pair.value.value : raw,
+                decoded,
+            });
+        },
+    });
+    return blocks;
+}
+/** For a workflow/composite-action YAML file: scans every `run:` block's effective shell text. */
+export function workflowYamlViolations(source) {
+    const violations = [];
+    for (const block of runBlocks(source)) {
+        const blockStartLine = lineNumberAt(source, block.offset);
+        for (const hit of ghApiShellQuotingHits(block.text)) {
+            // A decoded block's delimiters (and, for folded blocks, its line breaks) are gone by the
+            // time the shell runs it, so there is no single source line the hit "belongs" to — report
+            // the block's start line instead of computing a byte offset into decoded text that no
+            // longer lines up with `source`.
+            violations.push({
+                line: block.decoded ? blockStartLine : lineNumberAt(source, block.offset + hit.offset),
+                excerpt: hit.excerpt,
+            });
+        }
+    }
+    return violations;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -267,6 +267,11 @@
       "import": "./dist/gh-cli/index.mjs",
       "default": "./dist/gh-cli/index.mjs"
     },
+    "./gh-api-shell-quoting": {
+      "types": "./dist/gh-api-shell-quoting/index.d.mts",
+      "import": "./dist/gh-api-shell-quoting/index.mjs",
+      "default": "./dist/gh-api-shell-quoting/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/skills/github-issue/SKILL.md

@@ -25,11 +25,18 @@ When an external creation target is denied, never write there. Search for and cr
 tracking issue in the current repository, or a consumer-selected tracker. Immediately before that
 write, refetch the destination repository and apply the issue-operation gate above. Include the
 intended upstream repository and a copy-ready report so a human can decide whether to file it. Before
-copying details to a less-restricted destination, remove private repository identity, paths, links,
-code, and findings; if redaction would make the report unusable, require explicit destination approval
-or return the draft without mutation. Authorization to file the external issue includes this tracking
-fallback unless the caller opts out; report the reroute explicitly. If no tracker passes, return the
-draft without mutation. Never fall back silently or to an unverified repository.
+naming that upstream repository anywhere in the report, resolve it and compare the returned canonical
+name against the name being written — a renamed repository's redirect resolves successfully under the
+stale name, so existence alone proves nothing. This comparison serves report accuracy, not the
+mutation-authority gate above: a rename is not the hard-deny mismatch that gate defines, so report the
+canonical name in its place; when the name does not resolve at all, route the follow-up to the current
+repository instead of naming an unreachable target. Before copying details to a less-restricted
+destination, remove private repository identity, paths, links, code, and findings; if redaction would
+make the report unusable, require explicit destination approval or return the draft without mutation.
+Authorization to file the external issue includes this tracking fallback unless the caller opts out;
+report the reroute explicitly. If no tracker passes, return the draft without mutation. Never fall back
+silently or to an unverified
+repository.
 
 ## Issue workflow