replay-doctor 0.6.0

package/README.md

@@ -0,0 +1,21 @@
+# replay-doctor (npm shim)
+
+```sh
+npx replay-doctor diff ~/.claude/projects/
+```
+
+Replay Doctor names the turn your prompt cache broke on and what it cost. It reads the transcripts your coding agent already keeps on disk; nothing leaves your machine.
+
+npm installs the one platform package that matches your machine (`@replay-doctor/darwin-arm64`, `linux-x64`, and so on, pinned to this exact version as optional dependencies), so the binary arrives through npm with the lockfile's integrity hash and provenance covering it. No postinstall script, no network at run time. If the platform package is missing (`--no-optional`), the launcher says so and stops; it does not fetch anything unless you tell it to (below). The package version and the binary version are the same tag. macOS and Linux, amd64 and arm64.
+
+## `REPLAY_DOCTOR_ALLOW_FETCH`
+
+The launcher goes to the network only when this variable is exactly `1`:
+
+```sh
+REPLAY_DOCTOR_ALLOW_FETCH=1 npx replay-doctor version
+```
+
+With it set, a missing platform package makes the launcher fetch the release tarball for your platform from the GitHub release that matches the package version, verify its sha256 against the release's `checksums.txt`, cache it once per version, and run it. Any other value, or no value, is a refusal: the launcher exits non-zero and prints the package it could not find, this variable, and the two other routes to the same binary, `go install github.com/RedRobotKK/Replay/cmd/replay@latest` and the release page at <https://github.com/RedRobotKK/Replay/releases>.
+
+Documentation, the other install routes and the signature check: <https://replay.doctor/install/>

package/bin/replay-doctor.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * npx replay-doctor <args>
+ *
+ * Resolves the binary from the platform package npm installed alongside this
+ * one (@replay-doctor/<os>-<cpu>, an optionalDependency pinned to this exact
+ * version) and execs it. That is the whole path for a normal install: no
+ * network, no postinstall, the lockfile's integrity hash covers the binary.
+ *
+ * When the platform package is absent (--no-optional, an unusual installer, a
+ * mirror that dropped it) the launcher stops and says so on stderr. It fetches
+ * the goreleaser tarball for this version from the GitHub release, verifies it
+ * against checksums.txt, caches it and execs that only when the environment
+ * variable REPLAY_DOCTOR_ALLOW_FETCH is exactly "1". A run that went to the
+ * network on its own would be a different promise than the one on the package
+ * page, so the network needs the user's word first (PRD E6).
+ */
+import { createReadStream, existsSync, mkdirSync, renameSync, rmSync, writeFileSync, chmodSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync, spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { target, archiveName, assetURL, expectedHash, releaseVersion } from '../lib/release.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+const version = releaseVersion(pkg.version);
+const require = createRequire(import.meta.url);
+
+function fromPlatformPackage() {
+  const t = target();
+  if (!t) return null;
+  const name = `@replay-doctor/${process.platform}-${process.arch}`;
+  try {
+    const p = join(dirname(require.resolve(`${name}/package.json`)), 'bin', 'replay');
+    return existsSync(p) ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+function cacheDir() {
+  if (process.env.REPLAY_DOCTOR_CACHE) return process.env.REPLAY_DOCTOR_CACHE;
+  if (process.env.XDG_CACHE_HOME) return join(process.env.XDG_CACHE_HOME, 'replay-doctor');
+  return process.platform === 'darwin' ? join(homedir(), 'Library', 'Caches', 'replay-doctor') : join(homedir(), '.cache', 'replay-doctor');
+}
+
+async function sha256(path) {
+  return new Promise((resolve, reject) => {
+    const h = createHash('sha256');
+    createReadStream(path).on('data', (d) => h.update(d)).on('end', () => resolve(h.digest('hex'))).on('error', reject);
+  });
+}
+
+async function download(url, to) {
+  const r = await fetch(url, { headers: { 'user-agent': `replay-doctor npm shim ${version}` } });
+  if (!r.ok) throw new Error(`${r.status} fetching ${url}`);
+  writeFileSync(to, Buffer.from(await r.arrayBuffer()));
+}
+
+async function fromRelease() {
+  const t = target();
+  if (!t) {
+    console.error(`replay-doctor: ${process.platform}/${process.arch} is not supported. macOS and Linux on amd64 and arm64 are; Windows is not.`);
+    process.exit(2);
+  }
+  const dir = join(cacheDir(), version, `${t.os}_${t.cpu}`);
+  const bin = join(dir, 'replay');
+  if (existsSync(bin)) return bin;
+  const name = archiveName(version, t);
+  const work = join(tmpdir(), `replay-doctor-${process.pid}`);
+  mkdirSync(work, { recursive: true });
+  try {
+    console.error(`replay-doctor: the platform package @replay-doctor/${process.platform}-${process.arch} is not installed; fetching ${name} from the v${version} release instead (once per version)`);
+    await download(assetURL(version, name), join(work, name));
+    await download(assetURL(version, 'checksums.txt'), join(work, 'checksums.txt'));
+    const want = expectedHash(readFileSync(join(work, 'checksums.txt'), 'utf8'), name);
+    if (!want) throw new Error(`${name} is not listed in checksums.txt for v${version}`);
+    const got = await sha256(join(work, name));
+    if (got !== want) throw new Error(`sha256 mismatch for ${name}: release says ${want}, downloaded ${got}. Nothing was installed.`);
+    mkdirSync(dir, { recursive: true });
+    execFileSync('tar', ['-xzf', join(work, name), '-C', work, 'replay']);
+    chmodSync(join(work, 'replay'), 0o755);
+    renameSync(join(work, 'replay'), bin);
+    console.error(`replay-doctor: verified against checksums.txt (sha256 ${want.slice(0, 12)}). Signature check: https://replay.doctor/install/`);
+    return bin;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+function refuseFetch() {
+  const t = target();
+  if (!t) {
+    console.error(`replay-doctor: ${process.platform}/${process.arch} is not supported. macOS and Linux on amd64 and arm64 are; Windows is not.`);
+    process.exit(2);
+  }
+  const name = `@replay-doctor/${process.platform}-${process.arch}`;
+  console.error(
+    `replay-doctor: the platform package ${name} is not installed, and this launcher does not go to the network on its own.\n` +
+    `  Reinstall without --no-optional so npm brings in ${name}, or take one of these:\n` +
+    `    REPLAY_DOCTOR_ALLOW_FETCH=1 npx replay-doctor ...   fetches ${archiveName(version, t)} from the v${version} GitHub release, verified against its checksums.txt\n` +
+    `    go install github.com/RedRobotKK/Replay/cmd/replay@latest\n` +
+    `  Release page: https://github.com/RedRobotKK/Replay/releases/tag/v${version}`
+  );
+  process.exit(2);
+}
+
+const bin = fromPlatformPackage() || (process.env.REPLAY_DOCTOR_ALLOW_FETCH === '1' ? await fromRelease() : refuseFetch());
+const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' });
+child.on('exit', (code, signal) => { if (signal) process.kill(process.pid, signal); else process.exit(code ?? 1); });

package/lib/release.mjs

@@ -0,0 +1,58 @@
+/**
+ * Pure helpers for the npm shim, kept apart from the launcher so they can be
+ * tested without touching the network or the filesystem.
+ *
+ * The shim does one thing: fetch the goreleaser tarball for this platform from
+ * the GitHub release that matches the package version, verify its sha256
+ * against the release's checksums.txt, unpack it once into a cache, and exec
+ * the binary. The package itself contains no binary, so `npm install` is
+ * instant and the bytes that run are the bytes the release signed. The
+ * checksums file is the same one cosign signs; the shim verifies the hash and
+ * tells you how to verify the signature, because sigstore in Node would be a
+ * second implementation of the thing the installer already does.
+ */
+export const REPO = 'RedRobotKK/Replay';
+
+/** Map Node's platform/arch to goreleaser's names. Returns null when unsupported. */
+export function target(platform = process.platform, arch = process.arch) {
+  const os = { darwin: 'darwin', linux: 'linux' }[platform];
+  const cpu = { x64: 'amd64', arm64: 'arm64' }[arch];
+  if (!os || !cpu) return null;
+  return { os, cpu };
+}
+
+/** The tarball name goreleaser produced for a version and target. */
+export function archiveName(version, t) {
+  return `replay_${version}_${t.os}_${t.cpu}.tar.gz`;
+}
+
+export function assetURL(version, name) {
+  return `https://github.com/${REPO}/releases/download/v${version}/${name}`;
+}
+
+/** Find the expected sha256 for a file in checksums.txt (goreleaser's "hash  name" lines). */
+export function expectedHash(checksums, name) {
+  for (const line of checksums.split('\n')) {
+    const m = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/);
+    if (m && m[2] === name) return m[1];
+  }
+  return null;
+}
+
+/**
+ * The version the launcher will fetch, which must be a real release tag.
+ *
+ * The checked-in package.json carries a placeholder that the publish workflow
+ * replaces from the tag. A prefix match let "0.0.0-set-by-release-workflow"
+ * through as 0.0.0, which would have sent a launcher run from the repository
+ * to fetch a release that does not exist. Whole-string semver, with an
+ * optional pre-release suffix for release candidates, and the placeholder is
+ * refused by name.
+ */
+export function releaseVersion(pkgVersion) {
+  const v = String(pkgVersion || '');
+  if (v.includes('set-by-release-workflow') || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$/.test(v)) {
+    throw new Error(`package version "${v}" is not a released version; the publish workflow sets it from the tag`);
+  }
+  return v;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "replay-doctor",
+  "version": "0.6.0",
+  "description": "Replay Doctor: names the turn your prompt cache broke on and what it cost. This package fetches the signed release binary for your platform, verifies it against checksums.txt, and runs it. macOS and Linux.",
+  "license": "BUSL-1.1",
+  "homepage": "https://replay.doctor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RedRobotKK/Replay.git",
+    "directory": "packaging/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/RedRobotKK/Replay/issues"
+  },
+  "keywords": [
+    "prompt-cache",
+    "claude-code",
+    "codex",
+    "coding-agent",
+    "token-cost",
+    "cache-break",
+    "llm-observability"
+  ],
+  "type": "module",
+  "bin": {
+    "replay-doctor": "bin/replay-doctor.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@replay-doctor/darwin-x64": "0.6.0",
+    "@replay-doctor/darwin-arm64": "0.6.0",
+    "@replay-doctor/linux-x64": "0.6.0",
+    "@replay-doctor/linux-arm64": "0.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "scripts": {
+    "test": "node --test test.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}