getprismo 0.1.21 → 0.1.22

package/README.md

@@ -180,6 +180,33 @@ Recommended Stack
 
 This makes PrismoDev the measure-first layer: it tells you whether you need ignore cleanup, output sandboxing, code indexing, repo packing, instruction trimming, session splitting, or MCP/tool hygiene.
 
+For the short version:
+
+```bash
+npx getprismo scan --report-card
+```
+
+That prints the simplest decision:
+
+```text
+PrismoDev Report Card
+
+Biggest waste: Generated artifacts / ignore cleanup: High
+Start with: npx getprismo doctor --apply-suggestions --dry-run
+Then: npx getprismo shield -- <noisy command>
+Code index needed: not yet
+Round-trip risk: Low
+```
+
+To benchmark a noisy command:
+
+```bash
+npx getprismo benchmark -- npm test
+npx getprismo benchmark session
+```
+
+`benchmark -- <command>` measures raw command output tokens versus the compact shield summary. `benchmark session` summarizes recent local Claude/Codex sessions, including round-trip context signals like tool calls, repeated commands, repeated source reads, and MCP/tool surface.
+
 ---
 
 ## new: context shield
@@ -580,6 +607,8 @@ no install needed. npx runs it directly.
 | `cc timeline` | session reconstruction with events |
 | `scan --usage` | full repo scan with local usage data |
 | `scan --optimizer-fit` | recommend which token-optimization path fits your repo/session |
+| `scan --report-card` | shortest decision-layer summary |
+| `benchmark` | measure command-output reduction or recent session round-trip context |
 | `scan --simple` | plain-english summary |
 | `scan --fix` | create safe fix files |
 | `scan --ci` | fail CI when token-risk gates fail |

package/lib/prismo-dev/benchmark.js

@@ -0,0 +1,122 @@
+module.exports = function createBenchmark(deps) {
+  const {
+    NPX_COMMAND,
+    estimateTokens,
+    formatTokenCount,
+    getUsageSummary,
+    runShield,
+    scanRepo,
+    color,
+  } = deps;
+
+function estimateSummaryTokens(shieldResult) {
+  const lines = shieldResult.output && Array.isArray(shieldResult.output.interestingLines)
+    ? shieldResult.output.interestingLines.join("\n")
+    : "";
+  return estimateTokens([
+    `Command: ${shieldResult.command}`,
+    `Exit: ${shieldResult.exitCode}`,
+    `Duration: ${shieldResult.durationMs}ms`,
+    lines,
+  ].join("\n"));
+}
+
+function runBenchmark(rootDir = process.cwd(), commandArgs = [], options = {}) {
+  if (options.sessionOnly || !commandArgs.length) {
+    const scan = scanRepo(rootDir, { includeUsage: true, usageLimit: options.limit || 5 });
+    const usage = getUsageSummary({ cwd: scan.root, limit: options.limit || 5, tool: "all" });
+    const fit = scan.optimizerFit;
+    return {
+      schemaVersion: 1,
+      mode: "session",
+      scannedPath: scan.root,
+      score: scan.score,
+      riskLevel: scan.risk,
+      sessions: usage.sessions.length,
+      tokens: usage.totals,
+      roundTripContext: fit.roundTripContext,
+      optimizerFit: fit.summary,
+      recommendedStack: fit.recommendedStack,
+      next: [`${NPX_COMMAND} scan --optimizer-fit`, `${NPX_COMMAND} watch --once`, `${NPX_COMMAND} cc timeline`],
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  const shield = runShield(rootDir, commandArgs);
+  const rawTokens = shield.output.estimatedTokens || 0;
+  const summaryTokens = estimateSummaryTokens(shield);
+  const reductionPercent = rawTokens > 0 ? Math.max(0, Math.round(((rawTokens - summaryTokens) / rawTokens) * 100)) : 0;
+  return {
+    schemaVersion: 1,
+    mode: "command",
+    scannedPath: shield.cwd,
+    command: shield.command,
+    exitCode: shield.exitCode,
+    durationMs: shield.durationMs,
+    rawOutput: {
+      bytes: shield.output.totalBytes,
+      estimatedTokens: rawTokens,
+    },
+    shieldedSummary: {
+      estimatedTokens: summaryTokens,
+      interestingLines: shield.output.interestingLines,
+    },
+    estimatedTokenReductionPercent: reductionPercent,
+    stored: shield.stored,
+    next: [
+      "Give the shield summary to the agent first.",
+      `${NPX_COMMAND} shield search "<error text>"`,
+      `${NPX_COMMAND} scan --optimizer-fit`,
+    ],
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function renderBenchmarkTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Benchmark", "bold"));
+  lines.push("");
+  if (result.mode === "session") {
+    lines.push(`Mode: session`);
+    lines.push(`Score: ${result.score}/100 (${result.riskLevel} risk)`);
+    lines.push(`Sessions: ${result.sessions}`);
+    lines.push(`Tokens: ${formatTokenCount(result.tokens.displayTokens || 0)} (${result.tokens.exactTokens ? "exact-local-log" : "estimated/local"})`);
+    lines.push(`Optimizer fit: ${result.optimizerFit}`);
+    lines.push("");
+    lines.push("Round-Trip Context:");
+    lines.push(`- Level: ${result.roundTripContext.level}`);
+    lines.push(`- Tool calls: ${result.roundTripContext.toolCalls}`);
+    lines.push(`- Repeated commands: ${result.roundTripContext.repeatedCommandMentions}`);
+    lines.push(`- Repeated source reads: ${result.roundTripContext.repeatedSourceReads}`);
+    lines.push("");
+    lines.push("Next:");
+    result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+    return lines.join("\n");
+  }
+
+  lines.push(`Mode: command`);
+  lines.push(`Command: ${result.command}`);
+  lines.push(`Exit: ${result.exitCode}`);
+  lines.push(`Duration: ${result.durationMs}ms`);
+  lines.push(`Raw output: ${result.rawOutput.bytes.toLocaleString()} bytes (~${result.rawOutput.estimatedTokens.toLocaleString()} tokens)`);
+  lines.push(`Shield summary: ~${result.shieldedSummary.estimatedTokens.toLocaleString()} tokens`);
+  lines.push(`Estimated reduction: ${result.estimatedTokenReductionPercent}%`);
+  lines.push("");
+  lines.push("Stored Output:");
+  lines.push(`- ${result.stored.stdout}`);
+  lines.push(`- ${result.stored.stderr}`);
+  lines.push("");
+  lines.push("Useful Lines:");
+  result.shieldedSummary.interestingLines.slice(0, 12).forEach((line) => lines.push(`- ${line}`));
+  lines.push("");
+  lines.push("Next:");
+  result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+  return lines.join("\n");
+}
+
+  return {
+    renderBenchmarkTerminal,
+    runBenchmark,
+  };
+};

package/lib/prismo-dev/report.js

@@ -141,11 +141,47 @@ function renderOptimizerFitTerminal(result, options = {}) {
     lines.push(`  ${item.reason}`);
   });
   lines.push("");
+  lines.push(color("Round-Trip Context", "bold", useColor));
+  lines.push(`- Level: ${fit.roundTripContext.level}`);
+  lines.push(`- Tool calls: ${fit.roundTripContext.toolCalls}`);
+  lines.push(`- Repeated command mentions: ${fit.roundTripContext.repeatedCommandMentions}`);
+  lines.push(`- Repeated source reads: ${fit.roundTripContext.repeatedSourceReads}`);
+  lines.push(`- MCP/tool servers: ${fit.roundTripContext.mcpServers}`);
+  lines.push(`- ${fit.roundTripContext.recommendation}`);
+  lines.push("");
   lines.push("Notes:");
   fit.caveats.forEach((caveat) => lines.push(`- ${caveat}`));
   return lines.join("\n");
 }
 
+function renderReportCardTerminal(result, options = {}) {
+  const useColor = options.color !== false;
+  const fit = result.optimizerFit;
+  const top = fit.recommendedStack[0];
+  const second = fit.recommendedStack[1];
+  const lines = [];
+  lines.push("");
+  lines.push(color("PrismoDev Report Card", "bold", useColor));
+  lines.push("");
+  lines.push(`Score: ${result.score}/100 (${result.risk} risk)`);
+  lines.push(`Biggest waste: ${fit.summary}`);
+  lines.push("");
+  if (top) lines.push(`Start with: ${top.command}`);
+  if (second) lines.push(`Then: ${second.command}`);
+  lines.push("");
+  const codeIndex = fit.bottlenecks.find((item) => item.id === "code-indexing");
+  const output = fit.bottlenecks.find((item) => item.id === "output-sandboxing");
+  const ignore = fit.bottlenecks.find((item) => item.id === "ignore-cleanup");
+  lines.push(`Code index needed: ${codeIndex && codeIndex.level === "High" ? "yes" : codeIndex && codeIndex.level === "Medium" ? "maybe" : "not yet"}`);
+  lines.push(`Output sandbox needed: ${output && output.level !== "Low" ? "yes" : "not yet"}`);
+  lines.push(`Ignore cleanup needed: ${ignore && ignore.level !== "Low" ? "yes" : "not urgent"}`);
+  lines.push(`Round-trip risk: ${fit.roundTripContext.level}`);
+  lines.push("");
+  lines.push("Why:");
+  fit.bottlenecks.slice(0, 3).forEach((item) => lines.push(`- ${item.label}: ${item.evidence[0]}`));
+  return lines.join("\n");
+}
+
 function evaluateCi(result, options = {}) {
   const minScore = Number(options.minScore || 80);
   const failures = [];
@@ -434,6 +470,7 @@ function writeReport(result) {
     renderCiReport,
     renderMarkdownReport,
     renderOptimizerFitTerminal,
+    renderReportCardTerminal,
     renderSimpleScanReport,
     renderTerminalReport,
     writeReport,

package/lib/prismo-dev/scan.js

@@ -390,12 +390,21 @@ function detectOptimizationStack(root, claudeConfig, codexConfig) {
   const projectHeadroom = fs.existsSync(path.join(root, ".headroom")) || fs.existsSync(path.join(os.homedir(), ".headroom"));
   const projectDistill = fs.existsSync(path.join(os.homedir(), ".config", "distill")) || commandExists("distill");
   const projectRtk = fs.existsSync(path.join(root, ".rtk")) || commandExists("rtk");
+  const packageText = readIfText(path.join(root, "package.json"), 512 * 1024) || "";
+  const readmeText = readIfText(path.join(root, "README.md"), 512 * 1024) || "";
+  const projectText = `${packageText}\n${readmeText}`.toLowerCase();
+  const hasText = (pattern) => pattern.test(projectText);
 
   const tools = {
     rtk: { detected: projectRtk, source: projectRtk ? "binary-or-project-config" : "not-detected" },
     headroom: { detected: projectHeadroom || commandExists("headroom"), source: projectHeadroom ? "local-config" : commandExists("headroom") ? "binary" : "not-detected" },
     distill: { detected: projectDistill, source: projectDistill ? "binary-or-user-config" : "not-detected" },
     mana: { detected: projectMana || commandExists("mana"), source: projectMana ? "local-config" : commandExists("mana") ? "binary" : "not-detected" },
+    contextMode: { detected: commandExists("context-mode") || hasText(/context-mode/), source: commandExists("context-mode") ? "binary" : hasText(/context-mode/) ? "project-reference" : "not-detected" },
+    leanCtx: { detected: commandExists("lean-ctx") || hasText(/lean-ctx|lean ctx/), source: commandExists("lean-ctx") ? "binary" : hasText(/lean-ctx|lean ctx/) ? "project-reference" : "not-detected" },
+    repomix: { detected: commandExists("repomix") || hasText(/repomix/), source: commandExists("repomix") ? "binary" : hasText(/repomix/) ? "project-reference" : "not-detected" },
+    codegraph: { detected: commandExists("codegraph") || hasText(/codegraph|codebase-memory-mcp|jcodemunch|sigmap/), source: commandExists("codegraph") ? "binary" : hasText(/codegraph|codebase-memory-mcp|jcodemunch|sigmap/) ? "project-reference" : "not-detected" },
+    tokf: { detected: commandExists("tokf") || hasText(/tokf/), source: commandExists("tokf") ? "binary" : hasText(/tokf/) ? "project-reference" : "not-detected" },
   };
 
   return {
@@ -908,6 +917,13 @@ function buildOptimizerFit(result) {
   const mcpEvidence = [];
   let mcpScore = result.optimizationStack.mcpServerTotal >= 10 ? 70 : result.optimizationStack.mcpServerTotal >= 5 ? 45 : 10;
   if (result.optimizationStack.mcpServerTotal) addEvidence(mcpEvidence, `${result.optimizationStack.mcpServerTotal} MCP/tool servers detected`);
+  const totalToolCalls = realUsage ? realUsage.sessions.reduce((sum, session) => sum + Number(session.toolCalls || 0), 0) : 0;
+  const repeatedCommands = realUsage ? realUsage.sessions.reduce((sum, session) => sum + (session.repeatedCommands || []).reduce((inner, item) => inner + Number(item.count || 0), 0), 0) : 0;
+  if (totalToolCalls >= 500) mcpScore += 30;
+  else if (totalToolCalls >= 100) mcpScore += 15;
+  if (repeatedCommands >= 20) mcpScore += 20;
+  if (totalToolCalls) addEvidence(mcpEvidence, `${totalToolCalls} tool calls in recent local sessions`);
+  if (repeatedCommands) addEvidence(mcpEvidence, `${repeatedCommands} repeated command/tool mentions`);
   bottlenecks.push({
     id: "tool-surface",
     label: "Tool/MCP surface overhead",
@@ -1006,6 +1022,17 @@ function buildOptimizerFit(result) {
         reason: "Best for one-shot repo handoff, less ideal for long live coding sessions.",
       },
     ],
+    roundTripContext: {
+      level: levelFromScore(Math.max(mcpScore, repeatedSourceReads >= 50 ? 60 : repeatedSourceReads >= 12 ? 35 : 0)),
+      toolCalls: totalToolCalls,
+      repeatedCommandMentions: repeatedCommands,
+      repeatedSourceReads,
+      mcpServers: result.optimizationStack.mcpServerTotal,
+      summary: totalToolCalls || repeatedCommands || repeatedSourceReads || result.optimizationStack.mcpServerTotal
+        ? "Round-trip context risk includes tool calls, repeated commands, repeated source reads, and MCP/tool surface."
+        : "No strong round-trip context signal found in local logs.",
+      recommendation: "Measure workflow-level savings, not only compressed payload size. Fewer tool round trips can beat smaller individual responses.",
+    },
     caveats: [
       "Do not stack optimizers blindly; measure one real workflow before and after.",
       "Payload reduction is not the same as workflow savings; repeated tool calls can erase compression wins.",

package/lib/prismo-dev-scan.js

@@ -194,6 +194,7 @@ const {
   renderCiReport,
   renderMarkdownReport,
   renderOptimizerFitTerminal,
+  renderReportCardTerminal,
   renderSimpleScanReport,
   renderTerminalReport,
   writeReport,
@@ -285,6 +286,19 @@ const {
   color,
 });
 
+const {
+  renderBenchmarkTerminal,
+  runBenchmark,
+} = require("./prismo-dev/benchmark")({
+  NPX_COMMAND,
+  estimateTokens,
+  formatTokenCount,
+  getUsageSummary,
+  runShield,
+  scanRepo: (...args) => scanRepo(...args),
+  color,
+});
+
 const {
   renderMcpDoctorTerminal,
   runMcpDoctor,
@@ -300,13 +314,14 @@ Usage:
   prismo init [--json] [--dry-run] [path]
   prismo doctor [--json] [--dry-run] [--apply-ignores-only] [--apply-suggestions] [--no-context-packs] [--limit N] [path]
   prismo firewall [task] [--json] [--dry-run] [path]
+  prismo benchmark [session] [--json] [--limit N] [path] [-- <command ...>]
   prismo shield [--json] [path] -- <command ...>
   prismo shield last [--json] [--limit N] [path]
   prismo shield search <query> [--json] [--limit N] [path]
   prismo mcp [path]
   prismo mcp doctor [--json] [path]
   prismo setup [--json] [--proxy-url URL] [path]
-  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--simple] [--no-report] [path]
+  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--report-card] [--simple] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
   prismo context [scope] [--json] [path]
   prismo cc [list|last N|all] [--json] [--limit N] [path]
@@ -319,6 +334,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.
+  benchmark   Measure command-output savings or recent session round-trip context.
   shield      Run a noisy command, store full output locally, and return a compact summary.
   mcp         Start a local MCP server exposing Prismo tools over stdio.
   scan        Run PrismoDev for Claude Code, Codex, Cursor, and AI coding workflows.
@@ -336,6 +352,7 @@ Options:
   --json      Output valid JSON only for CI or future dashboard ingestion.
   --usage     Include real local Codex/Claude Code session usage in scan diagnostics.
   --optimizer-fit Recommend the right optimization path for this repo/session.
+  --report-card Print a short plain-English optimization report card.
   --simple    Print a plain-English scan summary for first-time or non-technical users.
   --no-report Do not write .prismo/prismo-dev-report.md.
   --limit N   Number of recent local sessions to show.
@@ -375,12 +392,13 @@ function printCommandHelp(command) {
     scan: `PrismoDev
 
 Usage:
-  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--simple] [--no-report] [--limit N] [path]
+  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--report-card] [--simple] [--no-report] [--limit N] [path]
 
 Examples:
   prismo scan
   prismo scan --usage
   prismo scan --optimizer-fit
+  prismo scan --report-card
   prismo scan --simple
   prismo scan --fix
   prismo scan --ci
@@ -390,6 +408,7 @@ Examples:
 Notes:
   --usage reads local Codex/Claude Code logs when present.
   --optimizer-fit explains whether ignore cleanup, output sandboxing, code indexing, repo packing, instruction trimming, or session splitting fits this repo best.
+  --report-card prints the shortest decision-layer summary.
   --simple keeps the output short and does not write a report unless combined with --fix.
   --fix creates safe recommendation files and never overwrites CLAUDE.md or AGENTS.md.`,
     optimize: `Prismo Optimize
@@ -608,8 +627,8 @@ async function runCli(argv) {
     printCommandHelp(command);
     return;
   }
-  if (!["dev", "init", "doctor", "firewall", "shield", "mcp", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
-    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo shield, prismo mcp, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
+  if (!["dev", "init", "doctor", "firewall", "benchmark", "shield", "mcp", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
+    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo benchmark, prismo shield, prismo mcp, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
   }
 
   if (command === "demo") {
@@ -692,6 +711,25 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "benchmark") {
+    const json = rest.includes("--json");
+    const limitIndex = rest.indexOf("--limit");
+    const separatorIndex = rest.indexOf("--");
+    const beforeSeparator = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
+    const commandArgs = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
+    const positional = getPositionals(beforeSeparator, new Set(["--limit"]));
+    const sessionOnly = positional[0] === "session" || commandArgs.length === 0;
+    const target = positional[0] === "session" ? positional[1] || process.cwd() : positional[0] || process.cwd();
+    const result = runBenchmark(target, commandArgs, {
+      sessionOnly,
+      limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
+    });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(renderBenchmarkTerminal(result));
+    if (result.mode === "command") process.exitCode = result.exitCode;
+    return;
+  }
+
   if (command === "shield") {
     const json = rest.includes("--json");
     const limitIndex = rest.indexOf("--limit");
@@ -926,12 +964,13 @@ async function runCli(argv) {
   const json = rest.includes("--json");
   const simple = rest.includes("--simple");
   const optimizerFit = rest.includes("--optimizer-fit");
+  const reportCard = rest.includes("--report-card");
   const ciMode = rest.includes("--ci");
-  const includeUsage = rest.includes("--usage") || optimizerFit;
+  const includeUsage = rest.includes("--usage") || optimizerFit || reportCard;
   const limitIndex = rest.indexOf("--limit");
   const usageToolIndex = rest.indexOf("--usage-tool");
   const target = getPositionals(rest, new Set(["--limit", "--usage-tool"]))[0] || process.cwd();
-  const scanDone = printStep(includeUsage ? "Scanning repo and local usage" : "Scanning repo", json || simple || optimizerFit);
+  const scanDone = printStep(includeUsage ? "Scanning repo and local usage" : "Scanning repo", json || simple || optimizerFit || reportCard);
   const result = scanRepo(target, {
     includeUsage,
     usageLimit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
@@ -952,13 +991,19 @@ async function runCli(argv) {
       payload.ci = evaluateCi(result);
       if (!payload.ci.passed) process.exitCode = 1;
     }
-    if (optimizerFit) {
+    if (optimizerFit || reportCard) {
       console.log(JSON.stringify({
         schemaVersion: 1,
         scannedPath: result.root,
         score: result.score,
         riskLevel: result.risk,
         optimizerFit: result.optimizerFit,
+        reportCard: reportCard ? {
+          biggestWaste: result.optimizerFit.summary,
+          startWith: result.optimizerFit.recommendedStack[0]?.command || null,
+          then: result.optimizerFit.recommendedStack[1]?.command || null,
+          roundTripRisk: result.optimizerFit.roundTripContext.level,
+        } : undefined,
         generatedAt: result.generatedAt,
       }, null, 2));
       return;
@@ -969,7 +1014,9 @@ async function runCli(argv) {
     return;
   }
 
-  if (optimizerFit) {
+  if (reportCard) {
+    console.log(renderReportCardTerminal(result));
+  } else if (optimizerFit) {
     console.log(renderOptimizerFitTerminal(result));
   } else if (simple) {
     console.log(renderSimpleScanReport(result));
@@ -985,7 +1032,7 @@ async function runCli(argv) {
     const actions = applyFixes(result);
     console.log("\nFix Mode:");
     actions.forEach((action) => console.log(`- ${action}`));
-  } else if (!noReport && !simple && !optimizerFit) {
+  } else if (!noReport && !simple && !optimizerFit && !reportCard) {
     const report = writeReport(result);
     if (report.backupPath) {
       console.log(`\nExisting report backed up to ${path.basename(report.backupPath)}.`);
@@ -1006,10 +1053,13 @@ module.exports = {
   renderWatchTerminal,
   renderWatchReport,
   renderTerminalReport,
+  renderOptimizerFitTerminal,
+  renderReportCardTerminal,
   renderDoctorTerminal,
   renderInitTerminal,
   runSetup,
   runOptimize,
+  runBenchmark,
   runDoctor,
   runInit,
   runCli,

package/package.json

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