@lannguyensi/harness 0.42.0 → 0.44.0

package/dist/runtime/command-normalize.d.ts

@@ -0,0 +1,405 @@
+export interface NormalizedCommand {
+    /**
+     * The command with wrapper prefixes peeled and git invocations
+     * canonicalised to `git <subcommand>`. Shell boundary characters
+     * (`\n ; | && ( )`) are preserved verbatim so a boundary-anchored
+     * regex still matches. Byte-identical to the input when nothing
+     * recognisable was found anywhere in the command.
+     */
+    normalized: string;
+    /**
+     * The effective target directory of the command's git invocation, or
+     * `null` when the command names none, the command names invocations
+     * that disagree, or the only named value is `~`-prefixed (see the
+     * module header's target-directory-extraction rules).
+     *
+     * STILL NOT WIRED TO ANY GATE (see the module header's STATUS
+     * paragraph): extracted and fully tested, but task `98ad072f`'s
+     * per-policy redesign (T-003) attributes a target from the per-segment
+     * `segmentViewOf` view below instead of this whole-command aggregate —
+     * a single per-event `targetDir` cannot express "this invocation
+     * targets repo B, but the gated verb after it runs in the caller's
+     * cwd," which is exactly the property the redesign needs.
+     */
+    targetDir: string | null;
+    /**
+     * When `targetDir` is a RELATIVE path, the directory it should be
+     * resolved against instead of the caller's own cwd — the wrapping
+     * `env -C` on the same invocation, or a leading `cd` prefix (see the
+     * module header). `null` when `targetDir` is absolute, `null` itself,
+     * or no more specific base was found.
+     *
+     * Same unconsumed status as `targetDir` above — see the module
+     * header's STATUS paragraph.
+     */
+    targetBase: string | null;
+    /**
+     * `true` when the input exceeded `MAX_NORMALIZE_LENGTH` and
+     * normalisation was skipped entirely (G4 fix, review round 2,
+     * 2026-07-27): the caller previously had no way to tell "nothing
+     * recognisable was found" apart from "normalisation never ran at all",
+     * so the skip carried no audit signal. `false` whenever the input WAS
+     * run through `normalizeCommandInner` (including when nothing
+     * recognisable was found there either — that case is still `false`,
+     * only the length-bound short-circuit sets this).
+     */
+    truncated: boolean;
+}
+/**
+ * One boundary-delimited segment's canonicalised text plus its own and
+ * "effective" target directory (task `98ad072f`, T-002 of run
+ * `2026-08-02-per-repo-gate-scoping-redesign`) — attributes a target to
+ * the SPECIFIC segment satisfying a policy's own `bash_match` trigger,
+ * instead of the single, whole-command `targetDir` / `targetBase` on
+ * `NormalizedCommand` above. Produced by `segmentViewOf`. WIRED as of
+ * T-003, this run: `src/runtime/intercept.ts`'s `attributeTriggerSegments`
+ * / `resolveAttributedContexts` are the consumer (see the module header's
+ * STATUS/UPDATE note for the exact contract).
+ */
+export interface CommandSegment {
+    /**
+     * This segment's canonicalised text — the same rewrite
+     * `NormalizedCommand.normalized` applies to the corresponding span,
+     * boundary tokens EXCLUDED (they sit between segments, never inside
+     * one). Every shipped `bash_match` pattern's boundary alternation
+     * includes a `^` branch, so testing such a pattern against THIS string
+     * alone (no leading boundary character) is well-defined — see
+     * `01-plan.md`'s Proposed Approach item 2 for how a future consumer
+     * uses this.
+     */
+    text: string;
+    /**
+     * D-021 (UNIVERSAL-ADDITIVE, run 2026-08-02-per-repo-gate-scoping-
+     * redesign): the only remaining consumer of this field is
+     * `computeSegmentTarget`'s own internal `effectiveTarget` derivation
+     * (below) — `src/runtime/intercept.ts`'s `resolveAttributedContexts`
+     * (the gate) reads `effectiveTarget` only and no longer consults
+     * `ownTarget` at all. Kept as a public, separately-populated field
+     * (part of the T-002 API) rather than folded away, since a future
+     * consumer distinguishing "this segment's OWN explicit target" from
+     * "the directory it composes to once an incoming `cd` basis is
+     * accounted for" is exactly what the two-field split exists for.
+     *
+     * This segment's OWN explicit target, named by ITS OWN invocation
+     * only — a git invocation's REPO-RELOCATING global option ONLY: `-C` /
+     * `--git-dir` (or the SAME invocation's wrapping `env -C`, git-own-
+     * target-prioritised the same way `NormalizedCommand.targetDir` already
+     * is) — or, for a recognised bare `cd <path>` segment, the parsed path.
+     * Deliberately EXCLUDES `--work-tree` (D-017, fix round 2, run
+     * `2026-08-02-per-repo-gate-scoping-redesign`): `--work-tree` sets a
+     * git invocation's working tree but does NOT relocate its `--git-dir`
+     * search, so `git --work-tree=<B> push`/`log`/`status` still operate on
+     * whatever repo the invocation's ACTUAL directory names, never `<B>`
+     * alone — folding it into this field as though it were repo-identity-
+     * bearing (the pre-fix behaviour) let `resolveAttributedContexts`
+     * (`src/runtime/intercept.ts`, D-011) REPLACE the cwd demand with `<B>`'s
+     * on the strength of a flag that never moved the invocation there,
+     * measured as a live cross-repo fail-open. `null` when this segment
+     * names no repo-relocating target of its own (not a git invocation, not
+     * a `cd` segment, a bare git invocation, or a git invocation whose ONLY
+     * target-bearing flag is `--work-tree`) OR the named value is one of
+     * this view's unattributable forms: `~`-prefixed, carrying a stray quote
+     * character (the tokeniser is not quote-aware — a quoted value is
+     * captured WITH its quote character(s) still attached, not a real
+     * path), containing a command-substitution marker (`$(` or a backtick),
+     * or — for `cd` specifically — a bare `cd` with no argument or a `cd`
+     * with a flag (`cd -P /x`, three tokens instead of two). ALSO `null`
+     * when the SAME invocation names a git target via BOTH a relative own
+     * `-C` / `--git-dir` AND a wrapping `env -C` / `--chdir` base (`env -C
+     * /tmp/base git -C sub status`) — a mixed, internally ambiguous
+     * composition, unattributable for the same reason a relative own target
+     * after a preceding `cd` is (see `effectiveTarget` below); this is the
+     * ONE case where `ownTarget` itself, not just `effectiveTarget`, is
+     * nulled by a composition rule rather than by the raw value being
+     * unrecognisable on its own. A relative value (including `-C .`) and an
+     * absolute value are both otherwise preserved here verbatim, unresolved
+     * against any cwd — that resolution is a future consumer's job, not
+     * this module's. `git --git-dir=<A>/.git --work-tree=<B> ...`: this
+     * field is `<A>` (the `.git` parent) — `--git-dir` wins regardless of
+     * which flag appears first in the invocation, because `--work-tree`
+     * never contributes to this field at all, not because of any ordering
+     * rule between the two.
+     *
+     * ALSO `null` (D-018, fix round 3, pass-3 CRITICAL) when the invocation
+     * carries MORE THAN ONE recognised, resolved repo-relocating option:
+     * two-or-more `-C`, `-C` combined with `--git-dir`, `--git-dir` twice,
+     * or a same-invocation `env -C`/`--chdir` wrap whose target diverges
+     * from git's own ABSOLUTE `-C`/`--git-dir` target. Real git composes
+     * every one of these cumulatively (a later absolute value wins); this
+     * module does not encode that composition (same "not this module's
+     * job" reasoning as the relative-mix case above) and instead falls back
+     * to unattributable rather than trust the first flag it saw — `git -C
+     * <forge> -C <realA> push` actually runs in `<realA>`, but a first-
+     * flag-wins reading named `<forge>`, letting an agent redirect a gate's
+     * demanded evidence away from the repo the verb truly targets (measured
+     * against real git 2.34.1). An EXACT repeat of the same already-
+     * recorded value (`-C X -C X`, `env -C X git -C X`) is not new
+     * information and does not trigger this — see `peelGitGlobalOptions`'s
+     * `noteRelocatingOption` for the precise counting rule.
+     *
+     * D-021 (UNIVERSAL-ADDITIVE, operator decision, run 2026-08-02-per-
+     * repo-gate-scoping-redesign): the D-017/D-018 exclusions above (only a
+     * SINGLE recognised repo-relocating flag sets this field; `--work-tree`
+     * never does) are PRECISION, not the safety mechanism, since
+     * `src/runtime/intercept.ts`'s `resolveAttributedContexts` no longer
+     * REPLACES the cwd demand with this field's value — it ADDS to it, and
+     * the cwd demand is never dropped regardless of what this field
+     * resolves to. What these exclusions still prevent is a SPURIOUS extra
+     * demand (over-attributing a target the invocation does not actually,
+     * unambiguously name), not a dropped one — see that function's own doc
+     * comment for the full D-021 rationale.
+     */
+    ownTarget: string | null;
+    /**
+     * The directory this segment's own invocation actually runs in, once
+     * composed with the LAST PRECEDING recognised `cd <path>` segment in the
+     * same command (not necessarily the immediately preceding segment — any
+     * non-`cd` segment in between leaves the running cd-basis unchanged, the
+     * same way a non-`cd` shell command never itself changes the directory).
+     * Composition rules (`01-plan.md`, Proposed Approach item 1, verbatim):
+     *   - `ownTarget === null` → inherits the incoming cd-basis as-is
+     *     (including `null` when nothing preceding named one either).
+     *   - `ownTarget` absolute → itself, unconditionally — an absolute
+     *     value is never "relative to" anything a preceding `cd` named.
+     *   - `ownTarget` relative AND a preceding `cd` basis is known
+     *     (non-`null`) → `null`. This is the K1 divergence case
+     *     (`docs/okf/quote-model-divergence.md`): `cd T && git -C sub
+     *     status` does NOT become `T/sub` here — that would need real
+     *     filesystem-shaped path joining this module deliberately does not
+     *     perform — so it is UNATTRIBUTABLE rather than guessed at.
+     *   - `ownTarget` relative AND no preceding `cd` basis is known → the
+     *     raw relative value itself (deferred to a future consumer to
+     *     resolve against the real cwd).
+     * A same-invocation mixed `env -C <base>` + relative own `-C`/
+     * `--git-dir` composition (see `ownTarget` above — `--work-tree` is
+     * EXCLUDED from this mix entirely, D-017: it never sets `ownTarget`, so
+     * it can never trigger this ambiguity either) is `null` here TOO —
+     * checked BEFORE the cd-basis rules above and
+     * independently of them: `env -C /tmp/base git -C sub status` never
+     * becomes `/tmp/base/sub` (real path joining, deliberately not this
+     * module's job — same reasoning as the cd-basis K1 case) NOR does it
+     * fall through to the "relative, no cd basis, stays raw" branch above
+     * (that would hand a future consumer resolving relatives against ITS
+     * OWN cwd a CONFIDENTLY WRONG repository whenever the caller's cwd
+     * differs from `/tmp/base` — the "relative and `~` target dirs resolve
+     * to a confidently wrong repo" class named in the 07-27 review). A bare
+     * `env -C <base> git status` (no relative own target) is UNAFFECTED —
+     * `ownTarget` is `<base>` as usual, composed the ordinary way below.
+     * A recognised `cd <path>` segment whose OWN value is one of the
+     * unattributable forms above (e.g. `cd ~`) still RESETS the running
+     * cd-basis to `null` for every LATER segment — a later segment must not
+     * silently keep inheriting whatever basis existed BEFORE that `cd`,
+     * since the shell genuinely changed directory to somewhere this module
+     * cannot name.
+     *
+     * FULL reset-trigger list (D-014, fix round, run 2026-08-02-per-repo-
+     * gate-scoping-redesign — corrects this comment, which previously named
+     * only the unattributable-`cd`-value case above): the running basis
+     * resets to `null` — rather than the pre-fix behaviour of silently
+     * carrying an earlier basis forward unchanged — for ALL of: a bare `cd`
+     * with no argument, `cd -`, any other flagged `cd` (`cd -P /tmp/x`),
+     * `pushd`, `popd` (see `classifyCdSegment`), and the unattributable-
+     * `cd`-value case documented above. TWO of the reset triggers are NOT
+     * decided by this per-segment composition at all — they depend on the
+     * BOUNDARY a segment sits behind, which only the caller
+     * (`segmentAndCanonicalize`'s own walk) can see: the basis never
+     * crosses a bare `|` (each side of a pipe is bash's own subshell), and
+     * it resets after any segment whose text contains a `)` (a subshell
+     * close — `BOUNDARY_RE` has no `)` boundary of its own, so this is a
+     * substring check on the segment that happens to end there, not paren-
+     * depth tracking). See `segmentAndCanonicalize`'s own comment at its
+     * `computeSegmentTarget` call site for those two. NOT covered by any of
+     * this (same ceiling as before this fix round, unchanged): a `cd`
+     * inside a NESTED subshell that never closes within the command
+     * string's visible boundaries, and any construct outside this module's
+     * documented NOT-SUPPORTED list in the module header.
+     */
+    effectiveTarget: string | null;
+}
+/**
+ * The `git` token itself, matched by BASENAME so a path-qualified
+ * invocation (`/usr/bin/git`, `./git`) is recognised too (F4 fix).
+ * Anchored to the WHOLE token (not a substring) so `mygit` / `git-foo`
+ * still correctly fail to match — `\S*` only ever contributes characters
+ * immediately before a literal `/`, never before `git` directly.
+ * Exported (fix round 2, finding F3) so
+ * `tests/runtime/bash-match-head-token-drift.test.ts` can couple this
+ * module's covered set to what FULL_TEMPLATE's shipped `bash_match`
+ * policies actually key on today, instead of a test-owned duplicate.
+ */
+export declare const GIT_TOKEN_RE: RegExp;
+/**
+ * The three OTHER head tokens this module covers (D-001, run
+ * 2026-07-28-nongit-trigger-wrappers) — `gh` (`gh pr merge` / `gh pr
+ * create`), `npm` (`npm publish`), `harness` (the kill-switch verbs). A
+ * closed set, deliberately NOT a general "any head token" rule (see the
+ * module header): matched by EXACT literal equality, unlike `GIT_TOKEN_RE`'s
+ * basename match, so a path-qualified spelling of any of these three stays
+ * out of scope (named residual, module header NOT-SUPPORTED list). This is
+ * NOT the complete set of head tokens a shipped `bash_match` trigger keys
+ * on — see the module header's "SHIPPED BUT NOT COVERED" paragraph (fix
+ * round 2, finding F1) for the four that are NOT in this set (`env`,
+ * `unset`, `tee`, `cp`) and why. Exported (fix round 2, finding F3) for the
+ * same drift-guard reason as `GIT_TOKEN_RE` above.
+ */
+export declare const NON_GIT_HEAD_TOKENS: ReadonlySet<string>;
+/**
+ * Above this length, normalisation is skipped entirely and the command
+ * is returned unchanged (F3 fix — see the module header for why command
+ * SIZE must be bounded even after `findNextBoundary` was made linear).
+ * 100k characters comfortably covers any command a human or agent would
+ * plausibly type, while keeping the worst case a small constant instead
+ * of scaling with whatever ends up pasted into a single Bash call.
+ * Exported (G4 fix, review round 2) so a caller reporting the skip (see
+ * `NormalizedCommand.truncated`) can reference the same number instead of
+ * hand-copying it into a diagnostic message.
+ */
+export declare const MAX_NORMALIZE_LENGTH = 100000;
+/**
+ * Second boundary alphabet (task aabbad63): identical to `BOUNDARY_RE`
+ * plus a bare `&` — bash's OWN "start a new command here" token, which
+ * every shipped `bash_match` trigger regex has treated as one of its own
+ * anchor characters since task `d834a065`, but which `BOUNDARY_RE` above
+ * has never recognised as a NORMALISATION-time boundary (see its comment
+ * for the reverted, measured-140/140-regression attempt to add it there
+ * directly).
+ *
+ * ALTERNATION ORDER IS LOAD-BEARING: `&&` MUST be listed to the LEFT of
+ * the bare `&` alternative. JS regex alternation is leftmost-FIRST, not
+ * leftmost-longest — with `&` tried before `&&`, every `&&` in a command
+ * would tokenise as TWO consecutive one-character `&` boundary MATCHES
+ * instead of a single two-character `&&` boundary match.
+ *
+ * MEASURED, NOT ASSUMED (do not "simplify" the pin below to an
+ * end-to-end `.normalized` string assertion): for THIS module's segment-
+ * and-rejoin architecture specifically, that reordering is, perhaps
+ * counter-intuitively, INVISIBLE in `normalizeCommandAmpAware`'s own
+ * output string. Two adjacent single-`&` matches sandwich a genuinely
+ * zero-length segment between them (the two `&` characters of a real
+ * `&&` are, by definition, adjacent), `canonicalizeSegment("")` is a
+ * verbatim no-op, and `parts.join("")` reassembles the exact same bytes
+ * either way — verified directly (not merely reasoned about) by
+ * temporarily swapping this alternation's order, rebuilding, and
+ * diffing `normalizeCommandAmpAware(...).normalized` across several
+ * `&&`-bearing commands (including this comment's own `git -C
+ * /tmp/repoB status && git -C /tmp/repoB log` example): byte-identical
+ * output both ways. So a test asserting on the OUTPUT STRING alone
+ * cannot distinguish the two orderings for this architecture — the pin
+ * in `tests/runtime/command-normalize.test.ts` therefore execs this
+ * regex object DIRECTLY against a `&&`-bearing string and asserts the
+ * match text is `"&&"`, not `"&"`, which DOES fail under a swap. The
+ * order is still specified exactly as documented above (leftmost-first
+ * is real JS semantics, and the internal `segmentAndCanonicalize`
+ * bookkeeping this alphabet ALSO drives — `hasAmbiguousNonGitSegment`,
+ * discarded by `normalizeCommandAmpAware` but not by a hypothetical
+ * future consumer of `segmentAndCanonicalize` under this alphabet —
+ * would still see a spurious extra "non-git segment" under the wrong
+ * order), it just cannot be pinned through this module's ONE exposed
+ * string alone.
+ *
+ * Used ONLY by `normalizeCommandAmpAware` below, which is consulted ONLY
+ * as `policyMatchesEvent`'s third, additional matching arm — see that
+ * function's own comment for why its result never carries a `targetDir`/
+ * `targetBase`, and `src/runtime/intercept.ts` for the memoised-thunk
+ * threading that keeps this off the common (raw-or-normalised-already-
+ * matched) path. Exported (mirrors `GIT_TOKEN_RE` / `NON_GIT_HEAD_TOKENS`
+ * / `MAX_NORMALIZE_LENGTH` above) solely so the ordering pin test can
+ * exec it directly instead of re-declaring an equivalent regex literal
+ * that would test JS semantics in general, not THIS source's actual
+ * alternation.
+ */
+export declare const AMP_BOUNDARY_RE: RegExp;
+/**
+ * Given a Bash command string, return its normalised form and the target
+ * directory (and base, if relative) of its git invocation. Never throws:
+ * any internal failure (there should be none — this is a defensive
+ * backstop matching the fail-safe shape used elsewhere in this codebase,
+ * e.g. `policyMatchesEvent`'s `try/catch` around `new RegExp`) falls back
+ * to the input unchanged.
+ */
+export declare function normalizeCommand(command: string): NormalizedCommand;
+/**
+ * Given a Bash command string, return its per-segment view (task
+ * `98ad072f` groundwork, T-002) — see `CommandSegment`'s own doc comment
+ * for the field-level composition rules. `null` when the input exceeded
+ * `MAX_NORMALIZE_LENGTH` (mirrors `NormalizedCommand.truncated`, but as
+ * the ABSENCE of a view rather than a boolean flag alongside one, since
+ * there is no meaningful per-segment view to return for an input whose
+ * normalisation itself was skipped). `[]` for an empty or non-string
+ * command, and as the never-throws fallback (mirrors `normalizeCommand`'s
+ * own defensive backstop — see its doc comment above).
+ *
+ * THIS function's OWN call into `segmentAndCanonicalize` (`collectSegments:
+ * true`) is one walk, O(length) — the "no additional pass" claim is scoped
+ * to that ONE call, not to a caller's total work. CORRECTED (D-015, fix
+ * round, run 2026-08-02-per-repo-gate-scoping-redesign) — the prior wording
+ * here read "no additional pass over the command string" without that
+ * scoping, which a reader could take as "calling this costs nothing beyond
+ * `normalizeCommand`'s own walk." Measured false: `normalizeCommand(cmd)`
+ * and `segmentViewOf(cmd)` are two SEPARATE top-level calls, each running
+ * its own full `segmentAndCanonicalize` pass over the SAME string — a
+ * caller needing both (as `src/cli/policy/intercept.ts` does, for
+ * `normalized`/`truncated` and the segment view respectively) pays TWO
+ * walks, not one; measured +206% at the `MAX_NORMALIZE_LENGTH` bound
+ * (2.73 → 8.36 ms), harmless against the 1000 ms hook budget but not free.
+ * As of the same fix round, the one production caller only pays this
+ * second walk lazily, when some matching policy actually needs it (see
+ * `InterceptOptions.commandSegmentsThunk` in `src/runtime/intercept.ts`) —
+ * but that laziness lives in the CALLER, not in this function, which still
+ * does exactly one walk every time it runs. The ampersand-aware second pass
+ * (`normalizeCommandAmpAware`) NEVER collects a segment view (always calls
+ * `segmentAndCanonicalize` with `collectSegments: false`) — see that
+ * function's own comment for why a directory extracted under the
+ * ampersand-aware alphabet would be unreliable in the first place; the
+ * same reasoning applies here, so this module offers no amp-aware variant
+ * of this function at all.
+ */
+export declare function segmentViewOf(command: string): CommandSegment[] | null;
+/**
+ * Return type of `normalizeCommandAmpAware` — deliberately NOT
+ * `NormalizedCommand` (task aabbad63, hard constraint). It carries only
+ * `normalized`/`truncated`; there is no `targetDir`/`targetBase` field at
+ * all, so a future caller cannot wire one up to a gate by mistake — see
+ * `normalizeCommandAmpAware`'s own comment for why a directory extracted
+ * under the ampersand-aware alphabet would be unreliable in the first
+ * place, not merely "unwired today".
+ */
+export interface AmpAwareNormalizedCommand {
+    /** Same contract as `NormalizedCommand.normalized`, under `AMP_BOUNDARY_RE`. */
+    normalized: string;
+    /** Same contract as `NormalizedCommand.truncated`. */
+    truncated: boolean;
+}
+/**
+ * Ampersand-aware SECOND normalisation pass (task aabbad63). Segments the
+ * command under `AMP_BOUNDARY_RE` (`BOUNDARY_RE` plus a bare `&`) instead
+ * of `BOUNDARY_RE`, then canonicalises exactly like the primary pass
+ * (same `canonicalizeSegment`, same wrapper-peeling rules, same
+ * `MAX_NORMALIZE_LENGTH` bound). Closes the gap `BOUNDARY_RE`'s own
+ * comment names: `A=x&env -C /tmp git status` and `echo hi & nice git
+ * status` were ungated because a wrapper can only be peeled after a
+ * recognised boundary, and a bare `&` was not one.
+ *
+ * Return type deliberately has NO `targetDir`/`targetBase` — not merely
+ * "always null under this alphabet", genuinely ABSENT from the type, so
+ * no consumer can read one by mistake. Reason: a bare `&` is ALSO how
+ * bash spells a background job (`git -C /x push &`) and how a redirect
+ * merges streams (`git -C /x log 2>&1`, `... &> out`). Under THIS
+ * alphabet each of those splits into a spurious extra "segment", which
+ * `segmentAndCanonicalize`'s own non-git-segment ambiguity rule (a
+ * segment that starts a new command and is not itself a git invocation
+ * forces `targetDir` to `null` — see its G1 comment) would turn into a
+ * wrong-shaped loss for a case the PRIMARY pass still resolves correctly
+ * today. Pinned in `tests/runtime/command-normalize.test.ts`'s "aabbad63
+ * groundwork" describe block, which exercises ONLY `normalizeCommand`
+ * (the primary pass), never this function — `targetDir`/`targetBase`
+ * stay the primary pass's property alone.
+ *
+ * Only consulted by `policyMatchesEvent`'s third arm
+ * (`src/runtime/intercept.ts`), and only when a policy's `bash_match`
+ * regex has already missed BOTH the raw command and the primary
+ * normalised form — see that module and `src/cli/policy/intercept.ts`
+ * for the memoised-thunk threading that keeps this computation off the
+ * common (already-matched) path.
+ */
+export declare function normalizeCommandAmpAware(command: string): AmpAwareNormalizedCommand;