rnxsim 0.1.369 → 0.1.371

package/cli/commands/assert.ts

@@ -14,6 +14,7 @@
 //   2   misuse — bad flags, unknown verb    (treated as bad by bisect)
 
 import { spawn } from 'child_process'
+import { rnxExit } from '../run-rnx'
 
 // READ_VERBS lists every command whose stdout we know is valid JSON under
 // --json. keeping this explicit means `sootsim assert tap 100 200` fails
@@ -403,13 +404,13 @@ function runJq(expr: string, payload: unknown): Promise<string> {
 export async function runAssert(rawArgs: string[]): Promise<void> {
   if (rawArgs[0] === '--help' || rawArgs[0] === '-h' || rawArgs.length === 0) {
     printHelp()
-    process.exit(rawArgs.length === 0 ? 2 : 0)
+    rnxExit(rawArgs.length === 0 ? 2 : 0)
   }
 
   const parsed = parseAssertArgs(rawArgs)
   if ('error' in parsed) {
     process.stderr.write(`  assert: ${parsed.error}\n`)
-    process.exit(2)
+    rnxExit(2)
   }
 
   const { verbArgs, predicates, withinMs, negate, quiet, allowTimeout } = parsed
@@ -420,7 +421,7 @@ export async function runAssert(rawArgs: string[]): Promise<void> {
       `  assert: unknown or non-read verb: ${verbArgs.join(' ')}\n` +
         `  supported: ${Array.from(READ_VERBS).sort().join(', ')}\n`,
     )
-    process.exit(2)
+    rnxExit(2)
   }
 
   // default assertion when none given is --exists. matches the common
@@ -452,7 +453,7 @@ export async function runAssert(rawArgs: string[]): Promise<void> {
         const label = exitCode === 1 ? 'fail' : 'skip'
         process.stderr.write(`  assert: ${label} — ${lastVerbSkipReason}\n`)
       }
-      process.exit(exitCode)
+      rnxExit(exitCode)
     }
 
     let allPass = true
@@ -468,7 +469,7 @@ export async function runAssert(rawArgs: string[]): Promise<void> {
       }
     } catch (err: any) {
       if (!quiet) process.stderr.write(`  assert: skip — ${err.message}\n`)
-      process.exit(125)
+      rnxExit(125)
     }
 
     const pass = negate ? !allPass : allPass
@@ -478,7 +479,7 @@ export async function runAssert(rawArgs: string[]): Promise<void> {
           `  assert: pass${attempts > 1 ? ` (attempt ${attempts})` : ''} — ${reasons.join('; ')}\n`,
         )
       }
-      process.exit(0)
+      rnxExit(0)
     }
 
     lastFailReason = reasons.join('; ')
@@ -491,7 +492,7 @@ export async function runAssert(rawArgs: string[]): Promise<void> {
         `  assert: fail${attempts > 1 ? ` after ${attempts} attempt(s)` : ''} — ${lastFailReason}\n`,
       )
     }
-    process.exit(1)
+    rnxExit(1)
   }
 }
 

package/cli/commands/auth.ts

@@ -1,5 +1,6 @@
 import { refreshSharedDesktopAuthSession } from '../../src/auth/shared-session'
 import { resolveCliAuth } from '../auth'
+import { rnxExit } from '../run-rnx'
 
 function printHelp(): void {
   console.log(`
@@ -55,5 +56,5 @@ export async function runAuth(args: string[]): Promise<void> {
 
   console.error(`  unknown auth command: ${sub}`)
   printHelp()
-  process.exit(1)
+  rnxExit(1)
 }

package/cli/commands/box/checkout-plane.ts

@@ -1,7 +1,6 @@
-// ProjectFilePlane over a real local checkout — the third provider behind the
-// seam Contrast's browser host and its server host already implement. writes
-// land on the user's actual disk, so this plane refuses anything it cannot
-// represent faithfully rather than round-tripping it through a string.
+// ProjectFilePlane over a real local checkout: the second host behind the
+// seam Contrast's browser already implements. writes land on the user's actual
+// disk, so nothing here converts content: the plane reads and writes bytes.
 //
 // the file set comes from `git ls-files -co --exclude-standard`, which is the
 // project's own definition of what belongs to it. a hardcoded skip list was
@@ -10,26 +9,48 @@
 // 67 ms. `index()` is a synchronous whole-project map, so the size of that set
 // is the whole cost model.
 
-import { execFile } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
-import { promisify } from 'node:util'
-import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness'
-
-const execFileAsync = promisify(execFile)
+import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness/plane'
 
 export class CheckoutRequiresGitError extends Error {}
 
-// a NUL byte is the usual "this is not text" test. the plane serves strings,
-// so a binary file cannot survive a read/write round trip. reading one gives
-// the same garbage real `cat` gives, which is fine; WRITING one back would
-// corrupt a file on the user's actual disk, so binary files are published as
-// read-only and the write path refuses them by name. detecting this at read
-// time is not an option: just-bash's `cat` discards every readFile error and
-// reports "No such file or directory" whatever the error says, so the refusal
-// has to live in the index where the filesystem layer can act on it.
+// a NUL byte is the usual "this is not text" test. it is published as metadata
+// rather than acted on here: moving a binary file is byte-exact and perfectly
+// fine, and so is deleting one, but a shell command that produced TEXT cannot
+// be allowed to overwrite it, because that text is a lossy decode of the
+// file's own bytes. HarnessProjectFs owns that refusal. detecting it at write
+// time instead is not an option: just-bash's `cat` discards every readFile
+// error and reports "No such file or directory" whatever the error says, so
+// the fact has to be in the index where the filesystem layer can read it.
 const BINARY_SNIFF_BYTES = 8192
 
+// every command a box runs re-indexes first, and the index read waits on a git
+// subprocess. it used to await one, and that await could never finish: measured
+// here over 961 refreshes, the call either answered within 314ms (p50 25ms) or
+// never answered at all, once for 29 seconds while the process's own timer kept
+// firing every second. that is not a slow git, it is a lost answer, and no
+// budget reaches it.
+//
+// a deadline on the async form does not help either, which is why this is
+// synchronous. node's `execFile` timeout kills the child and then still waits
+// for a 'close' event to settle the promise, so the lost event takes the
+// deadline down with it: the bound below was armed and silent through all 29
+// of those seconds. `execFileSync` waits in the runtime instead of on a
+// javascript event, so there is nothing to miss, and its timeout is enforced
+// the same way.
+//
+// it costs nothing. the entry loop below is already synchronous stat and read,
+// and under 24-way load the two forms were indistinguishable over 960 calls
+// each, interleaved: p50 1529ms synchronous against 1520ms asynchronous.
+//
+// 10s is roughly fifteen times the slowest full refresh measured on a
+// 14,889-file checkout (430-840 ms, of which `git ls-files` itself is 67 ms),
+// so it cannot fire for a project that is merely large or a machine that is
+// merely busy.
+const LIST_FILES_TIMEOUT_MS = 10_000
+
 function looksBinary(filePath: string, size: number): boolean {
   if (size === 0) return false
   let fd: number | undefined
@@ -45,12 +66,32 @@ function looksBinary(filePath: string, size: number): boolean {
   }
 }
 
+// the box re-indexes before every command, so the sniff above runs against the
+// whole project every time a user presses return. on a 14,889-file checkout
+// that is 277-644 ms of a 430-840 ms refresh, and nearly all of it re-reads
+// files that did not change. a file whose size and mtime both match the last
+// look has the same first 8 KB, so remember the answer against those two.
+// `statSync` already returns mtimeMs, and it carries sub-millisecond
+// resolution here, so the window in which a same-size rewrite could hide is
+// narrower than a millisecond rather than git's one-second racy-clean case.
+interface SniffedFile {
+  size: number
+  mtimeMs: number
+  binary: boolean
+}
+
 export class CheckoutFilePlane implements ProjectFilePlane {
   readonly root: string
   private entries = new Map<string, ProjectFileMeta>()
+  private sniffed = new Map<string, SniffedFile>()
+  // the deadline above, as a number a caller can set. what it changes is how
+  // long a wedged git is waited on, never whether it is waited on, so proving
+  // the kill does not have to cost the production deadline.
+  private readonly listTimeoutMs: number
 
-  constructor(root: string) {
+  constructor(root: string, options: { listTimeoutMs?: number } = {}) {
     this.root = path.resolve(root)
+    this.listTimeoutMs = options.listTimeoutMs ?? LIST_FILES_TIMEOUT_MS
   }
 
   index(): ReadonlyMap<string, ProjectFileMeta> {
@@ -63,20 +104,47 @@ export class CheckoutFilePlane implements ProjectFilePlane {
       // -z so paths containing spaces or newlines survive; -co --exclude-standard
       // is tracked plus untracked-not-ignored, which is what a person means by
       // "the files in my project".
-      const result = await execFileAsync(
-        'git',
-        ['ls-files', '-co', '--exclude-standard', '-z'],
-        { cwd: this.root, maxBuffer: 64 * 1024 * 1024 },
-      )
-      stdout = result.stdout
+      stdout = execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+        cwd: this.root,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: this.listTimeoutMs,
+        // stating the environment is not redundant here. bun 1.3.14 resolves
+        // the binary for the synchronous form against the PATH it captured at
+        // startup and ignores a later change to `process.env.PATH`, so without
+        // this it runs a different git than every other call in the process.
+        env: process.env,
+      })
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
+      // the deadline kills with SIGTERM, so that signal is what tells a bound
+      // run apart from git failing on its own terms, and it is worth naming
+      // separately: "git was killed by SIGTERM" reads as git's problem, when
+      // what happened is that it never answered.
+      const killed =
+        error instanceof Error && 'signal' in error && error.signal === 'SIGTERM'
+      throw new CheckoutRequiresGitError(
+        killed
+          ? `git did not list the project's files in ${this.root} within ${this.listTimeoutMs / 1000}s, so the box has no file set to serve. the checkout may be on a stalled filesystem, or this machine may be too loaded to start a subprocess.`
+          : `could not list the project's files with git in ${this.root}: ${message}`,
+      )
+    }
+
+    // a busy machine also hands back a child that exits 0 having written
+    // nothing, which docs/testing.md owns: empty child output never means an
+    // empty answer. without this the box would build an empty index and every
+    // read would report the file as missing, which is a broken project rather
+    // than a broken box, and nothing would say so.
+    if (stdout.length === 0) {
       throw new CheckoutRequiresGitError(
-        `could not list the project's files with git in ${this.root}: ${message}`,
+        `git listed no files in ${this.root}. either git tracks nothing there and nothing untracked is visible to it, or this machine could not read the child process's output.`,
       )
     }
 
     const next = new Map<string, ProjectFileMeta>()
+    // rebuilt alongside the index rather than pruned, so a deleted file's
+    // record cannot outlive it in a box that stays open all day
+    const nextSniffed = new Map<string, SniffedFile>()
     for (const relative of stdout.split('\0')) {
       if (!relative) continue
       let stat: fs.Stats
@@ -87,12 +155,22 @@ export class CheckoutFilePlane implements ProjectFilePlane {
         continue
       }
       if (!stat.isFile()) continue
+      const seen = this.sniffed.get(relative)
+      const binary =
+        seen && seen.size === stat.size && seen.mtimeMs === stat.mtimeMs
+          ? seen.binary
+          : looksBinary(path.join(this.root, relative), stat.size)
+      nextSniffed.set(relative, { size: stat.size, mtimeMs: stat.mtimeMs, binary })
       next.set(relative, {
         size: stat.size,
-        readOnly: looksBinary(path.join(this.root, relative), stat.size),
+        // a checkout carries no write policy of its own; if the user can write
+        // the file, so can the shell
+        readOnly: false,
+        binary,
       })
     }
     this.entries = next
+    this.sniffed = nextSniffed
   }
 
   private absolute(planePath: string): string {
@@ -113,13 +191,15 @@ export class CheckoutFilePlane implements ProjectFilePlane {
     return fs.promises.readFile(this.absolute(planePath))
   }
 
-  async write(planePath: string, content: string): Promise<void> {
+  async write(planePath: string, content: Uint8Array): Promise<void> {
     const absolute = this.absolute(planePath)
     await fs.promises.mkdir(path.dirname(absolute), { recursive: true })
-    await fs.promises.writeFile(absolute, content, 'utf8')
+    await fs.promises.writeFile(absolute, content)
     this.entries.set(planePath, {
-      size: Buffer.byteLength(content, 'utf8'),
+      size: content.byteLength,
       readOnly: false,
+      // the bytes are in hand, so the same NUL test costs nothing here
+      binary: content.subarray(0, BINARY_SNIFF_BYTES).includes(0),
     })
   }
 

package/cli/commands/box/cloud-box.ts

@@ -0,0 +1,294 @@
+// the client half of a cloud box: create it, seed this checkout into it, and
+// run its shell over the box's own WebSocket.
+//
+// the box holds the files and the shell; this process holds neither. so the
+// REPL here sends `shell:exec` and prints what comes back, and `cwd` is
+// whatever the box last reported rather than anything tracked locally. that is
+// the whole difference between the two placements, and it is why the same
+// readline loop drives both.
+//
+// there is no default endpoint. a cloud box has to be deployed before one can
+// exist, and pointing at a URL that answers nothing would advertise a
+// capability that always fails.
+
+import WebSocket from 'ws'
+import type { CheckoutFilePlane } from './checkout-plane'
+import type { HarnessShellResult } from '@contrast/harness/shell'
+
+// a checkout is 15k files on this repo, so seeding is batched by BYTES rather
+// than by count: one request carrying every file would be a single multi-
+// hundred-megabyte body, and one request per file would be 15k round trips.
+const SEED_BATCH_BYTES = 4 * 1024 * 1024
+// base64 costs 4 bytes for every 3, and a request carries the encoded size.
+const BASE64_OVERHEAD = 4 / 3
+
+export interface CloudBoxSession {
+  readonly cwd: string
+  exec(command: string): Promise<HarnessShellResult>
+  close(): void
+}
+
+export class CloudBoxError extends Error {}
+
+function endpointOf(base: string, name: string, verb: string): string {
+  return `${base.replace(/\/+$/, '')}/v1/boxes/${encodeURIComponent(name)}/${verb}`
+}
+
+async function boxFetch(
+  base: string,
+  name: string,
+  verb: string,
+  token: string | null,
+  body?: unknown,
+): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (token) headers.authorization = `Bearer ${token}`
+  let response: Response
+  try {
+    response = await fetch(endpointOf(base, name, verb), {
+      method: body === undefined ? 'GET' : 'POST',
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+  } catch (error) {
+    throw new CloudBoxError(
+      `could not reach the box service at ${base}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+  const text = await response.text()
+  const parsed = text ? JSON.parse(text) : {}
+  if (!response.ok) {
+    throw new CloudBoxError(
+      String(parsed.error ?? `box ${verb} failed (${response.status})`),
+    )
+  }
+  return parsed
+}
+
+/**
+ * create the box and copy this checkout into it.
+ *
+ * `apiKey` is the ACCOUNT's key, which the box service forwards to
+ * /v1/rnx/sessions to authenticate the caller and start the session that pays
+ * for the box. the box's own token comes back minted by the box; a caller does
+ * not choose it.
+ */
+export async function createCloudBox(options: {
+  endpoint: string
+  name: string
+  apiKey: string
+  plane: CheckoutFilePlane
+  onProgress?: (seeded: number, total: number) => void
+}): Promise<{ files: number; token: string; sessionId: string }> {
+  const { endpoint, name, apiKey, plane } = options
+  const created = await boxFetch(endpoint, name, 'create', apiKey, { name })
+  const token = String(created.token ?? '')
+  if (!token) throw new CloudBoxError('the box service returned no access token')
+
+  const paths = [...plane.index().keys()].sort()
+  let batch: [string, string][] = []
+  let batchBytes = 0
+  let seeded = 0
+
+  const flush = async () => {
+    if (batch.length === 0) return
+    await boxFetch(endpoint, name, 'seed', token, { files: batch })
+    seeded += batch.length
+    options.onProgress?.(seeded, paths.length)
+    batch = []
+    batchBytes = 0
+  }
+
+  for (const path of paths) {
+    const bytes = await plane.readBytes(path)
+    batch.push([path, Buffer.from(bytes).toString('base64')])
+    batchBytes += bytes.byteLength * BASE64_OVERHEAD
+    if (batchBytes >= SEED_BATCH_BYTES) await flush()
+  }
+  await flush()
+
+  const status = await boxFetch(endpoint, name, 'status', token)
+  return {
+    files: Number(status.files ?? 0),
+    token,
+    sessionId: String(status.sessionId ?? ''),
+  }
+}
+
+/**
+ * stop a box, or stop and wipe it.
+ *
+ * takes the ACCOUNT key, not the box token: it ends the session the account is
+ * billed for, which the box deliberately cannot do on its own.
+ */
+export async function stopCloudBox(options: {
+  endpoint: string
+  name: string
+  apiKey: string
+  purge?: boolean
+}): Promise<Record<string, unknown>> {
+  return boxFetch(
+    options.endpoint,
+    options.name,
+    options.purge ? 'delete' : 'stop',
+    options.apiKey,
+    {},
+  )
+}
+
+/**
+ * the account's running boxes, from the session meter rather than from the box
+ * service. the meter already knows what this account is running and what it
+ * cost, so a second per-account index of boxes would be a second answer to the
+ * same question, free to drift.
+ */
+export async function listCloudBoxes(options: {
+  apiOrigin: string
+  apiKey: string
+}): Promise<{ id: string; name: string | null; startedAt: string; meteredMs: number }[]> {
+  const response = await fetch(
+    `${options.apiOrigin.replace(/\/+$/, '')}/v1/rnx/sessions`,
+    {
+      headers: { authorization: `Bearer ${options.apiKey}` },
+    },
+  )
+  const text = await response.text()
+  const parsed = text ? JSON.parse(text) : {}
+  if (!response.ok) {
+    throw new CloudBoxError(
+      String(parsed.message ?? parsed.error ?? 'could not list boxes'),
+    )
+  }
+  const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : []
+  return sessions
+    .filter((session: { kind?: string }) => session.kind === 'box')
+    .map((session: Record<string, unknown>) => ({
+      id: String(session.id),
+      name: typeof session.name === 'string' ? session.name : null,
+      startedAt: String(session.startedAt ?? ''),
+      meteredMs: Number(session.meteredMs ?? 0),
+    }))
+}
+
+/**
+ * bank the wall clock while a box is open.
+ *
+ * the box holds no account credential and so cannot heartbeat for itself; the
+ * client that is actually using it does. when this process dies the heartbeats
+ * stop and the site's stale sweep closes the session at the last one, which is
+ * why there is no second idle timer in the box.
+ */
+export function heartbeatSession(options: {
+  apiOrigin: string
+  apiKey: string
+  sessionId: string
+  everyMs?: number
+}): { stop: () => void } {
+  const url = `${options.apiOrigin.replace(/\/+$/, '')}/v1/rnx/sessions/${encodeURIComponent(
+    options.sessionId,
+  )}`
+  const timer = setInterval(() => {
+    void fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${options.apiKey}` },
+    }).catch(() => {
+      // a missed heartbeat is not an error worth interrupting a shell for.
+      // the sweep closes the session at the last one that landed.
+    })
+  }, options.everyMs ?? 60_000)
+  // do not hold the process open just to keep billing alive
+  timer.unref?.()
+  return { stop: () => clearInterval(timer) }
+}
+
+/** open the box's socket and return a session the REPL can drive. */
+export async function connectCloudBox(options: {
+  endpoint: string
+  name: string
+  token: string
+}): Promise<CloudBoxSession> {
+  const { endpoint, name, token } = options
+  const url = endpointOf(endpoint, name, 'connect').replace(/^http/, 'ws')
+  // as a subprotocol, not a header. a browser cannot set a header on a
+  // WebSocket, and the box takes the token one way rather than one way per
+  // kind of caller.
+  const socket = new WebSocket(url, [`rnx-box-token.${token}`])
+
+  // a persistent handler, installed before the handshake can fail. ws emits
+  // 'error' again after a refused upgrade, and a `once` listener consumed by
+  // the rejection leaves that second emit unhandled, which crashes the
+  // process rather than failing the command.
+  let socketError: string | null = null
+  socket.on('error', (error) => {
+    socketError = error.message
+  })
+  await new Promise<void>((resolve, reject) => {
+    socket.once('open', resolve)
+    socket.once('error', (error) => {
+      socket.close()
+      reject(error)
+    })
+  }).catch(async (error: unknown) => {
+    // ws's handshake error text is runtime-specific: node says "Unexpected
+    // server response: 401" and bun says "Expected 101 status code" with no
+    // status at all. so ask the service itself why, over plain HTTP, and
+    // report THAT. this runs only on the failure path.
+    const reason = await boxFetch(endpoint, name, 'status', token).then(
+      () => null,
+      (failure: unknown) =>
+        failure instanceof Error ? failure.message : String(failure),
+    )
+    const fallback = error instanceof Error ? error.message : String(error)
+    throw new CloudBoxError(`could not open the box shell: ${reason ?? fallback}`)
+  })
+
+  let nextId = 0
+  const waiting = new Map<number, (reply: Record<string, unknown>) => void>()
+  socket.on('message', (data) => {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(String(data))
+    } catch {
+      return
+    }
+    if (typeof parsed !== 'object' || parsed === null) return
+    const reply = parsed as Record<string, unknown>
+    const resolve = waiting.get(Number(reply.id))
+    if (!resolve) return
+    waiting.delete(Number(reply.id))
+    resolve(reply)
+  })
+
+  // the socket dying mid-command must fail the command rather than hang the
+  // prompt forever, so every waiter is settled when it closes.
+  let closedReason: string | null = null
+  const settleAll = (reason: string) => {
+    closedReason = reason
+    for (const [id, resolve] of waiting) resolve({ id, error: reason })
+    waiting.clear()
+  }
+  socket.on('close', () => settleAll(socketError ?? 'the box closed the connection'))
+  socket.on('error', (error) => settleAll(error.message))
+
+  let cwd = '/project'
+  return {
+    get cwd() {
+      return cwd
+    },
+    async exec(command: string): Promise<HarnessShellResult> {
+      if (closedReason) throw new CloudBoxError(closedReason)
+      const id = nextId++
+      const reply = await new Promise<Record<string, unknown>>((resolve) => {
+        waiting.set(id, resolve)
+        socket.send(JSON.stringify({ type: 'shell:exec', id, command }))
+      })
+      if (reply.error) throw new CloudBoxError(String(reply.error))
+      const result = reply.result as HarnessShellResult
+      if (result.cwd) cwd = result.cwd
+      return result
+    },
+    close: () => socket.close(),
+  }
+}