instar 1.3.1663 → 1.3.1664

package/dist/core/SafeGitExecutor.d.ts

@@ -34,11 +34,19 @@
 import { type ChildProcess } from 'node:child_process';
 import { SourceTreeGuardError } from './SourceTreeGuard.js';
 /**
- * Verbs treated as destructive. Closed enumeration; additions are spec changes.
+ * How the funnel classes a verb.
+ *   read  — every form is treated as a read.
+ *   write — every form is treated as a write.
+ *   shape — the verb has both forms; isReadOnlyShape decides per call.
  */
+export type GitVerbClass = 'read' | 'write' | 'shape';
+export declare const GIT_VERB_CLASSES: ReadonlyMap<string, GitVerbClass>;
+/** Verbs a write surface can run: `write` and `shape`. Derived from the table. */
 export declare const DESTRUCTIVE_GIT_VERBS: ReadonlySet<string>;
 /**
- * Read-only verbs explicitly safe to call. Closed enumeration.
+ * Verbs a read surface can run: `read` and `shape`. Derived from the table.
+ * Membership is the funnel's classification, NOT proof the verb writes nothing:
+ * some forms of these verbs can write or run a program (EVO-029 items 4 and 5).
  */
 export declare const READONLY_GIT_VERBS: ReadonlySet<string>;
 /**
@@ -81,6 +89,13 @@ declare function extractVerbAndTargets(args: readonly string[], cwd: string | un
  * membership).
  */
 declare function isReadOnlyShape(verb: string, verbArgs: readonly string[]): boolean | null;
+export type GitInvocationClass = 'read' | 'write' | 'unclassified';
+/**
+ * The one answer to "what does the funnel class this invocation as". `read`
+ * means the funnel classifies it as a read, not that git will write nothing.
+ * A verb outside GIT_VERB_CLASSES is `unclassified`, never read or write.
+ */
+export declare function classifyGitInvocation(verb: string, verbArgs: readonly string[]): GitInvocationClass;
 interface AuditEntry {
     timestamp: string;
     executor: 'git' | 'fs';
@@ -234,13 +249,15 @@ export declare class SafeGitExecutor {
      * Synchronous destructive git execution.
      *
      * 1. Extract the verb and ALL target directories from args + opts.cwd.
-     * 2. Canonicalize each target and call assertNotInstarSourceTree on each.
-     * 3. Verify the verb is in DESTRUCTIVE_GIT_VERBS (or is an ambiguous verb
-     *    in destructive shape). Read-only verbs throw — callers must use readSync.
-     * 4. Strip env denylist; inject GIT_CONFIG_GLOBAL/SYSTEM=/dev/null.
-     * 5. Spawn git via execFileSync; return stdout.
+     * 2. Refuse an unclassified verb, before anything else, on every surface.
+     * 3. Canonicalize each target and call assertNotInstarSourceTree on each.
+     * 4. Verify the invocation classifies as a write. Reads throw — callers must
+     *    use readSync.
+     * 5. Strip env denylist; inject GIT_CONFIG_GLOBAL/SYSTEM=/dev/null.
+     * 6. Spawn git via execFileSync; return stdout.
      *
-     * Throws SourceTreeGuardError if any target is the instar source tree.
+     * Throws SourceTreeGuardError if any target is the instar source tree and the
+     * verb is classified.
      * Throws SafeGitExecutorError on classification mismatch or arg errors.
      */
     static execSync(args: readonly string[], opts: SafeGitOptions): string;
@@ -262,9 +279,13 @@ export declare class SafeGitExecutor {
      */
     static readSync(args: readonly string[], opts: SafeGitOptions): string;
     /**
-     * Verb-aware dispatcher. Routes to readSync for known read-only verbs and to
-     * execSync otherwise. Use this from generic git() helpers that take dynamic
-     * args and don't know at the call site whether the verb is destructive.
+     * Verb-aware dispatcher. A write goes to execSync and everything else to
+     * readSync, which extracts the verb itself and makes the real decision. Use
+     * this from generic git() helpers that take dynamic args and don't know at the
+     * call site whether the verb is destructive.
+     *
+     * It reads args[0] as the verb, so a pre-verb flag such as `-c` classifies as
+     * unclassified here and lands on readSync (EVO-029 item 1).
      */
     static run(args: readonly string[], opts: SafeGitOptions): string;
 }
@@ -284,6 +305,7 @@ export declare function isLocalVerifyClonePath(target: string, verifyRoot: strin
 export declare const _internal: {
     extractVerbAndTargets: typeof extractVerbAndTargets;
     isReadOnlyShape: typeof isReadOnlyShape;
+    GIT_VERB_CLASS_ENTRIES: readonly (readonly [string, GitVerbClass])[];
     sanitizeEnv: typeof sanitizeEnv;
     GIT_ENV_DENYLIST: ReadonlySet<string>;
     repoHasLocalIdentity: typeof repoHasLocalIdentity;

package/dist/core/SafeGitExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SafeGitExecutor.d.ts","sourceRoot":"","sources":["../../src/core/SafeGitExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SafeGitExecutor.d.ts","sourceRoot":"","sources":["../../src/core/SafeGitExecutor.ts"],"names":[],"mappings":"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"}

package/dist/core/SafeGitExecutor.js

@@ -39,92 +39,96 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withSyncOp } from './InFlightSyncOpMarker.js';
 import { assertNotInstarSourceTree, SourceTreeGuardError, } from './SourceTreeGuard.js';
-// ── Verb classification ─────────────────────────────────────────────
 /**
- * Verbs treated as destructive. Closed enumeration; additions are spec changes.
+ * The one verb classification every surface reads. Closed enumeration; an
+ * addition is a spec change. A verb that is not listed is unclassified, and no
+ * surface will run it. Kept as raw entries so a test can see a duplicate, which
+ * the Map built from them would hide.
  */
-export const DESTRUCTIVE_GIT_VERBS = new Set([
-    'add',
-    'am',
-    'apply',
-    'branch', // shape-checked: bare `branch <name>` is destructive
-    'checkout',
-    'cherry-pick',
-    'clean',
-    'clone',
-    'commit',
-    'fetch',
-    'gc',
-    'init',
-    'merge',
-    'mv',
-    'pull',
-    'push',
-    'rebase',
-    'reset',
-    'restore',
-    'revert',
-    'rm',
-    'stash',
-    'submodule',
-    'switch',
-    'tag',
-    'update-ref',
+const GIT_VERB_CLASS_ENTRIES = [
+    // Writes.
+    ['add', 'write'],
+    ['am', 'write'],
+    ['apply', 'write'],
+    ['checkout', 'write'],
+    ['cherry-pick', 'write'],
+    ['clean', 'write'],
+    ['clone', 'write'],
+    ['commit', 'write'],
+    ['fetch', 'write'],
+    ['gc', 'write'],
+    ['init', 'write'],
+    ['merge', 'write'],
+    ['mv', 'write'],
+    ['pull', 'write'],
+    ['push', 'write'],
+    ['rebase', 'write'],
+    ['reset', 'write'],
+    ['restore', 'write'],
+    ['revert', 'write'],
+    ['rm', 'write'],
+    ['submodule', 'write'],
+    ['switch', 'write'],
+    ['tag', 'write'],
+    ['update-ref', 'write'],
     // Object-database writers (no ref or working-tree change); destructive-classified so
     // they route through execSync. local-verify's merge-tree/commit-tree path (§2 step 1).
-    'merge-tree',
-    'commit-tree',
-    'worktree', // shape-checked: `worktree list` is read-only
-    'prune',
-    'notes',
-    'replace',
-    'filter-branch',
-    'remote', // shape-checked: `remote get-url` is read-only
-    'config', // shape-checked: `config --get` is read-only
-    'format-patch', // shape-checked: --inline is destructive
-]);
+    ['merge-tree', 'write'],
+    ['commit-tree', 'write'],
+    ['prune', 'write'],
+    ['notes', 'write'],
+    ['replace', 'write'],
+    ['filter-branch', 'write'],
+    // Reads.
+    ['status', 'read'],
+    ['log', 'read'],
+    ['diff', 'read'],
+    ['show', 'read'],
+    ['rev-parse', 'read'],
+    ['rev-list', 'read'],
+    ['ls-files', 'read'],
+    ['ls-tree', 'read'],
+    ['ls-remote', 'read'],
+    ['describe', 'read'],
+    ['name-rev', 'read'],
+    ['blame', 'read'],
+    ['cat-file', 'read'],
+    ['cherry', 'read'], // lists +/- patch-equivalence vs an upstream; no mutation
+    ['grep', 'read'],
+    ['shortlog', 'read'],
+    ['count-objects', 'read'],
+    ['fsck', 'read'],
+    ['var', 'read'],
+    ['version', 'read'],
+    ['--version', 'read'],
+    ['help', 'read'],
+    ['write-tree', 'read'],
+    ['interpret-trailers', 'read'],
+    ['check-ref-format', 'read'],
+    ['check-ignore', 'read'], // exit code is the answer: 0 matched, 1 no match, 128 git failed
+    ['symbolic-ref', 'read'],
+    ['show-ref', 'read'],
+    ['for-each-ref', 'read'],
+    ['merge-base', 'read'],
+    ['hash-object', 'read'],
+    // Both forms; isReadOnlyShape decides.
+    ['branch', 'shape'], // bare `branch <name>` writes; --list / -l / --show-current / -v read
+    ['stash', 'shape'], // `stash list` / `stash show` read
+    ['worktree', 'shape'], // `worktree list` reads
+    ['remote', 'shape'], // `remote get-url` / `remote show` read
+    ['config', 'shape'], // `config --get` reads
+    ['format-patch', 'shape'], // --inline writes
+    ['reflog', 'shape'], // bare / show / exists read; everything else goes through execSync
+];
+export const GIT_VERB_CLASSES = new Map(GIT_VERB_CLASS_ENTRIES);
+/** Verbs a write surface can run: `write` and `shape`. Derived from the table. */
+export const DESTRUCTIVE_GIT_VERBS = new Set(GIT_VERB_CLASS_ENTRIES.filter(([, cls]) => cls !== 'read').map(([verb]) => verb));
 /**
- * Read-only verbs explicitly safe to call. Closed enumeration.
+ * Verbs a read surface can run: `read` and `shape`. Derived from the table.
+ * Membership is the funnel's classification, NOT proof the verb writes nothing:
+ * some forms of these verbs can write or run a program (EVO-029 items 4 and 5).
  */
-export const READONLY_GIT_VERBS = new Set([
-    'status',
-    'log',
-    'diff',
-    'show',
-    'rev-parse',
-    'rev-list',
-    'ls-files',
-    'ls-tree',
-    'ls-remote',
-    'describe',
-    'name-rev',
-    'blame',
-    'cat-file',
-    'cherry', // read-only: lists +/- patch-equivalence vs an upstream; no mutation
-    'grep',
-    'shortlog',
-    'count-objects',
-    'fsck',
-    'var',
-    'version',
-    '--version',
-    'help',
-    'write-tree',
-    'interpret-trailers',
-    'check-ref-format',
-    'symbolic-ref',
-    'show-ref',
-    'for-each-ref',
-    'merge-base',
-    'reflog', // read-only by default; reflog expire/delete is destructive (caller must use execSync)
-    'hash-object',
-    'config', // overlap with destructive set; readSync shape-check enforces --get only
-    'remote', // overlap; readSync shape-check enforces list/get-url only
-    'branch', // overlap; readSync shape-check enforces --list / -l / --show-current / -v
-    'worktree', // overlap; readSync shape-check enforces list only
-    'format-patch', // overlap; readSync shape-check rejects --inline
-    'stash', // shape-check: `stash list` / `stash show` allowed
-]);
+export const READONLY_GIT_VERBS = new Set(GIT_VERB_CLASS_ENTRIES.filter(([, cls]) => cls !== 'write').map(([verb]) => verb));
 /**
  * Verbs that are "data-pull": they touch the object database and FETCH_HEAD
  * but DO NOT modify the working tree, committed refs (heads/tags/remotes),
@@ -156,6 +160,7 @@ export const SOURCE_TREE_READ_TIER_VERBS = new Set([
     'status',
     'cherry',
     'ls-files', // reaper checks ignored files before allowing worktree removal
+    'check-ignore', // reads ignore rules; a caller may need the answer on the source tree itself
 ]);
 // ── Env denylist ────────────────────────────────────────────────────
 const GIT_ENV_DENYLIST = new Set([
@@ -657,6 +662,19 @@ function isReadOnlyShape(verb, verbArgs) {
             return null;
     }
 }
+/**
+ * The one answer to "what does the funnel class this invocation as". `read`
+ * means the funnel classifies it as a read, not that git will write nothing.
+ * A verb outside GIT_VERB_CLASSES is `unclassified`, never read or write.
+ */
+export function classifyGitInvocation(verb, verbArgs) {
+    const cls = GIT_VERB_CLASSES.get(verb);
+    if (cls === undefined)
+        return 'unclassified';
+    if (cls === 'shape')
+        return isReadOnlyShape(verb, verbArgs) === false ? 'write' : 'read';
+    return cls;
+}
 /** Return the verbArgs (slice after the verb), accounting for pre-verb flags. */
 function sliceAfterVerb(args, verb) {
     const idx = args.indexOf(verb);
@@ -924,19 +942,23 @@ export class SafeGitExecutor {
      * Synchronous destructive git execution.
      *
      * 1. Extract the verb and ALL target directories from args + opts.cwd.
-     * 2. Canonicalize each target and call assertNotInstarSourceTree on each.
-     * 3. Verify the verb is in DESTRUCTIVE_GIT_VERBS (or is an ambiguous verb
-     *    in destructive shape). Read-only verbs throw — callers must use readSync.
-     * 4. Strip env denylist; inject GIT_CONFIG_GLOBAL/SYSTEM=/dev/null.
-     * 5. Spawn git via execFileSync; return stdout.
+     * 2. Refuse an unclassified verb, before anything else, on every surface.
+     * 3. Canonicalize each target and call assertNotInstarSourceTree on each.
+     * 4. Verify the invocation classifies as a write. Reads throw — callers must
+     *    use readSync.
+     * 5. Strip env denylist; inject GIT_CONFIG_GLOBAL/SYSTEM=/dev/null.
+     * 6. Spawn git via execFileSync; return stdout.
      *
-     * Throws SourceTreeGuardError if any target is the instar source tree.
+     * Throws SourceTreeGuardError if any target is the instar source tree and the
+     * verb is classified.
      * Throws SafeGitExecutorError on classification mismatch or arg errors.
      */
     static execSync(args, opts) {
         const { verb, targets: rawTargets } = extractVerbAndTargets(args, opts.cwd);
         const targets = withLocalVerifyTargets(rawTargets, opts);
         const verbArgs = sliceAfterVerb(args, verb);
+        const invocation = classifyGitInvocation(verb, verbArgs);
+        refuseUnclassified(invocation, verb, opts, targets);
         // Run source-tree assertion against every target — unless the caller
         // explicitly opted into the narrow data-pull allowlist (fetch / etc.)
         // for the documented LAYER B + LAYER C canonical-ref read path. See
@@ -948,14 +970,14 @@ export class SafeGitExecutor {
             audit('git', opts.operation, verb, targets[0], 'allowed', 'sourceTree-bypass');
         }
         // Verb classification.
-        const ambiguousReadOnly = isReadOnlyShape(verb, verbArgs);
-        if (ambiguousReadOnly === true) {
+        const shapeChecked = GIT_VERB_CLASSES.get(verb) === 'shape';
+        if (invocation === 'read' && shapeChecked) {
             // The verb is ambiguous and the shape is read-only — caller used the
             // wrong method. Fail loud rather than silently allow.
             audit('git', opts.operation, verb, targets[0], 'denied', 'read-only-shape-via-execSync');
             throw new SafeGitExecutorError(`SafeGitExecutor.execSync called with read-only shape '${verb} ${verbArgs.join(' ')}' — use SafeGitExecutor.readSync instead.`);
         }
-        if (ambiguousReadOnly === null && !DESTRUCTIVE_GIT_VERBS.has(verb)) {
+        if (invocation === 'read') {
             // Pure read-only verb routed through execSync.
             audit('git', opts.operation, verb, targets[0], 'denied', 'readonly-verb-via-execSync');
             throw new SafeGitExecutorError(`SafeGitExecutor.execSync called with read-only verb '${verb}' — use SafeGitExecutor.readSync instead.`);
@@ -987,18 +1009,20 @@ export class SafeGitExecutor {
         const { verb, targets: rawTargets } = extractVerbAndTargets(args, opts.cwd);
         const targets = withLocalVerifyTargets(rawTargets, opts);
         const verbArgs = sliceAfterVerb(args, verb);
+        const invocation = classifyGitInvocation(verb, verbArgs);
+        refuseUnclassified(invocation, verb, opts, targets);
         if (!isSourceTreeCheckBypassed(verb, verbArgs, opts, targets)) {
             runSourceTreeChecks(targets, opts.operation, 'git', verb);
         }
         else {
             audit('git', opts.operation, verb, targets[0], 'allowed', 'sourceTree-bypass');
         }
-        const ambiguousReadOnly = isReadOnlyShape(verb, verbArgs);
-        if (ambiguousReadOnly === true) {
+        const shapeChecked = GIT_VERB_CLASSES.get(verb) === 'shape';
+        if (invocation === 'read' && shapeChecked) {
             audit('git', opts.operation, verb, targets[0], 'denied', 'read-only-shape-via-spawn');
             throw new SafeGitExecutorError(`SafeGitExecutor.spawn called with read-only shape '${verb}' — use SafeGitExecutor.readSync instead.`);
         }
-        if (ambiguousReadOnly === null && !DESTRUCTIVE_GIT_VERBS.has(verb)) {
+        if (invocation === 'read') {
             audit('git', opts.operation, verb, targets[0], 'denied', 'readonly-verb-via-spawn');
             throw new SafeGitExecutorError(`SafeGitExecutor.spawn called with read-only verb '${verb}' — use SafeGitExecutor.readSync instead.`);
         }
@@ -1020,12 +1044,14 @@ export class SafeGitExecutor {
         const { verb, targets: rawTargets } = extractVerbAndTargets(args, opts.cwd);
         const targets = withLocalVerifyTargets(rawTargets, opts);
         const verbArgs = sliceAfterVerb(args, verb);
-        const ambiguousReadOnly = isReadOnlyShape(verb, verbArgs);
-        if (ambiguousReadOnly === false) {
+        const invocation = classifyGitInvocation(verb, verbArgs);
+        refuseUnclassified(invocation, verb, opts, targets);
+        const shapeChecked = GIT_VERB_CLASSES.get(verb) === 'shape';
+        if (invocation === 'write' && shapeChecked) {
             audit('git', opts.operation, verb, targets[0], 'denied', 'destructive-shape-via-readStream');
             throw new SafeGitExecutorError(`SafeGitExecutor.readStream called with destructive shape '${verb} ${verbArgs.join(' ')}' — use SafeGitExecutor.spawn instead.`);
         }
-        if (ambiguousReadOnly === null && !READONLY_GIT_VERBS.has(verb)) {
+        if (invocation === 'write') {
             audit('git', opts.operation, verb, targets[0], 'denied', 'destructive-verb-via-readStream');
             throw new SafeGitExecutorError(`SafeGitExecutor.readStream called with destructive verb '${verb}' — use SafeGitExecutor.spawn instead.`);
         }
@@ -1058,12 +1084,14 @@ export class SafeGitExecutor {
         // misusing this method get a clear "use execSync" error rather than
         // a guard error first.
         const verbArgs = sliceAfterVerb(args, verb);
-        const ambiguousReadOnly = isReadOnlyShape(verb, verbArgs);
-        if (ambiguousReadOnly === false) {
+        const invocation = classifyGitInvocation(verb, verbArgs);
+        refuseUnclassified(invocation, verb, opts, targets);
+        const shapeChecked = GIT_VERB_CLASSES.get(verb) === 'shape';
+        if (invocation === 'write' && shapeChecked) {
             audit('git', opts.operation, verb, targets[0], 'denied', 'destructive-shape-via-readSync');
             throw new SafeGitExecutorError(`SafeGitExecutor.readSync called with destructive shape '${verb} ${verbArgs.join(' ')}' — use SafeGitExecutor.execSync instead.`);
         }
-        if (ambiguousReadOnly === null && !READONLY_GIT_VERBS.has(verb)) {
+        if (invocation === 'write') {
             audit('git', opts.operation, verb, targets[0], 'denied', 'destructive-verb-via-readSync');
             throw new SafeGitExecutorError(`SafeGitExecutor.readSync called with destructive verb '${verb}' — use SafeGitExecutor.execSync instead.`);
         }
@@ -1098,30 +1126,29 @@ export class SafeGitExecutor {
         return stdout || '';
     }
     /**
-     * Verb-aware dispatcher. Routes to readSync for known read-only verbs and to
-     * execSync otherwise. Use this from generic git() helpers that take dynamic
-     * args and don't know at the call site whether the verb is destructive.
+     * Verb-aware dispatcher. A write goes to execSync and everything else to
+     * readSync, which extracts the verb itself and makes the real decision. Use
+     * this from generic git() helpers that take dynamic args and don't know at the
+     * call site whether the verb is destructive.
+     *
+     * It reads args[0] as the verb, so a pre-verb flag such as `-c` classifies as
+     * unclassified here and lands on readSync (EVO-029 item 1).
      */
     static run(args, opts) {
         const verb = args[0];
-        if (verb && READONLY_GIT_VERBS.has(verb)) {
-            const verbArgs = args.slice(1);
-            const shape = isReadOnlyShape(verb, verbArgs);
-            if (shape !== false)
-                return SafeGitExecutor.readSync(args, opts);
-        }
-        if (verb && !DESTRUCTIVE_GIT_VERBS.has(verb)) {
-            return SafeGitExecutor.readSync(args, opts);
-        }
-        if (verb) {
-            const verbArgs = args.slice(1);
-            const shape = isReadOnlyShape(verb, verbArgs);
-            if (shape === true)
-                return SafeGitExecutor.readSync(args, opts);
+        if (verb && classifyGitInvocation(verb, args.slice(1)) === 'write') {
+            return SafeGitExecutor.execSync(args, opts);
         }
-        return SafeGitExecutor.execSync(args, opts);
+        return SafeGitExecutor.readSync(args, opts);
     }
 }
+/** The one refusal for a verb outside GIT_VERB_CLASSES. Every surface calls it first. */
+function refuseUnclassified(invocation, verb, opts, targets) {
+    if (invocation !== 'unclassified')
+        return;
+    audit('git', opts.operation, verb, targets[0], 'denied', 'unclassified-verb');
+    throw new SafeGitExecutorError(`SafeGitExecutor: git verb '${verb}' is not classified. It is not in GIT_VERB_CLASSES, so no surface will run it. Adding a verb is a reviewed change to that table.`);
+}
 function isSourceTreeCheckBypassed(verb, verbArgs, opts, targets = []) {
     if (opts.sourceTreeReadOk && SOURCE_TREE_READ_TIER_VERBS.has(verb))
         return true;
@@ -1372,6 +1399,7 @@ function audit(executor, operation, verb, target, outcome, reason) {
 export const _internal = {
     extractVerbAndTargets,
     isReadOnlyShape,
+    GIT_VERB_CLASS_ENTRIES,
     sanitizeEnv,
     GIT_ENV_DENYLIST,
     repoHasLocalIdentity,