@cad0p/pi-steering 0.1.0

package/dist/plugins/git/branch-tracker.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * `branch` tracker for the git plugin.
+ *
+ * Models the effective git branch AT EACH extracted command within a
+ * single `tool_call`. The motivating case is the ADR's
+ * `git checkout A && git commit` example: a session-level
+ * "current branch" query would miss the mid-command checkout and allow
+ * the commit on what looks like a non-protected branch. A walker-backed
+ * tracker folds the `git checkout` delta into the branch value seen by
+ * the subsequent `git commit`, so a rule gated on
+ * `when: { branch: /^main$/ }` correctly fires if the chain ends up on
+ * `main`.
+ *
+ * Semantics:
+ *   - `git checkout X`  - sequential; branch becomes `X` for the rest
+ *     of this scope.
+ *   - `git switch X`    - sequential; same as above.
+ *   - `git checkout -b NEW` / `git switch -c NEW` - sequential; branch
+ *     becomes `NEW`. The `-b` / `-c` token is consumed; the following
+ *     argument is the new branch name.
+ *   - Anything else under `git` (including `git commit`, `git status`,
+ *     `git checkout -- FILE`) leaves the branch unchanged. Returning
+ *     `current` (not `undefined`) is important: a `git commit` that
+ *     happens to carry a non-static arg (e.g. `-m "$MSG"`) must NOT
+ *     collapse branch state to `unknown`.
+ *   - Non-static branch names (`git checkout $BR`, `git checkout "$BR"`)
+ *     return `undefined`, which the walker translates to the tracker's
+ *     `unknown` sentinel. Predicates then apply their `onUnknown`
+ *     policy (default `"block"` - see the `branch` predicate handler).
+ *
+ * Subshells: `isolated` - a `(git checkout X)` inside parens cannot
+ * change the enclosing shell's branch (real git semantics - the
+ * subshell has no effect on the parent's working tree state for this
+ * dimension).
+ *
+ * The tracker distinguishes two "I don't know the branch" states so
+ * predicates can apply the correct policy:
+ *
+ *   - `initial: NO_CHECKOUT_IN_CHAIN` - no branch-changing modifier
+ *     has fired in this ref's scope. The plugin cannot synchronously
+ *     know the session's current branch at construction time; the
+ *     `branch` predicate handler shells out via `ctx.exec("git",
+ *     ["branch", "--show-current"])` to learn it. (A session-start
+ *     prefetch is a reasonable future optimization but out of scope
+ *     here.)
+ *   - `unknown: "unknown"` - a modifier FIRED but couldn't resolve
+ *     statically (e.g. `git checkout $VAR`). The predicate must NOT
+ *     shell out in this case: `git branch --show-current` would
+ *     return the PRE-checkout branch and silently defeat the
+ *     walker's tracking. Predicates apply their `onUnknown` policy
+ *     instead (default `"block"` -> fail-closed).
+ *
+ * The `NO_CHECKOUT_IN_CHAIN` sentinel is chosen to be a string that
+ * cannot occur as a real git branch name (git refuses refs containing
+ * `:`). Exported so tests and plugin authors can reference it; it
+ * should never be constructed ad-hoc.
+ *
+ * ## Note for plugin authors
+ *
+ * This tracker is a canonical example of the strict Tracker contract -
+ * unresolvable modifier targets return `undefined`, NOT `current`. The
+ * built-in `cwdTracker.cd` modifier is a documented Phase-1 exception;
+ * do not copy its "return current" shortcut in new trackers.
+ */
+import { isStaticallyResolvable, } from "@cad0p/unbash-walker";
+/**
+ * Sentinel value for `branchTracker.initial` - marks "no branch-
+ * changing modifier has fired in this ref's scope yet". Distinct
+ * from the `"unknown"` sentinel (which marks "a modifier DID fire
+ * but couldn't resolve statically"). See the file JSDoc for why the
+ * distinction matters to the `branch` predicate's exec fallback
+ * decision. The colon is chosen because git rejects it in branch
+ * names, so this value cannot collide with a real branch.
+ */
+export const NO_CHECKOUT_IN_CHAIN = "pi-steering:no-checkout-in-chain";
+/** Branch-changing git subcommands. */
+const CHECKOUT_SUBCOMMANDS = new Set(["checkout", "switch"]);
+/** `git checkout -b NEW` / `git switch -c NEW` - new-branch flags. */
+const NEW_BRANCH_FLAGS = new Set(["-b", "-c"]);
+/**
+ * Sequential modifier that applies to every `git`-basename command.
+ *
+ * Returns the new branch for `checkout` / `switch` invocations;
+ * returns `current` unchanged for every other git subcommand (so
+ * `git commit -m "x"` does NOT collapse the branch to `unknown`);
+ * returns `undefined` when the target branch name can't be resolved
+ * statically.
+ *
+ * Pre-subcommand flags are skipped before we look at the subcommand
+ * token. Git accepts `git -C PATH`, `git -c KEY=VAL`, `git --no-pager`,
+ * `git --git-dir=/x`, `git --work-tree=/y`, `git --paginate`, etc.
+ * before the subcommand. Without this skip, `git -C /other checkout
+ * feat` would look at the `-C` flag as the subcommand, miss the
+ * checkout, and silently bypass `no-main-commit`. This mirrors the
+ * `applyGitCwd` flag scanner in `unbash-walker/src/trackers/cwd.ts`:
+ * only `-C <path>` and `-c <key=value>` consume an additional token;
+ * every other flag form (short cluster, long with or without attached
+ * value) is a single token.
+ */
+const gitBranchModifier = {
+    scope: "sequential",
+    apply: (args, current) => {
+        // Scan past pre-subcommand flags to find the real subcommand.
+        // Known value-consuming flags: `-C <path>`, `-c <key=val>`.
+        // Others (`--no-pager`, `--git-dir=/x`, `--work-tree=/y`,
+        // `--paginate`, `-p`, etc.) are single tokens.
+        let i = 0;
+        while (i < args.length) {
+            const tokWord = args[i];
+            const tok = tokWord?.value ?? tokWord?.text ?? "";
+            if (!tok.startsWith("-"))
+                break; // found the subcommand
+            if (tok === "-C" || tok === "-c") {
+                i += 2;
+                continue;
+            }
+            i++; // --long-flag, --long=value, or -shortcluster
+        }
+        // No subcommand - e.g. bare `git` or `git --help`. Branch unchanged.
+        const subcmdWord = args[i];
+        if (!subcmdWord)
+            return current;
+        const subcmd = subcmdWord.value ?? subcmdWord.text;
+        if (!subcmd || !CHECKOUT_SUBCOMMANDS.has(subcmd))
+            return current;
+        // `git checkout` / `git switch` with no further args: also a
+        // help / error case. Leave branch alone.
+        const firstArgWord = args[i + 1];
+        if (!firstArgWord)
+            return current;
+        const firstArg = firstArgWord.value ?? firstArgWord.text;
+        if (firstArg === undefined)
+            return current;
+        // `git checkout --help` / `git checkout -h` - help request, not a
+        // branch change. Every other unrecognised flag form (e.g. `--`, `.`,
+        // `--force`) still flows through the default branch-name path and
+        // is accepted as a documented false-positive (see test cases).
+        if (firstArg === "--help" || firstArg === "-h")
+            return current;
+        // `git checkout -b NEW` / `git switch -c NEW` - the branch
+        // argument is at position i + 2.
+        if (NEW_BRANCH_FLAGS.has(firstArg)) {
+            const newBranchWord = args[i + 2];
+            if (!newBranchWord)
+                return current;
+            if (!isStaticallyResolvable(newBranchWord))
+                return undefined;
+            const newBranch = newBranchWord.value ?? newBranchWord.text;
+            return newBranch === undefined ? current : newBranch;
+        }
+        // Plain `git checkout X` / `git switch X`. Note: `git checkout --
+        // FILE` (restore path) is NOT a branch change, but the first arg
+        // `--` happens to be statically resolvable AND `!= undefined`.
+        // That's a false-positive corner we accept for Phase 4 - agents
+        // rarely emit the `--` separator form, and the alternative
+        // (hard-coding a `--` check) brittles against other pathspec
+        // conventions. Follow-up if it bites.
+        if (!isStaticallyResolvable(firstArgWord))
+            return undefined;
+        return firstArg;
+    },
+};
+/**
+ * The branch tracker.
+ *
+ * Registered by the git plugin under `trackers.branch`. Walker-merged
+ * with any future plugin wanting to extend branch semantics (though
+ * the tracker name `branch` is expected to stay owned by the git
+ * plugin - name collisions are a hard error per the plugin-merger).
+ */
+export const branchTracker = {
+    initial: NO_CHECKOUT_IN_CHAIN,
+    unknown: "unknown",
+    modifiers: {
+        git: gitBranchModifier,
+    },
+    subshellSemantics: "isolated",
+};
+//# sourceMappingURL=branch-tracker.js.map

package/dist/plugins/git/branch-tracker.js.map

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

package/dist/plugins/git/cwd-extensions.d.ts

@@ -0,0 +1,10 @@
+import { type Modifier } from "@cad0p/unbash-walker";
+/**
+ * Modifiers the git plugin registers under `cwd.git`. Exposed as an
+ * array so the plugin merger sees each entry distinctly; the runtime
+ * could today also accept a single modifier, but the array form
+ * leaves room for future git-specific cwd tweaks without changing
+ * the plugin manifest.
+ */
+export declare const gitCwdExtensions: readonly Modifier<unknown>[];
+//# sourceMappingURL=cwd-extensions.d.ts.map

package/dist/plugins/git/cwd-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd-extensions.d.ts","sourceRoot":"","sources":["../../../src/plugins/git/cwd-extensions.ts"],"names":[],"mappings":"AAqFA,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAiE7E;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,QAAQ,CAAC,OAAO,CAAC,EAExD,CAAC"}

package/dist/plugins/git/cwd-extensions.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * `cwd` tracker extensions for the git plugin.
+ *
+ * The built-in `cwdTracker` (in unbash-walker) handles `git -C DIR
+ * subcmd`. Two narrower git flags - `--git-dir=/path` and
+ * `--work-tree=/path` - express the same "run this command as if the
+ * working directory were /path" intent, but weren't modelled in the
+ * walker's core to keep its git knowledge minimal. Parsing them lives
+ * in the git plugin as a tracker extension: registered under
+ * `trackerExtensions.cwd.git`, the modifier layers on top of the core
+ * cwd tracker's own `git` per-command modifier.
+ *
+ * Scope is `per-command` - consistent with `-C` and git's own runtime
+ * behavior: these flags affect only the command they're attached to.
+ *
+ * Composition with `-C`:
+ *
+ *   `git -C /a --git-dir=/b status`
+ *
+ * The plugin-merger appends this extension's modifier AFTER the core
+ * `-C` modifier under the same basename. The walker then runs BOTH
+ * modifiers left-to-right against the same arg list, each layering
+ * its own contribution on top of the running recorded value:
+ *
+ *   1. Core `-C /a` modifier (scans pre-subcommand flags only):
+ *        running cwd "/initial" -> "/a"
+ *   2. This `--git-dir=/b` modifier (scans all args for the two
+ *      specific flag forms):
+ *        running cwd "/a"        -> "/b"
+ *
+ * The LATER modifier wins on absolute paths; for relative paths it
+ * joins against the running value from the previous step. Test
+ * expectation for `git -C /a --git-dir=b status` is `/a/b`.
+ *
+ * Order in the source matters too:
+ *
+ *   - `git --git-dir=/b -C /a status` -> `/b` (core `-C` runs on
+ *     the pre-sequential value `/initial`, producing `/a`; then
+ *     this modifier runs against the same args, overriding to
+ *     `/b`).
+ *   - `git -C /a --git-dir=/b status` -> `/b` (same left-to-right
+ *     modifier order; the core scanner produces `/a`, this one
+ *     overrides to `/b`).
+ *
+ * In both cases the `--git-dir=` / `--work-tree=` flags win, matching
+ * git's documented precedence.
+ *
+ * Known limitations:
+ *
+ *   - `--git-dir` without an `=` (space-separated form:
+ *     `git --git-dir /path ...`) is NOT handled. Both git and shell
+ *     tokenize this as two words; walker modifiers today only see the
+ *     single `--git-dir` token. Wiring a two-token form is possible
+ *     but agents overwhelmingly emit the `=` form; follow-up.
+ *   - Non-static targets (`--git-dir=$VAR`) return `undefined`,
+ *     collapsing the per-command cwd to `"unknown"`. Predicates then
+ *     apply `onUnknown`.
+ *   - `--work-tree` without `--git-dir` is semantically incomplete in
+ *     real git (the gitdir still points at the default), but for cwd
+ *     tracking purposes we treat them identically - they both mean
+ *     "the command's effective cwd is this path". If a rule author
+ *     needs the distinction (e.g. a repo-path vs tree-path
+ *     predicate), they can split it in their own plugin.
+ *
+ * Known accepted false-positives:
+ *
+ *   - `git log --git-dir=/repo` -> cwd recorded as /repo. Real git
+ *     treats post-subcommand `--git-dir=` as a pathspec, not a
+ *     global flag. Over-match rate is low in practice (agents emit
+ *     `git --git-dir=/x log`, not the inverse), and stopping the
+ *     scan at the first non-flag token would break composition with
+ *     the core `-C` modifier which iterates the same args list.
+ *     Accepted as a Phase-4 corner.
+ *   - `git diff -- --git-dir=/x` -> cwd recorded as /x. Arguments
+ *     after `--` are always pathspecs in real git. Same mitigation
+ *     rationale as above; stopping the scan at `--` would still
+ *     need to run after the core `-C` scanner has finished, not
+ *     before, to avoid the composition breakage.
+ */
+import * as path from "node:path";
+import { isStaticallyResolvable } from "@cad0p/unbash-walker";
+/** Regex matched against each `git`-command argument token. */
+const GIT_DIR_RE = /^--git-dir=(.+)$/;
+const WORK_TREE_RE = /^--work-tree=(.+)$/;
+/**
+ * Read a word's static value. Falls back to `text` when `value`
+ * isn't materialised (pure literal fast path in unbash).
+ */
+function wordValue(w) {
+    return w?.value ?? w?.text;
+}
+/**
+ * Scan git's pre-subcommand flags for `--git-dir=DIR` / `--work-tree=DIR`
+ * and layer the target on top of the current cwd.
+ *
+ * Stops at the first non-flag token (the subcommand) - identical shape
+ * to the core `-C` scanner. Multiple occurrences compose left-to-right
+ * (an absolute path replaces, a relative path joins to the running
+ * cwd). If we encounter a target we can't statically resolve, we bail
+ * returning `undefined`; the walker translates that to the cwd
+ * tracker's `"unknown"` sentinel.
+ */
+const gitCwdExtension = {
+    scope: "per-command",
+    apply: (args, current) => {
+        let cwd = current;
+        // Scan ALL args (not just pre-subcommand): we match only the two
+        // specific flag forms `--git-dir=X` / `--work-tree=X`, so there's
+        // no ambiguity with subcommand arguments. `git log
+        // --grep="--git-dir=foo"` is safe because the quoted string is a
+        // SINGLE argument whose text starts with `--grep`, not
+        // `--git-dir`, so the regex doesn't match.
+        //
+        // A stop-at-non-flag scan (mirroring the core `-C` modifier)
+        // would break composition with `-C`: the walker runs this
+        // modifier AGAINST THE SAME args the core `-C` modifier saw, not
+        // a reduced arg list. On `git -C /a --git-dir=/b status`, the
+        // args are still `[-C, /a, --git-dir=/b, status]`; a stop-at-
+        // non-flag scan would terminate at `/a` (the value of `-C`,
+        // which doesn't start with `-`) and miss the `--git-dir=` flag.
+        for (const w of args) {
+            const tok = wordValue(w);
+            if (tok === undefined)
+                continue;
+            const gitDirMatch = tok.match(GIT_DIR_RE);
+            const workTreeMatch = tok.match(WORK_TREE_RE);
+            const match = gitDirMatch ?? workTreeMatch;
+            if (!match)
+                continue;
+            // `--git-dir=$VAR` / `--work-tree=$(...)` - the captured
+            // piece is there in the raw text, but the overall Word is
+            // non-static. Refuse to invent a value.
+            if (!isStaticallyResolvable(w))
+                return undefined;
+            const target = match[1];
+            if (target === undefined || target.length === 0)
+                continue;
+            cwd = path.isAbsolute(target) ? target : path.join(cwd, target);
+        }
+        return cwd;
+    },
+};
+/**
+ * Modifiers the git plugin registers under `cwd.git`. Exposed as an
+ * array so the plugin merger sees each entry distinctly; the runtime
+ * could today also accept a single modifier, but the array form
+ * leaves room for future git-specific cwd tweaks without changing
+ * the plugin manifest.
+ */
+export const gitCwdExtensions = [
+    gitCwdExtension,
+];
+//# sourceMappingURL=cwd-extensions.js.map

package/dist/plugins/git/cwd-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd-extensions.js","sourceRoot":"","sources":["../../../src/plugins/git/cwd-extensions.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAiB,MAAM,sBAAsB,CAAC;AAE7E,+DAA+D;AAC/D,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;GAGG;AACH,SAAS,SAAS,CAAC,CAAmB;IACpC,OAAO,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,IAAI,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,eAAe,GAAqB;IACxC,KAAK,EAAE,aAAa;IACpB,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;QACvB,IAAI,GAAG,GAAG,OAAO,CAAC;QAClB,iEAAiE;QACjE,kEAAkE;QAClE,mDAAmD;QACnD,iEAAiE;QACjE,uDAAuD;QACvD,2CAA2C;QAC3C,EAAE;QACF,6DAA6D;QAC7D,0DAA0D;QAC1D,iEAAiE;QACjE,8DAA8D;QAC9D,8DAA8D;QAC9D,4DAA4D;QAC5D,gEAAgE;QAChE,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YACzB,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS;YAEhC,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC1C,MAAM,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,WAAW,IAAI,aAAa,CAAC;YAC3C,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,yDAAyD;YACzD,0DAA0D;YAC1D,wCAAwC;YACxC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC;gBAAE,OAAO,SAAS,CAAC;YAEjD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAC1D,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAiC;IAC5D,eAAoC;CACrC,CAAC"}

package/dist/plugins/git/git-ops.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Raw git query helpers for the git plugin — reusable functions that
+ * shell out to git and return trimmed raw data (or `null` on any
+ * failure). Exposed so downstream plugins can compose per-directory
+ * scans without re-implementing the shell invocations, and so the
+ * predicates in this plugin stay thin pattern-matching wrappers
+ * around the helpers.
+ *
+ * Each helper:
+ *
+ *   - takes `(ctx, cwd?)`; `cwd` defaults to `ctx.cwd`, letting
+ *     callers iterate over per-subpackage git dirs (common in
+ *     multi-package workspace contexts like `cr --all`).
+ *   - returns the raw data on success, `null` on any failure
+ *     (non-zero exit, spawn error, exception thrown inside
+ *     `ctx.exec`). Callers layer their own "what does null mean"
+ *     policy — predicates apply `onUnknown`; custom logic can
+ *     inspect the null directly.
+ *   - relies on the evaluator's per-tool_call `exec` memoization
+ *     (`(cmd, args, cwd)` tuple) so multiple helpers reading the
+ *     same repo state don't re-fork git.
+ *
+ * ## Consumer note
+ *
+ * The helpers return **raw query results** and are INTENTIONALLY free
+ * of the `onUnknown` / pattern-matching layer. That layer lives in
+ * `predicates.ts`. If you want predicate-style semantics, call the
+ * matching `when.*` handler (also re-exported from the plugin index)
+ * rather than the helper.
+ *
+ * ## Branch caveat
+ *
+ * {@link getBranch} intentionally DOES NOT consult `walkerState.branch`
+ * — the walker-state short-circuit is a predicate-layer concern (see
+ * the `branch` predicate's JSDoc for the three-way tracker
+ * discrimination). Downstream plugins iterating per-directory usually
+ * care about the on-disk branch at each directory, not the
+ * walker-tracked branch of the current bash chain at `ctx.cwd`; the
+ * helper therefore always shells out.
+ */
+import type { PredicateContext } from "../../schema.ts";
+/**
+ * `git branch --show-current` at `cwd` (default: `ctx.cwd`). Returns
+ * the current branch name, or `null` when the command fails OR stdout
+ * is empty (detached HEAD).
+ *
+ * Does NOT consult `ctx.walkerState.branch` — see file header
+ * "Branch caveat" for why. Predicates that need the walker-state
+ * short-circuit should use the `branch` predicate handler instead.
+ */
+export declare function getBranch(ctx: PredicateContext, cwd?: string): Promise<string | null>;
+/**
+ * `git rev-parse --abbrev-ref @{upstream}` at `cwd` (default:
+ * `ctx.cwd`). Returns the tracking branch name (e.g. `origin/main`),
+ * or `null` when no upstream is configured or the command fails.
+ */
+export declare function getUpstream(ctx: PredicateContext, cwd?: string): Promise<string | null>;
+/**
+ * `git rev-list --count <wrt>..HEAD` at `cwd` (default: `ctx.cwd`).
+ * Returns the number of commits HEAD is ahead of `wrt`, or `null`
+ * when the command fails (e.g. `wrt` doesn't resolve, detached HEAD,
+ * not a repo).
+ *
+ * `wrt` defaults to `@{upstream}`. Pass a specific ref like
+ * `"origin/main"` when the upstream configuration isn't guaranteed.
+ */
+export declare function getCommitsAhead(ctx: PredicateContext, wrt?: string, cwd?: string): Promise<number | null>;
+/**
+ * `git diff --cached --quiet` at `cwd` (default: `ctx.cwd`). Exit
+ * code discrimination:
+ *
+ *   - `0`  → no staged changes     → returns `false`
+ *   - `1`  → staged changes exist  → returns `true`
+ *   - anything else (spawn error, weird exit) → returns `null`
+ */
+export declare function getStagedChanges(ctx: PredicateContext, cwd?: string): Promise<boolean | null>;
+/**
+ * `git status --porcelain` at `cwd` (default: `ctx.cwd`). Returns
+ * `true` when the working tree is clean (empty output), `false`
+ * when dirty, `null` on any command failure.
+ */
+export declare function getWorkingTreeClean(ctx: PredicateContext, cwd?: string): Promise<boolean | null>;
+/**
+ * `git config --get remote.origin.url` at `cwd` (default: `ctx.cwd`).
+ * Returns the origin URL string, or `null` when no origin is
+ * configured or the command fails.
+ */
+export declare function getRemoteUrl(ctx: PredicateContext, cwd?: string): Promise<string | null>;
+//# sourceMappingURL=git-ops.d.ts.map

package/dist/plugins/git/git-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-ops.d.ts","sourceRoot":"","sources":["../../../src/plugins/git/git-ops.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAuBxD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,GAAG,GAAE,MAAsB,EAC3B,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAUzB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAIzB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB"}

package/dist/plugins/git/git-ops.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Run a git command in the given cwd and return its trimmed stdout on
+ * exit 0, or `null` on any failure. Thin wrapper used by every helper
+ * here so failure modes (non-zero exit, spawn error, exception)
+ * collapse to a uniform `null`.
+ */
+async function tryGit(ctx, args, cwd) {
+    try {
+        const opts = cwd !== undefined ? { cwd } : { cwd: ctx.cwd };
+        const res = await ctx.exec("git", [...args], opts);
+        if (res.exitCode !== 0)
+            return null;
+        return res.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `git branch --show-current` at `cwd` (default: `ctx.cwd`). Returns
+ * the current branch name, or `null` when the command fails OR stdout
+ * is empty (detached HEAD).
+ *
+ * Does NOT consult `ctx.walkerState.branch` — see file header
+ * "Branch caveat" for why. Predicates that need the walker-state
+ * short-circuit should use the `branch` predicate handler instead.
+ */
+export async function getBranch(ctx, cwd) {
+    const out = await tryGit(ctx, ["branch", "--show-current"], cwd);
+    if (out === null || out.length === 0)
+        return null;
+    return out;
+}
+/**
+ * `git rev-parse --abbrev-ref @{upstream}` at `cwd` (default:
+ * `ctx.cwd`). Returns the tracking branch name (e.g. `origin/main`),
+ * or `null` when no upstream is configured or the command fails.
+ */
+export async function getUpstream(ctx, cwd) {
+    const out = await tryGit(ctx, ["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+    if (out === null || out.length === 0)
+        return null;
+    return out;
+}
+/**
+ * `git rev-list --count <wrt>..HEAD` at `cwd` (default: `ctx.cwd`).
+ * Returns the number of commits HEAD is ahead of `wrt`, or `null`
+ * when the command fails (e.g. `wrt` doesn't resolve, detached HEAD,
+ * not a repo).
+ *
+ * `wrt` defaults to `@{upstream}`. Pass a specific ref like
+ * `"origin/main"` when the upstream configuration isn't guaranteed.
+ */
+export async function getCommitsAhead(ctx, wrt = "@{upstream}", cwd) {
+    const out = await tryGit(ctx, ["rev-list", "--count", `${wrt}..HEAD`], cwd);
+    if (out === null)
+        return null;
+    const count = Number.parseInt(out, 10);
+    return Number.isFinite(count) ? count : null;
+}
+/**
+ * `git diff --cached --quiet` at `cwd` (default: `ctx.cwd`). Exit
+ * code discrimination:
+ *
+ *   - `0`  → no staged changes     → returns `false`
+ *   - `1`  → staged changes exist  → returns `true`
+ *   - anything else (spawn error, weird exit) → returns `null`
+ */
+export async function getStagedChanges(ctx, cwd) {
+    try {
+        const opts = cwd !== undefined ? { cwd } : { cwd: ctx.cwd };
+        const res = await ctx.exec("git", ["diff", "--cached", "--quiet"], opts);
+        if (res.exitCode === 0)
+            return false;
+        if (res.exitCode === 1)
+            return true;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `git status --porcelain` at `cwd` (default: `ctx.cwd`). Returns
+ * `true` when the working tree is clean (empty output), `false`
+ * when dirty, `null` on any command failure.
+ */
+export async function getWorkingTreeClean(ctx, cwd) {
+    const out = await tryGit(ctx, ["status", "--porcelain"], cwd);
+    if (out === null)
+        return null;
+    return out.length === 0;
+}
+/**
+ * `git config --get remote.origin.url` at `cwd` (default: `ctx.cwd`).
+ * Returns the origin URL string, or `null` when no origin is
+ * configured or the command fails.
+ */
+export async function getRemoteUrl(ctx, cwd) {
+    const out = await tryGit(ctx, ["config", "--get", "remote.origin.url"], cwd);
+    if (out === null || out.length === 0)
+        return null;
+    return out;
+}
+//# sourceMappingURL=git-ops.js.map

package/dist/plugins/git/git-ops.js.map

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