cgraphx 1.4.1 → 2.0.0

package/scripts/agent-eval/subagent-token-cost.py

@@ -1,188 +0,0 @@
-#!/usr/bin/env python3
-"""Measure real API token usage and $ cost from Claude Code subagent transcripts.
-
-Reads the `.output` JSONL file Claude Code writes per background subagent
-(the `output_file` returned by the Agent tool), sums the `usage` field on
-each assistant message, and applies Sonnet list pricing to get a cache-aware
-$ cost.
-
-Why this exists: tool-output chars (the easy thing to count by eye) is a
-poor proxy for real cost. The dominant cost driver in multi-turn sessions is
-`cache_read_input_tokens` — every turn re-sends the growing conversation as
-cached input, billed at ~10% of full input cost. A tool that returns tiny
-output but forces many turns (grep) is more expensive than a tool that
-returns rich output in few turns (codegraph_explore). chars hides this;
-`usage` + $ pricing exposes it.
-
-See docs/features/2026-07-01-calls-command/abac-comparison.md for the case
-study that motivated this script.
-
-Pricing (Sonnet, per million tokens):
-    input             $3.00
-    output            $15.00
-    cache_read        $0.30   (10% of input)
-    cache_creation    $3.75   (125% of input — first-time cache write)
-
-Usage:
-    python3 subagent-token-cost.py <agent-id> [<agent-id> ...]
-    python3 subagent-token-cost.py --dir <tasks-dir>   # all .output files
-
-The agent-id form looks up `<tasks-dir>/<agent-id>.output` under the standard
-session tasks directory. Pass `--dir` to point at a different directory
-(e.g. when comparing across sessions).
-
-Output: one line per arm with turns, tool_uses, input/output/cache_read/
-cache_write token counts, raw total, and $ cost. Sorted in input order.
-
-Notes:
-- This reads ONLY the `usage` field and tool_use block counts — never message
-  content. Safe to run on large transcripts; won't overflow your context.
-- For main-session cost (not subagent), use offload-eval-cost.mjs instead,
-  which reads the structured eval-runs format and uses Claude Code's own
-  authoritative costUSD accounting from the `result` event.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-# Sonnet list pricing, per million tokens.
-PRICE_INPUT_PER_M = 3.00
-PRICE_OUTPUT_PER_M = 15.00
-PRICE_CACHE_READ_PER_M = 0.30
-PRICE_CACHE_WRITE_PER_M = 3.75
-
-
-def default_tasks_dir() -> Path:
-    """Best-effort default for this session's tasks dir."""
-    # Claude Code writes subagent .output files under a session-scoped tasks dir.
-    # The exact path varies; common locations:
-    candidates = [
-        Path('/private/tmp/claude-501'),
-        Path.home() / '.claude' / 'tasks',
-    ]
-    for c in candidates:
-        if c.exists():
-            # Find the most recently modified session dir
-            session_dirs = sorted(
-                c.glob('*-Users-*'), key=lambda p: p.stat().st_mtime, reverse=True
-            )
-            for sd in session_dirs:
-                tasks = sd / 'tasks'
-                if tasks.exists():
-                    return tasks
-    return Path('/private/tmp/claude-501/unknown-session/tasks')
-
-
-def measure_file(path: Path) -> dict | None:
-    if not path.exists():
-        return None
-    totals = {'input': 0, 'output': 0, 'cache_read': 0, 'cache_creation': 0}
-    assistant_turns = 0
-    tool_uses = 0
-    with path.open() as f:
-        for line in f:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                obj = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            msg = obj.get('message') or {}
-            if msg.get('role') != 'assistant':
-                continue
-            usage = msg.get('usage') or {}
-            if not usage:
-                continue
-            assistant_turns += 1
-            totals['input'] += usage.get('input_tokens', 0) or 0
-            totals['output'] += usage.get('output_tokens', 0) or 0
-            totals['cache_read'] += usage.get('cache_read_input_tokens', 0) or 0
-            totals['cache_creation'] += usage.get('cache_creation_input_tokens', 0) or 0
-            content = msg.get('content') or []
-            if isinstance(content, list):
-                for block in content:
-                    if isinstance(block, dict) and block.get('type') == 'tool_use':
-                        tool_uses += 1
-    cost = (
-        totals['input'] * PRICE_INPUT_PER_M
-        + totals['output'] * PRICE_OUTPUT_PER_M
-        + totals['cache_read'] * PRICE_CACHE_READ_PER_M
-        + totals['cache_creation'] * PRICE_CACHE_WRITE_PER_M
-    ) / 1_000_000
-    return {
-        'turns': assistant_turns,
-        'tool_uses': tool_uses,
-        'totals': totals,
-        'all_tokens': sum(totals.values()),
-        'cost_usd': cost,
-    }
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
-    ap.add_argument('agent_ids', nargs='*', help='subagent IDs to measure')
-    ap.add_argument(
-        '--dir',
-        help='tasks directory containing <id>.output files (default: auto-detect latest session)',
-    )
-    ap.add_argument(
-        '--label',
-        action='append',
-        default=[],
-        help='label for an agent, in the same order as agent_ids (repeatable)',
-    )
-    args = ap.parse_args()
-
-    tasks_dir = Path(args.dir) if args.dir else default_tasks_dir()
-
-    if not args.agent_ids:
-        # Measure every .output file in the tasks dir
-        files = sorted(tasks_dir.glob('*.output'))
-        if not files:
-            print(f'no .output files in {tasks_dir}', file=sys.stderr)
-            return 1
-        targets = [(f.stem, f) for f in files]
-    else:
-        targets = [(aid, tasks_dir / f'{aid}.output') for aid in args.agent_ids]
-
-    rows = []
-    for i, (label, path) in enumerate(targets):
-        if args.label and i < len(args.label):
-            label = args.label[i]
-        r = measure_file(path)
-        if r is None:
-            print(f'{label}: transcript not found at {path}', file=sys.stderr)
-            continue
-        r['label'] = label
-        rows.append(r)
-
-    if not rows:
-        return 1
-
-    header = (
-        f'{"Arm":<32} {"turns":>6} {"tools":>6} {"input":>10} {"output":>10} '
-        f'{"cache_r":>10} {"cache_w":>10} {"total_tok":>11} {"$ cost":>9}'
-    )
-    print(header)
-    print('-' * len(header))
-    for r in rows:
-        t = r['totals']
-        print(
-            f'{r["label"]:<32} {r["turns"]:>6} {r["tool_uses"]:>6} {t["input"]:>10,} '
-            f'{t["output"]:>10,} {t["cache_read"]:>10,} {t["cache_creation"]:>10,} '
-            f'{r["all_tokens"]:>11,} ${r["cost_usd"]:>8.4f}'
-        )
-
-    print()
-    print('Pricing: Sonnet list. input $3/M, output $15/M, cache_read $0.30/M, cache_write $3.75/M.')
-    print('total_tok = raw token sum (ignores cache discount). $ cost = cache-aware (what actually bills).')
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())

package/scripts/build-bundle.sh

@@ -1,118 +0,0 @@
-#!/usr/bin/env bash
-#
-# Build a self-contained CodeGraph bundle: an official Node runtime + the
-# compiled app + its production deps, so CodeGraph runs with NO system Node and
-# NO native build — node:sqlite is built into the bundled Node. One archive per
-# platform.
-#
-# Because dropping better-sqlite3 left zero native addons, the recipe is pure
-# file-packaging (download the target's Node, copy the app, archive) — so any
-# platform's bundle can be built on any OS. No cross-compile, no native runners.
-#
-# Usage:
-#   scripts/build-bundle.sh <target> [node-version]
-#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
-#                  | win32-x64 | win32-arm64
-#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
-#
-# Output:
-#   unix:    release/cgraphx-<target>.tar.gz   (launcher: bin/cgraphx)
-#   windows: release/cgraphx-<target>.zip      (launcher: bin/cgraphx.cmd)
-set -euo pipefail
-
-TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
-NODE_VERSION="${2:-v24.16.0}"
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OUT="$ROOT/release"
-WORK="$(mktemp -d)"
-trap 'rm -rf "$WORK"' EXIT
-
-ARCH="${TARGET##*-}"   # x64 | arm64
-OSFAM="${TARGET%-*}"   # darwin | linux | win32
-
-echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
-
-# 1. Download + extract the official Node runtime for the target platform.
-if [ "$OSFAM" = "win32" ]; then
-  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
-  if command -v unzip >/dev/null 2>&1; then
-    unzip -q "$WORK/node.zip" -d "$WORK"
-  else
-    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
-  fi
-  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
-else
-  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
-  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
-  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
-fi
-[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
-
-# 2. Build the app (compiled JS + copied wasm/schema assets).
-echo "[bundle] building app"
-( cd "$ROOT" && npm run build >/dev/null )
-
-# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
-STAGE="$WORK/cgraphx-${TARGET}"
-mkdir -p "$STAGE/lib" "$STAGE/bin"
-cp -R "$ROOT/dist" "$STAGE/lib/dist"
-cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
-echo "[bundle] installing production dependencies"
-( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
-rm -f "$STAGE/lib/package-lock.json"
-
-# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
-#    path, so no system Node is ever needed).
-#
-# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
-# baseline compiler so they never reach the turboshaft optimizing tier, whose
-# per-compilation Zone arena OOMs the whole process (`Fatal process out of
-# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
-# V8 engine init so it must be on node's command line; the parse worker inherits
-# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
-# also self-relaunches with this flag when launched without it, so non-bundled
-# runs are covered too; passing it here avoids that extra spawn.)
-if [ "$OSFAM" = "win32" ]; then
-  cp "$NODE_BIN" "$STAGE/node.exe"
-  printf '@"%%~dp0..\\node.exe" --liftoff-only "%%~dp0..\\lib\\dist\\bin\\codegraph.js" %%*\r\n' \
-    > "$STAGE/bin/cgraphx.cmd"
-else
-  cp "$NODE_BIN" "$STAGE/node"
-  cat > "$STAGE/bin/cgraphx" <<'LAUNCH'
-#!/bin/sh
-# Resolve symlinks (e.g. the ~/.local/bin/cgraphx link install.sh creates) so
-# we find the real bundle dir, not the symlink's location.
-SELF="$0"
-while [ -L "$SELF" ]; do
-  target="$(readlink "$SELF")"
-  case "$target" in
-    /*) SELF="$target" ;;
-    *) SELF="$(dirname "$SELF")/$target" ;;
-  esac
-done
-DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
-# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
-exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/codegraph.js" "$@"
-LAUNCH
-  chmod +x "$STAGE/bin/cgraphx"
-fi
-
-# 5. Archive (.zip for Windows, .tar.gz otherwise).
-mkdir -p "$OUT"
-if [ "$OSFAM" = "win32" ]; then
-  ARCHIVE="$OUT/cgraphx-${TARGET}.zip"
-  rm -f "$ARCHIVE"
-  ( cd "$WORK" && zip -rqX "$ARCHIVE" "cgraphx-${TARGET}" )
-else
-  ARCHIVE="$OUT/cgraphx-${TARGET}.tar.gz"
-  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
-  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "cgraphx-${TARGET}"
-fi
-echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"

package/scripts/extract-release-notes.mjs

@@ -1,130 +0,0 @@
-#!/usr/bin/env node
-/**
- * Extract a release-notes block from CHANGELOG.md for a given version
- * (or unwrap text supplied on stdin), then join hard-wrapped paragraphs.
- *
- * Why: GitHub renders release-note Markdown with GFM hard breaks, so
- * every `\n` becomes `<br>`. The CHANGELOG is hard-wrapped at ~75
- * chars for readable diffs, which then renders as awkward visible
- * line breaks on the release page. This script joins indented
- * continuation lines into a single line per bullet so the GFM
- * renderer produces clean paragraphs.
- *
- * Repo-level CHANGELOG.md viewing is unaffected (CommonMark treats
- * newlines as spaces there).
- *
- * Usage:
- *   extract-release-notes.mjs <version>     # read CHANGELOG.md
- *   extract-release-notes.mjs --stdin       # read from stdin (any text)
- */
-
-import { readFileSync } from 'fs';
-
-const arg = process.argv[2];
-if (!arg) {
-  console.error('usage: extract-release-notes.mjs <version> | --stdin');
-  process.exit(1);
-}
-
-let block;
-if (arg === '--stdin') {
-  block = readFileSync(0, 'utf8').replace(/\r\n?/g, '\n').split('\n');
-} else {
-  const version = arg;
-  const escaped = version.replace(/\./g, '\\.');
-  const headerRe = new RegExp(`^## \\[${escaped}\\]`);
-  const anyHeaderRe = /^## \[/;
-  const lines = readFileSync('CHANGELOG.md', 'utf8').split('\n');
-  const start = lines.findIndex((l) => headerRe.test(l));
-  if (start === -1) {
-    console.error(`no '## [${version}]' entry found in CHANGELOG.md`);
-    process.exit(1);
-  }
-  const after = lines.findIndex((l, i) => i > start && anyHeaderRe.test(l));
-  block = lines.slice(start, after === -1 ? lines.length : after);
-}
-
-// Track a stack of `{ indent: number }` frames so a continuation line
-// can attach to the right ancestor. Handles the post-nested-list
-// continuation pattern:
-//
-//     - top-level
-//         - nested
-//       back to top-level  <- 2-space indent, joins the top-level bullet
-const out = [];
-let buf = '';
-let stack = [];
-
-function flushBuf() {
-  if (buf !== '') {
-    out.push(buf);
-    buf = '';
-  }
-}
-
-function leadingSpaces(s) {
-  const m = s.match(/^(\s*)/);
-  return m ? m[1].length : 0;
-}
-
-// Bullets: `-`, `*`, `digit.` only. `+` is intentionally excluded — the
-// CHANGELOG uses literal `+` inline (`config + instructions`) and we
-// don't want to misread those as nested bullets.
-const listItemRe = /^(\s*)([-*]|\d+\.)\s+/;
-const fenceRe = /^\s*```/;
-
-let inFence = false;
-
-for (const line of block) {
-  // Fenced code blocks: pass through verbatim, no joining.
-  if (fenceRe.test(line)) {
-    flushBuf();
-    stack = [];
-    out.push(line);
-    inFence = !inFence;
-    continue;
-  }
-  if (inFence) {
-    out.push(line);
-    continue;
-  }
-  if (/^\s*$/.test(line)) {
-    flushBuf();
-    out.push('');
-    continue;
-  }
-  if (/^#/.test(line)) {
-    flushBuf();
-    stack = [];
-    out.push(line);
-    continue;
-  }
-  const itemMatch = line.match(listItemRe);
-  if (itemMatch) {
-    flushBuf();
-    const indent = itemMatch[1].length;
-    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
-      stack.pop();
-    }
-    stack.push({ indent });
-    buf = line;
-    continue;
-  }
-  if (/^\s/.test(line)) {
-    const indent = leadingSpaces(line);
-    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
-      flushBuf();
-      stack.pop();
-    }
-    const trimmed = line.replace(/^\s+/, '');
-    buf = buf === '' ? trimmed : `${buf} ${trimmed}`;
-    continue;
-  }
-  flushBuf();
-  stack = [];
-  out.push(line);
-}
-flushBuf();
-
-process.stdout.write(out.join('\n'));
-if (!out[out.length - 1]?.endsWith('\n')) process.stdout.write('\n');

package/scripts/local-install.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Build the current branch and link it as the global `cgraphx` for
-# hands-on testing. Replaces any existing global install for as long
-# as the symlink is in place.
-#
-# Usage:
-#   ./scripts/local-install.sh           # build + link
-#   ./scripts/local-install.sh --undo    # unlink + restore the published version
-
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-PKG=$(node -p "require('./package.json').name")
-VERSION=$(node -p "require('./package.json').version")
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-if [ "${1:-}" = "--undo" ]; then
-  echo "→ unlinking ${PKG}"
-  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
-  echo "→ reinstalling published ${PKG}"
-  npm install -g "${PKG}"
-  echo "done: global cgraphx -> $(command -v cgraphx)"
-  exit 0
-fi
-
-echo "→ building ${PKG} ${VERSION} (${BRANCH})"
-npm run build
-
-echo "→ linking globally"
-npm link
-
-LINKED=$(command -v cgraphx || echo "(not on PATH)")
-echo
-echo "✓ global cgraphx now points to this branch"
-echo "  binary:  ${LINKED}"
-echo "  branch:  ${BRANCH}"
-echo "  version: ${VERSION}"
-echo
-echo "To restore the published version:"
-echo "  ./scripts/local-install.sh --undo"

package/scripts/npm-sdk.js

@@ -1,75 +0,0 @@
-'use strict';
-//
-// Programmatic / embedded SDK entry for cgraphx (issue #354).
-//
-// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
-// the tool never depends on the user's runtime. Embedded library consumers are
-// the opposite case: they already run their own Node and just want the compiled
-// API — `require("cgraphx")` returning the CodeGraph class et al.
-//
-// The compiled library + its production dependencies (web-tree-sitter,
-// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
-//   cgraphx-<platform>-<arch>/lib/dist/index.js
-// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
-// the main package thin — no second 50 MB copy of the grammars — while making the
-// SDK work in the consumer's process. Types are a separate concern: the main
-// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
-// the same release so it can never skew from the runtime it re-exports.
-//
-// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
-// the SQLite adapter — so loading this module is safe on older Node, and the
-// node:sqlite requirement surfaces with an actionable error only when a DB is
-// actually opened. Heavy extraction additionally wants the bundled launcher's
-// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
-// host that drives large indexing should pass that flag to its own Node.
-
-var path = require('path');
-var os = require('os');
-var fs = require('fs');
-
-var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
-var pkg = 'cgraphx-' + target;
-
-module.exports = require(resolveLibrary());
-
-// Locate the compiled library entry inside the installed per-platform bundle.
-// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
-// is present, so an embedded consumer knows exactly what to install.
-function resolveLibrary() {
-  // 1) The npm-installed optional dependency — the normal case.
-  try {
-    return require.resolve(pkg + '/lib/dist/index.js');
-  } catch (e) {
-    /* fall through to the self-healed cache */
-  }
-
-  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
-  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
-  //    cached bundle here — unlike the CLI shim we never trigger a network
-  //    download from inside require(), which must stay synchronous and cheap.
-  var cached = cachedLibrary();
-  if (cached) return cached;
-
-  throw new Error(
-    'cgraphx: the programmatic API is unavailable because the platform bundle\n' +
-    '(' + pkg + ') is not installed.\n' +
-    'The compiled library ships inside that per-platform optional dependency.\n' +
-    'Fixes:\n' +
-    '  - install from the official npm registry so the matching bundle is fetched:\n' +
-    '      npm i cgraphx --registry=https://registry.npmjs.org\n' +
-    '  - or run the CLI once (e.g. `npx cgraphx status`) to\n' +
-    '    self-heal the bundle into ~/.cgraphx, then require() will find it.'
-  );
-}
-
-function cachedLibrary() {
-  try {
-    var version = require(path.join(__dirname, 'package.json')).version;
-    var base = process.env.CGRAPHX_INSTALL_DIR || path.join(os.homedir(), '.cgraphx');
-    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
-    if (fs.existsSync(lib)) return lib;
-  } catch (e) {
-    /* no readable cache → caller reports the install guidance */
-  }
-  return null;
-}