@mbeato/contextscope 0.1.0

package/.next/standalone/bin/cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * contextscope CLI
+ *
+ * Subcommands:
+ *   (default)         spawn the dashboard server + open browser
+ *   install-plugin    install the /usage slash command for Claude Code
+ *   uninstall-plugin  remove the slash command
+ *
+ * Flags (default cmd):
+ *   --port <n>        pin a port (errors if taken)
+ *   --no-open         skip auto-opening the browser
+ *   --help            show this
+ */
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createServer } from "node:net";
+import { existsSync, promises as fs } from "node:fs";
+import { homedir } from "node:os";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, "..");
+const STANDALONE_SERVER = join(PKG_ROOT, ".next", "standalone", "server.js");
+const STANDALONE_STATIC = join(PKG_ROOT, ".next", "standalone", ".next", "static");
+const REAL_STATIC = join(PKG_ROOT, ".next", "static");
+const STANDALONE_PUBLIC = join(PKG_ROOT, ".next", "standalone", "public");
+const REAL_PUBLIC = join(PKG_ROOT, "public");
+const PLUGIN_COMMAND_SRC = join(PKG_ROOT, "plugin", "commands", "usage.md");
+const CLAUDE_COMMAND_DST = join(homedir(), ".claude", "commands", "usage.md");
+
+const args = process.argv.slice(2);
+const subcommand = args[0] && !args[0].startsWith("-") ? args[0] : null;
+
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(
+    [
+      "contextscope — local dashboard for Claude Code per-turn context audit",
+      "",
+      "Usage:",
+      "  contextscope                     start the dashboard (default)",
+      "  contextscope install-plugin      install the /usage slash command",
+      "  contextscope uninstall-plugin    remove the /usage slash command",
+      "",
+      "Flags (default cmd):",
+      "  --port <n>     pin a port (default: find first free starting at 3939)",
+      "  --no-open      do not open the browser automatically",
+      "  --help         show this message",
+      "",
+    ].join("\n")
+  );
+  process.exit(0);
+}
+
+if (subcommand === "install-plugin") {
+  if (!existsSync(PLUGIN_COMMAND_SRC)) {
+    process.stderr.write(`error: slash command source not found at ${PLUGIN_COMMAND_SRC}\n`);
+    process.exit(1);
+  }
+  await fs.mkdir(dirname(CLAUDE_COMMAND_DST), { recursive: true });
+  await fs.copyFile(PLUGIN_COMMAND_SRC, CLAUDE_COMMAND_DST);
+  process.stdout.write(`installed /usage at ${CLAUDE_COMMAND_DST}\n`);
+  process.stdout.write(`restart Claude Code, then run /usage in any session.\n`);
+  process.exit(0);
+}
+
+if (subcommand === "uninstall-plugin") {
+  try {
+    await fs.unlink(CLAUDE_COMMAND_DST);
+    process.stdout.write(`removed ${CLAUDE_COMMAND_DST}\n`);
+  } catch (e) {
+    if (e && e.code === "ENOENT") process.stdout.write(`not installed (nothing to remove)\n`);
+    else throw e;
+  }
+  process.exit(0);
+}
+
+const pinnedPortIdx = args.indexOf("--port");
+const pinnedPort = pinnedPortIdx >= 0 ? Number(args[pinnedPortIdx + 1]) : null;
+const noOpen = args.includes("--no-open");
+
+if (!existsSync(STANDALONE_SERVER)) {
+  process.stderr.write(
+    `error: standalone server not found at ${STANDALONE_SERVER}\n` +
+      `Run \`npm run build\` first (this should have happened automatically on install).\n`
+  );
+  process.exit(1);
+}
+
+// next standalone expects static assets co-located. When shipping via npm we
+// copy ./next/static and ./public next to the bundled server; create symlinks
+// at runtime if the published package didn't ship them.
+async function ensureStaticAssets() {
+  if (!existsSync(STANDALONE_STATIC) && existsSync(REAL_STATIC)) {
+    try {
+      await fs.symlink(REAL_STATIC, STANDALONE_STATIC, "dir");
+    } catch {
+      // ignore — may have been created by a parallel start
+    }
+  }
+  if (!existsSync(STANDALONE_PUBLIC) && existsSync(REAL_PUBLIC)) {
+    try {
+      await fs.symlink(REAL_PUBLIC, STANDALONE_PUBLIC, "dir");
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on("error", () => resolve(false));
+    srv.listen({ port, host: "127.0.0.1" }, () => {
+      srv.close(() => resolve(true));
+    });
+  });
+}
+
+async function findPort() {
+  if (pinnedPort != null) {
+    const free = await isPortFree(pinnedPort);
+    if (!free) {
+      process.stderr.write(`error: --port ${pinnedPort} is in use\n`);
+      process.exit(1);
+    }
+    return pinnedPort;
+  }
+  for (let p = 3939; p < 3939 + 50; p++) {
+    if (await isPortFree(p)) return p;
+  }
+  process.stderr.write("error: no free port found in 3939–3988\n");
+  process.exit(1);
+}
+
+async function main() {
+  await ensureStaticAssets();
+  const port = await findPort();
+  const url = `http://localhost:${port}`;
+
+  const child = fork(STANDALONE_SERVER, [], {
+    env: { ...process.env, PORT: String(port), HOSTNAME: "127.0.0.1" },
+    stdio: "inherit",
+  });
+
+  // Open browser once server is ready. We poll the port instead of waiting on
+  // child stdout — more portable across Next versions.
+  if (!noOpen) {
+    const { default: open } = await import("open");
+    const start = Date.now();
+    const poll = setInterval(async () => {
+      if (Date.now() - start > 10_000) {
+        clearInterval(poll);
+        return;
+      }
+      try {
+        const ok = await fetch(url, { method: "HEAD" }).then((r) => r.status >= 200);
+        if (ok) {
+          clearInterval(poll);
+          open(url).catch(() => {});
+        }
+      } catch {
+        // not yet ready
+      }
+    }, 200);
+  }
+
+  process.stdout.write(`contextscope running on ${url}\n  (Ctrl+C to stop)\n`);
+
+  const shutdown = (code = 0) => {
+    if (!child.killed) child.kill("SIGTERM");
+    process.exit(code);
+  };
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+main().catch((err) => {
+  process.stderr.write(`fatal: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/.next/standalone/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/.next/standalone/lib/files.ts

@@ -0,0 +1,148 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getEncoding } from "js-tiktoken";
+
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, ".claude");
+const PROJECTS_DIR = join(CLAUDE_DIR, "projects");
+const enc = getEncoding("cl100k_base");
+const SCAN_ROOTS = [HOME]; // searched for CLAUDE.md
+const SCAN_MAX_DEPTH = 4;
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  ".turbo",
+  ".vercel",
+  ".cache",
+  ".pnpm-store",
+  // Dotfile dirs that ship dependency-bundled CLAUDE.md files we don't author
+  ".vscode",
+  ".antigravity",
+  ".bun",
+  ".cursor",
+  ".windsurf",
+  // GSD/Claude worktree shadow copies
+  "worktrees",
+]);
+
+export type ContextFile = {
+  category: "claude-md-global" | "claude-md-project" | "memory-md";
+  name: string;          // human-readable label
+  filePath: string;
+  tokens: number;
+  loadedWhen: string;    // human-readable: "every session" / "when cwd matches X" / "in project X"
+};
+
+function countTokens(s: string): number {
+  return enc.encode(s).length;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTokens(filePath: string): Promise<number> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return countTokens(raw);
+  } catch {
+    return 0;
+  }
+}
+
+async function findClaudeMds(root: string, depth: number, acc: string[]): Promise<void> {
+  if (depth > SCAN_MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.name !== ".claude") {
+      if (SKIP_DIRS.has(e.name)) continue;
+      // Skip other dotfiles too — too noisy
+      if (depth > 0) continue;
+    }
+    if (SKIP_DIRS.has(e.name)) continue;
+    const p = join(root, e.name);
+    if (e.isDirectory()) {
+      await findClaudeMds(p, depth + 1, acc);
+    } else if (e.isFile() && e.name === "CLAUDE.md") {
+      acc.push(p);
+    }
+  }
+}
+
+export async function getContextFiles(): Promise<ContextFile[]> {
+  const out: ContextFile[] = [];
+
+  // 1) Global CLAUDE.md — always loaded
+  const globalPath = join(CLAUDE_DIR, "CLAUDE.md");
+  if (await exists(globalPath)) {
+    out.push({
+      category: "claude-md-global",
+      name: "~/.claude/CLAUDE.md",
+      filePath: globalPath,
+      tokens: await readTokens(globalPath),
+      loadedWhen: "every session",
+    });
+  }
+
+  // 2) Project CLAUDE.md files — find under HOME
+  const projectClaudeMds: string[] = [];
+  for (const root of SCAN_ROOTS) {
+    await findClaudeMds(root, 0, projectClaudeMds);
+  }
+  // Exclude the global one (which lives under ~/.claude)
+  for (const p of projectClaudeMds) {
+    if (p === globalPath) continue;
+    const tokens = await readTokens(p);
+    const rel = p.replace(HOME, "~");
+    // The directory containing this file is its "project"
+    const dirRel = rel.replace(/\/CLAUDE\.md$/, "");
+    out.push({
+      category: "claude-md-project",
+      name: rel,
+      filePath: p,
+      tokens,
+      loadedWhen: `when cwd is ${dirRel} (or below)`,
+    });
+  }
+
+  // 3) MEMORY.md files — per-project auto-memory
+  if (await exists(PROJECTS_DIR)) {
+    let projDirs: import("node:fs").Dirent[] = [];
+    try {
+      projDirs = await readdir(PROJECTS_DIR, { withFileTypes: true });
+    } catch {
+      projDirs = [];
+    }
+    for (const d of projDirs) {
+      if (!d.isDirectory()) continue;
+      const dirName = String(d.name);
+      const memPath = join(PROJECTS_DIR, dirName, "memory", "MEMORY.md");
+      if (!(await exists(memPath))) continue;
+      // Project dir name encodes cwd, e.g. "-Users-vtx-VTX" => /Users/vtx/VTX
+      const inferredCwd = dirName.replace(/^-/, "/").replaceAll("-", "/");
+      out.push({
+        category: "memory-md",
+        name: `${dirName}/memory/MEMORY.md`,
+        filePath: memPath,
+        tokens: await readTokens(memPath),
+        loadedWhen: `in project ${inferredCwd}`,
+      });
+    }
+  }
+
+  return out.sort((a, b) => b.tokens - a.tokens);
+}

package/.next/standalone/lib/hooks.ts

@@ -0,0 +1,161 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { getEncoding } from "js-tiktoken";
+
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+const enc = getEncoding("cl100k_base");
+
+const DRY_RUN_EVENTS = new Set(["SessionStart", "UserPromptSubmit"]);
+const DRY_RUN_TIMEOUT_MS = 5000;
+
+export type HookEntry = {
+  event: string;
+  matcher?: string;
+  command: string;
+  status: "measured" | "not-run-side-effects" | "error" | "timeout";
+  perTurnTokens: number;     // tokenized stdout (0 if not measured)
+  loadedWhen: string;        // human description
+  output?: string;           // truncated preview of injected text
+  error?: string;
+};
+
+function countTokens(s: string): number {
+  return enc.encode(s).length;
+}
+
+async function runHook(command: string, sampleInput: object): Promise<{ stdout: string; error?: string; timeout?: boolean }> {
+  return new Promise((resolve) => {
+    const child = spawn("bash", ["-lc", command], { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+      resolve({ stdout, timeout: true });
+    }, DRY_RUN_TIMEOUT_MS);
+    child.stdout?.on("data", (d) => (stdout += d.toString()));
+    child.stderr?.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve({ stdout, error: err.message });
+    });
+    child.on("close", (code) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      if (code !== 0 && !stdout) resolve({ stdout, error: stderr.trim() || `exit ${code}` });
+      else resolve({ stdout });
+    });
+    try {
+      child.stdin?.write(JSON.stringify(sampleInput));
+      child.stdin?.end();
+    } catch {
+      // ignore
+    }
+  });
+}
+
+export async function getHooks(): Promise<HookEntry[]> {
+  let parsed: Record<string, unknown> | undefined;
+  try {
+    const raw = await readFile(SETTINGS_PATH, "utf8");
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const hooksMap = (parsed?.hooks ?? {}) as Record<
+    string,
+    Array<{ matcher?: string; hooks: Array<{ type: string; command: string; timeout?: number }> }>
+  >;
+
+  type Pending = { event: string; matcher?: string; command: string; measure: boolean };
+  const pending: Pending[] = [];
+  for (const [event, blocks] of Object.entries(hooksMap)) {
+    for (const block of blocks) {
+      const matcher = block.matcher;
+      for (const h of block.hooks ?? []) {
+        if (h.type !== "command") continue;
+        pending.push({ event, matcher, command: h.command, measure: DRY_RUN_EVENTS.has(event) });
+      }
+    }
+  }
+
+  const results = await Promise.all(
+    pending.map(async (p): Promise<HookEntry> => {
+      const { event, matcher, command, measure } = p;
+      if (measure) {
+        const sampleInput =
+          event === "UserPromptSubmit"
+            ? { prompt: "sample prompt for measurement" }
+            : {};
+        const r = await runHook(command, sampleInput);
+        if (r.timeout) {
+          return {
+            event,
+            matcher,
+            command,
+            status: "timeout",
+            perTurnTokens: countTokens(r.stdout),
+            loadedWhen: event === "SessionStart" ? "session start" : "every user prompt",
+            output: r.stdout.slice(0, 280),
+            error: `dry-run hit ${DRY_RUN_TIMEOUT_MS}ms timeout`,
+          };
+        }
+        if (r.error) {
+          return {
+            event,
+            matcher,
+            command,
+            status: "error",
+            perTurnTokens: 0,
+            loadedWhen: event === "SessionStart" ? "session start" : "every user prompt",
+            error: r.error,
+          };
+        }
+        return {
+          event,
+          matcher,
+          command,
+          status: "measured",
+          perTurnTokens: countTokens(r.stdout),
+          loadedWhen: event === "SessionStart" ? "session start (sticks until restart)" : "every user prompt",
+          output: r.stdout.slice(0, 280),
+        };
+      }
+      return {
+        event,
+        matcher,
+        command,
+        status: "not-run-side-effects",
+        perTurnTokens: 0,
+        loadedWhen: describeEvent(event),
+      };
+    })
+  );
+  return results;
+}
+
+function describeEvent(event: string): string {
+  switch (event) {
+    case "PreToolUse":
+      return "before each tool call (not measured — has side effects)";
+    case "PostToolUse":
+      return "after each tool call (not measured — has side effects)";
+    case "Stop":
+      return "on session stop (not measured — has side effects)";
+    case "PreCompact":
+      return "before context compaction (not measured)";
+    default:
+      return event;
+  }
+}