@jwilger/pi-development-system 0.1.2 → 0.3.0

package/src/core/test-weakening.ts

@@ -0,0 +1,68 @@
+import { parse } from "shell-quote";
+
+export type WeakeningSignals = { addsSkip: boolean; emptied: boolean };
+
+const SKIP_MARKERS: readonly RegExp[] = [
+  /\b(?:it|test|describe|context)\.(?:skip|todo)\b/,
+  /\bx(?:it|describe|test)\(/,
+  /#\[ignore\b/,
+  /@pytest\.mark\.skip|@unittest\.skip|\bpytest\.skip\(/,
+  /\bt\.Skip(?:Now|f)?\(/,
+  /@Disabled\b|@Ignore\b/,
+];
+
+const countSkips = (text: string): number =>
+  SKIP_MARKERS.reduce((n, re) => n + (text.match(new RegExp(re.source, "g"))?.length ?? 0), 0);
+
+/** Deterministic weakening signals between two versions of a test file. */
+export function weakeningSignals(before: string, after: string): WeakeningSignals {
+  return {
+    addsSkip: countSkips(after) > countSkips(before),
+    emptied: before.trim() !== "" && after.trim() === "",
+  };
+}
+
+/** Applies `edits` to `content` (first occurrence each, in order); unmatched edits are ignored. */
+export function applyEdits(
+  content: string,
+  edits: ReadonlyArray<{ oldText: string; newText: string }>,
+): string {
+  return edits.reduce((text, e) => {
+    const at = text.indexOf(e.oldText);
+    return at < 0 ? text : text.slice(0, at) + e.newText + text.slice(at + e.oldText.length);
+  }, content);
+}
+
+/** True when every line of `before` still appears (with multiplicity) in `after`. */
+export function isPureAddition(before: string, after: string): boolean {
+  const remaining = new Map<string, number>();
+  for (const line of after.split("\n")) remaining.set(line, (remaining.get(line) ?? 0) + 1);
+  for (const line of before.split("\n")) {
+    const left = remaining.get(line) ?? 0;
+    if (left === 0) return false;
+    remaining.set(line, left - 1);
+  }
+  return true;
+}
+
+const DELETERS = new Set(["rm", "unlink", "trash", "rmdir"]);
+
+/** Paths a bash command removes via rm / unlink / `git rm` (best effort, per simple command). */
+export function bashDeletedPaths(command: string): string[] {
+  const paths: string[] = [];
+  let current: string[] = [];
+  const flush = () => {
+    const head = current[0] === "git" && current[1] === "rm" ? "rm" : current[0];
+    const args = current[0] === "git" ? current.slice(2) : current.slice(1);
+    if (head !== undefined && DELETERS.has(head)) {
+      paths.push(...args.filter((a) => !a.startsWith("-")));
+    }
+    current = [];
+  };
+  for (const token of parse(command)) {
+    if (typeof token === "string") current.push(token);
+    else flush();
+  }
+  flush();
+  return paths;
+}

package/src/gates/approvals.ts

@@ -0,0 +1,101 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Departure, parseDeparture } from "../core/departure.ts";
+import { lookupGate } from "../core/gates.ts";
+import { redactSecrets } from "../core/redact.ts";
+import { type GateId, isParseError } from "../core/types.ts";
+import { appendDecision } from "../state/decision-log.ts";
+import { DEPARTURE_ENTRY_TYPE } from "./record-departure-tool.ts";
+
+export const APPROVAL_ENTRY_TYPE = "devsys-approval";
+
+type Approval = { id: string; gate: string; command: string; used: boolean };
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Pre-granted, single-use approvals for an exact (gate, command) pair, persisted as session entries. */
+export type ApprovalStore = {
+  grant(gate: string, command: string, id: string): void;
+  /** True (and marks the approval used) when an unused approval exists for this exact pair. */
+  consume(gate: string, command: string): boolean;
+  rebuildFrom(entries: ReadonlyArray<{ customType: string; data: unknown }>): void;
+};
+
+export function createApprovalStore(pi: ExtensionAPI): ApprovalStore {
+  let approvals: Approval[] = [];
+  const persist = (a: Approval) => pi.appendEntry(APPROVAL_ENTRY_TYPE, a);
+  return {
+    grant(gate, command, id) {
+      const approval = { id, gate, command: command.trim(), used: false };
+      approvals.push(approval);
+      persist(approval);
+    },
+    consume(gate, command) {
+      const found = approvals.find(
+        (a) => !a.used && a.gate === gate && a.command === command.trim(),
+      );
+      if (found === undefined) return false;
+      found.used = true;
+      persist(found);
+      return true;
+    },
+    rebuildFrom(entries) {
+      const byId = new Map<string, Approval>();
+      for (const e of entries) {
+        if (e.customType !== APPROVAL_ENTRY_TYPE || !isRecord(e.data)) continue;
+        const { id, gate, command, used } = e.data;
+        if (
+          typeof id === "string" &&
+          typeof gate === "string" &&
+          typeof command === "string" &&
+          typeof used === "boolean"
+        ) {
+          byId.set(id, { id, gate, command, used });
+        }
+      }
+      approvals = [...byId.values()];
+    },
+  };
+}
+
+export type HardStopRequest = {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  gate: GateId;
+  command: string;
+  why: string;
+  toolCallId: string;
+  now?: () => Date;
+};
+
+export type HardStopOutcome =
+  | { kind: "approved"; departure: Departure }
+  | { kind: "declined" }
+  | { kind: "unavailable" };
+
+/** Asks the user to approve one irreversible action; on approval records it (hard · user · once). */
+export async function requestHardStop(req: HardStopRequest): Promise<HardStopOutcome> {
+  if (!req.ctx.hasUI) return { kind: "unavailable" };
+  const approved = await req.ctx.ui.confirm(
+    "Development system — hard stop",
+    `${redactSecrets(req.command)}\nGate: ${req.gate}\nThis is irreversible. Approve once?`,
+  );
+  if (!approved) return { kind: "declined" };
+  const at = (req.now ?? (() => new Date()))();
+  const departure = parseDeparture({
+    id: `dep-${at.getTime()}-${req.toolCallId}`,
+    gate: req.gate,
+    tier: "hard",
+    default: lookupGate(req.gate)?.default ?? "hard stop",
+    chosen: redactSecrets(req.command),
+    why: redactSecrets(req.why),
+    costIfWrong: "an irreversible git operation is performed",
+    approver: "user",
+    scope: { kind: "once", toolCallId: req.toolCallId },
+    recordedAt: at.toISOString().replace(/\.\d{3}Z$/, "Z"),
+  });
+  if (isParseError(departure)) throw new Error(departure.message);
+  await appendDecision(req.ctx.cwd, departure, at);
+  req.pi.appendEntry(DEPARTURE_ENTRY_TYPE, departure);
+  return { kind: "approved", departure };
+}

package/src/gates/git-guard.ts

@@ -0,0 +1,79 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { classifyGitCommand, type GitIntent } from "../core/git-intent.ts";
+import { redactSecrets } from "../core/redact.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeShellIntent } from "../jev/questions/shell-intent.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+const HARD: ReadonlySet<GitIntent> = new Set([
+  "history-rewrite",
+  "force-push",
+  "branch-delete-remote",
+  "destructive-reset",
+  "no-verify",
+]);
+
+export type GitGuardDeps = {
+  pi: ExtensionAPI;
+  approvals: ApprovalStore;
+  /** Jev for the current context; absent means the deterministic fast path only. */
+  jev?: (ctx: ExtensionContext) => Jev;
+  now?: () => Date;
+};
+
+/** Registers the `tool_call` hard stop for irreversible git operations in bash. */
+export function registerGitGuard(deps: GitGuardDeps): void {
+  deps.pi.on("tool_call", async (event, ctx) => {
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const command = event.input.command;
+    let intent = classifyGitCommand(command);
+    if (intent === "unknown") {
+      const judged =
+        deps.jev === undefined ? undefined : await judgeShellIntent(deps.jev(ctx), command);
+      if (judged?.ok === true && judged.value.intent !== "unknown") {
+        intent = judged.value.intent;
+      } else {
+        const approved = ctx.hasUI
+          ? await ctx.ui.confirm(
+              "Development system — unclassified command",
+              `${redactSecrets(command)}\nCould not classify this command (Jev ${judged?.ok === false ? `unavailable: ${judged.error.kind}` : "not confident"}). It may run an irreversible git operation. Approve?`,
+            )
+          : false;
+        return approved
+          ? undefined
+          : {
+              block: true,
+              reason: ctx.hasUI
+                ? "the user declined an unclassifiable command; propose a simpler, explicit git command"
+                : "could not classify this command and Jev is unavailable or unsure; run interactively or use an explicit git command",
+            };
+      }
+    }
+    if (!HARD.has(intent)) return undefined;
+    const gate = parseGateId(`git.${intent}`);
+    if (isParseError(gate)) return { block: true, reason: gate.message };
+    if (deps.approvals.consume(gate, command)) return undefined;
+    const outcome = await requestHardStop({
+      pi: deps.pi,
+      ctx,
+      gate,
+      command,
+      why: "approved interactively at the hard-stop dialog",
+      toolCallId: event.toolCallId,
+      ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    if (outcome.kind === "approved") return undefined;
+    return {
+      block: true,
+      reason:
+        outcome.kind === "unavailable"
+          ? `hard stop ${gate}: requires user approval; run interactively`
+          : `hard stop ${gate}: the user declined this command. Do not retry it; propose a reversible alternative.`,
+    };
+  });
+}

package/src/gates/record-departure-tool.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { parseDeparture, renderDepartureMarkdown } from "../core/departure.ts";
+import { gateIds, lookupGate } from "../core/gates.ts";
+import { redactSecrets } from "../core/redact.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import { appendDecision } from "../state/decision-log.ts";
+import type { SessionState } from "../state/session-state.ts";
+
+export const DEPARTURE_ENTRY_TYPE = "devsys-departure";
+
+const Parameters = Type.Object({
+  gate: Type.String({ description: `Gate id. One of: ${gateIds().join(", ")}` }),
+  chosen: Type.String({ description: "What you are doing instead of the default" }),
+  why: Type.String({ description: "Why the default does not fit here" }),
+  costIfWrong: Type.String({ description: "What goes wrong if this judgement is mistaken" }),
+  scope: Type.Union([Type.Literal("slice"), Type.Literal("session"), Type.Literal("once")], {
+    description: "How long the departure applies",
+  }),
+  revisitWhen: Type.Optional(Type.String({ description: "Condition that should reopen this" })),
+});
+
+export type RecordDepartureDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  now?: () => Date;
+};
+
+const fail = (text: string) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError: true,
+});
+
+function resolveScope(kind: "slice" | "session" | "once", toolCallId: string, slice?: string) {
+  if (kind === "once") return { kind, toolCallId };
+  if (kind === "session") return { kind };
+  return slice !== undefined ? { kind, slice } : undefined;
+}
+
+/** `devsys_record_departure`: the sanctioned escape hatch for soft gates. */
+export function createRecordDepartureTool(
+  deps: RecordDepartureDeps,
+): ToolDefinition<typeof Parameters> {
+  const now = deps.now ?? (() => new Date());
+  return {
+    name: "devsys_record_departure",
+    label: "Record departure",
+    description:
+      "Record a deliberate departure from a soft default before acting against it. " +
+      "Hard stops (git history/force/no-verify) cannot be recorded here; use devsys_request_approval.",
+    promptSnippet: "Record a departure from a development-system default (soft gates only)",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(toolCallId, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const gate = parseGateId(params.gate);
+      const info = isParseError(gate) ? undefined : lookupGate(gate);
+      if (isParseError(gate) || info === undefined) {
+        return fail(`Unknown gate "${params.gate}". Registered gates: ${gateIds().join(", ")}`);
+      }
+      if (info.tier === "hard") {
+        return fail(
+          `Gate ${gate} is a hard stop: it needs the user. Call devsys_request_approval with the command and your reason.`,
+        );
+      }
+      const current = deps.state.get();
+      const scope = resolveScope(params.scope, toolCallId, current.activeSlice);
+      if (scope === undefined) {
+        return fail('scope "slice" needs an active slice; use "session" or "once" instead.');
+      }
+      const recordedAt = now();
+      const departure = parseDeparture({
+        id: `dep-${recordedAt.getTime()}-${toolCallId}`,
+        gate,
+        tier: info.tier,
+        default: info.default,
+        chosen: redactSecrets(params.chosen),
+        why: redactSecrets(params.why),
+        costIfWrong: redactSecrets(params.costIfWrong),
+        approver: "agent",
+        scope,
+        ...(params.revisitWhen !== undefined
+          ? { revisitWhen: redactSecrets(params.revisitWhen) }
+          : {}),
+        recordedAt: recordedAt.toISOString().replace(/\.\d{3}Z$/, "Z"),
+      });
+      if (isParseError(departure)) return fail(departure.message);
+      const { path } = await appendDecision(ctx.cwd, departure, recordedAt);
+      deps.pi.appendEntry(DEPARTURE_ENTRY_TYPE, departure);
+      deps.state.update((s) => ({ ...s, openDepartures: [...s.openDepartures, departure] }));
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Recorded in ${path}:\n\n${renderDepartureMarkdown(departure)}`,
+          },
+        ],
+        details: undefined,
+      };
+    },
+  };
+}

package/src/gates/request-approval-tool.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { gateIds, lookupGate } from "../core/gates.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+const Parameters = Type.Object({
+  gate: Type.String({ description: "A hard gate id, e.g. git.force-push" }),
+  command: Type.String({ description: "The exact command you intend to run afterwards" }),
+  why: Type.String({ description: "Why this irreversible action is needed" }),
+});
+
+const text = (t: string, isError = false) => ({
+  content: [{ type: "text" as const, text: t }],
+  details: undefined,
+  isError,
+});
+
+export type RequestApprovalDeps = { pi: ExtensionAPI; approvals: ApprovalStore; now?: () => Date };
+
+/** `devsys_request_approval`: ask the user ahead of time to approve one hard-stop command. */
+export function createRequestApprovalTool(
+  deps: RequestApprovalDeps,
+): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_request_approval",
+    label: "Request approval",
+    description:
+      "Ask the user to approve one irreversible command (hard stop). Approval is single-use and " +
+      "only valid for the exact command text. Unavailable when running headless.",
+    promptSnippet: "Ask the user to approve an irreversible git command (hard stop)",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(toolCallId, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const gate = parseGateId(params.gate);
+      if (isParseError(gate) || gate.includes(":") || lookupGate(gate)?.tier !== "hard") {
+        const hard = gateIds().filter((id) => lookupGate(id)?.tier === "hard");
+        return text(`"${params.gate}" is not a hard gate. Hard gates: ${hard.join(", ")}`, true);
+      }
+      const outcome = await requestHardStop({
+        pi: deps.pi,
+        ctx,
+        gate,
+        command: params.command,
+        why: params.why,
+        toolCallId,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+      });
+      if (outcome.kind === "unavailable") {
+        return text("unavailable headless: hard stops need an interactive user.", true);
+      }
+      if (outcome.kind === "declined") {
+        return text(
+          "The user declined. Do not run this command; propose a reversible alternative.",
+          true,
+        );
+      }
+      deps.approvals.grant(gate, params.command, outcome.departure.id);
+      return text(`Approved once for gate ${gate}. Run exactly: ${params.command}`);
+    },
+  };
+}

package/src/gates/test-guard.ts

@@ -0,0 +1,176 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { isTestPath } from "../core/test-paths.ts";
+import {
+  applyEdits,
+  bashDeletedPaths,
+  isPureAddition,
+  weakeningSignals,
+} from "../core/test-weakening.ts";
+import { type GateId, isParseError, parseGateId } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeTestChange, WEAKENS_THRESHOLD } from "../jev/questions/test-change.ts";
+import type { SessionState } from "../state/session-state.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+export type TestGuardDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  approvals: ApprovalStore;
+  jev: (ctx: ExtensionContext) => Jev;
+  now?: () => Date;
+};
+
+type Change = { path: string; before: string; after: string | undefined };
+
+type Verdict =
+  | { kind: "allow" }
+  | { kind: "require-departure"; why: string }
+  | { kind: "hard-stop"; why: string };
+
+const GATE_ID = "tests.weaken";
+
+const describeSignals = (
+  deleted: boolean,
+  signals: { addsSkip: boolean; emptied: boolean },
+): string | undefined => {
+  if (deleted) return "deletes the test file";
+  if (signals.addsSkip) return "skips tests";
+  if (signals.emptied) return "empties the test file";
+  return undefined;
+};
+
+const readIfExists = (file: string): string | undefined => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+const repoPath = (cwd: string, path: string): string =>
+  isAbsolute(path) ? relative(cwd, path) : path;
+
+/**
+ * Soft gate `tests.weaken`: deleting, skipping, emptying or loosening tests needs a recorded
+ * departure; a change Jev reads as gaming a failing gate escalates to a hard stop.
+ */
+export function registerTestGuard(deps: TestGuardDeps): void {
+  const gate: GateId | undefined = (() => {
+    const parsed = parseGateId(GATE_ID);
+    return isParseError(parsed) ? undefined : parsed;
+  })();
+  if (gate === undefined) return;
+
+  const hasOpenDeparture = (): boolean => {
+    const { openDepartures, activeSlice } = deps.state.get();
+    return openDepartures.some(
+      (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
+    );
+  };
+
+  const consumeOpenDeparture = (): void => {
+    const { openDepartures, activeSlice } = deps.state.get();
+    const used = openDepartures.find(
+      (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
+    );
+    if (used?.scope.kind !== "once") return;
+    deps.state.update((s) => ({
+      ...s,
+      openDepartures: s.openDepartures.filter((d) => d.id !== used.id),
+    }));
+  };
+
+  const judge = async (change: Change, ctx: ExtensionContext): Promise<Verdict> => {
+    const deleted = change.after === undefined;
+    if (!deleted && isPureAddition(change.before, change.after ?? "")) return { kind: "allow" };
+    const signals = deleted
+      ? { addsSkip: false, emptied: false }
+      : weakeningSignals(change.before, change.after ?? "");
+    const deterministic = describeSignals(deleted, signals);
+    const judged = await judgeTestChange(deps.jev(ctx), {
+      path: change.path,
+      before: change.before,
+      ...(change.after !== undefined ? { after: change.after } : {}),
+    });
+    if (judged.ok && judged.value.weakens >= WEAKENS_THRESHOLD) {
+      return judged.value.motive === "gate-gaming"
+        ? {
+            kind: "hard-stop",
+            why: "Jev reads this change as weakening a check to get a green result",
+          }
+        : {
+            kind: "require-departure",
+            why: `Jev reads this change as weakening the tests (motive: ${judged.value.motive})`,
+          };
+    }
+    return deterministic !== undefined
+      ? { kind: "require-departure", why: `this change ${deterministic}` }
+      : { kind: "allow" };
+  };
+
+  deps.pi.on("tool_call", async (event, ctx) => {
+    const changes: Change[] = [];
+    if (isToolCallEventType("bash", event)) {
+      for (const raw of bashDeletedPaths(event.input.command)) {
+        const path = repoPath(ctx.cwd, raw);
+        if (!isTestPath(path)) continue;
+        changes.push({ path, before: readIfExists(join(ctx.cwd, path)) ?? "", after: undefined });
+      }
+    } else if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+      const path = repoPath(ctx.cwd, event.input.path);
+      if (!isTestPath(path)) return undefined;
+      const before = readIfExists(join(ctx.cwd, path));
+      if (before === undefined) return undefined;
+      const after = isToolCallEventType("write", event)
+        ? event.input.content
+        : applyEdits(before, event.input.edits);
+      changes.push({ path, before, after });
+    } else {
+      return undefined;
+    }
+
+    for (const change of changes) {
+      const verdict = await judge(change, ctx);
+      if (verdict.kind === "allow") continue;
+      if (verdict.kind === "require-departure") {
+        if (hasOpenDeparture()) {
+          consumeOpenDeparture();
+          continue;
+        }
+        return {
+          block: true,
+          reason:
+            `${GATE_ID}: ${verdict.why} (${change.path}). Tests are the oracle; weakening them needs a ` +
+            `recorded decision. If this is deliberate, call devsys_record_departure with gate "${GATE_ID}", ` +
+            "what you are doing instead, why, and the cost if wrong; then retry. Otherwise fix the code, not the test.",
+        };
+      }
+      const command = `${isToolCallEventType("bash", event) ? "delete" : "change"} ${change.path}`;
+      if (deps.approvals.consume(gate, command)) continue;
+      const outcome = await requestHardStop({
+        pi: deps.pi,
+        ctx,
+        gate,
+        command,
+        why: verdict.why,
+        toolCallId: event.toolCallId,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+      });
+      if (outcome.kind === "approved") continue;
+      return {
+        block: true,
+        reason:
+          outcome.kind === "unavailable"
+            ? `hard stop ${GATE_ID}: ${verdict.why} (${change.path}); requires user approval; run interactively`
+            : `hard stop ${GATE_ID}: the user declined this change to ${change.path}. Fix the code instead of weakening the test.`,
+      };
+    }
+    return undefined;
+  });
+}