getprismo 0.1.11 → 0.1.13

package/README.md

@@ -33,6 +33,7 @@ after you code      npx getprismo cc timeline
 **doctor** diagnoses the repo, applies safe fixes, and shows the before/after score.
 **watch** monitors context pressure live and warns when things go wrong.
 **cc timeline** reconstructs what happened in the session so you learn from it.
+**shield** runs noisy commands without dumping full output back into the agent context.
 
 ---
 
@@ -137,6 +138,51 @@ watch caught lockfiles entering context, a file being read 286 times, and tool o
 
 ---
 
+## new: context shield
+
+if you know a command may dump huge output, run it through prismo:
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield -- pytest -q
+npx getprismo shield -- npm run build
+```
+
+shield executes the command locally, stores full stdout/stderr under `.prismo/shield/runs/`, indexes the output in `.prismo/shield/shield.sqlite` using SQLite FTS5 when available, and prints only a compact summary plus useful error lines.
+
+this is the lightweight context-sandbox layer: the full output stays on disk until you explicitly inspect it, instead of being pasted into the model context and re-sent every turn.
+
+example:
+
+```text
+Prismo Shield
+
+Command: npm test
+Exit: 1
+Captured: 186 KB (~46,500 tokens kept out of chat)
+
+Full Output Stored:
+- .prismo/shield/runs/2026-05-20T.../stdout.txt
+- .prismo/shield/runs/2026-05-20T.../stderr.txt
+- .prismo/shield/shield.sqlite
+
+Summary Returned To Context:
+- ERROR: auth.test.ts expected 200 received 401
+- FAIL src/auth/session.test.ts
+```
+
+search previous shield output without reloading whole logs:
+
+```bash
+npx getprismo shield last
+npx getprismo shield search "auth expected 200"
+npx getprismo shield search "AUTH_FAILURE" --json
+```
+
+this is intentionally not magic interception yet. it is a safe local-first primitive you can tell agents to use for noisy commands.
+
+---
+
 ## new: live guardrails mode
 
 the easiest proactive mode is:
@@ -485,6 +531,7 @@ no install needed. npx runs it directly.
 | `scan --ci` | fail CI when token-risk gates fail |
 | `optimize` | generate `.prismo/` context packs |
 | `context` | print paste-ready prompt for agents |
+| `shield` | run noisy commands while keeping full output out of chat |
 | `setup` | detect tools, logs, proxy readiness |
 | `usage` | show raw session token usage |
 | `init` | add npm scripts and .prismo/README.md |
@@ -526,6 +573,16 @@ npx getprismo watch codex                # only codex sessions
 npx getprismo watch claude               # only claude code sessions
 ```
 
+### shield mode
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield -- pytest -q
+npx getprismo shield --json -- npm run build
+npx getprismo shield last
+npx getprismo shield search "auth failure"
+```
+
 ---
 
 ## cc modes

package/lib/prismo-dev/shield.js

@@ -0,0 +1,384 @@
+module.exports = function createShield(deps) {
+  const {
+    fs,
+    path,
+    estimateTokens,
+    formatBytes,
+    color,
+  } = deps;
+  const { spawnSync } = require("child_process");
+
+const SHIELD_SCHEMA_VERSION = 1;
+
+function nowId() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function pickInterestingLines(text, limit = 24) {
+  const lines = String(text || "").split(/\r?\n/).filter(Boolean);
+  const interesting = [];
+  const patterns = [
+    /\b(error|failed|failure|exception|traceback|fatal|panic|segmentation fault)\b/i,
+    /\b(warn|warning|deprecated|timeout|denied|unauthorized|forbidden)\b/i,
+    /\b(assert|expected|received|diff|not found|cannot find|module not found)\b/i,
+  ];
+  for (const line of lines) {
+    if (patterns.some((pattern) => pattern.test(line))) interesting.push(line.slice(0, 500));
+    if (interesting.length >= limit) break;
+  }
+  if (interesting.length) return interesting;
+  return lines.slice(Math.max(0, lines.length - Math.min(limit, 12))).map((line) => line.slice(0, 500));
+}
+
+function summarizeOutput(stdout, stderr) {
+  const stdoutText = String(stdout || "");
+  const stderrText = String(stderr || "");
+  const combined = [stderrText, stdoutText].filter(Boolean).join("\n");
+  const totalBytes = Buffer.byteLength(stdoutText) + Buffer.byteLength(stderrText);
+  const totalTokens = estimateTokens(combined);
+  return {
+    stdoutBytes: Buffer.byteLength(stdoutText),
+    stderrBytes: Buffer.byteLength(stderrText),
+    totalBytes,
+    estimatedTokens: totalTokens,
+    interestingLines: pickInterestingLines(combined),
+  };
+}
+
+function renderStoredReadCommand(pathValue) {
+  return `sed -n '1,160p' ${JSON.stringify(pathValue)}`;
+}
+
+function shieldRoot(root) {
+  return path.join(root, ".prismo", "shield");
+}
+
+function shieldDbPath(root) {
+  return path.join(shieldRoot(root), "shield.sqlite");
+}
+
+function indexPath(root) {
+  return path.join(shieldRoot(root), "index.jsonl");
+}
+
+function sqlString(value) {
+  return `'${String(value == null ? "" : value).replace(/'/g, "''")}'`;
+}
+
+function sqliteAvailable() {
+  const result = spawnSync("sqlite3", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  return result.status === 0;
+}
+
+function sqliteExec(dbPath, sql, json = false) {
+  const args = json ? ["-json", dbPath, sql] : [dbPath, sql];
+  const result = spawnSync("sqlite3", args, { encoding: "utf8", maxBuffer: 20 * 1024 * 1024 });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.error?.message || "sqlite3 failed").trim());
+  }
+  if (!json) return null;
+  const out = String(result.stdout || "").trim();
+  return out ? JSON.parse(out) : [];
+}
+
+function ensureSqliteIndex(root) {
+  if (!sqliteAvailable()) return { available: false, reason: "sqlite3-not-found" };
+  ensureDir(shieldRoot(root));
+  const dbPath = shieldDbPath(root);
+  sqliteExec(dbPath, `
+    PRAGMA journal_mode=WAL;
+    CREATE TABLE IF NOT EXISTS shield_runs (
+      id TEXT PRIMARY KEY,
+      command TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      exit_code INTEGER NOT NULL,
+      started_at TEXT NOT NULL,
+      finished_at TEXT NOT NULL,
+      duration_ms INTEGER NOT NULL,
+      stdout_path TEXT NOT NULL,
+      stderr_path TEXT NOT NULL,
+      total_bytes INTEGER NOT NULL,
+      estimated_tokens INTEGER NOT NULL,
+      summary_json TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS shield_output USING fts5(
+      run_id UNINDEXED,
+      command,
+      stream UNINDEXED,
+      content,
+      tokenize='unicode61'
+    );
+  `);
+  return { available: true, path: path.relative(root, dbPath).replace(/\\/g, "/") };
+}
+
+function indexShieldRun(root, payload, stdout, stderr) {
+  const sqlite = ensureSqliteIndex(root);
+  if (!sqlite.available) return { mode: "jsonl", sqlite };
+  const dbPath = shieldDbPath(root);
+  const runId = path.basename(payload.stored.directory);
+  sqliteExec(dbPath, `
+    INSERT OR REPLACE INTO shield_runs (
+      id, command, cwd, exit_code, started_at, finished_at, duration_ms,
+      stdout_path, stderr_path, total_bytes, estimated_tokens, summary_json
+    ) VALUES (
+      ${sqlString(runId)},
+      ${sqlString(payload.command)},
+      ${sqlString(payload.cwd)},
+      ${Number(payload.exitCode || 0)},
+      ${sqlString(payload.startedAt)},
+      ${sqlString(payload.finishedAt)},
+      ${Number(payload.durationMs || 0)},
+      ${sqlString(payload.stored.stdout)},
+      ${sqlString(payload.stored.stderr)},
+      ${Number(payload.output.totalBytes || 0)},
+      ${Number(payload.output.estimatedTokens || 0)},
+      ${sqlString(JSON.stringify(payload))}
+    );
+    DELETE FROM shield_output WHERE run_id = ${sqlString(runId)};
+    INSERT INTO shield_output (run_id, command, stream, content)
+      VALUES (${sqlString(runId)}, ${sqlString(payload.command)}, 'stdout', ${sqlString(stdout)});
+    INSERT INTO shield_output (run_id, command, stream, content)
+      VALUES (${sqlString(runId)}, ${sqlString(payload.command)}, 'stderr', ${sqlString(stderr)});
+  `);
+  return { mode: "sqlite-fts5", sqlite };
+}
+
+function readJsonlIndex(root) {
+  const filePath = indexPath(root);
+  if (!fs.existsSync(filePath)) return [];
+  return fs.readFileSync(filePath, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function readStoredText(root, relPath) {
+  const fullPath = path.join(root, relPath);
+  try {
+    return fs.readFileSync(fullPath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function fallbackSearch(root, query, limit = 10) {
+  const needle = String(query || "").toLowerCase();
+  if (!needle) return [];
+  const rows = readJsonlIndex(root).reverse();
+  const results = [];
+  for (const row of rows) {
+    for (const stream of ["stderr", "stdout"]) {
+      const relPath = row.stored?.[stream];
+      const text = readStoredText(root, relPath || "");
+      const lower = text.toLowerCase();
+      const index = lower.indexOf(needle);
+      if (index < 0) continue;
+      const start = Math.max(0, index - 180);
+      const end = Math.min(text.length, index + needle.length + 320);
+      results.push({
+        runId: path.basename(row.stored.directory),
+        command: row.command,
+        stream,
+        path: relPath,
+        exitCode: row.exitCode,
+        finishedAt: row.finishedAt,
+        snippet: text.slice(start, end).replace(/\s+/g, " ").trim(),
+      });
+      if (results.length >= limit) return results;
+    }
+  }
+  return results;
+}
+
+function runShieldSearch(rootDir = process.cwd(), query = "", options = {}) {
+  const root = path.resolve(rootDir);
+  const limit = options.limit || 10;
+  if (!String(query || "").trim()) throw new Error("No search query provided. Use: prismo shield search \"error text\"");
+  const sqlite = ensureSqliteIndex(root);
+  if (sqlite.available && fs.existsSync(shieldDbPath(root))) {
+    try {
+      const phrase = `"${String(query).replace(/"/g, '""')}"`;
+      const rows = sqliteExec(shieldDbPath(root), `
+        SELECT
+          shield_output.run_id AS runId,
+          shield_output.command AS command,
+          shield_output.stream AS stream,
+          CASE shield_output.stream
+            WHEN 'stderr' THEN shield_runs.stderr_path
+            ELSE shield_runs.stdout_path
+          END AS path,
+          shield_runs.exit_code AS exitCode,
+          shield_runs.finished_at AS finishedAt,
+          snippet(shield_output, 3, '[', ']', ' ... ', 24) AS snippet
+        FROM shield_output
+        JOIN shield_runs ON shield_runs.id = shield_output.run_id
+        WHERE shield_output MATCH ${sqlString(phrase)}
+        ORDER BY rank
+        LIMIT ${Number(limit)};
+      `, true);
+      return { query, mode: "sqlite-fts5", results: rows };
+    } catch {
+      // FTS queries can reject punctuation-heavy input; fall back to JSONL/plain text scan.
+    }
+  }
+  return { query, mode: "jsonl-fallback", results: fallbackSearch(root, query, limit) };
+}
+
+function runShieldLast(rootDir = process.cwd(), options = {}) {
+  const root = path.resolve(rootDir);
+  const limit = options.limit || 5;
+  return {
+    mode: fs.existsSync(shieldDbPath(root)) ? "sqlite-fts5" : "jsonl-fallback",
+    runs: readJsonlIndex(root).reverse().slice(0, limit),
+  };
+}
+
+function runShield(rootDir = process.cwd(), commandArgs = [], options = {}) {
+  const root = path.resolve(rootDir);
+  if (!commandArgs.length) {
+    throw new Error("No command provided. Use: prismo shield -- npm test");
+  }
+
+  const startedAt = new Date();
+  const id = nowId();
+  const runsDir = path.join(root, ".prismo", "shield", "runs", id);
+  ensureDir(runsDir);
+
+  const command = commandArgs[0];
+  const args = commandArgs.slice(1);
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: options.maxBuffer || 30 * 1024 * 1024,
+    shell: false,
+    env: process.env,
+  });
+
+  const finishedAt = new Date();
+  const stdout = result.stdout || "";
+  const stderr = result.stderr || "";
+  const stdoutPath = path.join(runsDir, "stdout.txt");
+  const stderrPath = path.join(runsDir, "stderr.txt");
+  const summary = summarizeOutput(stdout, stderr);
+  fs.writeFileSync(stdoutPath, stdout, "utf8");
+  fs.writeFileSync(stderrPath, stderr, "utf8");
+
+  const payload = {
+    schemaVersion: 1,
+    command: commandArgs.join(" "),
+    cwd: root,
+    exitCode: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null,
+    error: result.error ? result.error.message : null,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+    output: summary,
+    stored: {
+      stdout: path.relative(root, stdoutPath).replace(/\\/g, "/"),
+      stderr: path.relative(root, stderrPath).replace(/\\/g, "/"),
+      directory: path.relative(root, runsDir).replace(/\\/g, "/"),
+    },
+    next: [
+      "Feed the summary to the agent first; inspect full output only if needed.",
+      `Read stdout: ${renderStoredReadCommand(path.relative(root, stdoutPath).replace(/\\/g, "/"))}`,
+      `Read stderr: ${renderStoredReadCommand(path.relative(root, stderrPath).replace(/\\/g, "/"))}`,
+    ],
+  };
+  fs.writeFileSync(path.join(runsDir, "summary.json"), JSON.stringify(payload, null, 2), "utf8");
+  fs.mkdirSync(path.join(root, ".prismo", "shield"), { recursive: true });
+  fs.appendFileSync(path.join(root, ".prismo", "shield", "index.jsonl"), `${JSON.stringify(payload)}\n`, "utf8");
+  payload.index = indexShieldRun(root, payload, stdout, stderr);
+  fs.writeFileSync(path.join(runsDir, "summary.json"), JSON.stringify(payload, null, 2), "utf8");
+  return payload;
+}
+
+function renderShieldTerminal(result) {
+  const lines = [];
+  const exitTone = result.exitCode === 0 ? "green" : "red";
+  lines.push("");
+  lines.push(color("Prismo Shield", "bold"));
+  lines.push("");
+  lines.push(`Command: ${result.command}`);
+  lines.push(`Exit: ${color(String(result.exitCode), exitTone)}`);
+  lines.push(`Duration: ${result.durationMs}ms`);
+  lines.push(`Captured: ${formatBytes(result.output.totalBytes)} (~${result.output.estimatedTokens.toLocaleString()} tokens kept out of chat)`);
+  lines.push("");
+  lines.push("Full Output Stored:");
+  lines.push(`- ${result.stored.stdout}`);
+  lines.push(`- ${result.stored.stderr}`);
+  lines.push(`- ${result.stored.directory}/summary.json`);
+  lines.push("");
+  lines.push("Summary Returned To Context:");
+  result.output.interestingLines.slice(0, 24).forEach((line) => lines.push(`- ${line}`));
+  lines.push("");
+  lines.push("Next:");
+  lines.push("1. Give the agent this summary first.");
+  lines.push("2. Inspect the stored full output only if the summary is not enough.");
+  lines.push(`3. ${renderStoredReadCommand(result.stored.stderr)}`);
+  return lines.join("\n");
+}
+
+function renderShieldSearchTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Shield Search", "bold"));
+  lines.push("");
+  lines.push(`Query: ${result.query}`);
+  lines.push(`Index: ${result.mode}`);
+  lines.push(`Results: ${result.results.length}`);
+  lines.push("");
+  if (!result.results.length) {
+    lines.push("No matching shield output found.");
+    return lines.join("\n");
+  }
+  result.results.forEach((item, index) => {
+    lines.push(`${index + 1}. ${item.path} (${item.stream}, exit ${item.exitCode})`);
+    lines.push(`   ${item.command}`);
+    lines.push(`   ${String(item.snippet || "").slice(0, 700)}`);
+  });
+  lines.push("");
+  lines.push("Next:");
+  lines.push("Use the stored path above only if the snippet is not enough.");
+  return lines.join("\n");
+}
+
+function renderShieldLastTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Shield Last", "bold"));
+  lines.push("");
+  lines.push(`Index: ${result.mode}`);
+  if (!result.runs.length) {
+    lines.push("No shield runs found.");
+    return lines.join("\n");
+  }
+  result.runs.forEach((run, index) => {
+    lines.push(`${index + 1}. ${run.finishedAt}  exit ${run.exitCode}  ${run.command}`);
+    lines.push(`   ${run.stored.directory}/summary.json`);
+    lines.push(`   ${formatBytes(run.output.totalBytes)} (~${run.output.estimatedTokens.toLocaleString()} tokens kept out of chat)`);
+  });
+  return lines.join("\n");
+}
+
+  return {
+    renderShieldLastTerminal,
+    renderShieldSearchTerminal,
+    renderShieldTerminal,
+    runShieldLast,
+    runShieldSearch,
+    runShield,
+  };
+};

package/lib/prismo-dev-scan.js

@@ -267,6 +267,21 @@ const {
   writeGeneratedFile,
 });
 
+const {
+  renderShieldLastTerminal,
+  renderShieldSearchTerminal,
+  renderShieldTerminal,
+  runShieldLast,
+  runShieldSearch,
+  runShield,
+} = require("./prismo-dev/shield")({
+  fs,
+  path,
+  estimateTokens,
+  formatBytes: (...args) => formatBytes(...args),
+  color,
+});
+
 function printHelp() {
   console.log(`Prismo CLI
 
@@ -275,6 +290,9 @@ Usage:
   prismo init [--json] [--dry-run] [path]
   prismo doctor [--json] [--dry-run] [--apply-ignores-only] [--no-context-packs] [--limit N] [path]
   prismo firewall [task] [--json] [--dry-run] [path]
+  prismo shield [--json] [path] -- <command ...>
+  prismo shield last [--json] [--limit N] [path]
+  prismo shield search <query> [--json] [--limit N] [path]
   prismo setup [--json] [--proxy-url URL] [path]
   prismo scan [--fix] [--ci] [--json] [--usage] [--simple] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
@@ -289,6 +307,7 @@ Commands:
   init        Add local PrismoDev helper docs and npm scripts when package.json exists.
   doctor      Diagnose, safely optimize, re-scan, and show before/after payoff.
   firewall    Generate allowed/blocked context policy files for an AI coding task.
+  shield      Run a noisy command, store full output locally, and return a compact summary.
   scan        Run PrismoDev for Claude Code, Codex, Cursor, and AI coding workflows.
   optimize    Generate lightweight AI-readable project context files in .prismo/.
   context     Print a copy-pasteable compact context prompt for AI coding tools.
@@ -475,6 +494,23 @@ Examples:
 Output:
   Writes .prismo/context-firewall.md, .prismo/allowed-context.txt, .prismo/blocked-context.txt, and .prismo/firewall-prompt.md.
   The firewall is a local policy file for the agent to follow before reading files; it does not enforce filesystem access by itself.`,
+    shield: `Prismo Shield
+
+Usage:
+  prismo shield [--json] [path] -- <command ...>
+  prismo shield last [--json] [--limit N] [path]
+  prismo shield search <query> [--json] [--limit N] [path]
+
+Examples:
+  prismo shield -- npm test
+  prismo shield -- pytest -q
+  prismo shield --json -- npm run build
+  prismo shield last
+  prismo shield search "auth failure"
+
+Output:
+  Runs the command locally, stores full stdout/stderr under .prismo/shield/runs/, indexes output in SQLite FTS5 when available, and prints only a compact summary plus useful error lines.
+  Search and last retrieve prior shield runs without re-feeding full output into agent context.`,
     ci: `Prismo CI
 
 Usage:
@@ -521,8 +557,8 @@ async function runCli(argv) {
     printCommandHelp(command);
     return;
   }
-  if (!["dev", "init", "doctor", "firewall", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
-    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
+  if (!["dev", "init", "doctor", "firewall", "shield", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
+    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo shield, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
   }
 
   if (command === "demo") {
@@ -604,6 +640,40 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "shield") {
+    const json = rest.includes("--json");
+    const limitIndex = rest.indexOf("--limit");
+    const limit = parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5);
+    const positional = getPositionals(rest, new Set(["--limit"]));
+    if (positional[0] === "last") {
+      const target = positional[1] || process.cwd();
+      const result = runShieldLast(target, { limit });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderShieldLastTerminal(result));
+      return;
+    }
+    if (positional[0] === "search") {
+      const query = positional[1];
+      const target = positional[2] || process.cwd();
+      const result = runShieldSearch(target, query, { limit });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderShieldSearchTerminal(result));
+      return;
+    }
+    const separatorIndex = rest.indexOf("--");
+    const beforeSeparator = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : [];
+    const commandArgs = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : getPositionals(rest);
+    const target = getPositionals(beforeSeparator)[0] || process.cwd();
+    const result = runShield(target, commandArgs);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderShieldTerminal(result));
+    }
+    process.exitCode = result.exitCode;
+    return;
+  }
+
   if (command === "setup") {
     const json = rest.includes("--json");
     const limitIndex = rest.indexOf("--limit");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",