@cad0p/pi-steering 0.1.0

package/src/plugins/git/rules.ts

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Plugin-shipped rules for the git plugin.
+ *
+ * Rules here ship as SUGGESTED defaults - the plugin is opt-in (users
+ * must explicitly import and list it under `plugins: [...]`), so
+ * shipping a curated starter set matches the ADR's "distribution unit
+ * for rule packs" framing.
+ *
+ * Users who want the branch predicate but NOT `no-main-commit` can
+ * keep it by disabling the rule selectively:
+ *
+ *   ```ts
+ *   defineConfig({
+ *     plugins: [gitPlugin],
+ *     disabledRules: ["no-main-commit"],
+ *   });
+ *   ```
+ *
+ * Rules ride on the branch predicate registered in `./predicates.ts`
+ * and the branch tracker in `./branch-tracker.ts`. The tracker makes
+ * the rule bypass-proof against the `git checkout main && git commit`
+ * pattern: the walker folds the checkout into the branch seen by the
+ * commit, so the rule still fires.
+ */
+
+import type { Rule } from "../../schema.ts";
+import { NO_CHECKOUT_IN_CHAIN } from "./branch-tracker.ts";
+import { walkerString } from "./predicates.ts";
+
+/**
+ * Bash command pattern matching `git commit` (with optional pre-subcommand
+ * flag slots like `git -C /path commit ...`). Shared by `no-main-commit`
+ * and `no-main-commit-github` so the family stays byte-equal as the
+ * regex evolves; reorderings that touch one rule's pattern can't
+ * silently drift from the other.
+ *
+ * Exported so tests can pin each rule's `pattern` field against this
+ * constant by value (`noMainCommit.pattern === GIT_COMMIT_PATTERN`).
+ * That catches accidental divergence between the two rules' patterns
+ * (e.g. one drops a `\b`, the other doesn't) and removal/rename of
+ * the constant itself. It does NOT catch a future inlining of the
+ * literal at a rule's definition site with the SAME bytes — string
+ * primitives compare by value, so byte-equal copy-pasted literals
+ * pass `===`. Plugin authors who need true shared-reference pinning
+ * should use a `RegExp` (object) constant instead of a string source.
+ */
+export const GIT_COMMIT_PATTERN =
+  "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b";
+
+/**
+ * Protected branch names that the gitPlugin's commit-on-main rules
+ * block by default (`main`, `master`, `mainline`, `trunk`). Shared by
+ * `no-main-commit` and `no-main-commit-github` so the protected-
+ * branch list stays uniform across the rule family — adding an alias
+ * here (e.g. a vendor-specific default-branch name) automatically
+ * propagates to both rules.
+ *
+ * `RegExp` (object) constant rather than a string source: that gives
+ * true shared-reference pinning at the test layer
+ * (`noMainCommit.when.branch === PROTECTED_BRANCH_PATTERN`), which
+ * also catches a future inline of the SAME bytes at a rule's
+ * definition site — something the string-source `GIT_COMMIT_PATTERN`
+ * pin can't do (see its JSDoc for the value-vs-reference tradeoff).
+ */
+export const PROTECTED_BRANCH_PATTERN = /^(main|master|mainline|trunk)$/;
+
+/**
+ * `no-main-commit` - block direct commits to a protected branch
+ * (main / master / mainline / trunk).
+ *
+ * Fires on:
+ *   - `git commit -m "..."` when the current branch is one of the
+ *     protected names,
+ *   - `git checkout main && git commit ...` (the branch tracker folds
+ *     the checkout into the branch state for the commit),
+ *   - `sh -c 'git commit ...'` (wrapper expansion),
+ *   - `git -C /other commit ...` where the repo at `/other` is on
+ *     main (the `branch` predicate queries git at the effective cwd).
+ *
+ * Does NOT fire on:
+ *   - `git commit` while on a feature branch,
+ *   - `git log --grep="commit"` (anchored to `git commit`, not
+ *     arbitrary git subcommands),
+ *   - `echo 'git commit -m "x"'` (extraction anchors to the
+ *     basename).
+ *
+ * Fail-closed on unresolvable branch: if the branch predicate can't
+ * determine the current branch (detached HEAD, not a repo, or the
+ * tracker collapsed to `unknown` via `git checkout $VAR`), the rule
+ * fires by default. Authors who want the allow-through behavior
+ * supply the object form explicitly:
+ *
+ *   `when: { branch: { pattern: /.../, onUnknown: "allow" } }`
+ *
+ * Reason text is dynamic via {@link ReasonFn}: when the branch
+ * tracker has resolved a concrete branch name for the guarded
+ * command (statically from a `git checkout <name>` earlier in the
+ * chain), the name is injected into the block message so the agent
+ * sees "You are on 'main'" instead of a generic reminder. The
+ * ReasonFn filters out the tracker's internal sentinels
+ * (`NO_CHECKOUT_IN_CHAIN` — no in-chain checkout, exec-fallback
+ * path; `"unknown"` — dynamic checkout the walker couldn't
+ * resolve) so those strings never leak into the agent-facing
+ * message; the static actionable tail still guides the agent to a
+ * feature branch in those cases.
+ *
+ * Pairs with {@link noMainCommitGithub} (specialization for
+ * github.com clones, placed BEFORE this rule in the rule array so
+ * first-match-wins routes the github-flavored guidance to github
+ * users; non-github contexts fall through to this generic rule).
+ *
+ * Override: allowed (the rule is overridable via a
+ * `# steering-override: no-main-commit` comment). This is a workflow
+ * rule, not an inherent-destructiveness rule - authors override when
+ * the commit is intentional (e.g. release process on `main`).
+ */
+export const noMainCommit = {
+  name: "no-main-commit",
+  tool: "bash",
+  field: "command",
+  pattern: GIT_COMMIT_PATTERN,
+  when: { branch: PROTECTED_BRANCH_PATTERN },
+  reason: (ctx) => {
+    // Delegate the sentinel classification to `walkerString` — the
+    // same three-way discrimination (value / unknown / missing)
+    // every other branch-consumer in this plugin uses. Single source
+    // of truth for tracker-sentinel semantics; future sentinel
+    // additions update one site (the classifier in predicates.ts),
+    // not this filter too. Empty-string remains filtered inline as
+    // a defensive check against future tracker contracts (detached
+    // HEAD or similar); the branch tracker doesn't emit it today.
+    const res = walkerString(ctx, "branch", NO_CHECKOUT_IN_CHAIN);
+    const branch =
+      res.kind === "value" && res.value !== "" ? res.value : undefined;
+    const onClause = branch !== undefined ? ` You are on '${branch}'.` : "";
+    return (
+      `Don't commit directly to a protected branch ` +
+      `(main / master / mainline / trunk).${onClause} ` +
+      `Create a feature branch first: \`git checkout -b feat/...\`.`
+    );
+  },
+  // Explicit override-OK: workflow rules are intentionally
+  // overridable.
+  noOverride: false,
+} as const satisfies Rule;
+
+/**
+ * `no-main-commit-github` — block direct commits to a protected
+ * branch (main / master / mainline / trunk) on github.com clones.
+ * Specialization of {@link noMainCommit} that emits PR-flow guidance
+ * instead of the generic feature-branch reminder.
+ *
+ * Pairs with {@link noMainCommit}: this rule is more specific (adds
+ * `remote:` check), placed BEFORE `noMainCommit` in the plugin's
+ * rule array so first-match-wins routing surfaces the github-
+ * flavored reason on github clones. Non-github contexts (Brazil
+ * packages, vault paths, /tmp scratch repos with non-github remotes)
+ * fall through to the generic `noMainCommit`.
+ *
+ * Override: allowed (intentionally overridable for legitimate cases
+ * like release-process commits to main). User can:
+ *   - Disable: `disabledRules: ["no-main-commit-github"]`
+ *   - Per-invocation: `# steering-override: no-main-commit-github` comment
+ *   - Customize: see gitPlugin's README "Customization" section
+ *
+ * @remarks Both `https://github.com/...` and `git@github.com:...`
+ *          clone URLs are matched (the `remote:` regex's `[/:]`
+ *          character class accepts both the HTTPS path separator
+ *          and the SSH user-host separator).
+ *
+ * @remarks `remote:` is configured as `{ pattern, onUnknown: "allow" }`.
+ *          The `onUnknown: "allow"` argument governs the case where
+ *          the walker resolved cwd but the inner exec couldn't
+ *          determine the remote URL — i.e. a known-cwd repo with no
+ *          `origin` remote configured (fresh-init, repo with
+ *          `upstream` but no `origin`, or other exec failure). In that
+ *          case the predicate skips and the engine falls through to
+ *          the generic `noMainCommit` (correct generic message).
+ *          The branch predicate stays at default `onUnknown: "block"`
+ *          (fail-closed) so protected-branch detection isn't weakened.
+ *
+ * Walker-unknown cwd: the `remote:` leaf surfaces trinary
+ * `"unknown"` (via the inline walker-unknown-cwd guard at the top of
+ * the handler) before the inner exec runs whenever
+ * `walkerState.cwd === "unknown"`. The engine's leaf-level
+ * `onUnknown:` policy reads the `"allow"` set on the leaf, projects
+ * `"unknown" → false`, and the github rule SKIPS. The engine then
+ * falls through to the generic {@link noMainCommit} (only `branch:`
+ * leaf), which fires fail-CLOSED and emits the generic
+ * protected-branch reason. The github-specific rule deliberately
+ * does NOT fire under walker-unknown cwd — a github-flavored reason
+ * would overstate what the engine has confirmed.
+ *
+ * Walker-unknown branch state: when `walkerState.cwd` is known but
+ * the branch tracker collapses to its `"unknown"` sentinel (dynamic
+ * checkout the walker couldn't resolve), the reason fn routes to a
+ * "could not verify the current branch" message rather than
+ * asserting a specific protected branch the engine hasn't
+ * confirmed.
+ *
+ * Pattern is shared with `noMainCommit` via the exported
+ * {@link GIT_COMMIT_PATTERN} constant so the two rules' bash-
+ * command applicability stays byte-equal as the family evolves.
+ *
+ * @see {@link noMainCommit}
+ */
+export const noMainCommitGithub = {
+  name: "no-main-commit-github",
+  tool: "bash",
+  field: "command",
+  pattern: GIT_COMMIT_PATTERN,
+  when: {
+    branch: PROTECTED_BRANCH_PATTERN,
+    // Intentional fail-OPEN — falls through to the generic
+    // `noMainCommit` rule when origin can't be resolved.
+    //
+    // `onUnknown: "allow"` posture: a github-specialized rule
+    // should only fire when github context is confirmed. The
+    // `"allow"` covers two opt-out paths:
+    //   1. Known-cwd no-`origin` case (fresh-init repo, repo with
+    //      `upstream` but no `origin`, or other exec failure):
+    //      handler returns `false`, leaf projects to false, github
+    //      rule skips. Generic `noMainCommit` fires next — user
+    //      gets the correct generic message rather than PR-flow
+    //      guidance for a repo where there's no PR to open.
+    //   2. Walker-unknown cwd (`cd "$VAR" && git commit`): the
+    //      handler's inline guard surfaces trinary `"unknown"`,
+    //      the leaf-level `"allow"` projects to false, github rule
+    //      skips. Generic `noMainCommit` fires fail-CLOSED via the
+    //      branch predicate's default `onUnknown: "block"`.
+    // Both paths land on the same generic protected-branch reason,
+    // avoiding overstated github-specific claims when context is
+    // unverified.
+    remote: { pattern: /github\.com[/:]/, onUnknown: "allow" },
+  },
+  reason: (ctx) => {
+    // Walker-unknown branch: protected-branch unverified. Don't
+    // make a positive claim about which protected branch is
+    // involved.
+    //
+    // (CWD is always known in this rule's reason fn — `remote:`'s
+    //  `onUnknown: "allow"` projects walker-unknown CWD to false at
+    //  the leaf level, so the rule skips to the generic
+    //  `noMainCommit` before this reason fn runs.)
+    const branchRes = walkerString(ctx, "branch", NO_CHECKOUT_IN_CHAIN);
+    if (branchRes.kind === "unknown") {
+      return (
+        `Could not verify the current branch — your command used a ` +
+        `dynamic checkout target (\`git checkout $VAR\`) that ` +
+        `couldn't be statically resolved. If you're on a protected ` +
+        `branch (main / master / mainline / trunk) on a github ` +
+        `clone, open a PR for review instead of committing directly.` +
+        `\n\n` +
+        `Safety: NEVER merge a PR or mark it ready-for-review unless ` +
+        `the user explicitly asks. Wait for explicit user instruction.`
+      );
+    }
+    // Reuse the same walkerString-based branch interpolation idiom
+    // noMainCommit's reason fn uses (single source of truth for
+    // tracker-sentinel semantics).
+    const branch =
+      branchRes.kind === "value" && branchRes.value !== ""
+        ? branchRes.value
+        : undefined;
+    const onClause = branch !== undefined ? ` You are on '${branch}'.` : "";
+    // Prose says "protected branch" rather than "main branch":
+    // the `when:` clause matches all four protected branch names
+    // (main / master / mainline / trunk). Mirrors
+    // `noMainCommit`'s wording, which lists them.
+    return (
+      `You're on a github clone's protected branch.${onClause} Open ` +
+      `a PR for review; \`gh pr merge\` lands the change after ` +
+      `approval. Direct commits to a protected branch bypass review ` +
+      `and break PR discipline.` +
+      `\n\n` +
+      `Safety: NEVER merge a PR or mark it ready-for-review unless ` +
+      `the user explicitly asks. Wait for explicit user instruction.`
+    );
+  },
+  // Explicit override-OK: workflow rules are intentionally
+  // overridable. Mirrors `noMainCommit`'s posture. Without this
+  // field the schema defaults to `defaultNoOverride: true`
+  // (fail-closed), making the rule non-overridable and contradicting
+  // the JSDoc above.
+  noOverride: false,
+} as const satisfies Rule;
+
+/**
+ * Suggested rules for the git plugin.
+ *
+ * **Order matters — first-match-wins.** The github-specific rule
+ * (`no-main-commit-github`) is placed BEFORE the generic
+ * (`no-main-commit`) so on github clones + on main, the github
+ * rule's `remote:` predicate matches → fires first → user gets
+ * PR-flow guidance. On non-github contexts (Brazil packages, vault
+ * paths, scratch repos with non-github remotes) the github rule's
+ * `remote:` predicate doesn't match → the engine falls through to
+ * the generic `no-main-commit`. Reordering for stylistic reasons
+ * breaks this routing; pinned via a unit test in `./rules.test.ts`.
+ */
+export const rules = [
+  noMainCommitGithub,
+  noMainCommit,
+] as const satisfies readonly Rule[];

package/src/schema.test.ts

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Runtime shape smoke tests for the v2 schema types.
+ *
+ * These tests construct object literals and assert their runtime shape —
+ * they do NOT currently exercise compile-time type enforcement via
+ * `@ts-expect-error` directives. Real type-level regression tests for
+ * `defineConfig` inference live in `define-config.test.ts`.
+ *
+ * The value here is: if the schema types drift incompatibly with their
+ * runtime contract (e.g., a field is renamed but the Rule interface
+ * isn't updated), these tests fail to compile even without explicit
+ * negative assertions. For richer type enforcement, extend with
+ * `@ts-expect-error` cases or move to `define-config.test.ts`.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+  Observer,
+  Plugin,
+  PredicateContext,
+  PredicateFn,
+  PredicateHandler,
+  Rule,
+  SteeringConfig,
+  WhenClause,
+} from "./schema.ts";
+
+describe("schema: shape smoke tests", () => {
+  it("Rule accepts a minimal bash rule with a string pattern", () => {
+    const rule: Rule = {
+      name: "test",
+      tool: "bash",
+      field: "command",
+      pattern: "^git push --force",
+      reason: "nope",
+    };
+    assert.equal(rule.name, "test");
+  });
+
+  it("Rule accepts RegExp in pattern / requires / unless", () => {
+    const rule: Rule = {
+      name: "regex-rule",
+      tool: "bash",
+      field: "command",
+      pattern: /^git push/,
+      requires: /--force/,
+      unless: /--force-with-lease/,
+      reason: "nope",
+    };
+    assert.ok(rule.pattern instanceof RegExp);
+  });
+
+  it("Rule accepts PredicateFn in requires / unless", () => {
+    const always: PredicateFn = async (_ctx) => true;
+    const rule: Rule = {
+      name: "fn-rule",
+      tool: "bash",
+      field: "command",
+      pattern: "^git",
+      requires: always,
+      unless: async (ctx) => ctx.tool === "bash",
+      reason: "nope",
+    };
+    assert.equal(typeof rule.requires, "function");
+  });
+
+  it("WhenClause accepts cwd as pattern or object with onUnknown", () => {
+    const w1: WhenClause = { cwd: "^/workplace" };
+    const w2: WhenClause = { cwd: /^\/workplace/ };
+    const w3: WhenClause = {
+      cwd: { pattern: /^\/workplace/, onUnknown: "block" },
+    };
+    assert.ok(w1.cwd !== undefined);
+    assert.ok(w2.cwd !== undefined);
+    assert.ok(w3.cwd !== undefined);
+  });
+
+  it("WhenClause.condition accepts a PredicateFn", () => {
+    const w: WhenClause = {
+      condition: (ctx) => ctx.tool === "bash",
+    };
+    assert.equal(typeof w.condition, "function");
+  });
+
+  it("WhenClause accepts plugin-registered custom keys", () => {
+    // Shape a plugin predicate registers. Consumers widen the
+    // index signature to carry arbitrary shapes.
+    const w: WhenClause = {
+      commitsAhead: { wrt: "origin/main", eq: 1 },
+    };
+    assert.ok("commitsAhead" in w);
+  });
+
+  it("Observer accepts minimal shape (name + onResult)", () => {
+    const obs: Observer = {
+      name: "spy",
+      onResult: (_ev, _ctx) => {},
+    };
+    assert.equal(obs.name, "spy");
+  });
+
+  it("Observer.watch accepts every documented filter", () => {
+    const obs: Observer = {
+      name: "filtered",
+      watch: {
+        toolName: "bash",
+        inputMatches: { command: /^git/ },
+        exitCode: "success",
+      },
+      onResult: () => {},
+    };
+    assert.equal(obs.watch?.exitCode, "success");
+  });
+
+  it("Plugin accepts every documented extension point", () => {
+    const fakeHandler: PredicateHandler<{ wrt: string }> = (args, _ctx) =>
+      args.wrt.startsWith("origin/");
+    const plugin: Plugin = {
+      name: "fake",
+      // No cast on the typed `PredicateHandler<{ wrt: string }>` here —
+      // Item 2 of PR #5 switched `Plugin.predicates` to
+      // `Record<string, AnyPredicateHandler>`, so specifically-typed
+      // handlers assign into the registry slot directly.
+      predicates: { commitsAhead: fakeHandler },
+      rules: [
+        {
+          name: "r",
+          tool: "bash",
+          field: "command",
+          pattern: /^x/,
+          reason: "n",
+        },
+      ],
+      observers: [{ name: "o", onResult: () => {} }],
+      // trackers and trackerExtensions left undefined — the
+      // schema-level type is just `Record<string, Tracker<unknown>>`,
+      // constructing a live tracker here would pull in walker
+      // runtime code we don't need for a shape test.
+    };
+    assert.equal(plugin.name, "fake");
+  });
+
+  it("Plugin.predicates accepts typed PredicateHandler<A> values without a cast", () => {
+    // Pins the Item 2 fix: `Plugin.predicates` is
+    // `Record<string, AnyPredicateHandler>`, so a specifically-typed
+    // `PredicateHandler<FooArgs>` assigns cast-free at the registry
+    // slot. If this starts failing to compile, the alias was
+    // widened/narrowed incompatibly — every downstream plugin that
+    // registers a typed handler will break on the same change.
+    interface FooArgs {
+      threshold: number;
+    }
+    const typed: PredicateHandler<FooArgs> = (args) => args.threshold > 0;
+    const plugin = {
+      name: "typed-predicates",
+      predicates: { foo: typed },
+    } satisfies Plugin;
+    assert.ok(plugin.predicates);
+  });
+
+  it("Rule.observer accepts inline Observer and string reference", () => {
+    const inline: Rule = {
+      name: "inline-obs",
+      tool: "bash",
+      field: "command",
+      pattern: /./,
+      reason: "r",
+      observer: { name: "o", onResult: () => {} },
+    };
+    const byName: Rule<"o"> = {
+      name: "by-name",
+      tool: "bash",
+      field: "command",
+      pattern: /./,
+      reason: "r",
+      observer: "o",
+    };
+    assert.equal(byName.observer, "o");
+    assert.ok(typeof inline.observer === "object");
+  });
+
+  it("Rule accepts writes + onFire for self-marking patterns", () => {
+    const rule: Rule = {
+      name: "self-marker",
+      tool: "bash",
+      field: "command",
+      pattern: /./,
+      reason: "r",
+      writes: ["cr-attempted"],
+      onFire: (ctx) => {
+        ctx.appendEntry("cr-attempted", {});
+      },
+    };
+    assert.deepEqual(rule.writes, ["cr-attempted"]);
+    assert.equal(typeof rule.onFire, "function");
+  });
+
+  it("Observer accepts writes declaration", () => {
+    const obs: Observer = {
+      name: "tracker",
+      writes: ["ws-sync-done", "ws-sync-failed"],
+      onResult: () => {},
+    };
+    assert.deepEqual(obs.writes, ["ws-sync-done", "ws-sync-failed"]);
+  });
+
+  it("WhenClause.happened accepts the { event, in } shape", () => {
+    const loop: WhenClause = {
+      happened: { event: "ws-sync-done", in: "agent_loop" },
+    };
+    const session: WhenClause = {
+      happened: { event: "welcome-shown", in: "session" },
+    };
+    assert.equal(loop.happened?.event, "ws-sync-done");
+    assert.equal(session.happened?.in, "session");
+  });
+
+  it("SteeringConfig accepts every top-level field", () => {
+    const cfg: SteeringConfig = {
+      defaultNoOverride: true,
+      disabledRules: ["no-force-push"],
+      disabledPlugins: ["git"],
+      disableDefaults: false,
+      plugins: [],
+      rules: [],
+      observers: [],
+    };
+    assert.equal(cfg.defaultNoOverride, true);
+  });
+
+  it("PredicateContext exposes the documented surface", () => {
+    // Pure shape test — we never invoke the context.
+    const fake: PredicateContext = {
+      cwd: "/",
+      tool: "bash",
+      input: { tool: "bash", command: "echo" },
+      agentLoopIndex: 0,
+      exec: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+      appendEntry: () => {},
+      findEntries: () => [],
+    };
+    assert.equal(fake.cwd, "/");
+  });
+});
+
+describe("package-root exports", () => {
+  it("AGENT_LOOP_INDEX_KEY resolves to the on-disk JSONL tag string (C3)", async () => {
+    // Pins the public export path. Plugin authors inspecting raw
+    // session entries via `findEntries` import the constant instead
+    // of hardcoding the string — a future rename would then break at
+    // import time, not at runtime.
+    const rootExports = await import("./index.ts");
+    assert.equal(rootExports.AGENT_LOOP_INDEX_KEY, "_agentLoopIndex");
+  });
+});