@bglocation/tune-context 2.4.0 → 3.0.0

package/cli/entry-point.mjs

@@ -0,0 +1,73 @@
+// What every runnable module needs at its entry, answered once — shared by bin/
+// and by every runnable module in eval/ (TASK-095): "was this file run, or
+// imported?", how a step ends when its reader leaves early, and reading stdin.
+//
+// One implementation on purpose. eval/ used to answer it with
+// `process.argv[1]?.endsWith('<name>.mjs')`, the exact test that shipped 2.0.0
+// with a silent CLI. Harmless there only for as long as nobody called those
+// scripts through a symlink — and `tune-context eval` exists precisely so that
+// people stop calling them by path.
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * True only when the module at `moduleUrl` (pass `import.meta.url`) is the
+ * process entry point, so importing it for its functions (tests, the
+ * extensionless bin/tune-context wrapper, the `tune-context eval` dispatcher)
+ * never runs its CLI as a side effect of the import.
+ *
+ * Deliberately NOT a filename-suffix test on argv[1]. npm installs the
+ * package.json `bin` entry as a symlink named `tune-context` — no extension —
+ * so `argv[1].endsWith('tune-context.mjs')` was false for every real npm-channel
+ * invocation: main() never ran and the CLI exited 0 in total silence. That
+ * shipped in 2.0.0 (see the symlink test in test/bin-tune-context.test.mjs);
+ * the whole suite missed it because tests and smoke:init both spawned the full
+ * `.../bin/tune-context.mjs` path, which is the one shape a user never uses.
+ *
+ * Comparing resolved real paths holds for all four shapes: direct `.mjs`
+ * invocation, the npm symlink (resolves THROUGH the link to the file), the
+ * extensionless wrapper or the dispatcher (a different real path, so this stays
+ * false and the caller's own main() call is the single entry — no double run),
+ * and `import` from a test (argv[1] is the test runner). realpathSync on both
+ * sides also survives a symlinked package dir, as `npm link` and nvm both
+ * produce.
+ */
+export function isEntryPoint(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    // argv[1] can name something unresolvable (deleted, or a bare `-`); a CLI
+    // that cannot identify its own entry point must stay silent, not crash.
+    return false;
+  }
+}
+
+let pipeGuarded = false;
+
+/**
+ * A reader that leaves early — `| head`, a pager quit after one screen — is a
+ * normal end for a step writing to stdout, not a crash. Without a listener the
+ * EPIPE becomes an uncaught 'error' and a stacktrace once the output outgrows
+ * the pipe buffer (64 KB): a long report page, an aggregate of many tasks. Any
+ * other stdout error still goes up.
+ *
+ * Every eval step's main() calls this first, so both doors end the same way —
+ * one guard instead of a copy in the steps somebody happened to pipe (TASK-094
+ * covered prompt-metrics; report and analyze had none). Idempotent: one
+ * listener per process, however many mains run in it.
+ */
+export function endQuietlyOnClosedPipe() {
+  if (pipeGuarded) return;
+  pipeGuarded = true;
+  process.stdout.on('error', (e) => {
+    if (e.code !== 'EPIPE') throw e;
+  });
+}
+
+/** All of stdin as text — for a step reading its input from a pipe. */
+export async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}

package/cli/experiment.mjs

@@ -190,7 +190,7 @@ export function observeArm({ claudeDir, cwd, pkgRoot }) {
 
   const claudeMdPath = join(cwd, 'CLAUDE.md');
   const claudeMd = readText(claudeMdPath);
-  const hasBlock = claudeMd !== null && claudeMd.includes(START_MARKER) && claudeMd.includes(END_MARKER);
+  const hasBlock = claudeMd !== null && [START_MARKER, END_MARKER].every((m) => claudeMd.includes(m));
 
   const skills = deployed(claudeDir, pkgRoot, 'skills');
   const agents = deployed(claudeDir, pkgRoot, 'agents');
@@ -276,7 +276,7 @@ function planMutations({ claudeDir, cwd, pkgRoot, tc, rag }) {
 
     const claudeMdPath = join(cwd, 'CLAUDE.md');
     const claudeMd = readText(claudeMdPath);
-    if (claudeMd !== null && claudeMd.includes(START_MARKER) && claudeMd.includes(END_MARKER)) {
+    if (claudeMd !== null && [START_MARKER, END_MARKER].every((m) => claudeMd.includes(m))) {
       mutations.push({
         label: 'managed block removed from the project CLAUDE.md',
         path: claudeMdPath,
@@ -430,7 +430,16 @@ export function appendLedger(claudeDir, entry) {
 
 /** Parsed ledger, oldest first. Unparseable lines are skipped, never guessed at. */
 export function readLedger(claudeDir) {
-  const raw = readText(experimentPaths(claudeDir).ledgerPath);
+  return readLedgerFile(experimentPaths(claudeDir).ledgerPath);
+}
+
+/**
+ * The same reading for a ledger that is not the config dir's own — an
+ * archive's (TASK-098), handed to prompt-metrics/analyze with `--ledger`. One
+ * parser, so a ledger cannot mean one thing live and another in the archive.
+ */
+export function readLedgerFile(path) {
+  const raw = readText(path);
   if (raw === null) return [];
   return raw
     .split('\n')
@@ -445,6 +454,29 @@ export function readLedger(claudeDir) {
     .filter(Boolean);
 }
 
+/**
+ * The ledger an eval step assigns arms by — prompt-metrics and analyze, one
+ * rule for both: `--ledger <path>` when it was given, else the config dir's own.
+ *
+ * An explicit path must be a file. Read as no ledger (missing) or as an empty
+ * one (a directory), it would turn every experiment row into `branch` — the
+ * source the paired pool refuses — and nothing would say why (TASK-098).
+ *
+ * @returns {{ledger: object[], ledgerAvailable: boolean}} what annotateRows()
+ *   and analyze() take.
+ * @throws {ExperimentError} an explicit path that is missing or not a file.
+ */
+export function readStepLedger(explicitPath, claudeDir) {
+  if (explicitPath !== undefined) {
+    const stat = statSync(explicitPath, { throwIfNoEntry: false });
+    if (stat === undefined) throw new ExperimentError(`no ledger at ${explicitPath} (--ledger)`);
+    if (!stat.isFile()) throw new ExperimentError(`--ledger ${explicitPath} is not a file`);
+  }
+  const path = explicitPath ?? experimentPaths(claudeDir).ledgerPath;
+  const ledgerAvailable = existsSync(path);
+  return { ledger: ledgerAvailable ? readLedgerFile(path) : [], ledgerAvailable };
+}
+
 /**
  * Switch to `{tc, rag}`, recording everything needed to switch back.
  *

package/cli/version.mjs

@@ -0,0 +1,118 @@
+// Which code is this? Two answers, for two readers (TASK-097).
+//
+//   readVersion()  the release number, for `tune-context --version` — a script
+//                  greps it, and the plugin manifests are cross-checked against
+//                  it (verify:plugin).
+//   meterStamp()   the CODE that computed a measurement, stamped on every
+//                  artifact of the eval chain: rows (`meter_version`), the
+//                  aggregate (`analyzed_by`), the verdict (`judged_by`).
+//
+// They differ on purpose. EPIC-009's verdict was voided because its rows came
+// from a meter with a bug (TASK-092, costs inflated 2.02x) and nothing in the
+// frozen files said which code wrote them. A release number alone would not
+// have said it either: under `npm link`, which the runbook prescribed for that
+// series, the number changes only at release — a fix committed before the
+// release carries the same number as the bug it fixes.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Paths whose state is the meter's state. Coarse on purpose: a change to a hook
+ * eval never imports also makes the stamp `.dirty`. A false "dirty" holds a
+ * verdict that could have been issued; a false "clean" issues one from code
+ * nobody can rebuild — the cheaper error is the first. epics/, tasks/ and
+ * docs/ do not touch the meter and do not dirty the stamp.
+ */
+const METER_PATHS = ['eval', 'cli', 'hooks', 'bin', 'package.json'];
+
+/**
+ * Version straight from the shipped package.json — one source of truth, the
+ * same file verify:plugin cross-checks against plugin.json/marketplace.json,
+ * so `--version` can never drift from what the manifests claim. Both channels
+ * ship it: npm always includes package.json in the tarball, and the plugin
+ * channel is a git clone of this repo (guarded in verify-plugin's REQUIRE).
+ */
+export function readVersion(pkgRoot = PKG_ROOT) {
+  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
+/**
+ * The environment for a git that must answer about `cwd` and nothing else:
+ * GIT_* variables dropped. Inside a git hook they point at the hook's own
+ * repository (GIT_DIR, GIT_INDEX_FILE), and git would read that one instead.
+ */
+export function gitEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+}
+
+function git(cwd, args) {
+  return execFileSync('git', ['--no-optional-locks', ...args], { cwd, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+/**
+ * The stamp for the package at `pkgRoot`, computed now. Grammar (number
+ * illustrative):
+ *
+ *   2.6.0                  pkgRoot is not the TOP of a git repo: an npm install,
+ *                          including a local node_modules inside someone else's
+ *                          repo. A registry version is immutable, so the number
+ *                          names the code, and `npx -p @bglocation/tune-context@2.6.0`
+ *                          rebuilds it on demand.
+ *   2.6.0+<sha>            a checkout of this repo (`npm link`, the plugin's
+ *                          clone, `node eval/…`), clean in METER_PATHS. The first
+ *                          12 characters of HEAD, always 12: a shorter prefix
+ *                          can turn ambiguous as the repo grows.
+ *   2.6.0+<sha>.dirty      changes in METER_PATHS, untracked files included.
+ *   2.6.0+unknown          the top of a repo, but git is missing or failed.
+ *
+ * "The top", compared by realpath: inside someone else's repo, their HEAD would
+ * pass for ours. No `.git` at pkgRoot settles it without spawning git — which
+ * is also how a missing git still tells an install from a checkout.
+ *
+ * Uncached, for tests that change a repository between calls. Everything else
+ * uses meterStamp().
+ */
+export function readMeterStamp(pkgRoot = PKG_ROOT) {
+  const version = readVersion(pkgRoot);
+  if (!existsSync(join(pkgRoot, '.git'))) return version;
+  try {
+    if (realpathSync(git(pkgRoot, ['rev-parse', '--show-toplevel'])) !== realpathSync(pkgRoot)) return version;
+    const sha = git(pkgRoot, ['rev-parse', 'HEAD']).slice(0, 12);
+    const dirty = git(pkgRoot, ['status', '--porcelain', '--untracked-files=all', '--', ...METER_PATHS]) !== '';
+    return `${version}+${sha}${dirty ? '.dirty' : ''}`;
+  } catch {
+    return `${version}+unknown`;
+  }
+}
+
+const stamps = new Map();
+
+/**
+ * The stamp, computed once per process (and per package root): every artifact
+ * one process writes carries the same stamp even if the tree changes while it
+ * runs — the code that is running did not change with it.
+ */
+export function meterStamp(pkgRoot = PKG_ROOT) {
+  if (!stamps.has(pkgRoot)) stamps.set(pkgRoot, readMeterStamp(pkgRoot));
+  return stamps.get(pkgRoot);
+}
+
+const STAMP = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+(?:[0-9a-f]{12}(\.dirty)?|(unknown)))?$/;
+
+/**
+ * Why a stamp does not name code anyone can rebuild — or null when it does.
+ * A message rather than a boolean, because the verdict has to say which of the
+ * three it was.
+ */
+export function stampProblem(stamp) {
+  if (typeof stamp !== 'string' || stamp === '') return 'no stamp at all';
+  const m = STAMP.exec(stamp);
+  if (m === null) return 'not a meter stamp';
+  if (m[1]) return "computed from uncommitted changes in the meter's paths — that code exists nowhere else";
+  if (m[2]) return 'computed from a checkout git could not read — the commit is unknown';
+  return null;
+}

package/eval/adoption-report.mjs

@@ -19,6 +19,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { endQuietlyOnClosedPipe, isEntryPoint } from '../cli/entry-point.mjs';
 import { claudeBaseDir } from '../hooks/config-dir.mjs';
 import { classifyAvailability, probeProjectMcp } from './mcp-probe.mjs';
 
@@ -76,7 +77,7 @@ Options:
   -h, --help     Show this help
 
 The log is written by the adoption-log.mjs PostToolUse hook (installed by
-tune-context). Cost in dollars is NOT here — see eval/prompt-metrics.mjs.
+tune-context). Cost in dollars is NOT here — see tune-context eval prompt-metrics.
 `.trim();
 
 export function parseLog(text) {
@@ -496,7 +497,7 @@ export function formatReport(a) {
   }
   L.push('');
   L.push('Cost (dollars) is not in the hook log. Two independent routes to it:');
-  L.push('  eval/prompt-metrics.mjs — prices the transcript, works with hooks OFF too.');
+  L.push('  tune-context eval prompt-metrics — prices the transcript, works with hooks OFF too.');
   L.push('  OTEL: CLAUDE_CODE_ENABLE_TELEMETRY=1 + an OTLP collector →');
   L.push('  metric `claude_code.cost.usage` (direct) / `claude_code.token.usage`.');
   L.push('  caveman (output style) leaves no tool call — not measured here.');
@@ -504,11 +505,16 @@ export function formatReport(a) {
   return L.join('\n');
 }
 
-function main() {
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval adoption-report` — one parser behind both doors (EPIC-010).
+ */
+export function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
   let logPath;
   try {
     const { values } = parseArgs({
-      args: process.argv.slice(2),
+      args,
       options: {
         log: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
@@ -539,6 +545,6 @@ function main() {
   process.stdout.write(`${formatReport(aggregate(records))}\n`);
 }
 
-if (process.argv[1] && process.argv[1].endsWith('adoption-report.mjs')) {
+if (isEntryPoint(import.meta.url)) {
   main();
 }