@cad0p/pi-steering 0.1.0

package/dist/plugins/git/predicates.js

@@ -0,0 +1,580 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Predicate handlers for the git plugin.
+ *
+ * Each handler is a `PredicateHandler<A>` where `A` is the
+ * plugin-author-facing argument shape the rule passes under the
+ * matching `when.<key>` slot. See each handler's JSDoc for the
+ * accepted shape and worked examples.
+ *
+ * Evaluation strategy:
+ *
+ *   - `branch`           - read `ctx.walkerState.branch` first (set by
+ *                           the branch tracker on in-chain checkouts).
+ *                           If the tracker resolved statically, use
+ *                           that value. If the tracker reports
+ *                           `"unknown"` (dynamic checkout like
+ *                           `git checkout $VAR` that the walker
+ *                           couldn't resolve), apply `onUnknown`
+ *                           policy without falling back to `exec` -
+ *                           a `git branch --show-current` call would
+ *                           return the PRE-checkout branch and
+ *                           silently defeat the walker. If no
+ *                           tracker state exists (no checkout in
+ *                           chain), shell out via `git branch
+ *                           --show-current`.
+ *   - `upstream`         - no tracker today; always shell out via
+ *                           `git rev-parse --abbrev-ref @{upstream}`.
+ *                           Inlines a {@link cwdIsWalkerUnknown} guard
+ *                           so walker-unknown cwd surfaces trinary
+ *                           `"unknown"` instead of shelling against
+ *                           the pi session cwd — the engine's
+ *                           `onUnknown:` policy then projects to a
+ *                           definite verdict (default `"block"` =
+ *                           fail-CLOSED).
+ *   - `commitsAhead`     - shell out via `git rev-list --count`.
+ *                           Inlines the same walker-unknown guard as
+ *                           `upstream`.
+ *   - `hasStagedChanges` - shell out via `git diff --cached --quiet`.
+ *   - `isClean`          - shell out via `git status --porcelain`.
+ *   - `remote`           - shell out via `git config --get
+ *                           remote.origin.url`.
+ *
+ * `ctx.exec` is memoized per `(cmd, args, cwd)` within one tool_call
+ * (see the evaluator's `createExecCache`) so multiple rules reading
+ * the same git state don't re-fork git.
+ *
+ * `onUnknown` policy for string-valued predicates (`branch`,
+ * `upstream`, `remote`): fail-closed by default. When the underlying
+ * query fails (not a repo, no upstream configured, ...), the predicate
+ * reports "match" so the rule fires. Rule authors opt into the
+ * "allow-through" behavior explicitly by passing
+ * `{ pattern, onUnknown: "allow" }`.
+ */
+import { isPattern } from "../../internal/pattern-utils.js";
+import { NO_CHECKOUT_IN_CHAIN } from "./branch-tracker.js";
+import { getCommitsAhead, getRemoteUrl, getStagedChanges, getUpstream, getWorkingTreeClean, } from "./git-ops.js";
+// ---------------------------------------------------------------------------
+// Walker-unknown cwd guard (inline trinary)
+// ---------------------------------------------------------------------------
+/**
+ * Inline trinary guard for runtime-cwd predicates: returns `true` when
+ * the walker couldn't statically resolve the command's effective cwd
+ * (the cwd-tracker `"unknown"` sentinel is on `ctx.walkerState.cwd`),
+ * which signals to the caller that the handler should bail with
+ * `"unknown"` instead of querying the wrong repo.
+ *
+ * Each runtime-cwd handler in this module starts with:
+ *
+ *   ```ts
+ *   if (cwdIsWalkerUnknown(ctx)) return "unknown";
+ *   ```
+ *
+ * Surfacing walker-unknown as trinary `"unknown"` lets the engine
+ * apply the leaf-level (or block-level, inside `not:`) `onUnknown:`
+ * policy. Default `"block"` is fail-CLOSED (the rule fires); a user
+ * with `onUnknown: "allow"` opts into fail-OPEN handling.
+ * Self-documenting + composable.
+ */
+function cwdIsWalkerUnknown(ctx) {
+    return ctx.walkerState?.cwd === "unknown";
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/**
+ * Normalize the shorthand forms accepted by the pattern-valued
+ * predicates (`branch`, `upstream`, `remote`) into a canonical
+ * `{ patterns, onUnknown }` shape:
+ *
+ *   - `Pattern`                                  -> `{ patterns: [pattern], onUnknown: "block" }`
+ *   - `Pattern[]`  (non-empty, all-Pattern)      -> `{ patterns, onUnknown: "block" }`
+ *   - `{ pattern: Pattern, onUnknown? }`         -> object used as-is,
+ *                                                    `pattern` re-wrapped
+ *                                                    into a single-element
+ *                                                    array; `onUnknown`
+ *                                                    defaults to `"block"`.
+ *   - `{ pattern: Pattern[], onUnknown? }`       -> array preserved,
+ *                                                    same `onUnknown`
+ *                                                    handling.
+ *
+ * Array semantics are OR-of-matches: the rule fires when the input
+ * matches ANY of the listed patterns. Array form requires at least
+ * one pattern (empty arrays are invalid).
+ *
+ * Returning `null` means the author supplied something that isn't a
+ * valid value for this predicate (e.g. a bare number, an empty array,
+ * or an array containing a non-Pattern value); handlers treat that as
+ * a non-match and don't throw - invalid config shouldn't crash the
+ * evaluator, but it also shouldn't silently fire.
+ */
+function unwrapPatternArg(value) {
+    // Shorthand: single Pattern.
+    if (isPattern(value)) {
+        return { patterns: [value], onUnknown: "block" };
+    }
+    // Shorthand: Pattern[] (must be non-empty + all-Pattern).
+    if (Array.isArray(value) && value.every(isPattern)) {
+        if (value.length === 0)
+            return null;
+        return { patterns: value, onUnknown: "block" };
+    }
+    // Object form: { pattern: Pattern | Pattern[]; onUnknown? }.
+    if (value !== null &&
+        typeof value === "object" &&
+        "pattern" in value) {
+        const obj = value;
+        const onUnknown = obj.onUnknown === "allow" ? "allow" : "block";
+        if (isPattern(obj.pattern)) {
+            return { patterns: [obj.pattern], onUnknown };
+        }
+        if (Array.isArray(obj.pattern) && obj.pattern.every(isPattern)) {
+            if (obj.pattern.length === 0)
+                return null;
+            return { patterns: obj.pattern, onUnknown };
+        }
+    }
+    return null;
+}
+/** Test a Pattern against a concrete string. */
+function matchPattern(pattern, target) {
+    if (pattern instanceof RegExp)
+        return pattern.test(target);
+    return new RegExp(pattern).test(target);
+}
+/**
+ * Apply the predicate's `onUnknown` policy to a shell failure or
+ * tracker-unknown case. "block" means the predicate reports "match"
+ * (rule fires); "allow" means the predicate reports "no match" (rule
+ * skips). Fail-closed default.
+ */
+function unknownVerdict(onUnknown) {
+    return onUnknown === "block";
+}
+/**
+ * Unwrap the boolean payload from a {@link PredicateShape}<boolean>
+ * argument. Accepts the bare form (`true` / `false`) and the
+ * spread form (`{ value: true, onUnknown? }` /
+ * `{ value: false, onUnknown? }`); the engine's `readLeafOnUnknown`
+ * reads any `onUnknown:` sibling and `projectVerdict` applies the
+ * policy to the handler's `"unknown"` returns. The handler itself
+ * treats `onUnknown:` as an opaque sibling field and only consumes
+ * `value:`.
+ *
+ * Returns `undefined` on malformed input — the caller decides what
+ * to do with that (typically `return false`, mirroring the existing
+ * pattern-unwrap fail-closed contract).
+ *
+ * Used by {@link isClean} and {@link hasStagedChanges}; both ship
+ * with `PredicateShape<boolean>` in the registry so the bare/spread
+ * shape is identical at the type level too.
+ *
+ * @internal
+ */
+function unwrapBooleanLeafArg(args) {
+    if (typeof args === "boolean")
+        return args;
+    if (args !== null &&
+        typeof args === "object" &&
+        typeof args.value === "boolean") {
+        return args.value;
+    }
+    return undefined;
+}
+/**
+ * Test-internal export of {@link unwrapBooleanLeafArg}. Module-private
+ * by intent; the `@internal` JSDoc tag (TypeScript ecosystem-standard)
+ * flags "not part of the public surface" and the underscore prefix
+ * mirrors the convention so external consumers can grep-discover it
+ * too. Direct unit tests pin malformed-input branches that are hard
+ * to drive via the engine end-to-end.
+ *
+ * @internal
+ */
+export const _unwrapBooleanLeafArg = unwrapBooleanLeafArg;
+/**
+ * Direct one-shot git exec used only by the `branch` predicate's
+ * tracker-missing fallback (the predicate's three-way tracker
+ * discrimination stays in predicate-land; see the `branch` JSDoc
+ * below AND `./git-ops.ts` file header "Branch caveat" for why
+ * `getBranch` is NOT called here).
+ * Other predicates delegate to helpers in `./git-ops.ts` and don't
+ * need this.
+ *
+ * Mirrors the failure-collapse contract of `tryGit` in git-ops:
+ * non-zero exit, spawn error, or thrown exception → `null`.
+ */
+async function tryExec(ctx, cmd, args, cwd) {
+    try {
+        const res = await ctx.exec(cmd, [...args], cwd !== undefined ? { cwd } : undefined);
+        if (res.exitCode !== 0)
+            return null;
+        return res.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a string tracker value from `ctx.walkerState[key]` into a
+ * three-state discriminated result. See {@link WalkerStringResult}
+ * for why callers must not conflate `unknown` with `missing`.
+ *
+ * `initialSentinel` is the tracker's initial value (distinct from
+ * its `unknown` sentinel). When `walkerState[key]` equals this
+ * sentinel, the result is `missing` - no modifier fired for this
+ * dimension in this ref's scope.
+ */
+export function walkerString(ctx, key, initialSentinel) {
+    // Guard against a tracker that reuses `"unknown"` as its initial
+    // sentinel. Accepting such a value here would silently collapse the
+    // three-way discrimination back into the pre-U1 two-step: the
+    // `missing` branch would swallow genuine dynamic-checkout signals
+    // and the predicate would exec-fallback onto the PRE-checkout
+    // branch — exactly the bug U1 exists to prevent. The JSDoc on
+    // WalkerStringResult documents this; the assertion makes the
+    // contract un-foot-shootable for new tracker authors.
+    if (initialSentinel === "unknown") {
+        throw new Error(`[pi-steering/git] walkerString: tracker initialSentinel cannot be ` +
+            `"unknown" — it's reserved for the unresolvable-dynamic-value ` +
+            `signal. Use a distinct initial value (e.g. "" or a sentinel ` +
+            `like NO_CHECKOUT_IN_CHAIN). See WalkerStringResult JSDoc.`);
+    }
+    const v = ctx.walkerState?.[key];
+    if (typeof v !== "string")
+        return { kind: "missing" };
+    if (v === initialSentinel)
+        return { kind: "missing" };
+    if (v === "unknown")
+        return { kind: "unknown" };
+    return { kind: "value", value: v };
+}
+// ---------------------------------------------------------------------------
+// branch
+// ---------------------------------------------------------------------------
+/**
+ * `when.branch` - match the current git branch.
+ *
+ * Accepted arg shapes:
+ *
+ *   ```ts
+ *   when: { branch: /^main$/ }                                  // single Pattern
+ *   when: { branch: "^feat-" }                                   // single Pattern (string)
+ *   when: { branch: [/^main$/, /^master$/, /^trunk$/] }          // Pattern[] (any-of)
+ *   when: { branch: { pattern: /^main$/, onUnknown: "allow" } }  // object form
+ *   when: { branch: { pattern: [/^main$/, /^master$/], onUnknown: "allow" } }
+ *   ```
+ *
+ * Array semantics: OR-of-matches (rule fires when the resolved
+ * branch matches ANY of the listed patterns). Empty arrays are
+ * invalid (rule skips); arrays containing non-Pattern values are
+ * invalid (rule skips).
+ *
+ * Resolution order:
+ *   1. `ctx.walkerState.branch` - set by the branch tracker when the
+ *       current bash chain contains `git checkout` / `git switch`.
+ *       Three outcomes:
+ *         - value resolved statically (e.g. `git checkout main`) ->
+ *           match the pattern against it.
+ *         - `"unknown"` sentinel (dynamic checkout like `git checkout
+ *           $VAR`) -> apply `onUnknown` policy. Do NOT fall through
+ *           to exec: a `git branch --show-current` call here would
+ *           return the PRE-checkout branch (the walker exists to
+ *           track exactly this kind of in-chain change statically).
+ *         - missing (no checkout in chain) -> fall through to exec.
+ *   2. `git branch --show-current` in `ctx.cwd`. Empty stdout is
+ *       treated as "no branch" (detached HEAD) - the predicate falls
+ *       back to `onUnknown`.
+ *
+ * `onUnknown` default is `"block"` (fail-closed): if we can't
+ * determine the branch, the predicate reports "match" so
+ * branch-gated rules still fire.
+ */
+export const branch = async (value, ctx) => {
+    const arg = unwrapPatternArg(value);
+    if (arg === null)
+        return false;
+    // 1. Walker state (tracker-resolved mid-command).
+    const fromWalker = walkerString(ctx, "branch", NO_CHECKOUT_IN_CHAIN);
+    if (fromWalker.kind === "value") {
+        return arg.patterns.some((p) => matchPattern(p, fromWalker.value));
+    }
+    if (fromWalker.kind === "unknown") {
+        // Dynamic in-chain checkout. Exec would return the PRE-checkout
+        // branch, which is the case the walker exists to catch. Apply
+        // the predicate's `onUnknown` policy instead of falling through.
+        return unknownVerdict(arg.onUnknown);
+    }
+    // 2. Shell out (tracker saw no in-chain checkout).
+    const out = await tryExec(ctx, "git", ["branch", "--show-current"], ctx.cwd);
+    if (out === null || out.length === 0)
+        return unknownVerdict(arg.onUnknown);
+    return arg.patterns.some((p) => matchPattern(p, out));
+};
+// ---------------------------------------------------------------------------
+// upstream
+// ---------------------------------------------------------------------------
+/**
+ * `when.upstream` - match the current branch's configured upstream.
+ *
+ * Accepted arg shapes: same as {@link branch}.
+ *
+ * Resolves via `git rev-parse --abbrev-ref @{upstream}`. A branch
+ * without an upstream set returns a non-zero exit; the predicate then
+ * applies `onUnknown`.
+ *
+ * No tracker today - upstream configuration isn't changed by in-chain
+ * git commands at a rate that justifies modelling it (and `git push
+ * -u origin main` changes it but only AFTER the push succeeds, which
+ * is past the point where a pre-execution guard would act). The
+ * per-tool_call exec cache ensures multiple upstream-gated rules share
+ * one git call.
+ *
+ * Runtime-cwd guard: `getUpstream` shells out at `ctx.cwd`. When the
+ * walker surfaces `ctx.walkerState.cwd === "unknown"` (dynamic
+ * `cd "$VAR/pkg"` the walker couldn't resolve), the exec would run
+ * against the pi session cwd — the wrong repo — and a user who opted
+ * into `onUnknown: "allow"` would get a silent fail-OPEN. The handler
+ * inlines a {@link cwdIsWalkerUnknown} check at the top and surfaces
+ * trinary `"unknown"`; the engine's leaf-level (outer) or block-level
+ * (inside `not:`) `onUnknown:` policy then projects to the right
+ * boolean (default `"block"` = fail-CLOSED).
+ *
+ * @see walkerUnknownCwdReason — compose the agent-facing reason text
+ *      for the walker-unknown-cwd fail-closed branch in your rule's
+ *      ReasonFn.
+ */
+export const upstream = async (value, ctx) => {
+    if (cwdIsWalkerUnknown(ctx))
+        return "unknown";
+    const arg = unwrapPatternArg(value);
+    if (arg === null)
+        return false;
+    const out = await getUpstream(ctx);
+    if (out === null)
+        return unknownVerdict(arg.onUnknown);
+    return arg.patterns.some((p) => matchPattern(p, out));
+};
+/**
+ * `when.commitsAhead` - match when commits-ahead-of-WRT satisfy every
+ * supplied comparator.
+ *
+ * Returns `false` (rule doesn't fire) when:
+ *   - the arg shape isn't an object with at least one of `eq` / `gt`
+ *     / `lt`,
+ *   - the `git rev-list` call fails,
+ *   - the comparator chain doesn't match.
+ *
+ * No `onUnknown` here: commits-ahead is a numeric comparator, not a
+ * pattern match, and "I couldn't learn the answer" arguably shouldn't
+ * fire a rule that's gated on a specific count. Authors who want the
+ * fail-closed behavior can layer `{ upstream: "..." }` first in the
+ * same `when` (AND semantics via the ADR's plugin predicates) - that
+ * handles the "no upstream" case with explicit `onUnknown`.
+ *
+ * Runtime-cwd guard: `getCommitsAhead` shells out at `ctx.cwd`. When
+ * the walker surfaces `ctx.walkerState.cwd === "unknown"`, the exec
+ * would run against the pi session cwd — wrong repo — and the
+ * `count === null` failure path returns `false`, silently skipping
+ * the rule (fail-OPEN). The handler inlines a
+ * {@link cwdIsWalkerUnknown} check at the top and surfaces trinary
+ * `"unknown"`; the engine's `onUnknown:` policy then projects to the
+ * right boolean (default `"block"` = fail-CLOSED, matching the policy
+ * used by the other runtime-cwd predicates in this plugin).
+ *
+ * @see walkerUnknownCwdReason — compose the agent-facing reason text
+ *      for the walker-unknown-cwd fail-closed branch in your rule's
+ *      ReasonFn.
+ * @see PiSteeringPredicates.commitsAhead — the registry entry that
+ *      declares the bare / spreadBase shape this handler dispatches
+ *      on.
+ */
+export const commitsAhead = async (args, ctx) => {
+    if (cwdIsWalkerUnknown(ctx))
+        return "unknown";
+    // Schema advertises `PredicateShape<number, { eq?, gt?, lt?, wrt? }>`
+    // — bare-number `commitsAhead: N` is sugar for `{ eq: N }`.
+    let eq;
+    let gt;
+    let lt;
+    let wrt = "@{upstream}";
+    if (typeof args === "number") {
+        eq = args;
+    }
+    else if (args !== null && typeof args === "object") {
+        const shape = args;
+        eq = shape.eq;
+        gt = shape.gt;
+        lt = shape.lt;
+        wrt = shape.wrt ?? "@{upstream}";
+    }
+    else {
+        return false;
+    }
+    if (eq === undefined && gt === undefined && lt === undefined) {
+        return false;
+    }
+    const count = await getCommitsAhead(ctx, wrt);
+    if (count === null)
+        return false;
+    if (eq !== undefined && count !== eq)
+        return false;
+    if (gt !== undefined && !(count > gt))
+        return false;
+    if (lt !== undefined && !(count < lt))
+        return false;
+    return true;
+};
+// ---------------------------------------------------------------------------
+// hasStagedChanges
+// ---------------------------------------------------------------------------
+/**
+ * `when.hasStagedChanges` - match on the presence / absence of staged
+ * changes in the repo at `ctx.cwd`.
+ *
+ *   - `when: { hasStagedChanges: true }`  - fires when there ARE staged
+ *     changes.
+ *   - `when: { hasStagedChanges: false }` - fires when there are NOT.
+ *
+ * Uses `git diff --cached --quiet`: exit 0 = no staged changes, exit
+ * 1 = staged changes exist. On any other exit / spawn failure, we
+ * conservatively report `false` - the caller can AND this with an
+ * `upstream` check if fail-closed behavior is needed.
+ *
+ * Runtime-cwd guard: the underlying `git diff --cached` call runs
+ * at `ctx.cwd`. When the walker surfaces `ctx.walkerState.cwd ===
+ * "unknown"` (dynamic `cd "$VAR/pkg"` the walker couldn't resolve),
+ * `ctx.cwd` falls back to the pre-cd ambient cwd — the PI session
+ * cwd, not the intended subpackage. The handler inlines a
+ * {@link cwdIsWalkerUnknown} check at the top and surfaces trinary
+ * `"unknown"`; the engine's `onUnknown:` policy then projects to the
+ * right boolean (default `"block"` = fail-CLOSED).
+ *
+ * @see walkerUnknownCwdReason — compose the agent-facing reason text
+ *      for the walker-unknown-cwd fail-closed branch in your rule's
+ *      ReasonFn.
+ * @see PiSteeringPredicates.hasStagedChanges — the registry entry
+ *      that declares the bare / spreadBase shape this handler
+ *      dispatches on.
+ */
+export const hasStagedChanges = async (args, ctx) => {
+    if (cwdIsWalkerUnknown(ctx))
+        return "unknown";
+    // Schema's `PredicateShape<boolean>` auto-detects spreadBase to
+    // `{ value: boolean; onUnknown? }`; unwrap consumes `value:` only.
+    // Authors attach modifiers via `{ value: true, onUnknown: "allow" }`;
+    // the engine reads any `onUnknown:` sibling via readLeafOnUnknown
+    // and projects the handler's `"unknown"` returns under that policy
+    // (the handler itself treats `onUnknown:` as an opaque sibling field).
+    const expected = unwrapBooleanLeafArg(args);
+    if (expected === undefined)
+        return false;
+    const state = await getStagedChanges(ctx);
+    if (state === null)
+        return false; // unknown — don't fire
+    return expected === state;
+};
+// ---------------------------------------------------------------------------
+// isClean
+// ---------------------------------------------------------------------------
+/**
+ * `when.isClean` - match on the working tree's cleanliness at
+ * `ctx.cwd`.
+ *
+ *   - `when: { isClean: true }`  - fires when the working tree is
+ *     clean (no unstaged, no untracked, no staged changes).
+ *   - `when: { isClean: false }` - fires when the working tree is
+ *     dirty.
+ *
+ * Uses `git status --porcelain`: empty stdout = clean. Non-zero exit
+ * returns `false` (unknown); pair with an `upstream` check for
+ * fail-closed behavior.
+ *
+ * Runtime-cwd guard: same rationale as {@link hasStagedChanges} — the
+ * handler inlines a {@link cwdIsWalkerUnknown} check at the top and
+ * surfaces trinary `"unknown"` when the walker couldn't statically
+ * resolve the command's effective cwd, rather than silently running
+ * `git status` at the pi session cwd.
+ *
+ * @see walkerUnknownCwdReason — compose the agent-facing reason text
+ *      for the walker-unknown-cwd fail-closed branch in your rule's
+ *      ReasonFn.
+ * @see PiSteeringPredicates.isClean — the registry entry that
+ *      declares the bare / spreadBase shape this handler dispatches
+ *      on.
+ */
+export const isClean = async (args, ctx) => {
+    if (cwdIsWalkerUnknown(ctx))
+        return "unknown";
+    // Schema's `PredicateShape<boolean>` auto-detects spreadBase to
+    // `{ value: boolean; onUnknown? }`; unwrap consumes `value:` only.
+    // Authors attach modifiers via `{ value: true, onUnknown: "allow" }`;
+    // the engine reads any `onUnknown:` sibling via readLeafOnUnknown
+    // and projects the handler's `"unknown"` returns under that policy
+    // (the handler itself treats `onUnknown:` as an opaque sibling field).
+    const expected = unwrapBooleanLeafArg(args);
+    if (expected === undefined)
+        return false;
+    const clean = await getWorkingTreeClean(ctx);
+    if (clean === null)
+        return false;
+    return expected === clean;
+};
+// ---------------------------------------------------------------------------
+// remote
+// ---------------------------------------------------------------------------
+/**
+ * `when.remote` - match the repo's `origin` remote URL.
+ *
+ * Accepted arg shapes: same as {@link branch}. Useful for rules that
+ * should only fire in specific repos ("never force-push to
+ * github.com/org/prod").
+ *
+ * Resolves via `git config --get remote.origin.url`. Non-zero exit
+ * (no origin configured) falls back to `onUnknown`.
+ *
+ * Runtime-cwd guard: the handler inlines a {@link cwdIsWalkerUnknown}
+ * check at the top and surfaces trinary `"unknown"` when the walker
+ * couldn't statically resolve the command's effective cwd — querying
+ * the wrong repo's remote would silently mis-route a repo-gated rule.
+ * Same rationale as {@link hasStagedChanges}.
+ *
+ * @see walkerUnknownCwdReason — compose the agent-facing reason text
+ *      for the walker-unknown-cwd fail-closed branch in your rule's
+ *      ReasonFn.
+ */
+export const remote = async (value, ctx) => {
+    if (cwdIsWalkerUnknown(ctx))
+        return "unknown";
+    const arg = unwrapPatternArg(value);
+    if (arg === null)
+        return false;
+    const out = await getRemoteUrl(ctx);
+    if (out === null)
+        return unknownVerdict(arg.onUnknown);
+    return arg.patterns.some((p) => matchPattern(p, out));
+};
+// ---------------------------------------------------------------------------
+// Plugin-level export
+// ---------------------------------------------------------------------------
+/**
+ * Bundle of predicate handlers the git plugin registers under
+ * `Plugin.predicates`. Keys become the `when.<key>` slots rule authors
+ * see.
+ *
+ * Typed as `Record<string, AnyPredicateHandler>` to match
+ * {@link Plugin.predicates} at the registry boundary — each handler's
+ * concrete argument shape is preserved in its individual declaration
+ * above, and consumers can import `commitsAhead`, `isClean`, etc.
+ * directly when they want the narrow type.
+ */
+export const predicates = {
+    branch,
+    upstream,
+    commitsAhead,
+    hasStagedChanges,
+    isClean,
+    remote,
+};
+//# sourceMappingURL=predicates.js.map

package/dist/plugins/git/predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.js","sourceRoot":"","sources":["../../../src/plugins/git/predicates.ts"],"names":[],"mappings":"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"}