@rmyndharis/aimhooman 0.1.0 → 0.1.2

package/src/hook.mjs

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { GIT_TIMEOUT_MS } from './git-environment.mjs';
 import { newEngineWithDiagnostics } from './scan.mjs';
 import { openRepo, stagedEntries } from './gitx.mjs';
 import { applyExclude, patternsForRules } from './exclude.mjs';
@@ -101,7 +102,12 @@ function hookPreToolUse(input) {
     const executorCommand = command(input, executor);
     if (executorCommand === null) return unknownExecutorShape(input, executor.name);
     const rawParsed = parseGit(executorCommand);
-    if (nonPosixExecutor(executor.name)) rawParsed.uncertainShell = true;
+    if (nonPosixExecutor(executor.name)) {
+        rawParsed.uncertainShell = true;
+        // The benign-pipeline classifier is POSIX-only; never exempt a non-POSIX
+        // shell line (pwsh/fish/cmd/nu) from opaque-commit-hiding treatment.
+        rawParsed.opaqueCommitHiding = true;
+    }
     if (executorTargetSyntaxUncertain(executor.name, executorCommand, rawParsed)
         && (rawParsed.addPaths.length > 0 || rawParsed.commands.some(isProtectedMutation))) {
         return emitDecision(
@@ -325,7 +331,11 @@ function hookPreToolUse(input) {
         }
     }
     let eng;
+    // diagnosticWarning is about the rule pack and drives the messages below;
+    // hygieneWarning is housekeeping that never touches the decision. Kept apart
+    // so the "invalid local pack skipped" wording stays true.
     let diagnosticWarning = '';
+    let hygieneWarning = '';
     try {
         const loaded = repo
             ? engineForPolicy(repo, policy, policy.head)
@@ -338,7 +348,6 @@ function hookPreToolUse(input) {
                 return emitDecision('deny', `aimhooman strict policy could not load local rules: ${diagnosticWarning}`);
             }
         }
-        if (repo) applyExclude(repo.excludeFile, patternsForRules(eng.rules));
     } catch (e) {
         const reason = e?.name === 'LocalOverridesError'
             ? `aimhooman cannot load local overrides: ${e.message}`
@@ -347,6 +356,17 @@ function hookPreToolUse(input) {
         if (profile === 'strict') return emitDecision('deny', reason);
         return emitDecision('allow', `${reason}; continuing because profile=${profile}`);
     }
+    // Refreshing the excludes is gitignore hygiene, not part of the verdict:
+    // pre-commit never writes them and still answers. Kept out of the block
+    // above so a read-only .git/info (CI checkout, read-only volume, a
+    // repository owned by another user) cannot decide what is allowed.
+    if (repo) {
+        try {
+            applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+        } catch (e) {
+            hygieneWarning = `could not refresh ${repo.excludeFile}: ${e.message}`;
+        }
+    }
     // A strict policy cannot make a meaningful guarantee if Git's own guards
     // are explicitly bypassed. Deny before the shell can stage-and-commit in a
     // single command, when inspecting the future index would be impossible.
@@ -364,7 +384,7 @@ function hookPreToolUse(input) {
     const prefixBypass = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.prefixRisk
-    )) || (parsed.uncertainShell && parsed.commands.length === 0 && parsed.prefixRisk);
+    )) || (parsed.opaqueCommitHiding && parsed.commands.length === 0 && parsed.prefixRisk);
     const aliasBypass = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.inlineAliasRisk
@@ -379,7 +399,13 @@ function hookPreToolUse(input) {
     const unmodelledPrefixReason =
         'aimhooman cannot verify the final staged snapshot or Git hooks after an earlier unmodelled command; run that command separately, then retry the commit.';
     const blocks = [];
-    const potentialCommit = commit || parsed.uncertainShell;
+    // potentialCommit treats a command as leading to a commit. uncertainShell
+    // was too broad: it flagged any pipe, so a benign read-only pipeline
+    // (gh ... | tail) was scanned and denied as if it staged a secret.
+    // opaqueCommitHiding keeps every commit-hiding shape (subshells,
+    // substitution, script-feeds, code-executing/unlisted pipe segments) while
+    // excluding pipelines of known read-only commands.
+    const potentialCommit = commit || parsed.opaqueCommitHiding;
     if (potentialCommit && repo) {
         try {
             const entries = stagedEntries(repo);
@@ -457,6 +483,9 @@ function hookPreToolUse(input) {
         if (diagnosticWarning) {
             return emitDecision('allow', `aimhooman warning: ${diagnosticWarning}; invalid local pack skipped`);
         }
+        if (hygieneWarning) {
+            return emitDecision('allow', `aimhooman warning: ${hygieneWarning}`);
+        }
         return 0;
     }
 
@@ -484,10 +513,8 @@ function hookPreToolUse(input) {
     }
     const guarded = repo && !bypassed && installedHooks(repo).includes('pre-commit');
     const advisory = advisoryReason(blocks, guarded, bypassed ? bypassContext : '');
-    return emitDecision(
-        'allow',
-        diagnosticWarning ? `${advisory} Warning: ${diagnosticWarning}.` : advisory
-    );
+    const notes = [diagnosticWarning, hygieneWarning].filter(Boolean).join('; ');
+    return emitDecision('allow', notes ? `${advisory} Warning: ${notes}.` : advisory);
 }
 
 function toolName(i) {
@@ -1055,11 +1082,17 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 : commands.some((candidate) => candidate.verb === 'commit' && candidate.futureIndex)
                     ? 'future-index'
                     : 'direct';
+    // opaqueCommitHiding narrows uncertainShell to uncertainty that can hide or
+    // feed a commit (subshells, substitution, script-feeds, code-executing or
+    // unlisted pipe segments). A bare pipeline of known read-only commands
+    // (gh ... | tail) cannot, so it is not treated as a potential commit.
+    const opaqueCommitHiding = uncertainShell && !benignReadOnlyPipeline(cmd);
     return {
         commit,
         noVerify,
         bypassHooks,
         uncertainShell,
+        opaqueCommitHiding,
         classification,
         environmentRisk: unique(commands.flatMap((candidate) => candidate.environmentRisk || [])),
         prefixRisk,
@@ -1196,7 +1229,12 @@ function configuredPushReceiver(repo) {
         return execFileSync(
             'git',
             ['config', '--get-regexp', '^remote\\..*\\.receivepack$'],
-            { cwd: repo.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+            {
+                cwd: repo.root,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: GIT_TIMEOUT_MS,
+            },
         ).trim().length > 0;
     } catch (error) {
         if (error?.status === 1) return false;
@@ -1431,6 +1469,7 @@ function readGitAlias(cwd, name) {
             cwd,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: GIT_TIMEOUT_MS,
         }).trim();
     } catch {
         return null;
@@ -1737,6 +1776,103 @@ function shellUnits(s) {
     return out;
 }
 
+// SAFE_PIPE_EXECUTABLES are commands permitted in a "benign read-only pipeline":
+// they take only data arguments, never run a sub-command, never execute code,
+// never write files, and cannot bypass Git hooks. Anything not listed is treated
+// as potentially able to hide or feed a commit (fail-closed). Deliberately
+// excluded: shells and interpreters, awk/sed/ed/vim, sqlite3/psql/dc/bc/octave
+// and other stdin-as-program readers, git, tee (writes files), env/xargs/find
+// (run sub-commands), and curl/wget (fetch arbitrary content to a pipe).
+const SAFE_PIPE_EXECUTABLES = new Set([
+    'cat', 'tac', 'head', 'tail', 'tr', 'cut', 'paste', 'fold', 'fmt', 'expand',
+    'unexpand', 'rev', 'nl', 'pr', 'column', 'sort', 'uniq', 'comm', 'tsort',
+    'shuf', 'wc', 'grep', 'egrep', 'fgrep', 'rg', 'ag', 'ack', 'xxd', 'od',
+    'hexdump', 'base64', 'base32', 'md5sum', 'sha1sum', 'sha224sum', 'sha256sum',
+    'sha384sum', 'sha512sum', 'cksum', 'b2sum', 'sum', 'file', 'ls', 'exa', 'eza',
+    'lsd', 'tree', 'du', 'df', 'stat', 'date', 'whoami', 'id', 'uname',
+    'hostname', 'uptime', 'printenv', 'pwd', 'basename', 'dirname', 'realpath',
+    'seq', 'yes', 'echo', 'printf', 'test', 'true', 'false', 'jq', 'yq', 'bat',
+    'gh', '[',
+]);
+
+// containsOpaquePipeLexeme is a quote-aware scan for shell constructs that can
+// hide or feed a commit or subcommand: command substitution, subshells, brace
+// expansion/groups, script-feed redirects, and command separators. Output
+// redirects (>, >>) and fd-dups such as 2>&1 are intentionally NOT opaque: they
+// cannot feed code into a pipe sink. A bare & (background) is opaque unless it
+// is part of an fd-dup (>& / <&) or &&.
+function containsOpaquePipeLexeme(command) {
+    let quote = '';
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        const prev = command[i - 1];
+        const next = command[i + 1];
+        if (escaped) { escaped = false; continue; }
+        if (char === '\\' && quote !== "'") { escaped = true; continue; }
+        if (quote) {
+            if (quote === '"' && (char === '`' || (char === '$' && next === '('))) return true;
+            if (char === quote) quote = '';
+            continue;
+        }
+        if (char === "'" || char === '"') { quote = char; continue; }
+        if (char === '`' || char === '(' || char === ')' || char === '{' || char === '}') return true;
+        if (char === '$' && (next === '(' || next === '{')) return true;
+        if (char === '<' || char === ';') return true;
+        if (char === '&' && next !== '&' && prev !== '&' && prev !== '>' && prev !== '<') return true;
+    }
+    return false;
+}
+
+// splitPipeSegments splits a command on an unquoted pipe (|) that is not part
+// of ||. Unlike shellUnits it does not break on &, so 2>&1 stays within a
+// segment.
+function splitPipeSegments(command) {
+    const segments = [];
+    let segment = '';
+    let quote = '';
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if (escaped) { segment += char; escaped = false; continue; }
+        if (char === '\\' && quote !== "'") { segment += char; escaped = true; continue; }
+        if (quote) { segment += char; if (char === quote) quote = ''; continue; }
+        if (char === "'" || char === '"') { segment += char; quote = char; continue; }
+        if (char === '|' && command[i + 1] !== '|') { segments.push(segment); segment = ''; continue; }
+        segment += char;
+    }
+    segments.push(segment);
+    return segments;
+}
+
+// pipelineSegmentExecutable returns the shellExecutable basename of the first
+// non-environment-assignment token in a pipe segment, or null when the segment
+// has no command. A leading redirect token (e.g. 2>&1 before the command) is
+// treated as unlisted -> null -> not benign (fail-closed), which is safe.
+function pipelineSegmentExecutable(segment) {
+    for (const word of shellWords(segment.trim())) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) continue;
+        return shellExecutable(word);
+    }
+    return null;
+}
+
+// benignReadOnlyPipeline reports whether a command is a bare pipeline whose
+// every segment is a known non-code-executing, non-mutating command with no
+// opaque shell syntax. Such a pipe cannot hide or feed a commit, so it is not a
+// "potential commit" for the unmodelled-prefix guard. Fail-closed: any opaque
+// lexeme, unlisted executable, missing executable, or non-pipe returns false.
+function benignReadOnlyPipeline(command) {
+    if (!command.includes('|')) return false;
+    if (containsOpaquePipeLexeme(command)) return false;
+    const segments = splitPipeSegments(command);
+    if (segments.length < 2) return false;
+    return segments.every((segment) => {
+        const executable = pipelineSegmentExecutable(segment);
+        return executable !== null && SAFE_PIPE_EXECUTABLES.has(executable);
+    });
+}
+
 function pipedShellCommitInvocations(source, initialCwd) {
     const units = shellUnits(source);
     const commits = [];

package/src/scan-session.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { gitEnvironment } from './git-environment.mjs';
+import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 
 export const DEFAULT_SCAN_LIMITS = Object.freeze({
     maxFileBytes: 2 << 20,
@@ -112,6 +112,7 @@ function readObjects(repo, objectIds, expectedBytes = 0) {
         input: Buffer.from(unique.join('\n') + '\n'),
         encoding: 'buffer',
         maxBuffer: Math.max(2 * 1024 * 1024, expectedBytes + unique.length * 256 + 1024),
+        timeout: GIT_TIMEOUT_MS,
     });
     const objects = new Map();
     const failures = [];

package/src/scan-target.mjs

@@ -49,6 +49,7 @@ export function scanMessage(repo, text, options = {}) {
     const { policy, head } = resolved;
     const loaded = engineForPolicy(repo, policy, options.overrideHead || head);
     const accumulator = createAccumulator(options.limits);
+    accumulator.addSkipped(loaded.skipped);
     accumulator.add(loaded.engine.checkMessage(text).map((finding) => decorate(finding, null, policy)));
     accumulator.addSkipped(loaded.engine.takeSkipped());
     return {
@@ -68,6 +69,7 @@ function scanIndex(repo, options) {
     const { rawPolicy, floor, policy, head, acknowledged } = resolveStagedPolicy(repo, options.explicitProfile);
     const loaded = engineForPolicy(repo, policy, options.overrideHead || head);
     const accumulator = createAccumulator(options.limits);
+    accumulator.addSkipped(loaded.skipped);
     let entries = kind === 'tracked' ? trackedEntries(repo) : stagedEntries(repo);
     const conflicts = unmergedPaths(repo);
     const diagnostics = [...loaded.diagnostics];
@@ -189,6 +191,7 @@ function scanCommit(repo, options) {
         reviewContexts,
     );
     const accumulator = createAccumulator(options.limits);
+    accumulator.addSkipped(loaded.skipped);
     const diagnostics = [...loaded.diagnostics];
 
     if (snapshot.shallowBoundary) {
@@ -261,6 +264,9 @@ function scanRange(repo, options) {
     // only constructs an Engine and applies overrides (see engineForPolicy).
     const preloaded = loadRulesWithDiagnostics(repo.stateDir);
     const preloadedOverrides = loadOverrides(repo.stateDir);
+    // Counted once for the range, not once per commit: the same packs back every
+    // commit's engine, so the per-commit loaded.skipped would inflate the tally.
+    accumulator.addSkipped(packSkipped(preloaded.errors));
 
     for (const commit of history.commits) {
         const changes = commitChanges(repo, commit.commit, commit.commit, commit.parents);
@@ -363,27 +369,38 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
 
 function scanReviewPathChanges(engine, entries, policy, accumulator, options = {}) {
     for (const entry of entries) {
-        const paths = [];
-        if (entry.status === 'D' || entry.type === 'deleted') paths.push(entry.path);
-        if (entry.status === 'R' && entry.sourcePath && entry.sourcePath !== entry.path) {
-            paths.push(entry.sourcePath);
-        }
-        for (const path of paths) {
-            const context = {
-                objectId: null,
-                mode: null,
-                transition: options.transition ?? entry.commit,
-                ...(options.allowMissingPolicy && path === '.aimhooman.json'
-                    ? { transientAllowRules: new Set(['generic.project-policy']) }
-                    : {}),
-            };
-            const findings = engine.checkPaths([path], context).filter((finding) => (
-                finding.matchedRuleIds?.some((ruleId) => (
-                    ruleId === 'generic.agent-instructions' || ruleId === 'generic.project-policy'
-                ))
-            ));
-            accumulator.add(findings.map((finding) => decorate(finding, entry, policy)));
-        }
+        // A deleted path is gone, so only structural policy rules (agent
+        // instructions, project policy) can still matter: deleting a secret or a
+        // session file is hygiene, not a violation. A renamed-away path is
+        // different — its content survives under a new name, so a path-only
+        // secret (e.g. .env) must still fire or a `git mv` to a neutral name
+        // would slip past the destination scan, which only catches content-shaped
+        // secrets. That finding is reported on the destination path (where the
+        // bytes now live) so clean-profile repair unstages the blob that carries
+        // the secret rather than the old name.
+        const deleted = entry.status === 'D' || entry.type === 'deleted';
+        const renamed = entry.status === 'R' && entry.sourcePath && entry.sourcePath !== entry.path;
+        if (!deleted && !renamed) continue;
+        const sourcePath = deleted ? entry.path : entry.sourcePath;
+        const context = {
+            objectId: null,
+            mode: null,
+            transition: options.transition ?? entry.commit,
+            ...(options.allowMissingPolicy && sourcePath === '.aimhooman.json'
+                ? { transientAllowRules: new Set(['generic.project-policy']) }
+                : {}),
+        };
+        const findings = engine.checkPaths([sourcePath], context).filter((finding) => {
+            if (finding.matchedRuleIds?.some((ruleId) => (
+                ruleId === 'generic.agent-instructions' || ruleId === 'generic.project-policy'
+            ))) return true;
+            return renamed && finding.category === 'secret';
+        });
+        accumulator.add(findings.map((finding) => decorate(
+            renamed && finding.category === 'secret' ? { ...finding, path: entry.path } : finding,
+            entry,
+            policy,
+        )));
     }
 }
 
@@ -441,7 +458,14 @@ export function engineForPolicy(
         [...reviewedInstructions, ...reviewedPolicies],
     );
     const diagnostics = loaded.errors.map((error) => ({ level: 'warning', message: `${error.message}; pack skipped` }));
-    return { engine: loaded.engine, diagnostics };
+    return { engine: loaded.engine, diagnostics, skipped: packSkipped(loaded.errors) };
+}
+
+// packSkipped turns rule-pack load failures into a counted skip reason. A pack
+// that never loaded is a hole in coverage, not an empty result: strict throws
+// above, and clean/compliance proceed but must not report a complete scan.
+function packSkipped(errors) {
+    return errors.length ? { 'local-pack-error': errors.length } : {};
 }
 
 function reviewedEngineEntry(entry, ruleId, transition) {
@@ -578,6 +602,10 @@ function rangeReportPolicy(basePolicy, policies, usedStrictFloor, explicitProfil
     };
 }
 
+// Skip reasons that mean a rule never ran, as opposed to a rule running and
+// matching nothing. Either way the scan cannot claim to have covered its input.
+const INCOMPLETE_SKIP_REASONS = new Set(['local-input-limit', 'local-pack-error']);
+
 function createAccumulator(limits = {}) {
     const effectiveLimits = { ...DEFAULT_SCAN_LIMITS, ...limits };
     const findings = [];
@@ -633,7 +661,7 @@ function createAccumulator(limits = {}) {
         addSkipped(skipped = {}) {
             for (const [reason, count] of Object.entries(skipped)) {
                 stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
-                if (reason === 'local-input-limit') complete = false;
+                if (INCOMPLETE_SKIP_REASONS.has(reason)) complete = false;
             }
         },
         markIncomplete() {