agentwaste-core 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# agentwaste-core
+
+Shared scanner/report engine used by the `agentmess` focused CLI tools.
+
+This package is meant as a dependency for:
+
+- `suckytraces`
+- `keybarf`
+- `tokengoblin`
+- `tooltantrum`
+- `agentmess`
+
+It has no public `npx` command of its own.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "agentwaste-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared local coding-agent scanner powering agentmess and the tiny gremlin CLI squad.",
+  "keywords": [
+    "ai",
+    "agents",
+    "cli",
+    "observability",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli.js",
+    "./report": "./src/report.js",
+    "./scanner": "./src/scanner.js",
+    "./tools": "./src/tools.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,331 @@
+import { resolve } from "node:path";
+
+import { buildReport, calculationGuide } from "./report.js";
+import { scanAgentWaste } from "./scanner.js";
+import { buildToolReport, explainTool, getToolConfig, listToolConfigs } from "./tools.js";
+
+const DEFAULT_PACKAGE = { name: "agentmess", version: "0.1.0" };
+
+export async function runAgentmessCli(argv, packageInfo = DEFAULT_PACKAGE) {
+  const parsed = parseArgs(argv, {
+    defaultCommand: "scan",
+    commands: new Set(["scan", "explain", "tools", "squad"]),
+    aliases: new Map([["list", "tools"]]),
+  });
+
+  if (parsed.help) {
+    console.log(agentmessHelp(packageInfo));
+    return;
+  }
+  if (parsed.version) {
+    console.log(packageInfo.version);
+    return;
+  }
+  if (parsed.options.command === "tools" || parsed.options.command === "squad") {
+    console.log(toolSquadText(packageInfo));
+    return;
+  }
+  if (parsed.options.command === "explain") {
+    console.log(calculationGuide({ version: packageInfo.version, json: parsed.options.json }));
+    return;
+  }
+
+  const startedAt = Date.now();
+  const spinner = startScanSpinner(parsed.options, "agentmess");
+  let stats;
+  try {
+    stats = await scanAgentWaste(parsed.options);
+  } finally {
+    spinner.stop();
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const report = buildReport(stats, {
+    version: packageInfo.version,
+    elapsedMs,
+    color: parsed.options.color,
+  });
+
+  if (parsed.options.json) {
+    console.log(JSON.stringify(report.json, null, 2));
+    return;
+  }
+
+  console.log(report.text);
+}
+
+export async function runToolCli(argv, toolId, packageInfo = { name: toolId, version: "0.1.0" }) {
+  const config = getToolConfig(toolId);
+  const parsed = parseArgs(argv, {
+    defaultCommand: "scan",
+    commands: new Set(["scan", "show", "sniff", "roast", "explain"]),
+    aliases: new Map([
+      ["show", "scan"],
+      ["sniff", "scan"],
+      ["roast", "scan"],
+    ]),
+  });
+
+  if (parsed.help) {
+    console.log(toolHelp(config, packageInfo));
+    return;
+  }
+  if (parsed.version) {
+    console.log(packageInfo.version);
+    return;
+  }
+  if (parsed.options.command === "explain") {
+    console.log(explainTool(toolId, { version: packageInfo.version, json: parsed.options.json }));
+    return;
+  }
+
+  const startedAt = Date.now();
+  const spinner = startScanSpinner(parsed.options, toolId);
+  let stats;
+  try {
+    stats = await scanAgentWaste(parsed.options);
+  } finally {
+    spinner.stop();
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const report = buildToolReport(stats, {
+    toolId,
+    version: packageInfo.version,
+    elapsedMs,
+    color: parsed.options.color,
+  });
+
+  if (parsed.options.json) {
+    console.log(JSON.stringify(report.json, null, 2));
+    return;
+  }
+
+  console.log(report.text);
+}
+
+function parseArgs(argv, config) {
+  const args = argv.slice(2);
+  const options = {
+    command: config.defaultCommand,
+    homeDir: undefined,
+    projectDir: process.cwd(),
+    days: 365,
+    maxFiles: Number.MAX_SAFE_INTEGER,
+    json: false,
+    color: process.stdout.isTTY,
+  };
+
+  if (args[0] && !args[0].startsWith("-")) {
+    const rawCommand = args.shift();
+    if (!config.commands.has(rawCommand)) throw new Error(`unknown command ${rawCommand}`);
+    options.command = config.aliases.get(rawCommand) ?? rawCommand;
+  }
+
+  let maxFilesExplicit = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") return { help: true, options };
+    if (arg === "--version" || arg === "-v") return { version: true, options };
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      options.color = false;
+      continue;
+    }
+    if (arg === "--all") {
+      options.days = "all";
+      if (!maxFilesExplicit) options.maxFiles = Number.MAX_SAFE_INTEGER;
+      continue;
+    }
+    if (arg === "--home") {
+      i += 1;
+      if (!args[i]) throw new Error("--home requires a path");
+      options.homeDir = resolve(args[i]);
+      continue;
+    }
+    if (arg === "--path") {
+      i += 1;
+      if (!args[i]) throw new Error("--path requires a path");
+      options.projectDir = resolve(args[i]);
+      continue;
+    }
+    if (arg === "--days") {
+      i += 1;
+      if (!args[i]) throw new Error("--days requires a number or all");
+      options.days = parseDays(args[i], "--days");
+      if (options.days === "all" && !maxFilesExplicit) options.maxFiles = Number.MAX_SAFE_INTEGER;
+      continue;
+    }
+    if (arg === "--max-files") {
+      i += 1;
+      if (!args[i]) throw new Error("--max-files requires a number");
+      maxFilesExplicit = true;
+      options.maxFiles = parsePositiveInt(args[i], "--max-files");
+      continue;
+    }
+    throw new Error(`unknown option ${arg}`);
+  }
+
+  return { options };
+}
+
+function parseDays(value, flag) {
+  if (String(value).toLowerCase() === "all") return "all";
+  return parsePositiveInt(value, flag);
+}
+
+function parsePositiveInt(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+  return parsed;
+}
+
+function agentmessHelp(packageInfo) {
+  return `agentmess v${packageInfo.version}
+
+Usage:
+  agentmess [scan] [options]
+  agentmess explain [options]
+  agentmess tools
+
+Commands:
+  scan                    Full local agent postmortem (default)
+  explain                 Explain every report formula without scanning logs
+  tools                   Show the focused npx CLIs
+
+Options:
+  --home <path>             Home directory to scan (default: current user's home)
+  --path <path>             Project directory to scan (default: cwd)
+  --days <number|all>       Lookback window in days (default: 365)
+  --all                     Scan all available sessions (same as --days all)
+  --max-files <number>      Maximum session files per source (default: unlimited)
+  --json                    Print machine-readable JSON
+  --no-color                Disable ANSI color
+  --version                 Print version
+  --help                    Show help
+
+Focused tools:
+${listToolConfigs().map((tool) => `  npx ${tool.binName.padEnd(16)} ${tool.emoji} ${tool.npc}`).join("\n")}
+
+The scanner runs locally. It counts redacted fingerprints and aggregate metrics;
+it does not upload transcripts or print raw secret values.`;
+}
+
+function toolHelp(config, packageInfo) {
+  return `${config.packageName} v${packageInfo.version}
+
+${config.emoji} ${config.npc}: ${config.tagline}
+
+Usage:
+  ${config.binName} [scan] [options]
+  ${config.binName} explain [options]
+
+Aliases:
+  ${config.binName} show
+  ${config.binName} sniff
+  ${config.binName} roast
+
+Options:
+  --home <path>             Home directory to scan (default: current user's home)
+  --path <path>             Project directory to scan (default: cwd)
+  --days <number|all>       Lookback window in days (default: 365)
+  --all                     Scan all available sessions (same as --days all)
+  --max-files <number>      Maximum session files per source (default: unlimited)
+  --json                    Print machine-readable JSON
+  --no-color                Disable ANSI color
+  --version                 Print version
+  --help                    Show help
+
+Try:
+  npx ${config.binName}
+  npx ${config.binName} --days 7
+  npx ${config.binName} --json`;
+}
+
+function toolSquadText(packageInfo) {
+  return [
+    `agentmess focused tools v${packageInfo.version}`,
+    "",
+    ...listToolConfigs().map((tool) => `npx ${tool.binName.padEnd(16)} ${tool.emoji} ${tool.npc} — ${tool.tagline}`),
+    "",
+    "npx agentmess       consolidated report for the focused checks",
+  ].join("\n");
+}
+
+async function narrate(options, toolId) {
+  if (options.json || !process.stdout.isTTY) return;
+  for (const line of narrationMessages(toolId)) {
+    process.stdout.write(`${ansi(options.color, "38;2;148;163;184", `  ${line}`)}\n`);
+    await sleep(170);
+  }
+}
+
+function narrationMessages(toolId) {
+  switch (toolId) {
+    case "suckytraces":
+      return ["scanning session logs.", "computing trace coverage."];
+    case "keybarf":
+      return ["scanning logs and config for secret fingerprints.", "checking whether fingerprints appear in model-facing records."];
+    case "tokengoblin":
+      return ["reading token usage records.", "computing fresh input, cache hit rate, and excess context."];
+    case "tooltantrum":
+      return ["counting tool calls and failures.", "computing retry recovery and unresolved failures."];
+    default:
+      return ["scanned the agent logs.", "numbers first, feelings later."];
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function startScanSpinner(options, toolId) {
+  if (options.json || !process.stdout.isTTY) return { stop() {} };
+
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const messages = spinnerMessages(toolId);
+  let index = 0;
+
+  const render = () => {
+    const frame = frames[index % frames.length];
+    const message = messages[Math.floor(index / 8) % messages.length];
+    process.stdout.write(`\r${ansi(options.color, "38;2;147;197;253", frame)} ${ansi(options.color, "38;2;148;163;184", message)} `);
+    index += 1;
+  };
+
+  render();
+  const timer = setInterval(render, 80);
+
+  return {
+    stop() {
+      clearInterval(timer);
+      process.stdout.write("\r\x1b[2K");
+    },
+  };
+}
+
+function spinnerMessages(toolId) {
+  switch (toolId) {
+    case "suckytraces":
+      return ["scanning session logs...", "checking trace identifiers...", "computing trace coverage..."];
+    case "keybarf":
+      return ["scanning secret patterns...", "fingerprinting matches...", "checking model-facing records..."];
+    case "tokengoblin":
+      return ["reading token usage...", "computing fresh input...", "checking cache hit rate..."];
+    case "tooltantrum":
+      return ["counting tool calls...", "measuring failure rate...", "checking retry recovery..."];
+    default:
+      return ["scanning sessions...", "checking token usage...", "checking secrets...", "checking tool reliability...", "checking trace coverage..."];
+  }
+}
+
+function ansi(enabled, code, value) {
+  if (!enabled) return value;
+  return `\x1b[${code}m${value}\x1b[0m`;
+}
+
+function color(code, value) {
+  return `\x1b[${code}m${value}\x1b[0m`;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { runAgentmessCli, runToolCli } from "./cli.js";
+export { buildReport, calculationGuide, toReportJson } from "./report.js";
+export { scanAgentWaste } from "./scanner.js";
+export { TOOL_IDS, buildToolReport, explainTool, getToolConfig, listToolConfigs } from "./tools.js";