pi-opa-net 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-01
+
+### Added
+
+- **decision-output.v1 schema** — JSON Schema draft 2020-12, strict (`additionalProperties: false`). Symmetric allow + deny output with rule provenance, fail-mode observability, and parse-confidence surfacing. 4 canonical examples, all validated by a hard test gate.
+- **OPA decision engine** (`OpaCliEngine`) — subprocess `opa eval` with temp-file input, fail-open/fail-closed branching, SHA-256 rulebook digest for drift detection.
+- **Hybrid command parser** — `ShellQuoteParser` (AST primary) + `RegexFallbackParser` (fallback), coordinated via `CommandParserCoordinator`. Program-aware subcommand classification (git/docker/gh/glab subcommand-style; rm/bd/gcloud/bq args-only).
+- **Rule registry + 37-rule catalog** mirroring `policy/safety.rego` message-for-message. A bidirectional parity test enforces zero drift between rego and the TS catalog.
+- **CLI** (`pi-opa-net eval`) — claude-code mode (suppress allow stdout) and `--json` mode (always emit schema). Exit codes `0 = allow`, `2 = deny` (Claude Code hook protocol compatible). Reads from args or stdin.
+- **Rego policy** (`policy/safety.rego`) — covers git, docker, docker-compose carve-outs, rm, gh, glab, gcloud, bq, bd families. Native bare-default handling (`git stash` ≡ push).
+- **Env-driven config** — `PI_OPA_FAIL_MODE`, `PI_OPA_TIMEOUT_MS`, `PI_OPA_BINARY` (mise-aware discovery), `PI_OPA_HOSTNAME`, `PI_OPA_SESSION_ID`.
+- **Decision-design docs** — `docs/locked-decisions.yaml` (LD1–LD5), `docs/open-threads.yaml` (OT1–OT5, all resolved with rationale).
+- **CI** — GitHub Actions workflow (typecheck + lint + test + coverage on ubuntu/macos).
+- **Skill doc** — `skills/pi-opa-net/SKILL.md` for pi agent discovery.
+
+### Resolved design threads
+
+- **OT1 (parser)** — hybrid: AST primary, regex fallback; `parse_confidence` surfaces path per-decision.
+- **OT2 (fail-mode)** — fail-open default (matches pi-safety-net fork), configurable to fail-closed.
+- **OT3 (bare git stash)** — handled natively in rego (`subcommand == "stash" && count(args) == 0`).
+- **OT4 (fork disposition)** — pi-safety-net kept as Path A (non-pi agents); pi-opa-net is Path B (OPA-backed).
+- **OT5 (pi extension wiring)** — deferred to a separate `pi-opa-net-ext` repo; this package exposes the engine + library + CLI.
+
+### Tests
+
+- 106 tests across 10 files (unit + e2e + schema gate).
+- Line coverage 98.89%, function coverage 88.98%.
+- E2E runs the live CLI against real OPA 1.18.1 — 20 distinct deny rules fire (≥40% of the 37-rule catalog) plus 5 allow carve-outs and fail-open/fail-closed paths.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buihongduc132
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# pi-opa-net
+
+[![npm version](https://img.shields.io/npm/v/pi-opa-net)](https://www.npmjs.com/package/pi-opa-net)
+[![CI](https://github.com/buihongduc132/pi-opa-net/actions/workflows/ci.yml/badge.svg)](https://github.com/buihongduc132/pi-opa-net/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> OPA-backed bash command guard for the [Pi](https://pi.dev) ecosystem. Structured `--json` output (decision-output.v1 schema), fail-open default, exit-code compatible with the Claude Code hook protocol.
+
+An **agent-agnostic** engine + CLI that evaluates shell commands against an [OPA](https://www.openpolicyagent.org/)/Rego policy and emits a strict, auditable decision record. Designed as the decision backend for pi extensions, Claude Code hooks, scripts, and any agent that needs a uniform bash-guard contract.
+
+## Why
+
+Three limitations of today's asymmetric, agent-specific guard output that this fixes:
+
+| # | Limitation | Fix |
+|---|------------|-----|
+| 1 | **Asymmetric** — allow is silent, deny emits a string | Both allow AND deny emit the full schema |
+| 2 | **No provenance** — only a human message | `reasons[].rule_id` traces decision → rule → source line |
+| 3 | **Agent-specific** — tied to one hook protocol | Agent-agnostic wrapper; adapters become thin views |
+
+## Status
+
+- **Stable:** v0.1.0 — schema v1.0, 37-rule catalog, full TDD coverage
+- **Engine:** OPA 1.x (lazy-loaded on every dev box)
+- **Scope:** bash command guarding only (see [`docs/locked-decisions.yaml`](docs/locked-decisions.yaml) LD3)
+- **Pi extension:** the thin tool_call adapter lives in a separate future repo (`pi-opa-net-ext`, per OT5) — this package is the engine + library
+
+## Installation
+
+### Prerequisites
+
+OPA 1.x on `PATH` (recommended via [mise](https://mise.jdx.dev)):
+
+```bash
+mise install opa@latest
+mise use -g opa@latest
+```
+
+### Install
+
+```bash
+# as a library (pi extension / script consumer)
+npm install pi-opa-net
+# or
+bun add pi-opa-net
+
+# run the CLI directly via bun
+bunx pi-opa-net eval "git stash pop"
+```
+
+## Usage
+
+### CLI
+
+```bash
+# claude-code mode (default): suppress stdout on allow, JSON on deny
+pi-opa-net eval "git stash pop"             # exit 2 + JSON on stdout
+pi-opa-net eval "git stash list"            # exit 0, empty stdout
+
+# --json: always emit the full decision-output.v1 schema
+pi-opa-net eval "git stash pop" --json
+
+# stdin
+echo "docker stop foo" | pi-opa-net eval
+```
+
+**Exit codes:** `0 = allow`, `2 = deny` (Claude Code hook protocol compatible).
+
+### Programmatic API
+
+```ts
+import { configFromEnv, CommandParserCoordinator, OpaCliEngine, DecisionBuilder, OutputFormatter, RULES, RuleRegistry } from 'pi-opa-net';
+
+const config = configFromEnv('/path/to/safety.rego');
+const parser = new CommandParserCoordinator();
+const engine = new OpaCliEngine(config);
+const builder = new DecisionBuilder({
+  config,
+  registry: new RuleRegistry(RULES),
+  digest: engine.rulebookDigest(),
+});
+
+const parsed = parser.parse('git stash pop');
+const engineDecision = await engine.evaluate(parsed);
+const output = builder.build(parsed, engineDecision);
+
+console.log(output.decision);  // 'deny'
+console.log(output.reasons[0].rule_id);  // 'block-git-stash-mutations'
+```
+
+## Output schema
+
+See [`schemas/decision-output.v1.json`](schemas/decision-output.v1.json) — JSON Schema draft 2020-12, strict (`additionalProperties: false` throughout). Every emitted record is validated against it before leaving the process.
+
+```jsonc
+{
+  "schema_version": "1.0",
+  "decision": "deny",            // allow | deny
+  "action": "block",             // allow | block | prompt_user(v2) | log_only(v2)
+  "source": "opa",               // opa | fail-open | fail-closed | cached
+  "reasons": [                   // every fired deny rule → one entry
+    { "rule_id": "block-git-stash-mutations",
+      "message": "Do not mutate stashes in shared work...",
+      "family": "git", "severity": "block" }
+  ],
+  "input": { "raw": "git stash pop", "program": "git",
+             "subcommand": "stash", "args": ["pop"],
+             "parse_confidence": "full" },   // full | partial | regex-only | failed
+  "summary": "BLOCKED: git stash pop (rule: block-git-stash-mutations)",
+  "suggestions": ["git stash list", "git stash show"],
+  "metadata": { "engine": "opa", "opa_version": "1.18.1",
+                "rulebook_digest": "dee3746bf7b5", "policy_path": "...",
+                "hostname": "box", "session_id": "" },
+  "evaluated_at": "2026-07-01T14:23:45.123Z",
+  "decision_id": "7f3a9c2e-1b4d-4e8f-9a2c-5d6e7f8a9b01",
+  "duration_ms": 4.2
+}
+```
+
+## Architecture
+
+Two halves (per the design findings):
+
+| Half | Responsibility | Module |
+|------|----------------|--------|
+| **Parse** | raw `"git stash list"` → `{program, subcommand, args, parse_confidence}` | `src/parser/` |
+| **Decide** | structured input → allow/deny + reasons | `policy/safety.rego` + `src/engine/` |
+
+```
+src/
+├── parser/     CommandParserCoordinator (hybrid: ShellQuote AST primary, regex fallback)
+├── engine/     OpaCliEngine (subprocess `opa eval` + fail-mode)
+├── rules/      RuleRegistry + catalog (message → rule_id + family provenance)
+├── output/     DecisionBuilder (schema assembly) + OutputFormatter (stdout/exit-code)
+├── config/     EngineConfig (fail-mode, OPA binary discovery)
+├── cli/        run.ts (wires the pipeline)
+└── util/       sha256Prefix (rulebook drift detection)
+```
+
+### Design principles
+
+- **OOP** — `DecisionEngine` and `CommandParser` interfaces; fakes injectable for tests.
+- **DRY** — `RuleRegistry` is the single source of truth for rule provenance; the catalog mirrors `policy/safety.rego` message-for-message (a parity test fails on drift).
+- **Observable** — the `source` field makes fail-mode (open/closed) auditable per-decision; `parse_confidence` surfaces parser fidelity.
+
+## Fail-mode
+
+When OPA is unreachable (cold-start, binary missing, timeout):
+
+| Mode | Behavior | `source` field |
+|------|----------|----------------|
+| `open` (default) | allow the command through | `fail-open` |
+| `closed` | block the command | `fail-closed` |
+
+```bash
+PI_OPA_FAIL_MODE=closed pi-opa-net eval "git stash pop"
+```
+
+The default `open` matches the [`pi-safety-net`](https://www.npmjs.com/package/pi-safety-net) fork's "never brick the shell" guarantee.
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `PI_OPA_BINARY` | auto (PATH → mise) | OPA binary path |
+| `PI_OPA_FAIL_MODE` | `open` | fail-mode |
+| `PI_OPA_TIMEOUT_MS` | `250` | OPA eval timeout |
+| `PI_OPA_HOSTNAME` | `os.hostname()` | metadata.hostname |
+| `PI_OPA_SESSION_ID` | `""` | metadata.session_id |
+
+## Develop
+
+```bash
+bun install
+bun test                 # all tests (106)
+bun test --coverage      # coverage (line > 98%)
+bun run typecheck        # tsc --noEmit
+bun run lint             # biome
+bun run smoke            # one-shot CLI check
+```
+
+E2E tests run the live CLI against real OPA + the real policy, covering ≥40% of the 37-rule catalog.
+
+## Decisions & open threads
+
+- [`docs/locked-decisions.yaml`](docs/locked-decisions.yaml) — LD1–LD5 (immutable inputs).
+- [`docs/open-threads.yaml`](docs/open-threads.yaml) — OT1–OT5 resolved at implementation time.
+
+## Project health
+
+- **Security policy:** [`SECURITY.md`](SECURITY.md)
+- **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- **Support:** [`SUPPORT.md`](SUPPORT.md)
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+
+## Related
+
+- [`pi-safety-net`](https://www.npmjs.com/package/pi-safety-net) — the fail-open fork of cc-safety-net (Path A: non-pi agents). pi-opa-net is Path B (OPA-backed, structured output).
+- [`cc-safety-net`](https://www.npmjs.com/package/cc-safety-net) — upstream Claude Code safety net.
+
+## License
+
+MIT © [buihongduc132](https://github.com/buihongduc132)

package/bin/pi-opa-net.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+/**
+ * pi-opa-net — OPA-backed bash command guard with structured --json output.
+ *
+ * Usage:
+ *   pi-opa-net eval "<command>"              # claude-code mode (default)
+ *   pi-opa-net eval "<command>" --json        # full schema on stdout always
+ *   echo "<command>" | pi-opa-net eval        # read from stdin
+ *
+ * Exit codes: 0=allow, 2=deny (Claude Code hook protocol compatible).
+ */
+import { defaultPolicyPath, runCli } from '../src/cli/run.ts';
+
+function parseArgs(argv) {
+  const args = argv.slice(2); // drop node + script
+  let mode = 'claude-code';
+  let command;
+  let policyPath = defaultPolicyPath();
+  let sawAction = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') {
+      mode = 'json';
+    } else if (a === '--policy' || a === '-p') {
+      policyPath = args[++i];
+    } else if (a === '--help' || a === '-h') {
+      printHelp();
+      process.exit(0);
+    } else if (!a.startsWith('-')) {
+      // First positional is the action verb ('eval'); subsequent ones form the command.
+      if (!sawAction && a === 'eval') {
+        sawAction = true;
+      } else {
+        command = command === undefined ? a : `${command} ${a}`;
+      }
+    }
+  }
+  return { command, mode, policyPath };
+}
+
+function printHelp() {
+  console.error(`pi-opa-net — OPA-backed bash command guard
+
+Usage:
+  pi-opa-net eval "<command>" [--json] [--policy <path>]
+  echo "<command>" | pi-opa-net eval
+
+Modes:
+  (default)   claude-code: suppress stdout on allow, JSON on deny
+  --json      always emit full decision-output.v1 schema on stdout
+
+Exit codes: 0=allow, 2=deny`);
+}
+
+async function main() {
+  const { command, mode, policyPath } = parseArgs(process.argv);
+  const { stdout, exitCode } = await runCli({ command, mode, policyPath });
+  if (stdout) {
+    console.log(stdout);
+  }
+  process.exit(exitCode);
+}
+
+void main();

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "pi-opa-net",
+  "version": "0.1.0",
+  "description": "OPA-backed bash command guard for the pi ecosystem — structured decision-output.v1 JSON, fail-open default, Claude Code hook protocol compatible. Agent-agnostic engine + CLI.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "pi-opa-net": "bin/pi-opa-net.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "schemas",
+    "policy",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --write src tests bin",
+    "lint:ci": "biome ci src tests bin",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "check": "bun run typecheck && bun run lint:ci && bun test --coverage",
+    "smoke": "bun run bin/pi-opa-net.js eval \"git stash pop\" --json",
+    "prepublishOnly": "bun run check"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-library",
+    "opa",
+    "rego",
+    "bash-guard",
+    "safety-net",
+    "claude-code",
+    "policy",
+    "decision-output"
+  ],
+  "pi": {
+    "skills": ["./skills"]
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "shell-quote": "^1.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "latest",
+    "@types/shell-quote": "^1.7.5",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "license": "MIT",
+  "author": "buihongduc132",
+  "homepage": "https://github.com/buihongduc132/pi-opa-net#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buihongduc132/pi-opa-net.git"
+  },
+  "bugs": {
+    "url": "https://github.com/buihongduc132/pi-opa-net/issues"
+  }
+}