@cad0p/pi-steering 0.1.0

package/dist/plugins/git/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Git plugin for `@cad0p/pi-steering`.
+ *
+ * Subpath import: `pi-steering/plugins/git`.
+ *
+ * Registers (in the terms of `Plugin`):
+ *
+ *   - `predicates`         - `branch`, `upstream`, `commitsAhead`,
+ *                             `hasStagedChanges`, `isClean`, `remote`.
+ *                             See `./predicates.ts` for the arg
+ *                             shapes each handler accepts.
+ *   - `rules`              - `no-main-commit-github` (github-flavored,
+ *                             first-match-wins) + `no-main-commit`
+ *                             (generic fallback). Both overridable.
+ *                             Users disable via
+ *                             `disabledRules: ["no-main-commit"]` /
+ *                             `["no-main-commit-github"]` or opt out
+ *                             of the whole plugin with
+ *                             `disabledPlugins: ["git"]`.
+ *   - `trackers.branch`    - sequential `git checkout` / `git switch`
+ *                             branch tracker. See `./branch-tracker.ts`.
+ *   - `trackerExtensions.cwd.git`
+ *                            - per-command `--git-dir=` / `--work-tree=`
+ *                              parser layered on the core cwd tracker.
+ *                              See `./cwd-extensions.ts`.
+ *
+ * Also re-exported as composable building blocks for downstream
+ * plugins (e.g. RDS-style multi-package `cr --all` scans that need
+ * to query git state per subpackage directory):
+ *
+ *   - `getBranch(ctx, cwd?)`            — current branch or `null`
+ *   - `getUpstream(ctx, cwd?)`          — upstream name or `null`
+ *   - `getCommitsAhead(ctx, wrt?, cwd?)` — commit count or `null`
+ *   - `getStagedChanges(ctx, cwd?)`     — boolean or `null`
+ *   - `getWorkingTreeClean(ctx, cwd?)`  — boolean or `null`
+ *   - `getRemoteUrl(ctx, cwd?)`         — origin URL or `null`
+ *   - `walkerString(value)`             — walker-sentinel narrowing
+ *                                          helper for plugin-author
+ *                                          predicates
+ *   - `NO_CHECKOUT_IN_CHAIN`            — branch-tracker fall-through
+ *                                          sentinel
+ *   - `GIT_COMMIT_PATTERN`              — shared `git commit` regex
+ *                                          source used by both
+ *                                          commit-on-main rules
+ *   - `PROTECTED_BRANCH_PATTERN`         — shared protected-branch
+ *                                          regex (main / master /
+ *                                          mainline / trunk) used by
+ *                                          both commit-on-main rules
+ *
+ * See `./git-ops.ts` for the helper contract (all collapse failure
+ * modes to `null`; caller decides what to do with it).
+ *
+ * Opt-in since the v0.1.x monorepo split: `DEFAULT_PLUGINS` is empty,
+ * so this plugin is registered ONLY when the user declares it:
+ *
+ * ```ts
+ * import gitPlugin from "@cad0p/pi-steering/plugins/git";
+ * export default defineConfig({ plugins: [gitPlugin] });
+ * ```
+ *
+ * Declaring it explicitly also feeds its rule / predicate names into
+ * `defineConfig`'s type unions (typo-checking on `disabledRules` /
+ * `disabledPlugins`); relying on a default would silently widen the
+ * union and let typos through.
+ *
+ * Tests build configs via `loadHarness({ includeDefaults: false })`
+ * and pass the plugin explicitly.
+ *
+ * ## Note for plugin authors
+ *
+ * This is the canonical reference plugin. Third-party plugins are
+ * expected to mirror this layout - one file per concern (tracker /
+ * extension / predicates / rules), a terse default export assembling
+ * them. Copy-adapt liberally.
+ */
+import type { Tracker } from "@cad0p/unbash-walker";
+import type { Patterns, PredicateShape } from "../../schema.ts";
+declare global {
+    /**
+     * gitPlugin's typed-predicate registry. Each entry declares the
+     * predicate's `bare` value type and (optionally) an explicit
+     * `spreadBase` (the spread's object form WITHOUT modifiers).
+     * Modifiers (currently `onUnknown:`) are added at use site via
+     * `& PredicateModifiers` (outer leaf) or at the not-block top
+     * level (inside `not:`).
+     *
+     * Note: `cwd` is intentionally NOT in this block. It's a built-in
+     * non-registry leaf on {@link BuiltInWhenLeaves} (see schema.ts) so
+     * authors can write `when: { cwd: /work/ }` against pi-steering core
+     * without needing gitPlugin's module augmentation in scope. The
+     * runtime handler that wires `when.cwd` to the walker still lives
+     * in pi-steering core; gitPlugin layers `git --git-dir=` /
+     * `--work-tree=` cwd extensions via {@link gitCwdExtensions} but
+     * does not own the predicate's registry shape.
+     *
+     * @see PredicateShape, DefaultSpreadBase, PredicateModifiers in
+     *      `schema.ts` for the full registry contract.
+     */
+    interface PiSteeringPredicates {
+        /**
+         * `when.branch` — match the current git branch. Pattern leaf,
+         * tracker-aware (in-chain `git checkout X` resolves statically;
+         * dynamic `git checkout $VAR` surfaces the walker's
+         * `"unknown"` sentinel — the engine's `onUnknown:` policy
+         * then projects to a definite verdict).
+         */
+        branch: PredicateShape<Patterns>;
+        /**
+         * `when.upstream` — match the current branch's configured
+         * upstream (`git rev-parse --abbrev-ref @{upstream}`). Pattern
+         * leaf. Inlines a walker-unknown-cwd guard at the handler
+         * top — surfaces trinary `"unknown"` instead of querying the
+         * wrong repo when the walker can't statically resolve cwd.
+         */
+        upstream: PredicateShape<Patterns>;
+        /**
+         * `when.remote` — match the repo's `origin` remote URL
+         * (`git config --get remote.origin.url`). Pattern leaf. Same
+         * walker-unknown-cwd guard as `upstream:`.
+         */
+        remote: PredicateShape<Patterns>;
+        /**
+         * `when.isClean` — `true` when the working tree has no
+         * unstaged / untracked / staged changes (`git status
+         * --porcelain` is empty); `false` otherwise. Boolean leaf;
+         * spreadBase auto-detects to `{ value: boolean }`. Inlines
+         * the walker-unknown-cwd guard.
+         */
+        isClean: PredicateShape<boolean>;
+        /**
+         * `when.hasStagedChanges` — `true` when there are staged
+         * changes (`git diff --cached --quiet` exits non-zero);
+         * `false` otherwise. Boolean leaf. Inlines the walker-
+         * unknown-cwd guard.
+         */
+        hasStagedChanges: PredicateShape<boolean>;
+        /**
+         * `when.commitsAhead` — match when the count of commits ahead
+         * of `wrt:` (default `@{upstream}`) satisfies every supplied
+         * comparator. Bare shorthand `commitsAhead: N` is equivalent
+         * to `{ eq: N }`. Spread form supports:
+         *   - `eq?: number` — exact equality (`count === eq`).
+         *   - `gt?: number` — strict greater-than (`count > gt`).
+         *   - `lt?: number` — strict less-than (`count < lt`).
+         *   - `wrt?: string` — git revision to count against (default
+         *     `"@{upstream}"`).
+         * At least one of `eq` / `gt` / `lt` MUST be specified;
+         * combined with AND.
+         *
+         * Mixed-bare predicate: explicit `SpreadBase` since auto-
+         * detection from `number` would give `{ value: number }`,
+         * which doesn't match the desired comparator-bag shape.
+         * Inlines the walker-unknown-cwd guard.
+         */
+        commitsAhead: PredicateShape<number, {
+            eq?: number;
+            gt?: number;
+            lt?: number;
+            wrt?: string;
+        }>;
+    }
+}
+/**
+ * The git plugin. Default export so `import gitPlugin from
+ * "pi-steering/plugins/git"` gives you the whole thing.
+ *
+ * `as const satisfies Plugin` (rather than `: Plugin`) preserves the
+ * literal `name: "git"` in the inferred type. That literal is the
+ * input to any future `AllPluginNames<P>`-style inference in
+ * `defineConfig`, which needs `name: "git"`, not `name: string`, to
+ * offer string-literal completion for e.g. `disabledPlugins`.
+ */
+declare const gitPlugin: {
+    readonly name: "git";
+    readonly predicates: Record<string, import("../../schema.ts").AnyPredicateHandler>;
+    readonly rules: readonly [{
+        readonly name: "no-main-commit-github";
+        readonly tool: "bash";
+        readonly field: "command";
+        readonly pattern: "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b";
+        readonly when: {
+            readonly branch: RegExp;
+            readonly remote: {
+                readonly pattern: RegExp;
+                readonly onUnknown: "allow";
+            };
+        };
+        readonly reason: (ctx: import("../../schema.ts").PredicateContext) => string;
+        readonly noOverride: false;
+    }, {
+        readonly name: "no-main-commit";
+        readonly tool: "bash";
+        readonly field: "command";
+        readonly pattern: "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b";
+        readonly when: {
+            readonly branch: RegExp;
+        };
+        readonly reason: (ctx: import("../../schema.ts").PredicateContext) => string;
+        readonly noOverride: false;
+    }];
+    readonly trackers: {
+        readonly branch: Tracker<unknown>;
+    };
+    readonly trackerExtensions: {
+        readonly cwd: {
+            readonly git: readonly import("@cad0p/unbash-walker").Modifier<unknown>[];
+        };
+    };
+};
+/**
+ * Type-level regression sentinel: if the plugin literal ever loses
+ * the `name: "git"` narrowing (for example, someone reintroducing
+ * `: Plugin` annotation), the inferred type of `GIT_PLUGIN_NAME`
+ * widens to `string` and any downstream literal-name inference
+ * breaks. Keep this export in place to fail compilation loudly when
+ * that happens.
+ */
+export declare const GIT_PLUGIN_NAME: "git";
+export default gitPlugin;
+export { branchTracker, NO_CHECKOUT_IN_CHAIN } from "./branch-tracker.ts";
+export { gitCwdExtensions } from "./cwd-extensions.ts";
+export { getBranch, getCommitsAhead, getRemoteUrl, getStagedChanges, getUpstream, getWorkingTreeClean, } from "./git-ops.ts";
+export { branch, type CommitsAheadArgs, commitsAhead, hasStagedChanges, isClean, predicates, remote, upstream, type WalkerStringResult, walkerString, } from "./predicates.ts";
+export { GIT_COMMIT_PATTERN, noMainCommit, noMainCommitGithub, PROTECTED_BRANCH_PATTERN, rules, } from "./rules.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/git/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/git/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAEV,QAAQ,EAER,cAAc,EACf,MAAM,iBAAiB,CAAC;AAMzB,OAAO,CAAC,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,oBAAoB;QAC5B;;;;;;WAMG;QACH,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QAEjC;;;;;;WAMG;QACH,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QAEnC;;;;WAIG;QACH,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QAEjC;;;;;;WAMG;QACH,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;QAEjC;;;;;WAKG;QACH,gBAAgB,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;QAE1C;;;;;;;;;;;;;;;;;WAiBG;QACH,YAAY,EAAE,cAAc,CAC1B,MAAM,EACN;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,CACxD,CAAC;KACH;CACF;AAED;;;;;;;;;GASG;AACH,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBASyB,OAAO,CAAC,OAAO,CAAC;;;;;;;CAO7B,CAAC;AAE5B;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,KAAsB,CAAC;AAErD,eAAe,SAAS,CAAC;AAKzB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,SAAS,EACT,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,MAAM,EACN,KAAK,gBAAgB,EACrB,YAAY,EACZ,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,KAAK,kBAAkB,EACvB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,GACN,MAAM,YAAY,CAAC"}

package/dist/plugins/git/index.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+import { branchTracker } from "./branch-tracker.js";
+import { gitCwdExtensions } from "./cwd-extensions.js";
+import { predicates } from "./predicates.js";
+import { rules } from "./rules.js";
+/**
+ * The git plugin. Default export so `import gitPlugin from
+ * "pi-steering/plugins/git"` gives you the whole thing.
+ *
+ * `as const satisfies Plugin` (rather than `: Plugin`) preserves the
+ * literal `name: "git"` in the inferred type. That literal is the
+ * input to any future `AllPluginNames<P>`-style inference in
+ * `defineConfig`, which needs `name: "git"`, not `name: string`, to
+ * offer string-literal completion for e.g. `disabledPlugins`.
+ */
+const gitPlugin = {
+    name: "git",
+    predicates,
+    rules,
+    trackers: {
+        // `Plugin.trackers` is typed `Record<string, Tracker<unknown>>`
+        // because the schema can't commit to a specific T per tracker.
+        // Cast is safe - the walker dispatches on `modifiers[basename]`
+        // and never narrows T at the tracker-registry layer.
+        branch: branchTracker,
+    },
+    trackerExtensions: {
+        cwd: {
+            git: gitCwdExtensions,
+        },
+    },
+};
+/**
+ * Type-level regression sentinel: if the plugin literal ever loses
+ * the `name: "git"` narrowing (for example, someone reintroducing
+ * `: Plugin` annotation), the inferred type of `GIT_PLUGIN_NAME`
+ * widens to `string` and any downstream literal-name inference
+ * breaks. Keep this export in place to fail compilation loudly when
+ * that happens.
+ */
+export const GIT_PLUGIN_NAME = gitPlugin.name;
+export default gitPlugin;
+// Named re-exports for consumers that want to pick pieces (e.g. a
+// test harness constructing a minimal config that uses only the
+// `branch` predicate without the shipped rule).
+export { branchTracker, NO_CHECKOUT_IN_CHAIN } from "./branch-tracker.js";
+export { gitCwdExtensions } from "./cwd-extensions.js";
+export { getBranch, getCommitsAhead, getRemoteUrl, getStagedChanges, getUpstream, getWorkingTreeClean, } from "./git-ops.js";
+export { branch, commitsAhead, hasStagedChanges, isClean, predicates, remote, upstream, walkerString, } from "./predicates.js";
+export { GIT_COMMIT_PATTERN, noMainCommit, noMainCommitGithub, PROTECTED_BRANCH_PATTERN, rules, } from "./rules.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/git/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AAsFvB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AA2FnC;;;;;;;;;GASG;AACH,MAAM,SAAS,GAAG;IAChB,IAAI,EAAE,KAAK;IACX,UAAU;IACV,KAAK;IACL,QAAQ,EAAE;QACR,gEAAgE;QAChE,+DAA+D;QAC/D,gEAAgE;QAChE,qDAAqD;QACrD,MAAM,EAAE,aAA4C;KACrD;IACD,iBAAiB,EAAE;QACjB,GAAG,EAAE;YACH,GAAG,EAAE,gBAAgB;SACtB;KACF;CACwB,CAAC;AAE5B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAU,SAAS,CAAC,IAAI,CAAC;AAErD,eAAe,SAAS,CAAC;AAEzB,kEAAkE;AAClE,gEAAgE;AAChE,gDAAgD;AAChD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,SAAS,EACT,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,MAAM,EAEN,YAAY,EACZ,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EAER,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,GACN,MAAM,YAAY,CAAC"}

package/dist/plugins/git/predicates.d.ts

@@ -0,0 +1,312 @@
+import type { AnyPredicateHandler, PredicateContext, PredicateHandler } from "../../schema.ts";
+/**
+ * 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
+ */
+declare function unwrapBooleanLeafArg(args: unknown): boolean | 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 declare const _unwrapBooleanLeafArg: typeof unwrapBooleanLeafArg;
+/**
+ * Resolved outcome of reading a string tracker value from
+ * `ctx.walkerState[key]`. Callers MUST distinguish the three cases:
+ *
+ *   - `value`   - the tracker resolved the value statically for this
+ *                  command ref. Use it directly.
+ *   - `unknown` - the tracker observed a write it couldn't resolve
+ *                  statically (e.g. `git checkout $VAR`). The walker
+ *                  deliberately surfaces this to signal "a change
+ *                  happened but I can't name the new value". Falling
+ *                  through to `exec` would return the PRE-write
+ *                  value and silently defeat the walker's static
+ *                  tracking - exactly the case it exists for.
+ *                  Callers must apply their `onUnknown` policy.
+ *   - `missing` - no tracker modifier fired for this dimension in
+ *                  this ref's scope (the walker threaded the
+ *                  tracker's initial sentinel, or `walkerState` has
+ *                  no key for this tracker at all). `exec` fallback
+ *                  is correct here: the shell's current state is the
+ *                  value the predicate wants.
+ *
+ * The three-way split requires cooperation from the tracker: its
+ * `initial` value must be distinct from its `unknown` sentinel, so
+ * the predicate can tell "no modifier fired" apart from "modifier
+ * fired and couldn't resolve". `branchTracker` does this via
+ * {@link NO_CHECKOUT_IN_CHAIN}. A tracker that reuses `"unknown"`
+ * for both initial and unknown would collapse these two cases -
+ * preserved here as `missing` for backward compatibility (the
+ * predicate then behaves as it did pre-U1, shelling out on any
+ * unknown).
+ */
+export type WalkerStringResult = {
+    kind: "value";
+    value: string;
+} | {
+    kind: "unknown";
+} | {
+    kind: "missing";
+};
+/**
+ * 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 declare function walkerString(ctx: PredicateContext, key: string, initialSentinel: string): WalkerStringResult;
+/**
+ * `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 declare const branch: PredicateHandler;
+/**
+ * `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 declare const upstream: PredicateHandler;
+/**
+ * Argument shape for {@link commitsAhead}.
+ *
+ * ```ts
+ * when: { commitsAhead: { eq: 1 } }                    // exactly one ahead
+ * when: { commitsAhead: { gt: 0 } }                    // at least one
+ * when: { commitsAhead: { lt: 5 } }                    // fewer than five
+ * when: { commitsAhead: { gt: 0, lt: 5 } }             // 1..4
+ * when: { commitsAhead: { wrt: "origin/main", eq: 1 } }
+ * ```
+ *
+ * At least one of `eq` / `gt` / `lt` MUST be specified. All provided
+ * comparisons must pass (AND). `wrt` is the git revision expression
+ * to count commits behind (`git rev-list --count WRT..HEAD`); it
+ * defaults to `@{upstream}`.
+ */
+export interface CommitsAheadArgs {
+    /** Git revision to count commits ahead of. Defaults to `@{upstream}`. */
+    wrt?: string;
+    /** Exact equality: `count === eq`. */
+    eq?: number;
+    /** Strict greater-than: `count > gt`. */
+    gt?: number;
+    /** Strict less-than: `count < lt`. */
+    lt?: number;
+}
+/**
+ * `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 declare const commitsAhead: PredicateHandler<number | CommitsAheadArgs>;
+/**
+ * `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 declare const hasStagedChanges: PredicateHandler<boolean | {
+    value: boolean;
+    onUnknown?: "allow" | "block";
+}>;
+/**
+ * `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 declare const isClean: PredicateHandler<boolean | {
+    value: boolean;
+    onUnknown?: "allow" | "block";
+}>;
+/**
+ * `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 declare const remote: PredicateHandler;
+/**
+ * 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 declare const predicates: Record<string, AnyPredicateHandler>;
+export {};
+//# sourceMappingURL=predicates.d.ts.map

package/dist/plugins/git/predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.d.ts","sourceRoot":"","sources":["../../../src/plugins/git/predicates.ts"],"names":[],"mappings":"AAyDA,OAAO,KAAK,EACV,mBAAmB,EAEnB,gBAAgB,EAChB,gBAAgB,EAGjB,MAAM,iBAAiB,CAAC;AAsHzB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAUhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,6BAAuB,CAAC;AAiC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,MAAM,GACtB,kBAAkB,CAsBpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,MAAM,EAAE,gBAoBpB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ,EAAE,gBAQtB,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,YAAY,EAAE,gBAAgB,CAAC,MAAM,GAAG,gBAAgB,CAiCpE,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAAgB,CAC7C,OAAO,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,CAc5D,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,EAAE,gBAAgB,CACpC,OAAO,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,CAc5D,CAAC;AAMF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,EAAE,gBAQpB,CAAC;AAMF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAO1D,CAAC"}