trail-code 0.0.0-stage → 0.28.0-semantic.3

package/scripts/pack-trail.mjs

@@ -0,0 +1,53 @@
+/**
+ * Lays out the `@trailhq/trail-code` package from this repo's build, in build/trail/.
+ *
+ * trail and graft are one program under two names, published as two packages
+ * from the same `dist/`:
+ *
+ *   @trailhq/trail-code  bin: trail  →  dist/bin/trail.js
+ *   @nanonets/graft  bin: graft  →  dist/bin/graft.js   (this repo's package.json)
+ *
+ * Each package ships exactly one command, so installing both never clashes on
+ * a bin name, and `graft upgrade` installs both. @nanonets/graft stays a full
+ * package rather than a pointer: the hook shims committed in thousands of repos
+ * resolve `@nanonets/graft/dist/claude/*` by path, and 78% of active installs
+ * are on versions older than the one that knows about trail.
+ *
+ * Usage, after `npm run build` (and the telemetry key stamp, when publishing):
+ *   node scripts/pack-trail.mjs
+ *   npm publish build/trail --access public
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const out = join(root, 'build', 'trail');
+
+if (!existsSync(join(root, 'dist', 'bin', 'trail.js'))) {
+  console.error('✗ dist/bin/trail.js not found — run `npm run build` first');
+  process.exit(1);
+}
+
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const trail = {
+  ...pkg,
+  name: '@trailhq/trail-code',
+  description:
+    "Your team's shared memory for coding agents: a code map on your machine, and the learnings, decisions and skills your whole team shares. Formerly graft.",
+  keywords: [...new Set(['trail', ...(pkg.keywords ?? [])])],
+  bin: { trail: 'dist/bin/trail.js' },
+  // Built already; nothing to compile in the published tree.
+  scripts: { postinstall: pkg.scripts.postinstall },
+};
+delete trail.devDependencies;
+
+rmSync(out, { recursive: true, force: true });
+mkdirSync(out, { recursive: true });
+for (const f of pkg.files) {
+  const from = join(root, f);
+  if (existsSync(from)) cpSync(from, join(out, f), { recursive: true });
+}
+writeFileSync(join(out, 'package.json'), JSON.stringify(trail, null, 2) + '\n');
+console.log(`✓ ${trail.name}@${trail.version} laid out in ${out}`);
+console.log('  publish it with: npm publish build/trail --access public');

package/scripts/postinstall.mjs

@@ -0,0 +1,65 @@
+// Prints a one-line nudge after install, and records the anonymous `install`
+// event. Never fails the install.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// The same code ships as `trail-code` (the `trail` command, this fork) as
+// `@trailhq/trail-code` (the same command, upstream) and as @nanonets/graft
+// (`graft`, its old name). The install event and the nudge say which one this is.
+let pkgName = '@nanonets/graft';
+try {
+  pkgName = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name ?? pkgName;
+} catch { /* the graft defaults */ }
+const isTrail = pkgName === 'trail-code' || pkgName === '@trailhq/trail-code';
+if (isTrail) process.env.TRAIL_INVOKED_AS = 'trail';
+
+/**
+ * Record the install, then hand the queue straight to a detached child.
+ *
+ * Sending here rather than letting the daily flush pick it up is the entire
+ * point of the event: the machine we most want to count is the one that installs
+ * graft and never runs a command, and that machine never reaches a flush. The
+ * child is detached with stdio ignored, so npm waits on no socket and an offline
+ * install looks like any other.
+ *
+ * Every gate still applies — a fork or a local build has no key, and CI,
+ * `DO_NOT_TRACK` and `graft telemetry disable` all close it. See TELEMETRY.md.
+ */
+async function recordInstall() {
+  // `dist/` is absent when this runs from a clone, where `prepare` builds AFTER
+  // postinstall. Nothing to record there, and a fork has no key regardless.
+  const entry = join(root, 'dist', 'telemetry', 'index.js');
+  const cli = join(root, 'dist', 'cli.js');
+  if (!existsSync(entry) || !existsSync(cli)) return;
+  const mod = await import(pathToFileURL(entry).href);
+  // A `dist/` from an older version has no such export. Absent, not broken.
+  if (typeof mod.trackInstallIfNew !== 'function') return;
+  // npm sets this for `npm i -g`; only its value 'true' means global.
+  mod.trackInstallIfNew({ global: process.env.npm_config_global === 'true' });
+  const child = spawn(process.execPath, [cli, '_telemetry-flush'], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+}
+
+try {
+  if (process.env.CI) process.exit(0);
+  const dir = process.env.INIT_CWD || process.cwd();
+  // Its own catch: the nudge is the part a user sees, and a telemetry fault must
+  // not be able to silence it.
+  try { await recordInstall(); } catch { /* telemetry is never worth an error */ }
+  if (existsSync(join(dir, '.claude', 'helpers', 'graft-statusline.cjs'))) process.exit(0);
+  if (existsSync(join(dir, '.claude', 'helpers', 'trail-statusline.cjs'))) process.exit(0);
+  console.log(
+    isTrail
+      ? '\n  Trail installed. Run `trail init` in a repo to wire it into your agents.\n'
+      : '\n  Graft installed. Run `npx graft init` to enable the Claude Code integration (statusline + hooks + auto-sync).\n',
+  );
+} catch {
+  /* never fail an install */
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,72 @@
+/**
+ * Runs the test suite without depending on shell glob expansion.
+ *
+ * `node --test test/*.test.ts` needs the *shell* to expand that glob, and on
+ * Windows nothing does: npm runs scripts through `cmd.exe` regardless of the
+ * shell that invoked npm, and Node's `--test` only accepts glob patterns itself
+ * from Node 21 (this package supports >=20). The literal pattern reaches Node as
+ * a filename and it exits with `Could not find '…\test\*.test.ts'` — so the
+ * Windows CI leg reported failure while actually running zero tests.
+ *
+ * Enumerating the files here instead means `npm test` behaves identically in
+ * cmd.exe, PowerShell, bash and CI, on any supported Node.
+ */
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const testDir = join(repoRoot, "test");
+
+// Sorted so a failure is reported in the same order on every platform and run.
+const files = readdirSync(testDir)
+  .filter((f) => f.endsWith(".test.ts"))
+  .sort()
+  .map((f) => join(testDir, f));
+
+if (files.length === 0) {
+  console.error(`✗ no test files found in ${testDir}`);
+  process.exit(1);
+}
+
+// Several tests `git init` a scratch repo and `git commit` into it to exercise the
+// incremental/submodule/ingest git paths. Those commits inherit the developer's
+// global git config — so a contributor who signs commits (gpg, or gitsign, whose
+// x509 flow opens a browser for OIDC on EVERY commit) gets a signing storm from a
+// run that has nothing to do with their identity. Inject config via GIT_CONFIG_*
+// (git merges these over the user's config for this process tree only) so test
+// commits never sign, without touching anyone's global settings.
+const gitEnv = {
+  GIT_CONFIG_COUNT: "2",
+  GIT_CONFIG_KEY_0: "commit.gpgsign", GIT_CONFIG_VALUE_0: "false",
+  GIT_CONFIG_KEY_1: "tag.gpgsign", GIT_CONFIG_VALUE_1: "false",
+};
+
+// Tests make thousands of scratch repos and homes under the temp folder and
+// don't all remove them: a day of runs left over 50,000 folders (6 GB). Give the
+// run its own temp folder and remove it at the end, whatever the outcome.
+const runTmp = mkdtempSync(join(tmpdir(), "trail-test-run-"));
+const tmpEnv = { TMPDIR: runTmp, TEMP: runTmp, TMP: runTmp };
+
+// A graft repo moves to trail when a session opens on a machine with the trail
+// command, so a contributor who has trail installed would see test repos move.
+// Off for the run; the tests of the move turn it back on.
+const result = spawnSync(process.execPath, ["--import", "tsx", "--test", ...files], {
+  cwd: repoRoot,
+  stdio: "inherit",
+  env: { ...process.env, ...gitEnv, ...tmpEnv, GRAFT_NO_TRAIL_SWITCH: "1" },
+});
+try {
+  rmSync(runTmp, { recursive: true, force: true });
+} catch {
+  /* best effort: a locked file on Windows must not fail the run */
+}
+
+if (result.error) {
+  console.error(`✗ could not start the test runner: ${result.error.message}`);
+  process.exit(1);
+}
+// A signal-killed run reports null status; treat anything non-zero as failure.
+process.exit(result.status ?? 1);

package/scripts/stamp-telemetry-key.mjs

@@ -0,0 +1,56 @@
+/**
+ * Bakes the PostHog key into the built `dist/telemetry/key.js` at publish time.
+ *
+ * This is what makes "forks never send" true by construction rather than by
+ * policy. The key exists only in the published tarball: the repository holds an
+ * empty string, so a clone, a fork, a CI build, and a contributor's local
+ * `npm run build` all produce a graft whose telemetry module short-circuits on
+ * the very first check.
+ *
+ * Runs from `prepare`, after `npm run build`. Without GRAFT_POSTHOG_KEY in the
+ * environment it changes nothing, and warns only when npm is packing or
+ * publishing — publishing a telemetry-less build is a valid thing to do, and it
+ * must never be a hard failure at the moment someone is trying to ship.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const target = join(root, 'dist', 'telemetry', 'key.js');
+
+const key = process.env.GRAFT_POSTHOG_KEY ?? '';
+const host = process.env.GRAFT_POSTHOG_HOST ?? '';
+
+if (!key) {
+  // `prepare` also runs on every `npm install` in a clone, where no key is expected.
+  if (['publish', 'pack'].includes(process.env.npm_command ?? '')) {
+    console.warn('⚠ GRAFT_POSTHOG_KEY not set — publishing a build that sends no telemetry.');
+  }
+  process.exit(0);
+}
+if (!existsSync(target)) {
+  console.warn(`⚠ ${target} not found — did the build run? Skipping the telemetry key stamp.`);
+  process.exit(0);
+}
+// A key with a quote or a newline in it would break the generated literal (and
+// is not a PostHog key). Refuse rather than emit something that won't parse.
+if (!/^[A-Za-z0-9_-]+$/.test(key)) {
+  console.error('✗ GRAFT_POSTHOG_KEY contains characters that are not valid in a project key.');
+  process.exit(1);
+}
+if (host && !/^https:\/\/[A-Za-z0-9.-]+(:\d+)?$/.test(host)) {
+  console.error('✗ GRAFT_POSTHOG_HOST must be a plain https origin, e.g. https://eu.i.posthog.com');
+  process.exit(1);
+}
+
+const src = readFileSync(target, 'utf8');
+let out = src.replace(/const BAKED_KEY = ['"][^'"]*['"];/, `const BAKED_KEY = '${key}';`);
+if (host) out = out.replace(/const BAKED_HOST = ['"][^'"]*['"];/, `const BAKED_HOST = '${host}';`);
+
+if (out === src) {
+  console.error('✗ could not find BAKED_KEY in dist/telemetry/key.js — the stamp target moved.');
+  process.exit(1);
+}
+writeFileSync(target, out);
+console.log(`✓ telemetry key stamped into dist/telemetry/key.js${host ? ` (host ${host})` : ''}`);

package/scripts/tally-audit.mjs

@@ -0,0 +1,140 @@
+/**
+ * "Saved vs said": how often does the agent actually TELL the user what graft saved?
+ *
+ *   node scripts/tally-audit.mjs [transcript-dir] [--json]
+ *
+ * `savedTokens` (src/claude/state.ts) counts what graft *computed* — every
+ * `[graft] tokens saved ≈ N` footer the PostToolUse accumulator swept up. This
+ * script measures the other half, offline and in full detail: of the turns that
+ * used graft, how many closed with the one-line tally SKILL.md asks for, was the
+ * number right, and did it name the call count.
+ *
+ * The shipped metric (`graft_turns_bucket` / `reported_turns_bucket` on
+ * `session_summary`) is the same ratio at bucket resolution, which is all that
+ * can cross the wire. Run this locally when the aggregate says something
+ * surprising and you need to see which turns and why.
+ *
+ * Reads Claude Code's own transcript JSONL, which defaults to
+ * ~/.claude/projects/<slugified-cwd>/. Nothing leaves the machine.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const SAVED_FOOTER = /\[graft\] tokens saved ≈ ([\d,]+)/g;
+const TALLY = /graft\s+saved\s*[~≈]?\s*([\d,.]+)\s*(k|m)?\s*(?:tok|tokens)/i;
+const CALLS = /(\d+)\s*calls?/i;
+/** How far past the tally to look for its call count. The tally is one line
+ * ("🌱 graft saved ~12,400 tokens this turn (3 calls)"); scanning the rest of
+ * the reply instead would match any unrelated "3 calls" further down and report
+ * near-perfect compliance for a field the agent mostly omits. */
+const TALLY_WINDOW = 60;
+/** Above this, a per-turn "saved" figure is an estimator artifact rather than a
+ * saving — a `--depth all` closure or a vendored tree summing whole-file
+ * baselines nobody would have read. Reported separately, never averaged in. */
+const IMPLAUSIBLE_TOKENS = 1_000_000;
+
+const args = process.argv.slice(2).filter((a) => a !== "--json");
+const asJson = process.argv.includes("--json");
+const dir = args[0] ?? defaultTranscriptDir();
+
+function defaultTranscriptDir() {
+  const slug = process.cwd().replace(/[/.]/g, "-");
+  return join(homedir(), ".claude", "projects", slug);
+}
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((p) => (p?.type === "text" ? p.text ?? "" : "")).join("\n");
+}
+function isUserPrompt(o) {
+  if (o.type !== "user" || o.isSidechain || o.isMeta) return false;
+  const c = o.message?.content;
+  if (typeof c === "string") return true;
+  return Array.isArray(c) && !c.some((p) => p?.type === "tool_result");
+}
+function median(ns) {
+  if (!ns.length) return 0;
+  const s = [...ns].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 ? s[mid] : Math.round((s[mid - 1] + s[mid]) / 2);
+}
+
+if (!existsSync(dir)) {
+  console.error(`no transcripts at ${dir}`);
+  process.exit(1);
+}
+
+const turns = [];
+for (const file of readdirSync(dir).filter((f) => f.endsWith(".jsonl"))) {
+  let turn = null;
+  const flush = () => { if (turn?.calls > 0) turns.push(turn); };
+  for (const line of readFileSync(join(dir, file), "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (o.isSidechain) continue;                    // a subagent's prose is not what the user read
+    if (isUserPrompt(o)) { flush(); turn = { file, calls: 0, saved: 0, said: null, statedCalls: null }; continue; }
+    if (!turn) continue;
+    if (o.type === "user") {                        // a tool_result wearing the user role
+      for (const m of JSON.stringify(o.message?.content ?? "").matchAll(SAVED_FOOTER)) {
+        turn.calls++;
+        turn.saved += Number(m[1].replace(/,/g, "")) || 0;
+      }
+    }
+    if (o.type === "assistant") {
+      const m = TALLY.exec(textOf(o.message?.content));
+      if (m) {
+        let n = Number(m[1].replace(/,/g, ""));
+        if (m[2]?.toLowerCase() === "k") n *= 1e3;
+        if (m[2]?.toLowerCase() === "m") n *= 1e6;
+        turn.said = n;
+        const c = CALLS.exec(textOf(o.message?.content).slice(m.index, m.index + TALLY_WINDOW));
+        turn.statedCalls = c ? Number(c[1]) : null;
+      }
+    }
+  }
+  flush();
+}
+
+const said = turns.filter((t) => t.said !== null);
+const plausible = turns.filter((t) => t.saved < IMPLAUSIBLE_TOKENS);
+const outliers = turns.filter((t) => t.saved >= IMPLAUSIBLE_TOKENS);
+const fidelity = { exact: 0, over: 0, under: 0 };
+for (const t of said.filter((t) => t.saved > 0)) {
+  const r = t.said / t.saved;
+  if (r >= 0.9 && r <= 1.1) fidelity.exact++;
+  else if (r > 1.1) fidelity.over++;
+  else fidelity.under++;
+}
+
+const report = {
+  transcripts: readdirSync(dir).filter((f) => f.endsWith(".jsonl")).length,
+  graft_turns: turns.length,
+  reported: said.length,
+  silent: turns.length - said.length,
+  reported_pct: turns.length ? Number(((said.length / turns.length) * 100).toFixed(1)) : 0,
+  stated_call_count: said.filter((t) => t.statedCalls !== null).length,
+  median_saved_per_turn: median(plausible.map((t) => t.saved)),
+  fidelity,
+  implausible_turns: outliers.length,
+  implausible_max: outliers.length ? Math.max(...outliers.map((t) => t.saved)) : 0,
+};
+
+if (asJson) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  const { graft_turns: n } = report;
+  console.log(`transcripts scanned:      ${report.transcripts}  (${dir})`);
+  console.log(`turns that used graft:    ${n}`);
+  console.log(`  ...reported a tally:    ${report.reported}  (${report.reported_pct}%)`);
+  console.log(`  ...silent:              ${report.silent}`);
+  console.log(`  ...named the call count ${report.stated_call_count}/${report.reported}`);
+  console.log(`median saved per turn:    ${report.median_saved_per_turn.toLocaleString()} tok`);
+  console.log(`reported number vs footer sum (±10%): exact ${fidelity.exact} · over ${fidelity.over} · under ${fidelity.under}`);
+  if (outliers.length) {
+    console.log(`\n⚠ ${outliers.length} turn(s) claim ≥${IMPLAUSIBLE_TOKENS.toLocaleString()} tokens saved ` +
+      `(max ${report.implausible_max.toLocaleString()}) — an estimator artifact, excluded from the median. ` +
+      `See savingsFor() in src/context/savings.ts.`);
+  }
+}

package/scripts/vendor-grammars.mjs

@@ -0,0 +1,53 @@
+/**
+ * Copies the depth tier's WASM grammars into dist/vendor/grammars/. Runs as part
+ * of `npm run build`; src/graph/depth-parser.ts loads them from there.
+ *
+ * The grammar packages are dev dependencies only. As dependencies they were native
+ * addons, and installing the package compiled C wherever one had no prebuilt
+ * binary (tree-sitter-kotlin has none at all). What the depth tier needs from each
+ * is one .wasm: the package's own where it ships one, else the one
+ * scripts/build-grammar-wasm.mjs compiled from its source into src/graph/grammars/.
+ * Each grammar's license comes along.
+ *
+ * Usage: node scripts/vendor-grammars.mjs [outDir]   (default dist/vendor)
+ */
+import { copyFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const vendorDir = resolve(process.argv[2] ?? join(root, "dist", "vendor"));
+const outDir = join(vendorDir, "grammars");
+const require = createRequire(join(root, "package.json"));
+
+/** Mirrors DEPTH_WASM in src/graph/depth-parser.ts, which a test holds this to. */
+export const GRAMMARS = [
+  { module: "tree-sitter-typescript", files: ["tree-sitter-typescript.wasm", "tree-sitter-tsx.wasm"] },
+  { module: "tree-sitter-python", files: ["tree-sitter-python.wasm"], built: true },
+  { module: "tree-sitter-go", files: ["tree-sitter-go.wasm"] },
+  { module: "tree-sitter-r", files: ["tree-sitter-r.wasm"] },
+  { module: "tree-sitter-java", files: ["tree-sitter-java.wasm"] },
+  { module: "tree-sitter-kotlin", files: ["tree-sitter-kotlin.wasm"], built: true },
+  { module: "tree-sitter-swift", files: ["tree-sitter-swift.wasm"], built: true },
+  { module: "tree-sitter-php", files: ["tree-sitter-php.wasm"] },
+];
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  rmSync(outDir, { recursive: true, force: true });
+  // Where earlier builds put the native tree-sitter-swift binaries: a dist/ built
+  // before would otherwise keep them, and pack them.
+  rmSync(join(vendorDir, "tree-sitter-swift"), { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  for (const { module, files, built } of GRAMMARS) {
+    const pkg = dirname(require.resolve(`${module}/package.json`));
+    const { version } = require(`${module}/package.json`);
+    for (const file of files) {
+      const from = built ? join(root, "src", "graph", "grammars", file) : join(pkg, file);
+      if (!existsSync(from)) throw new Error(`${module}@${version}: ${from} is missing`);
+      copyFileSync(from, join(outDir, file));
+    }
+    copyFileSync(join(pkg, "LICENSE"), join(outDir, `${module}.LICENSE`));
+  }
+  console.log(`vendored grammars → ${outDir} (${GRAMMARS.flatMap((g) => g.files).length} wasm)`);
+}