@oisin-ee/oisinpi 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @oisin-ee/oisinpi
+
+## 0.2.0
+
+### Minor Changes
+
+- [#10](https://github.com/oisin-ee/oisinpi/pull/10) [`1c8612b`](https://github.com/oisin-ee/oisinpi/commit/1c8612b7dd1ce00e948d6fd6d3a421f956629e1a) Thanks [@momo-momokaya](https://github.com/apps/momo-momokaya)! - `@oisin-ee/oisinpi` replaces `@oisin-ee/pi-prewalk-kit`. It bundles pi-prewalk, pi-todo, pi-guardrails, and
+  pi-wrangle 0.11.0. `@oisin-ee/pi-guardrails` is new: the agent hook policies for pi, Claude Code (`agent-hook`), and
+  Codex, ported from the dotfiles hooks runtime.
+
+### Patch Changes
+
+- Updated dependencies [[`1c8612b`](https://github.com/oisin-ee/oisinpi/commit/1c8612b7dd1ce00e948d6fd6d3a421f956629e1a)]:
+  - @oisin-ee/pi-guardrails@0.2.0
+  - @oisin-ee/pi-prewalk@0.2.0
+  - @oisin-ee/pi-todo@0.2.0

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @oisin-ee/oisinpi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Oisin's [pi](https://pi.dev) packages in one install, at versions tested together:
+
+| Package                                                                            | Contents                                                                   |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [`@oisin-ee/pi-prewalk`](https://www.npmjs.com/package/@oisin-ee/pi-prewalk)       | A frontier model plans and makes the first edit; a cheaper model finishes. |
+| [`@oisin-ee/pi-todo`](https://www.npmjs.com/package/@oisin-ee/pi-todo)             | The `todo` tool, which also opens the prewalk gate.                        |
+| [`@oisin-ee/pi-wrangle`](https://www.npmjs.com/package/@oisin-ee/pi-wrangle)       | The board, `/wrangle`, and the inbox for children and jobs across hosts.   |
+| [`@oisin-ee/pi-guardrails`](https://www.npmjs.com/package/@oisin-ee/pi-guardrails) | Git safety, the wait gate, and the agent-typing gate on every tool call.   |
+
+```bash
+pi install npm:@oisin-ee/oisinpi
+```
+
+The collection bundles the four packages in its tarball and adds no code. No member imports another, so each one also
+installs by itself. pi-wrangle needs the `wrangle` binary at the same version
+([oisin-ee/wrangle](https://github.com/oisin-ee/wrangle)).

package/node_modules/@oisin-ee/pi-guardrails/README.md

@@ -0,0 +1,29 @@
+# @oisin-ee/pi-guardrails
+
+Agent guardrails for [pi](https://pi.dev), Claude Code, and Codex. One set of policies checks every shell and edit call:
+
+- **Git safety:** no `--no-verify`, no discarding uncommitted work, no stash push and pop in one command, worktrees only
+  under `.worktrees/`, no on-the-fly identity.
+- **Wait gate:** no `sleep`, `watch`, follow flags, `--wait`/`--watch`, or wait subcommands. Start long work in the
+  background instead.
+- **Agent typing:** no `herdr agent prompt` or `pane send-*` into another agent's terminal. Use `wrangle send`.
+- **GitOps:** no imperative `kubectl`, `helm`, `argocd`, or `nix` mutations, and no `fsck`/`mkfs`.
+- **Generated paths:** no hand-edits of lockfiles or generated files.
+
+In pi, it also fills a missing shell timeout (120 s) and blocks one above 10 minutes, naming each tool's unit.
+Shell text is parsed with `shfmt`, which must be on `PATH`. A command that cannot be parsed is blocked.
+
+## pi
+
+```bash
+pi install npm:@oisin-ee/pi-guardrails
+```
+
+## Claude Code and Codex
+
+Install the package globally, then run `agent-hook` as a `PreToolUse` hook for shell and edit tools. It reads the hook
+payload on stdin and exits 2 with the reason on stderr to block.
+
+```json
+{ "type": "command", "command": "agent-hook", "timeout": 30 }
+```

package/node_modules/@oisin-ee/pi-guardrails/dist/agent-hook.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/*
+ * The hook command for Claude Code and Codex: `agent-hook` in their PreToolUse
+ * hooks. Built to `dist/agent-hook.js`, because Node does not strip types from
+ * files under `node_modules`.
+ */
+import { main } from "./lifecycle-runner.js";
+process.exitCode = await main();

package/node_modules/@oisin-ee/pi-guardrails/dist/common.js

@@ -0,0 +1,66 @@
+/* Shared shapes and helpers for the hook payloads and the policies. */
+import { shellCallGuards, shellCalls } from "./shell-parser.js";
+const BLOCK_CODE = 2, SHELL_TOOLS = new Set(["Bash", "bash", "shell"]), EDIT_TOOLS = new Set([
+    "Edit",
+    "Write",
+    "MultiEdit",
+    "apply_patch",
+    "write",
+    "edit",
+    "patch",
+]), isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value), text = (value) => (typeof value === "string" ? value : undefined), 
+/**
+ * The shell text of a hook payload's tool input.
+ * @param {HookPayload} payload A hook payload.
+ * @returns {string} The command, or "".
+ */
+commandFromPayload = (payload) => {
+    const input = payload.tool_input ?? {};
+    return text(input["command"]) ?? text(input["cmd"]) ?? text(input["commandText"]) ?? "";
+}, 
+/**
+ * The calls in `command`. An argument list from an argv-style spawn is
+ * already one call; only shell text needs parsing.
+ * @param {Command} command Shell text or an argument list.
+ * @returns {string[][]} One word list per call.
+ */
+splitShell = (command) => typeof command === "string" ? shellCalls(command) : [[...command]], 
+/**
+ * The `&&` guard pipeline of each splitShell piece. An argv-style call has no
+ * shell operators, so no guard.
+ * @param {Command} command Shell text or an argument list.
+ * @returns {(string[][] | null)[]} One guard per call.
+ */
+splitShellGuards = (command) => typeof command === "string" ? shellCallGuards(command) : [null], 
+/**
+ * The words of the first call in `command`.
+ * @param {Command} command Shell text or an argument list.
+ * @returns {string[]} The words, or none.
+ */
+tokens = (command) => typeof command === "string" ? (shellCalls(command)[0] ?? []) : [...command], 
+/**
+ * A command word without quotes, directory, or `@version`.
+ * @param {string} token A command word.
+ * @returns {string} The bare command name.
+ */
+commandName = (token) => (token
+    .replaceAll(/^["']|["']$/gu, "")
+    .split("/")
+    .pop() ?? "").split("@")[0] ?? "", 
+/**
+ * Blocks a tool call: writes `message` and returns exit code 2.
+ * @param {string} message The reason shown to the agent.
+ * @param {HookIO} io Where the message goes.
+ * @returns {HookResult} The blocking result.
+ */
+block = (message, io) => {
+    io.stderr(`${message}\n`);
+    return { code: BLOCK_CODE };
+}, 
+/**
+ * Allows a tool call, with optional output for the harness.
+ * @param {Readonly<Record<string, unknown>>} extra Keys printed as JSON.
+ * @returns {HookResult} The allowing result.
+ */
+ok = (extra = {}) => ({ code: 0, ...extra });
+export { BLOCK_CODE, EDIT_TOOLS, SHELL_TOOLS, block, commandFromPayload, commandName, isRecord, ok, splitShell, splitShellGuards, tokens, };

package/node_modules/@oisin-ee/pi-guardrails/dist/event-registry.js

@@ -0,0 +1,42 @@
+/* Routes a Claude Code or Codex hook event to the policies. */
+import { EDIT_TOOLS, SHELL_TOOLS, block, commandFromPayload, ok } from "./common.js";
+import { SHELL_CLASSIFIERS } from "./policies/shell.js";
+import { classifyEdits, editInputsFromPayload } from "./policies/edit.js";
+const preShell = (runtime, payload) => {
+    const command = commandFromPayload(payload), cwd = payload.cwd ?? runtime.cwd;
+    for (const classify of SHELL_CLASSIFIERS) {
+        const message = classify(command, cwd);
+        if (message !== null) {
+            return message;
+        }
+    }
+    return null;
+}, 
+/**
+ * The verdict for one hook event. Only `PreToolUse` on a shell or edit tool
+ * can block; a policy that throws, such as an unparsable command, blocks.
+ * @param {Runtime} runtime The working directory and stderr.
+ * @param {HookPayload} payload The hook payload.
+ * @returns {HookResult} Exit code 2 to block, otherwise 0.
+ */
+runEvent = (runtime, payload) => {
+    if (payload.hook_event_name !== "PreToolUse") {
+        return ok();
+    }
+    const tool = payload.tool_name ?? "";
+    if (SHELL_TOOLS.has(tool)) {
+        try {
+            const message = preShell(runtime, payload);
+            return message === null ? ok() : block(message, runtime);
+        }
+        catch (error) {
+            return block(error instanceof Error ? error.message : String(error), runtime);
+        }
+    }
+    if (EDIT_TOOLS.has(tool)) {
+        const message = classifyEdits(editInputsFromPayload(payload), payload.cwd ?? runtime.cwd);
+        return message === null ? ok() : block(message, runtime);
+    }
+    return ok();
+};
+export { runEvent };

package/node_modules/@oisin-ee/pi-guardrails/dist/lifecycle-runner.js

@@ -0,0 +1,59 @@
+/*
+ * The Claude Code and Codex hook command. It reads one hook payload on stdin,
+ * prints the verdict's extra keys as JSON, and exits with the verdict's code:
+ * 2 blocks the tool call. An internal failure is recorded and allows the call,
+ * so a broken install never stops every tool.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isRecord } from "./common.js";
+import { runEvent } from "./event-registry.js";
+/**
+ * The verdict for one raw hook payload.
+ * @param {HookRun} run The payload and the process context.
+ * @returns {HookResult} The verdict; a payload that is not an object allows.
+ */
+const runLifecycleHook = (run) => {
+    const parsed = typeof run.payload === "string" ? JSON.parse(run.payload) : run.payload;
+    if (!isRecord(parsed)) {
+        return { code: 0 };
+    }
+    return runEvent({
+        cwd: run.cwd ?? process.cwd(),
+        stderr: run.stderr ??
+            ((message) => {
+                process.stderr.write(message);
+            }),
+    }, parsed);
+}, errorRoot = () => join(process.env["XDG_STATE_HOME"] ?? join(process.env["HOME"] ?? homedir(), ".local", "state"), "agent-hooks", "runtime"), readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}, 
+/**
+ * Runs the hook on this process's stdin and returns the exit code.
+ * @returns {Promise<number>} The process exit code.
+ */
+main = async () => {
+    const raw = await readStdin();
+    if (raw.trim().length === 0) {
+        return 0;
+    }
+    try {
+        const { code, ...output } = runLifecycleHook({ payload: raw });
+        if (Object.keys(output).length > 0) {
+            process.stdout.write(`${JSON.stringify(output)}\n`);
+        }
+        return code;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error), root = errorRoot();
+        await mkdir(root, { recursive: true });
+        await writeFile(join(root, "last-error.txt"), `${message}\n`);
+        return 0;
+    }
+};
+export { main, runLifecycleHook };

package/node_modules/@oisin-ee/pi-guardrails/dist/policies/edit.js

@@ -0,0 +1,98 @@
+/* The generated-path gate: lockfiles and generated files change only through their tools. */
+import { basename, dirname, resolve } from "node:path";
+const LOCKFILES = new Set([
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "Cargo.lock",
+    "composer.lock",
+    "Gemfile.lock",
+    "poetry.lock",
+    "uv.lock",
+    "flake.lock",
+    "go.sum",
+]), PACKAGE_LOCKFILES = new Set([
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+]), GENERATED_PATH = new RegExp([
+    /\.gen\./u.source,
+    /_pb2(?:_grpc)?\.py$/u.source,
+    /\.pb\.go$/u.source,
+    /_generated\./u.source,
+    /\.g\.dart$/u.source,
+    /\.freezed\.dart$/u.source,
+    /(?:^|\/)(?:generated|__generated__|\.gen)\//u.source,
+].join("|"), "u"), PATCH_FILE = /^\*\*\* (?<operation>Add|Update|Delete) File: (?<path>.+)$/u, PATCH_MOVE = /^\*\*\* Move to: (?<path>.+)$/u, text = (value) => (typeof value === "string" ? value : undefined), 
+/**
+ * The files an `apply_patch` body touches.
+ * @param {string} command The patch text.
+ * @returns {EditInput[]} One entry per file header or move.
+ */
+patchInputs = (command = "") => {
+    const inputs = [], lines = command.split("\n"), start = lines.indexOf("*** Begin Patch"), end = lines.indexOf("*** End Patch", start + 1);
+    if (start === -1 || end === -1) {
+        return inputs;
+    }
+    for (const line of lines.slice(start + 1, end)) {
+        const file = PATCH_FILE.exec(line)?.groups;
+        if (file?.["operation"] !== undefined && file["path"] !== undefined) {
+            inputs.push({ filePath: file["path"], operation: file["operation"].toLowerCase() });
+        }
+        const move = PATCH_MOVE.exec(line)?.groups?.["path"];
+        if (move !== undefined) {
+            inputs.push({ filePath: move, operation: "move" });
+        }
+    }
+    return inputs;
+}, 
+/**
+ * The files a hook payload's edit touches.
+ * @param {HookPayload} payload A hook payload.
+ * @returns {EditInput[]} The files and operations.
+ */
+editInputsFromPayload = (payload) => {
+    const input = payload.tool_input ?? {};
+    if (payload.tool_name === "apply_patch" || payload.tool_name === "patch") {
+        return patchInputs(text(input["command"]) ?? "");
+    }
+    const filePath = text(input["file_path"]) ?? text(input["filePath"]) ?? text(input["path"]) ?? "";
+    return filePath === "" ? [] : [{ filePath, operation: "update" }];
+}, 
+/**
+ * Why `filePath` is generated, or null.
+ * @param {string} filePath A file path.
+ * @returns {string | null} The reason and the tool to use.
+ */
+generatedReason = (filePath) => {
+    if (LOCKFILES.has(basename(filePath))) {
+        return "lockfile. Use its package manager";
+    }
+    return GENERATED_PATH.test(filePath) ? "generated file. Use its code generator" : null;
+}, 
+// Deleting a JS lockfile together with its package.json removes the package, which no tool does.
+removesPackage = (input, inputs, cwd) => {
+    if (input.operation !== "delete" || !PACKAGE_LOCKFILES.has(basename(input.filePath))) {
+        return false;
+    }
+    const manifest = resolve(dirname(resolve(cwd, input.filePath)), "package.json"), changes = inputs.filter((item) => resolve(cwd, item.filePath) === manifest);
+    return changes.length === 1 && changes[0]?.operation === "delete";
+}, 
+/**
+ * The block message for the first hand-edit of a generated path, or null.
+ * @param {readonly EditInput[]} inputs The files an edit touches.
+ * @param {string} cwd The directory relative paths resolve from.
+ * @returns {string | null} The block message.
+ */
+classifyEdits = (inputs, cwd) => {
+    for (const input of inputs) {
+        const reason = generatedReason(input.filePath);
+        if (reason !== null && !removesPackage(input, inputs, cwd)) {
+            return `generated-path: blocked hand-edit of ${input.filePath}: ${reason}.`;
+        }
+    }
+    return null;
+};
+export { classifyEdits, editInputsFromPayload, generatedReason, patchInputs };