@autor3search/javascript 0.2.0

package/src/state/index.js

@@ -0,0 +1,312 @@
+/**
+ * Persists a run's reference points OUT-OF-TREE from the repository being
+ * optimized.
+ *
+ * None of this may live inside the repository. The agent edits the
+ * repository, so in-tree state would be silently writable by the very agent
+ * it constrains: it could rewrite a frozen golden copy, drop a key from the
+ * manifest, or — worst — edit the pinned baseline WORKTREE to make the
+ * BASELINE slow, after which every candidate "improves" and every experiment
+ * returns KEEP without optimizing anything.
+ */
+import { createHash } from 'node:crypto'
+import { lstat, mkdir, readFile, realpath, symlink, writeFile } from 'node:fs/promises'
+import { homedir, platform } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+/** Per-repository state directory name under the user cache. */
+export const STATE_DIR_NAME = 'autor3search-javascript'
+
+/** Environment variable relocating every run's out-of-tree state. */
+export const STATE_HOME_ENV = 'AUTOR3SEARCH_JAVASCRIPT_STATE_HOME'
+
+/** Paths within a run's state directory. */
+export const BASELINE_FILE = 'baseline.json'
+export const WORKTREE_NAME = 'baseline-worktree'
+
+/** Run branches are named `<prefix><tag>`. */
+export const BRANCH_PREFIX = 'autor3search-javascript/'
+
+/**
+ * Mode for every directory the harness creates under the state home.
+ *
+ * The state home holds the frozen store and its manifest — the two things the
+ * score is defined against — so it is the one place outside the repository
+ * where write access is equivalent to control of the verdict. Under the
+ * default home (~/Library/Caches, ~/.cache) the parent already restricts
+ * access, but AUTOR3SEARCH_JAVASCRIPT_STATE_HOME may point anywhere,
+ * including a shared directory.
+ */
+export const DIR_MODE = 0o700
+
+/**
+ * The strict allow-list for a run tag: letters, digits, '.', '_' and '-'.
+ *
+ * Notably absent is '/' — or any other path separator — which alone blocks
+ * both directory traversal ("../../etc") and an absolute path
+ * ("/etc/passwd"), because a tag can then never be more than one path
+ * segment. stateDir joins the tag into a filesystem path and callers mkdir
+ * that path immediately, long before git's own ref-name rules would get a
+ * chance to reject a bad tag.
+ */
+const VALID_TAG = /^[A-Za-z0-9._-]+$/
+
+/**
+ * Reports whether tag is safe to use as a filesystem path segment.
+ *
+ * "." and ".." are rejected even though both characters are individually
+ * allowed: either one alone means "this directory" or "the parent directory"
+ * rather than naming anything.
+ *
+ * @param {string} tag
+ * @throws {Error}
+ */
+export function validTag(tag) {
+  if (!tag) throw new Error('tag must not be empty')
+  if (tag === '.' || tag === '..') {
+    throw new Error(`tag ${JSON.stringify(tag)} is not allowed: it is a directory reference, not a run identifier`)
+  }
+  if (!VALID_TAG.test(tag)) {
+    throw new Error(
+      `tag ${JSON.stringify(tag)} is not allowed: tags may contain only letters, digits, '.', '_' and '-'`,
+    )
+  }
+}
+
+/**
+ * The out-of-tree directory holding every piece of state the metric depends
+ * on, for one repository and run tag.
+ *
+ * Keyed by a hash of the repository's real absolute path, so two checkouts of
+ * the same project never share state and the same checkout reached by two
+ * spellings resolves to one key.
+ *
+ * @param {string} repoRoot
+ * @param {string} tag
+ * @returns {Promise<string>}
+ */
+export async function stateDir(repoRoot, tag) {
+  validTag(tag)
+  let absolute = resolve(repoRoot)
+  // Resolve symlinked ancestors (macOS's /tmp -> /private/tmp, for one) so the
+  // same repository reached by two different spellings hashes the same. A
+  // path that does not exist yet falls back to the unresolved form rather
+  // than failing.
+  absolute = await realpath(absolute).catch(() => absolute)
+  const key = createHash('sha256').update(absolute).digest('hex').slice(0, 16)
+  return join(await stateHome(), key, tag)
+}
+
+/**
+ * The directory holding every repository's run state.
+ *
+ * A relative override is REFUSED rather than resolved. Joining one would
+ * succeed, but the result would then depend on the working directory each
+ * command was invoked from — so `eval` run from a subdirectory and `stop` run
+ * from the repository root would address different state for the same run,
+ * and the brake would silently miss.
+ */
+async function stateHome() {
+  const override = process.env[STATE_HOME_ENV]
+  if (override) {
+    if (!isAbsolute(override)) {
+      throw new Error(
+        `${STATE_HOME_ENV} must be an absolute path, got ${JSON.stringify(override)}: a relative state ` +
+          `home would resolve differently depending on where each command is run from`,
+      )
+    }
+    return override
+  }
+  return join(userCacheDir(), STATE_DIR_NAME)
+}
+
+/** The conventional per-platform user cache directory. */
+function userCacheDir() {
+  if (process.env.XDG_CACHE_HOME && isAbsolute(process.env.XDG_CACHE_HOME)) {
+    return process.env.XDG_CACHE_HOME
+  }
+  if (platform() === 'darwin') return join(homedir(), 'Library', 'Caches')
+  if (platform() === 'win32') return process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local')
+  return join(homedir(), '.cache')
+}
+
+/**
+ * Symlinks the repository's own `node_modules` into a pinned worktree, so a
+ * bench runner spawned inside it can resolve its own binary and the
+ * project's dependencies.
+ *
+ * Lives here, next to WORKTREE_NAME and the worktree-tamper check above,
+ * because this module is already the one concerned with the pinned
+ * worktree's identity and integrity — this is a third worktree-lifecycle
+ * concern, not a new one, even though (unlike the rest of this file) it
+ * touches the filesystem rather than a JSON record.
+ *
+ * A `git worktree add` checks out only TRACKED files, and virtually every
+ * real project gitignores `node_modules` — so a freshly created worktree
+ * has none, and the baseline side of every measurement would otherwise fail
+ * outright the moment the bench runner tries to resolve itself (see
+ * src/adapters/bench/vitest.js's `vitestBin`). Symlinking the real
+ * `node_modules` in is the fix: both worktree and repository root then
+ * resolve the exact same installed packages.
+ *
+ * No-op, and NEVER throws, when: the repository has no `node_modules` (a
+ * repo with no dependencies — nothing to link); the worktree already has an
+ * entry there (a previous call already linked it, or something else put a
+ * real install there — either way, leave it alone); or the link attempt
+ * itself fails for some other filesystem reason. Called from both
+ * `cmd-baseline.js` (right after the worktree is created) and
+ * `src/pipeline.js` (before every measurement), so a worktree that loses the
+ * link — the target moved, the link was removed — self-heals on the very
+ * next eval rather than failing every run after the first.
+ *
+ * @param {string} repoRoot
+ * @param {string} worktreeDir
+ * @returns {Promise<void>}
+ */
+export async function linkNodeModules(repoRoot, worktreeDir) {
+  const repoModules = join(repoRoot, 'node_modules')
+  const worktreeModules = join(worktreeDir, 'node_modules')
+  try {
+    await lstat(repoModules)
+  } catch {
+    return // the repository has no node_modules: nothing to link
+  }
+  try {
+    await lstat(worktreeModules)
+    return // the worktree already has an entry there: leave it alone
+  } catch {
+    // does not exist yet — fall through and create the link
+  }
+  try {
+    await symlink(repoModules, worktreeModules, 'dir')
+  } catch {
+    // Best-effort only. A transient permission or filesystem error here must
+    // not sink an experiment that may not even need node_modules (a repo
+    // that vendors its dependencies, for instance) — the bench runner will
+    // report its own, more specific failure if resolution still fails.
+  }
+}
+
+/**
+ * Creates a state directory and refuses to use one that other users can write.
+ *
+ * mkdir's `mode` applies only to directories it actually CREATES, so a
+ * directory that was already there keeps whatever owner and mode it had. That
+ * is the case worth checking: under a shared state home someone else can
+ * pre-create the run directory, and then swapping the frozen store and its
+ * manifest together — consistently, so the hash check still passes — puts
+ * their content into the test files that `restore` writes back before every
+ * evaluation.
+ *
+ * Every level from the state home down is checked, not just the leaf: owning
+ * the parent is enough to replace the child. Ancestors ABOVE the state home
+ * are deliberately not checked — a 0700 home inside a sticky /tmp is fine, and
+ * walking to / would fail on every ordinary machine.
+ *
+ * POSIX only. Windows reports synthetic mode bits and has no getuid, so the
+ * check is skipped there rather than made to look like it ran.
+ *
+ * @param {string} dir a directory at or below the state home
+ * @returns {Promise<string>} dir
+ */
+export async function ensureSecureDir(dir) {
+  await mkdir(dir, { recursive: true, mode: DIR_MODE })
+  if (typeof process.getuid !== 'function') return dir
+
+  // Walk up by path segment, never by string prefix: "/tmp/state" is a prefix
+  // of "/tmp/state-evil" but not its parent.
+  const home = resolve(await stateHome())
+  const levels = []
+  for (let cur = resolve(dir); ; cur = dirname(cur)) {
+    levels.push(cur)
+    if (cur === home || cur === dirname(cur)) break
+  }
+  // A caller that passed something outside the state home walked to the root
+  // instead of stopping at it; check only what it named.
+  if (levels[levels.length - 1] !== home) levels.length = 1
+
+  for (const level of levels) {
+    const st = await lstat(level)
+    if (st.uid !== process.getuid()) {
+      throw new Error(
+        `refusing to use ${level}: it is owned by uid ${st.uid}, not by you (uid ${process.getuid()}). ` +
+          `Whoever owns this directory controls the frozen benchmarks the score is measured against.`,
+      )
+    }
+    if ((st.mode & 0o022) !== 0) {
+      throw new Error(
+        `refusing to use ${level}: mode ${(st.mode & 0o777).toString(8)} lets other users write to it. ` +
+          `Whoever can write here can replace the frozen benchmarks the score is measured against. ` +
+          `Run: chmod 700 ${JSON.stringify(level)}`,
+      )
+    }
+  }
+  return dir
+}
+
+/**
+ * @typedef {object} Baseline
+ * @property {string} tag human-chosen run identifier
+ * @property {string} branch run branch checked out when the baseline was recorded
+ * @property {string} commit the FROZEN anchor — never changes after `baseline` records it
+ * @property {string} measureCommit the ADVANCING pointer the pinned worktree tracks
+ * @property {string} createdAt ISO-8601, UTC
+ * @property {string[]} benchmarks the declared benchmark set
+ * @property {string} pattern the name filter derived from benchmarks
+ * @property {string} configSha256 hash of the in-repo config at baseline time
+ */
+
+/** Writes the baseline as indented JSON, creating parent directories. */
+export async function saveBaseline(path, baseline) {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(baseline, null, 2)}\n`)
+}
+
+/**
+ * Reads a baseline written by saveBaseline.
+ *
+ * A record written before measureCommit existed has no such field; it falls
+ * back to commit — exactly the value a fresh baseline starts it at — rather
+ * than staying undefined, which would fail the worktree integrity check on
+ * the very first eval of an older run.
+ *
+ * @returns {Promise<Baseline>}
+ */
+export async function loadBaseline(path) {
+  let text
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`no baseline at ${path}: run 'autor3search-javascript baseline' first`, { cause: err })
+    }
+    throw new Error(`read baseline ${path}: ${err.message}`, { cause: err })
+  }
+  let record
+  try {
+    record = JSON.parse(text)
+  } catch (err) {
+    throw new Error(`parse baseline ${path}: ${err.message}`, { cause: err })
+  }
+  if (!record.measureCommit) record.measureCommit = record.commit
+  return record
+}
+
+/**
+ * Builds a name filter matching exactly these benchmarks. An empty list
+ * yields "." — every benchmark.
+ *
+ * Each name is regexp-escaped. Names found by src/discover.js need no
+ * escaping, but `benchmarks:` in config.yaml is documented as hand-editable,
+ * and a stray metacharacter in a hand-typed name would otherwise silently
+ * BROADEN the pattern to match benchmarks nobody selected.
+ *
+ * @param {string[]} names
+ * @returns {string}
+ */
+export function benchPattern(names) {
+  if (names.length === 0) return '.'
+  return `^(${names.map(escapeRegExp).join('|')})$`
+}
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')

package/src/state/lock.js

@@ -0,0 +1,189 @@
+/**
+ * The eval claim: at most one `eval` may run against a given run at a time.
+ *
+ * Two concurrent evals is itself a bug — they would fight over the same
+ * pinned worktree — so a claim that cannot be taken is reported as an error
+ * naming the incumbent pid rather than silently proceeding.
+ *
+ * Node has no flock binding, so the claim is an atomic mkdir of a lock
+ * directory holding the owner's pid and a heartbeat it refreshes. A lock is
+ * stale only when BOTH the pid is not alive AND the heartbeat has gone cold:
+ * pids are recycled, so liveness alone would eventually let one run steal
+ * another's claim, and a heartbeat alone would strand a lock whose owner was
+ * SIGKILLed.
+ */
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { ensureSecureDir } from './index.js'
+import { join } from 'node:path'
+
+export const LOCK_DIR = 'eval.lock'
+
+/** How often a live eval refreshes its heartbeat. */
+export const HEARTBEAT_MS = 5_000
+
+/** How cold a heartbeat must be before a dead owner's lock is reclaimed. */
+export const STALE_AFTER_MS = 30_000
+
+/**
+ * Claims the run in stateDir for this process.
+ *
+ * @param {string} stateDir
+ * @param {number} [pid]
+ * @returns {Promise<{release(): Promise<void>, touch(): Promise<void>}>}
+ * @throws {Error} when a live eval already holds the claim
+ */
+export async function claimEval(stateDir, pid = process.pid) {
+  await ensureSecureDir(stateDir)
+  const lockPath = join(stateDir, LOCK_DIR)
+
+  for (;;) {
+    try {
+      await mkdir(lockPath)
+      break
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+      const held = await readLock(lockPath)
+      if (!(await isStale(held, lockPath))) {
+        throw new Error(
+          `another autor3search-javascript eval (pid ${held.pid ?? 'unknown'}) is already running for this run`,
+        )
+      }
+      // Stale: the owner is gone and its heartbeat is cold. Take it over by
+      // removing the abandoned directory and retrying the atomic mkdir — this
+      // keeps two racing processes from both believing they won: only one
+      // mkdir can succeed per iteration, and a loser that lands here again
+      // rereads the (now fresh) lock and refuses like any other contender.
+      await rm(lockPath, { recursive: true, force: true }).catch(() => {})
+    }
+  }
+
+  const touch = async () => {
+    await writeFile(join(lockPath, 'heartbeat'), String(Date.now()))
+  }
+  await writeFile(join(lockPath, 'pid'), String(pid))
+  await touch()
+
+  const timer = setInterval(() => {
+    touch().catch(() => {})
+  }, HEARTBEAT_MS)
+  // Never hold the event loop open on the heartbeat alone.
+  timer.unref?.()
+
+  return {
+    touch,
+    async release() {
+      clearInterval(timer)
+      await rm(lockPath, { recursive: true, force: true })
+    },
+  }
+}
+
+/**
+ * Reports the pid of the eval currently running for this run.
+ *
+ * A pid file that exists but does not hold a plausible pid is an ERROR, not a
+ * missing one: the value is about to be handed to a kill(2), where a
+ * non-positive target means something far broader than one process. Refusing
+ * to guess is the only safe reading of a corrupt file.
+ *
+ * The documented shape is `{pid, running}`; `heartbeat` rides along as a
+ * non-enumerable extra for callers (and tests) that want to observe it
+ * advancing, without changing what a deep-equality check against the
+ * documented shape sees.
+ *
+ * @returns {Promise<{pid: number|null, running: boolean, heartbeat?: number}>}
+ */
+export async function evalRunning(stateDir) {
+  const lockPath = join(stateDir, LOCK_DIR)
+  const held = await readLock(lockPath)
+  if (held.error) throw held.error
+  if (held.pid === null && held.heartbeat === null && !(await stat(lockPath).catch(() => null))) {
+    return withHeartbeat(null, false, null)
+  }
+  const stale = await isStale(held, lockPath)
+  return withHeartbeat(stale ? null : held.pid, !stale, held.heartbeat)
+}
+
+/** Builds an evalRunning result with heartbeat attached non-enumerably. */
+function withHeartbeat(pid, running, heartbeat) {
+  const result = { pid, running }
+  Object.defineProperty(result, 'heartbeat', { value: heartbeat, enumerable: false })
+  return result
+}
+
+/** Removes a lock left behind. Removing one that is not there is not an error. */
+export async function clearEvalLock(stateDir) {
+  await rm(join(stateDir, LOCK_DIR), { recursive: true, force: true })
+}
+
+/** Reads the lock directory's contents, deferring pid validation to the caller. */
+async function readLock(lockPath) {
+  const pidText = await readFile(join(lockPath, 'pid'), 'utf8').catch(() => null)
+  const beatText = await readFile(join(lockPath, 'heartbeat'), 'utf8').catch(() => null)
+  const heartbeat = beatText === null ? null : Number(beatText.trim())
+
+  if (pidText === null) return { pid: null, heartbeat, error: null }
+  const trimmed = pidText.trim()
+  // Require the pid file to hold nothing but an integer (with optional sign):
+  // Number() would otherwise accept '', ' ', '0x10', 'Infinity', and other
+  // strings no process id can be.
+  const isIntegerText = /^-?\d+$/.test(trimmed)
+  const pid = isIntegerText ? Number(trimmed) : NaN
+  if (!isIntegerText || !Number.isSafeInteger(pid)) {
+    return {
+      pid: null,
+      heartbeat,
+      error: new Error(`${join(lockPath, 'pid')}: ${JSON.stringify(trimmed)} is not a pid`),
+    }
+  }
+  // pid <= 1 is refused, not just pid <= 0: kill(1, ...) targets init/launchd
+  // (every process on the system on some platforms), and kill(-1, ...) - the
+  // exact form `stop --force` uses for its own valid pids - means "every
+  // process the caller may signal". A pid file holding either must never be
+  // read back and handed to process.kill.
+  if (pid <= 1) {
+    return {
+      pid: null,
+      heartbeat,
+      error: new Error(`${join(lockPath, 'pid')}: pid ${pid} is not a process this command will signal`),
+    }
+  }
+  return { pid, heartbeat, error: null }
+}
+
+/**
+ * A lock is stale only when its owner is gone AND its heartbeat is cold.
+ *
+ * When neither a pid nor a heartbeat can be read, the lock directory exists
+ * but is (so far) empty. That happens in exactly two situations, and they
+ * must not be confused: another claimant's mkdir just won and it has not yet
+ * written its pid/heartbeat files (a race lasting microseconds), or a past
+ * claimant crashed between its mkdir and those writes and the directory is
+ * permanently abandoned. Time is what tells them apart — so this falls back
+ * to the lock DIRECTORY's own age against the same staleness window, rather
+ * than ever treating "unreadable" as "absent" the way an empty pid/heartbeat
+ * pair alone would. Without this, one claimEval racing another could delete
+ * and recreate the winner's still-forming lock directory out from under it,
+ * and both callers would believe they held the claim.
+ */
+async function isStale(held, lockPath) {
+  if (held.error) return false
+  if (held.pid !== null && alive(held.pid)) return false
+  if (held.heartbeat !== null && Number.isFinite(held.heartbeat)) {
+    return Date.now() - held.heartbeat > STALE_AFTER_MS
+  }
+  const dirStat = await stat(lockPath).catch(() => null)
+  if (!dirStat) return true // lock directory is gone entirely: nothing to protect
+  return Date.now() - dirStat.mtimeMs > STALE_AFTER_MS
+}
+
+/** Signal 0 tests for the existence of a process without touching it. */
+function alive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    // EPERM means the process exists but belongs to another user.
+    return err.code === 'EPERM'
+  }
+}

package/src/state/stop.js

@@ -0,0 +1,56 @@
+/**
+ * The sentinel coordinating between the human's shell and the agent's loop.
+ *
+ * It lives out-of-tree alongside the rest of the run state, for the same
+ * reason everything else there does: a sentinel inside the repository would
+ * dirty the working tree the agent commits from, and would have to be
+ * special-cased in the scope gate and in .gitignore. Out here it is invisible
+ * to every gate and to git, and both `stop` and `eval` still find it because
+ * the state directory is derived from the repository path and run tag, not
+ * from anything either process holds privately.
+ */
+import { rm, stat, writeFile } from 'node:fs/promises'
+import { ensureSecureDir } from './index.js'
+import { join } from 'node:path'
+
+/**
+ * Marks that the human has asked the run to end. `eval` reports its presence
+ * alongside the verdict; the AGENT decides when to act on it, which is what
+ * makes a graceful stop graceful — nothing here interrupts an experiment
+ * already under way.
+ */
+export const STOP_REQUEST_FILE = 'stop.request'
+
+/**
+ * Asks the run in stateDir to end after the current experiment.
+ *
+ * Creating stateDir when missing is deliberate: a human reaching for the
+ * brake should never be told the directory does not exist yet. A request
+ * against a tag whose baseline never finished is harmless — the sentinel
+ * simply sits there until a run reads it, or clearStop removes it.
+ */
+export async function requestStop(stateDir) {
+  await ensureSecureDir(stateDir)
+  await writeFile(join(stateDir, STOP_REQUEST_FILE), 'stop requested\n')
+}
+
+/** Cancels a pending request. Clearing one never made is not an error. */
+export async function clearStop(stateDir) {
+  await rm(join(stateDir, STOP_REQUEST_FILE), { force: true })
+}
+
+/**
+ * Reports whether a stop is pending.
+ *
+ * Returns a boolean rather than throwing, because every caller wants the same
+ * answer for an unreadable sentinel as for an absent one: carry on. A stop
+ * that cannot be read must never abort a run by itself.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function stopRequested(stateDir) {
+  return stat(join(stateDir, STOP_REQUEST_FILE)).then(
+    () => true,
+    () => false,
+  )
+}