@xaccefy/pi-casefile 0.2.3 → 0.2.5

package/README.md

@@ -1,51 +1,70 @@
 # pi-casefile
 
-`pi-casefile` is a local-first case ledger and validation harness designed to track offensive security investigations, bug bounty findings, and CTF progress. It features a SQLite storage engine and an isolated PoC execution runner.
+Local-first security case ledger for Pi Agent. Tracks hypotheses → confirmed findings with a hard PoC gate, SQLite storage, and an isolated PoC runner.
 
-## Features
-
-- **State Management**: Enforces strict lifecycle transitions across states (`hypothesis`, `investigating`, `confirmed`, `blocked`, `killed`, `reported`).
-- **PoC Runner**: Validates vulnerability reachability in an isolated Docker sandbox with `--network none` or locally on the host.
-- **SQL Backend**: Syncs case information to SQLite via Node's `node:sqlite` or Bun's `bun:sqlite` compat layers.
-- **Reporting**: Automatically compiles markdown vulnerability reports for confirmed or reported findings.
-
-## Installation
+## Install
 
 ```bash
-pi install npm:pi-casefile
+pi install npm:@xaccefy/pi-casefile
 ```
 
-## Environment Variables
+Or via the XPI umbrella package: `pi install npm:@xaccefy/pi-xpi`
+
+## XP mode (default OFF)
+
+The cyber-workflow context injection is **quiet by default** so normal dev work is not flooded with security process text.
+
+| Control | Effect |
+|---------|--------|
+| `/xp` | Toggle ON/OFF |
+| `/xp on` / `/xp off` | Set explicitly |
+| `PI_XP_MODE=on` | Force ON for this process (overrides file) |
+| `PI_XP_MODE=off` | Force OFF |
+
+When **ON**, every prompt injects the attacker-oriented cyber workflow plus any active (non-killed/non-reported) cases. When **OFF**, nothing is injected; tools remain available.
+
+State is persisted next to the ledger as `xp-mode` (e.g. `.pi/xp-mode`).
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `PI_CASEFILE_PATH` | Absolute path to the SQLite ledger file |
+| `CASEFILE_WORKSPACE_ROOT` / `PI_WORKSPACE_ROOT` | Override workspace root used to place `.pi/casefile.db` |
+
+Default DB path: `<workspace>/.pi/casefile.db`
+
+## State machine
+
+```
+hypothesis → investigating → confirmed → reported
+                 ↓               ↓
+              blocked         killed (terminal)
+```
 
-- `CASEFILE_PATH`: Set explicit absolute path to the SQLite database file.
-- `CASEFILE_SCOPE`: Scope database storage. Options: `project` (default, stores in `.pi/casefile.db` or `.casefile/casefile.db` relative to workspace root) or `global` (stores in `~/.pi/casefile/casefile.db` or `~/.casefile/casefile.db`).
+- **investigating** requires `evidence` + `confidence`
+- **confirmed** only via `PromoteFinding` (PoC exit 0) — `CaseUpdate(status:"confirmed")` is rejected
+- **reported** requires `CaseReport` first
+- **killed** / **reported** are terminal (no further field edits)
 
-## Core Workflow & State Transitions
+There is **no** `impact_proof` tool field. Put proof text in `impact` or `evidence`.
 
-The ledger acts as a state gate to ensure finding validity:
-1. **Hypothesis**: Initial lead tracking (`CaseAdd`).
-2. **Investigation**: Move to `investigating` when code paths or reachability trace are identified (`CaseUpdate`).
-3. **Confirmation**: Validate with a working PoC script (`PromoteFinding`). Requires the PoC script to exit with code `0`.
-4. **Chaining**: Link low-impact primitives to build high-impact chains (`CaseLink`).
-5. **Reporting**: Compile markdown report (`CaseReport`) and transition finding to `reported` (`CaseUpdate`).
+## Tools
 
-## Tools Reference
+| Tool | Use |
+|------|-----|
+| `CaseAdd` | Open a case (`title` required; start as `hypothesis` or `investigating`) |
+| `CaseUpdate` | Evidence, impact, severity, status (not direct confirm) |
+| `PromoteFinding` | Run on-disk PoC (Docker sandbox by default; `local:true` for host) → confirm on exit 0 |
+| `CaseGet` / `CaseList` / `CaseSearch` | Read / filter / search |
+| `CaseLink` / `CaseUnlink` | Bidirectional exploit chains |
+| `CaseReport` | Markdown report for confirmed/reported cases |
 
-| Tool | Action | Requirements |
-|---|---|---|
-| `CaseAdd` | Create a new hypothesis or investigation case | Title, target (scope) |
-| `CaseUpdate` | Modify case details (remediation, impact, status) | ID, field updates |
-| `PromoteFinding` | Run on-disk PoC script to transition status to `confirmed` | ID, `poc_path`, `local` flag |
-| `CaseGet` | Retrieve full JSON details of a case | ID |
-| `CaseList` | Query and filter cases by status/confidence/tags | Filter flags, limit, offset |
-| `CaseSearch` | Perform full-text search across specific case fields | Query string, optional field |
-| `CaseLink` | Create a bidirectional link between two cases | Source ID, Target ID |
-| `CaseUnlink` | Remove link between two cases | Source ID, Target ID |
-| `CaseReport` | Write markdown report to disk | ID (must be `confirmed` or `reported`) |
+Commands: `/casefile` (dashboard), `/xp` (XP mode).
 
-## Development and Testing
+## Development
 
-Run tests via Bun:
 ```bash
-bun test
+bun test packages/pi-casefile
+bun run typecheck
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -9,6 +9,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
 
 import {
   addCaseResult,
@@ -542,6 +545,58 @@ function buildAgentInjection(active: CaseRecord[]): string {
   return caseList ? `${caseList}\n\n${STATIC_CYBER_WORKFLOW}` : STATIC_CYBER_WORKFLOW;
 }
 
+// ── XP (offensive / exploit) mode toggle ─────────────────────────────
+// Casefile historically injected the cyber workflow into every prompt.
+// For normal dev work that is just noise, so XP mode defaults OFF. Enable
+// it for offensive/audit sessions to get the full attacker discipline back.
+// Toggle with /xp (or /xp on|off); override per-session with PI_XP_MODE.
+// Pure helpers exported for unit tests.
+
+export const XP_MODE_ENV = "PI_XP_MODE";
+export type XpMode = "on" | "off";
+
+export function getXpModeStatePath(): string {
+  try {
+    return join(dirname(getCasefilePath()), "xp-mode");
+  } catch {
+    return join(homedir(), ".pi", "xp-mode");
+  }
+}
+
+export function readXpMode(
+  envValue: string | undefined = process.env[XP_MODE_ENV],
+  statePath: string = getXpModeStatePath(),
+): XpMode {
+  const env = (envValue ?? "").trim().toLowerCase();
+  if (env === "on" || env === "1" || env === "true") return "on";
+  if (env === "off" || env === "0" || env === "false") return "off";
+  try {
+    if (existsSync(statePath)) {
+      const v = readFileSync(statePath, "utf8").trim().toLowerCase();
+      if (v === "on") return "on";
+      if (v === "off") return "off";
+    }
+  } catch {
+    // ignore and fall through to default
+  }
+  return "off";
+}
+
+export function writeXpMode(state: XpMode, statePath: string = getXpModeStatePath()): void {
+  try {
+    writeFileSync(statePath, state, "utf8");
+  } catch {
+    // best-effort; env var can still override at runtime
+  }
+}
+
+export function parseXpModeArg(args: string, current: XpMode): XpMode {
+  const arg = (args ?? "").trim().toLowerCase();
+  if (arg === "on") return "on";
+  if (arg === "off") return "off";
+  return current === "on" ? "off" : "on";
+}
+
 // ── Main extension ────────────────────────────────────────────────────
 
 export default function casefileExtension(pi: ExtensionAPI) {
@@ -976,6 +1031,10 @@ export default function casefileExtension(pi: ExtensionAPI) {
     name: "CaseUnlink",
     label: "Unlink Cases",
     description: "Remove a bidirectional link between two cases.",
+    promptSnippet: "Remove a link between two cases",
+    promptGuidelines: [
+      "Use CaseUnlink to detach two cases that were previously linked with CaseLink (e.g. when a chain step is disproven or no longer relevant).",
+    ],
     parameters: UnlinkSchema,
 
     async execute(_id, params, _signal, _onUpdate, _ctx) {
@@ -1068,6 +1127,21 @@ export default function casefileExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── Command: /xp (toggle offensive XP mode) ──
+
+  pi.registerCommand("xp", {
+    description:
+      "Toggle casefile XP (offensive) mode. ON injects the full cyber workflow each prompt; OFF (default) keeps context quiet for normal dev work. Usage: /xp [on|off]",
+    handler: async (args, ctx) => {
+      const next = parseXpModeArg(args ?? "", readXpMode());
+      writeXpMode(next);
+      ctx.ui.notify(
+        `Casefile XP mode: ${next.toUpperCase()} (takes effect on the next prompt)`,
+        next === "on" ? "info" : "warning",
+      );
+    },
+  });
+
   // ── Command: /casefile ──
 
   pi.registerCommand("casefile", {
@@ -1103,10 +1177,15 @@ export default function casefileExtension(pi: ExtensionAPI) {
   });
 
   // ── Event: Inject context into system prompt ──
+  // XP (offensive) mode is OFF by default so normal dev work stays quiet.
+  // Only when enabled do we inject the cyber workflow (and case list) each
+  // prompt. This keeps the agent focused during everyday development while
+  // still allowing the full attacker discipline to be switched on for
+  // offensive/audit/bounty sessions.
 
   pi.on("before_agent_start", async () => {
-    // Once per user prompt (not every tool turn). Always inject workflow so empty
-    // ledgers still get attacker discipline; attach case list only when useful.
+    if (readXpMode() === "off") return;
+
     let active: CaseRecord[] = [];
     try {
       const records = readCasefile();