peachsim 0.1.527

package/cli/commands/box.ts

@@ -0,0 +1,925 @@
+// `rnx box` — the box environment.
+//
+// bare `rnx box` is LOCAL and mounts the current checkout at /project. cloud
+// create provisions through the shared client and enters the same shell unless
+// --json asks for a noninteractive result. connect asks the account service to
+// turn a Box name into an authorized reference and enters that same shell, so
+// this process never stores a Box token.
+//
+// every verb that acts on an existing Box takes it the same way: the id or
+// name on the command line, else the one `rnx box use` remembered. see
+// boxTarget below.
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { createInterface } from 'node:readline'
+import { BoxClientError, createBoxClient } from '@rnx/box/client'
+import { createBoxHostProvider } from '@rnx/box/host'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
+import { terminalBoxStack } from '@rnx/box/stack'
+import {
+  BoxTemplateRegistry,
+  prebuiltBundleBoxTemplate,
+  sourceControlBoxTemplate,
+  terminalBoxTemplate,
+} from '@rnx/box/template'
+import {
+  cloudBoxConnectUrl,
+  createCloudBoxProvider,
+  ensureCloudBoxBrowser,
+  heartbeatSession,
+  resolveCloudBoxReference,
+} from 'rnx-cloud-box/client'
+import { readDefaultBox, writeDefaultBox } from '../../src/home-paths'
+import { rnxPublicBrand } from '../../src/public-brand'
+import { authHeaderOrExit, cloudAccountIdOrExit, type CliAuth } from '../auth'
+import { produceCloudBoxArtifact, type CloudBoxArtifactProduction } from '../cloud-client'
+import { findRepositoryPackageRoot } from '../setup-repository'
+import { resolvePlacement } from '../ws-bridge'
+import { BundleFilePlane } from './box/bundle-plane'
+import { CheckoutFilePlane, CheckoutRequiresGitError } from './box/checkout-plane'
+import { sharePlane } from './box/plane-share'
+import { createRnxCommand } from './box/rnx-command'
+import { createSearchCommand } from './box/search-command'
+import type { BoxShellSession } from '@rnx/box/client'
+import type { BoxTemplateResolution } from '@rnx/box/template'
+
+interface BoxCommandOptions {
+  port?: number
+  verbose?: boolean
+}
+
+// no default. a cloud box service has to be deployed before one can exist, and
+// defaulting to an origin that answers nothing would advertise a capability
+// that always fails.
+const ENDPOINT_ENV = 'RNX_BOX_ENDPOINT'
+const API_ORIGIN_ENV = 'RNX_API_ORIGIN'
+const BOX_TEMPLATES = new BoxTemplateRegistry([
+  terminalBoxTemplate,
+  sourceControlBoxTemplate,
+  prebuiltBundleBoxTemplate,
+])
+
+export async function runBox(
+  args: string[],
+  opts: BoxCommandOptions = {},
+): Promise<number> {
+  // a box inside a box would mount the same checkout twice and give the
+  // user two shells writing through one filesystem. refuse at the top rather
+  // than letting the second one start and quietly race the first.
+  const placement = resolvePlacement()
+  if (placement === 'local-box') {
+    console.error(
+      `  ${rnxPublicBrand.commandName} box: you are already in a box.\n` +
+        `  this shell is the box — run ${rnxPublicBrand.commandName} commands directly, or \`exit\` to leave.`,
+    )
+    return 1
+  }
+
+  const subcommand = args.find((arg) => !arg.startsWith('-'))
+  if (subcommand === 'create') return runCloudBoxCreate(args, opts)
+  if (subcommand === 'use') return runCloudBoxUse(args)
+  if (subcommand === 'connect') return runCloudBoxConnect(args)
+  if (subcommand === 'send') return runBoxSend(args, opts)
+  if (subcommand === 'open') return runCloudBoxOpen(args)
+  if (subcommand === 'stop' || subcommand === 'delete') {
+    return runCloudBoxStop(args, subcommand === 'delete')
+  }
+  if (subcommand === 'ls') return runCloudBoxList(args)
+  if (subcommand !== undefined) {
+    console.error(
+      `  unknown command: ${rnxPublicBrand.commandName} box ${subcommand}\n` +
+        `  run \`${rnxPublicBrand.commandName} box --help\` to see the box surface.`,
+    )
+    return 1
+  }
+
+  if (args.includes('--json')) {
+    console.error(
+      `  ${rnxPublicBrand.commandName} box --json requires a noninteractive cloud subcommand such as create.`,
+    )
+    return 1
+  }
+
+  return runLocalBox(opts)
+}
+
+function flag(args: string[], name: string): string | undefined {
+  const inline = args.find((arg) => arg.startsWith(`--${name}=`))
+  if (inline) return inline.slice(name.length + 3)
+  const index = args.indexOf(`--${name}`)
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('-')) {
+    return args[index + 1]
+  }
+  return undefined
+}
+
+// the account service, which owns /api/v1/rnx/sessions and the box connect
+// route. a login session names the origin it was issued by; an api key
+// carries none, so it goes where every other key-authenticated command goes.
+function apiOrigin(args: string[], auth: CliAuth): string {
+  return (
+    flag(args, 'api-origin') ??
+    process.env[API_ORIGIN_ENV]?.trim() ??
+    (auth.kind === 'session' ? auth.origin : 'https://contrast.dev')
+  ).replace(/\/+$/, '')
+}
+
+// the Box named on the command line: the second positional, since the first is
+// the verb, or `--name` which is the same thing spelled as a flag.
+function namedBox(args: string[]): string | undefined {
+  return args.filter((arg) => !arg.startsWith('-'))[1] ?? flag(args, 'name')
+}
+
+/**
+ * which Box a verb acts on.
+ *
+ * one order for every verb that acts on a Box that already exists: the id or
+ * name on the command line, else the one `rnx box use` remembered, else
+ * nothing and the reason printed here.
+ */
+function boxTarget(args: string[], label: string): string | null {
+  const named = namedBox(args)
+  if (named) return named
+  const stored = readDefaultBox()
+  if (stored) return stored.boxId
+  const rnx = rnxPublicBrand.commandName
+  console.error(
+    `  ${rnx} box ${label}: which box? pass its ID or name, as \`${rnx} box ls\` prints it,\n` +
+      `  or set one for every box command with \`${rnx} box use <id-or-name>\`.`,
+  )
+  return null
+}
+
+/**
+ * `rnx box use` — the Box every other verb acts on when none is named.
+ *
+ * it resolves through the account service exactly as connect does, because
+ * that is the only thing that knows which account owns a Box, and a default
+ * pointing at somebody else's Box would fail at every later verb instead of
+ * here. what is written down is the id and the display name; the Box's own
+ * token is resolved again per command and never reaches disk.
+ */
+async function runCloudBoxUse(args: string[]): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const named = namedBox(args)
+  if (!named) {
+    const stored = readDefaultBox()
+    if (!stored) {
+      console.log(
+        `  no default box. \`${rnx} box use <id-or-name>\` targets one, and every\n` +
+          `  other box command then acts on it when you name none.`,
+      )
+      return 0
+    }
+    console.log(`  ${stored.name ?? stored.boxId}`)
+    return 0
+  }
+
+  const { auth, header } = authHeaderOrExit('box use')
+  const apiKey = header.replace(/^Bearer /, '')
+  try {
+    const reference = await resolveCloudBoxReference({
+      apiOrigin: apiOrigin(args, auth),
+      apiKey,
+      boxId: named,
+    })
+    // attach for the Box's own name: the caller may have typed either an id or
+    // a name, and the default has to be able to print the one a person reads.
+    const box = await createBoxClient(
+      createCloudBoxProvider({
+        endpoint: reference.endpoint,
+        authority: { kind: 'attach' },
+      }),
+    ).attach({
+      reference: { boxId: reference.boxId, accessToken: reference.token },
+    })
+    writeDefaultBox({ boxId: box.description.boxId, name: box.description.name })
+    console.log(
+      `  ...box commands now target ${box.description.name ?? box.description.boxId}`,
+    )
+    return 0
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box use: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+function requireEndpoint(args: string[], label: string): string | null {
+  return cloudBoxEndpoint(args, `box ${label}`)
+}
+
+/**
+ * the cloud box service this command talks to, or null with the reason
+ * printed. exported because `rnx box send` creates a box too, and a second
+ * spelling of where boxes live is a second place to configure.
+ */
+export function cloudBoxEndpoint(args: string[], command: string): string | null {
+  const endpoint = flag(args, 'endpoint') ?? process.env[ENDPOINT_ENV]?.trim()
+  if (endpoint) return endpoint
+  console.error(
+    `  ${rnxPublicBrand.commandName} ${command}: no cloud box service to talk to.\n` +
+      `  set ${ENDPOINT_ENV} or pass --endpoint=<url>.`,
+  )
+  return null
+}
+
+/** the api origin a cloud box bills against. */
+export function cloudBoxApiOrigin(args: string[], auth: CliAuth): string {
+  return apiOrigin(args, auth)
+}
+
+// `rnx box send` — the CLI half of "send to box". the shell's rail button runs
+// the same function inside the daemon; this is the same send for an agent or a
+// terminal, and it prints the id and URL either way.
+async function runBoxSend(args: string[], opts: BoxCommandOptions): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const { auth, header } = authHeaderOrExit('box send')
+  const accountId = cloudAccountIdOrExit(auth)
+  const { createBridgeFromParsed, parseBridgeCliArgs } = await import('../ws-bridge')
+  const parsed = parseBridgeCliArgs(
+    args.filter((arg) => arg !== 'send'),
+    {
+      port: opts.port,
+      stripBooleanFlags: ['--no-auth', '--json'],
+      stripValueFlags: ['--name', '--api-origin'],
+    },
+  )
+  const bridge = createBridgeFromParsed(parsed)
+  try {
+    const { sendToBox } = await import('../send-to-box')
+    const result = await sendToBox({
+      send: (command) => bridge.send(command),
+      authorization: header,
+      accountId,
+      carryAuth: !args.includes('--no-auth'),
+      boxName: flag(args, 'name') ?? null,
+      apiOrigin: flag(args, 'api-origin'),
+    })
+    if (args.includes('--json')) console.log(JSON.stringify(result))
+    return 0
+  } catch (error) {
+    console.error(
+      `  ${rnx} box send: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return 1
+  } finally {
+    bridge.close()
+  }
+}
+
+async function runCloudBoxStop(args: string[], purge: boolean): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const label = purge ? 'delete' : 'stop'
+  const endpoint = requireEndpoint(args, label)
+  if (!endpoint) return 1
+  const name = boxTarget(args, label)
+  if (!name) return 1
+  const { auth, header } = authHeaderOrExit(`box ${label}`)
+  const apiKey = header.replace(/^Bearer /, '')
+  const accountId = cloudAccountIdOrExit(auth)
+  const client = createBoxClient(
+    createCloudBoxProvider({
+      endpoint,
+      authority: { kind: 'account', apiOrigin: apiOrigin(args, auth), apiKey, accountId },
+    }),
+  )
+  try {
+    const result = purge
+      ? await client.delete({ boxId: name })
+      : await client.stop({ boxId: name })
+    // the box the default named is gone, so the default goes with it rather
+    // than pointing every later command at a box that stopped answering.
+    const stored = readDefaultBox()
+    if (stored && (stored.boxId === name || stored.name === name)) writeDefaultBox(null)
+    console.log(
+      purge
+        ? `  deleted ${name}, freeing ${Number(result.freedBytes ?? 0)} bytes`
+        : `  stopped ${name}`,
+    )
+    return 0
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box ${label}: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+async function runCloudBoxList(args: string[]): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const { auth, header } = authHeaderOrExit('box ls')
+  const apiKey = header.replace(/^Bearer /, '')
+  const accountId = cloudAccountIdOrExit(auth)
+  const client = createBoxClient(
+    createCloudBoxProvider({
+      endpoint: flag(args, 'endpoint') ?? process.env[ENDPOINT_ENV]?.trim() ?? '',
+      authority: { kind: 'account', apiOrigin: apiOrigin(args, auth), apiKey, accountId },
+    }),
+  )
+  try {
+    const boxes = await client.list()
+    if (boxes.length === 0) {
+      console.log(`  no cloud boxes running on this account`)
+      return 0
+    }
+    for (const box of boxes) {
+      const minutes = Math.round(box.meteredMs / 60_000)
+      console.log(
+        `  ${box.name ?? box.boxId}  running ${minutes}m  since ${box.startedAt}`,
+      )
+    }
+    return 0
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box ls: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+async function runCloudBoxConnect(args: string[]): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const json = args.includes('--json')
+  const boxId = boxTarget(args, 'connect')
+  if (!boxId) return 1
+
+  // the ACCOUNT's credential. the account service is the only thing that knows
+  // which account a Box belongs to, so it resolves the name and hands back the
+  // Box's own token; nothing here writes that token down.
+  const { auth, header } = authHeaderOrExit('box connect')
+  const apiKey = header.replace(/^Bearer /, '')
+  const origin = apiOrigin(args, auth)
+
+  let session: BoxShellSession | null = null
+  let heartbeat: { stop: () => void } | null = null
+  try {
+    const reference = await resolveCloudBoxReference({ apiOrigin: origin, apiKey, boxId })
+    const box = await createBoxClient(
+      createCloudBoxProvider({
+        endpoint: reference.endpoint,
+        authority: { kind: 'attach' },
+      }),
+    ).attach({
+      // no stack here on purpose: the Box reports the one it was created
+      // with, and holding somebody else's Box to a stack this process guessed
+      // would offer primitives it does not actually have.
+      reference: { boxId: reference.boxId, accessToken: reference.token },
+    })
+    if (json) {
+      // the reference without its token. a caller scripting against this gets
+      // the Box's identity; the credential stays out of stdout and out of
+      // whatever collects it.
+      console.log(JSON.stringify({ endpoint: reference.endpoint, ...box.description }))
+      return 0
+    }
+    console.log(`  ...connected to Box ${box.id}`)
+    if (box.description.pageUrl) {
+      console.log(`  ...open ${box.description.pageUrl}`)
+    }
+    console.log(`  ...accessing shell\n`)
+    session = await box.connect()
+    // the same reason `create` heartbeats: the box holds no account credential,
+    // so the client using it is what keeps its session alive.
+    const sessionId = box.description.sessionId
+    if (!sessionId) throw new BoxClientError('the box service returned no session id')
+    heartbeat = heartbeatSession({ apiOrigin: origin, apiKey, sessionId })
+    return await repl(session, '')
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box connect: ${error.message}`)
+      return 1
+    }
+    throw error
+  } finally {
+    heartbeat?.stop()
+    session?.close()
+  }
+}
+
+/**
+ * watch a cloud box in a browser.
+ *
+ * the box runs its app in one Browser Run page, and this opens the Box page,
+ * which streams THAT instance rather than booting a second copy. so what the
+ * person sees is what the agent is working on, and two people opening the same
+ * box see the same screen.
+ *
+ * the url carries no credential: it is the box's page on the Contrast origin,
+ * and opening it signed in resolves the box through the account service. that
+ * makes it a link somebody can keep, paste, or reload.
+ */
+async function runCloudBoxOpen(args: string[]): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const json = args.includes('--json')
+  const print = args.includes('--print')
+  const boxId = boxTarget(args, 'open')
+  if (!boxId) return 1
+
+  // the ACCOUNT's credential, for the same reason connect takes one: the
+  // account service is what knows which account owns this Box, and it hands
+  // back the Box's own token rather than this process storing one.
+  const { auth, header } = authHeaderOrExit('box open')
+  const apiKey = header.replace(/^Bearer /, '')
+
+  try {
+    const reference = await resolveCloudBoxReference({
+      apiOrigin: apiOrigin(args, auth),
+      apiKey,
+      boxId,
+    })
+    const connectUrl = cloudBoxConnectUrl(reference.endpoint, reference.boxId)
+    // ensure first: it is what navigates the generation's tab to the Box page,
+    // so a box whose browser lapsed gets a new generation with its page
+    // restored before anybody is looking at it. without it the page opens onto
+    // a box with no simulator running and nothing to stream.
+    const browser = await ensureCloudBoxBrowser({
+      connectUrl,
+      accessToken: reference.token,
+    })
+    if (!browser.reused && !json && !print) {
+      console.log(`  ...started this box's browser`)
+    }
+    const box = await createBoxClient(
+      createCloudBoxProvider({
+        endpoint: reference.endpoint,
+        authority: { kind: 'attach' },
+      }),
+    ).attach({
+      reference: { boxId: reference.boxId, accessToken: reference.token },
+    })
+    // the box owns this url because it is the only side that knows both the
+    // page origin and the route.
+    const url = box.description.pageUrl
+    if (!url) {
+      console.error(
+        `  ${rnx} box open: this box service has no page origin configured, so it has no page to open.`,
+      )
+      return 1
+    }
+    if (json) {
+      console.log(JSON.stringify({ url }))
+      return 0
+    }
+    if (print) {
+      console.log(url)
+      return 0
+    }
+    return await openInBrowser(url)
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box open: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+/**
+ * hand a URL to the operating system's browser.
+ *
+ * argv rather than a shell string, because this URL is a bearer capability and
+ * a shell would take it through history, expansion and quoting on the way. when
+ * `open` cannot run it is printed instead: this process is the only place the
+ * URL exists, so dropping it would cost the caller another mint.
+ */
+export async function openInBrowser(url: string): Promise<number> {
+  const child = spawn('open', [url], { stdio: 'ignore' })
+  const opened = await new Promise<boolean>((resolve) => {
+    child.once('error', () => resolve(false))
+    child.once('close', (code) => resolve(code === 0))
+  })
+  if (!opened) console.log(url)
+  return 0
+}
+
+function cloudBoxClient(options: {
+  endpoint: string
+  apiOrigin: string
+  apiKey: string
+  accountId: string | null
+}) {
+  return createBoxClient(
+    createCloudBoxProvider({
+      endpoint: options.endpoint,
+      authority: {
+        kind: 'account',
+        apiOrigin: options.apiOrigin,
+        apiKey: options.apiKey,
+        accountId: options.accountId,
+      },
+    }),
+  )
+}
+
+/**
+ * create a Box that runs an app somebody already built.
+ *
+ * `box create --bundle` reaches this with a file from disk and `rnx box send`
+ * with the artifact it just produced. both are the same box: the bundle is
+ * the whole project, the provenance says so, and the page that opens it boots
+ * that bundle instead of building anything.
+ */
+export async function createPrebuiltBundleBox(options: {
+  bundle: Uint8Array
+  name: string
+  endpoint: string
+  apiOrigin: string
+  apiKey: string
+  accountId: string | null
+}) {
+  return cloudBoxClient(options).create({
+    name: options.name,
+    stack: prebuiltBundleBoxTemplate.stack,
+    template: BOX_TEMPLATES.resolve({ name: prebuiltBundleBoxTemplate.name }).provenance,
+    source: new BundleFilePlane(options.bundle),
+  })
+}
+
+async function runCloudBoxCreate(
+  args: string[],
+  opts: BoxCommandOptions,
+): Promise<number> {
+  const rnx = rnxPublicBrand.commandName
+  const json = args.includes('--json')
+  const endpoint = flag(args, 'endpoint') ?? process.env[ENDPOINT_ENV]?.trim()
+  if (!endpoint) {
+    console.error(
+      `  ${rnx} box create: no cloud box service to create a box in.\n` +
+        `  set ${ENDPOINT_ENV} or pass --endpoint=<url>. \`${rnx} box\` runs the\n` +
+        `  same shell locally over this checkout.`,
+    )
+    return 1
+  }
+
+  // --bundle IS the template choice: the box runs an app that is already
+  // built, so naming a second template would ask for two different boxes.
+  const bundlePath = flag(args, 'bundle')
+  const namedTemplate = flag(args, 'template')
+  if (bundlePath && namedTemplate) {
+    console.error(
+      `  ${rnx} box create: --bundle creates a ${prebuiltBundleBoxTemplate.name} box,\n` +
+        `  so it cannot be combined with --template ${namedTemplate}.`,
+    )
+    return 1
+  }
+  const templateName = bundlePath
+    ? prebuiltBundleBoxTemplate.name
+    : (namedTemplate ?? sourceControlBoxTemplate.name)
+  let template: BoxTemplateResolution
+  try {
+    template = BOX_TEMPLATES.resolve({ name: templateName })
+  } catch (error) {
+    console.error(
+      `  ${rnx} box create: ${error instanceof Error ? error.message : String(error)}.`,
+    )
+    return 1
+  }
+
+  // a prebuilt box holds the bundle; a source box holds the checkout it is
+  // built from. nothing holds both, so they are not two nullable variables.
+  let source: { bundle: Uint8Array } | { checkout: CheckoutFilePlane }
+  let defaultName: string
+  if (bundlePath) {
+    // a prebuilt box carries no sources, so there is no checkout to read and
+    // this can run anywhere, including a directory that is not a repository.
+    const resolved = path.resolve(bundlePath)
+    // the page boots these bytes with no asset server behind it, so the Metro
+    // assets beside the bundle are embedded the way every other remote path
+    // embeds them. the box service owns the size ceiling, not this producer.
+    let artifact: CloudBoxArtifactProduction
+    try {
+      artifact = await produceCloudBoxArtifact(resolved)
+    } catch (error) {
+      console.error(
+        `  ${rnx} box create: could not prepare the bundle at ${resolved}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      return 1
+    }
+    if (artifact.bytes.byteLength === 0) {
+      console.error(`  ${rnx} box create: the bundle at ${resolved} is empty.`)
+      return 1
+    }
+    for (const warning of artifact.warnings) console.error(`  ${warning}`)
+    source = { bundle: new Uint8Array(artifact.bytes) }
+    defaultName = path.basename(resolved).replace(/\.[^.]+$/, '')
+  } else {
+    const root = findRepositoryPackageRoot(process.cwd())
+    if (!root) {
+      console.error(
+        `  ${rnx} box create: no project here. a box is created from a checkout,\n` +
+          `  so run this inside a git repository that has a package.json.`,
+      )
+      return 1
+    }
+    const checkout = new CheckoutFilePlane(root, { trackedOnly: true })
+    try {
+      await checkout.refresh()
+    } catch (error) {
+      if (error instanceof CheckoutRequiresGitError) {
+        console.error(`  ${rnx} box create: ${error.message}`)
+        return 1
+      }
+      throw error
+    }
+    source = { checkout }
+    defaultName = path.basename(root)
+  }
+
+  const name = flag(args, 'name') ?? defaultName
+  // the ACCOUNT's key. the box service forwards it to /v1/rnx/sessions, which
+  // is what authenticates this caller, names the account, and starts the
+  // session the box is billed against.
+  const { auth, header } = authHeaderOrExit('box create')
+  const apiKey = header.replace(/^Bearer /, '')
+  const accountId = cloudAccountIdOrExit(auth)
+
+  if (!json) console.log(`  ...creating cloud box ${name}`)
+  const connection = {
+    endpoint,
+    apiOrigin: apiOrigin(args, auth),
+    apiKey,
+    accountId,
+  }
+  let session: BoxShellSession | null = null
+  let heartbeat: { stop: () => void } | null = null
+  try {
+    const box =
+      'bundle' in source
+        ? await createPrebuiltBundleBox({ ...connection, bundle: source.bundle, name })
+        : await cloudBoxClient(connection).create({
+            name,
+            stack: template.stack,
+            template: template.provenance,
+            source: source.checkout,
+            onProgress:
+              opts.verbose && !json
+                ? (seeded, total) => console.log(`  ...seeded ${seeded}/${total} files`)
+                : undefined,
+          })
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ...box.description,
+          ...(box.accessToken ? { accessToken: box.accessToken } : {}),
+        }),
+      )
+      return 0
+    }
+    console.log(`  ...created Box ${box.id}`)
+    console.log(
+      'bundle' in source
+        ? `  ...seeded a prebuilt bundle of ${source.bundle.byteLength} bytes`
+        : `  ...seeded ${box.description.files} project files`,
+    )
+    // shown once and never stored: this process does not own a credential
+    // store, and inventing one here would be a second place secrets live.
+    console.log(`  ...box token (shown once): ${box.accessToken}`)
+    // last, so it is the line still on screen when the shell takes over. it
+    // carries no credential: opening it signed in resolves the box through the
+    // account service.
+    if (box.description.pageUrl) {
+      console.log(`  ...open ${box.description.pageUrl}`)
+    }
+    console.log(`  ...accessing shell\n`)
+    session = await box.connect()
+    // bank the wall clock while the shell is open. the box holds no account
+    // credential, so the client that is using it is what keeps the session
+    // alive; when this process dies the sweep closes it at the last heartbeat.
+    const sessionId = box.description.sessionId
+    if (!sessionId) throw new BoxClientError('the box service returned no session id')
+    heartbeat = heartbeatSession({
+      apiOrigin: apiOrigin(args, auth),
+      apiKey,
+      sessionId,
+    })
+    return await repl(session, '')
+  } catch (error) {
+    if (error instanceof BoxClientError) {
+      console.error(`  ${rnx} box create: ${error.message}`)
+      return 1
+    }
+    throw error
+  } finally {
+    heartbeat?.stop()
+    session?.close()
+  }
+}
+
+async function runLocalBox(opts: BoxCommandOptions): Promise<number> {
+  // findRepositoryPackageRoot answers both halves of what a box needs: the
+  // nearest package.json, and only when it sits inside a git repository. git
+  // is what decides which files belong to the project, so a box without it
+  // would have to walk the whole directory tree — measured at 230k files on
+  // this repo against 15k from git.
+  const root = findRepositoryPackageRoot(process.cwd())
+  if (!root) {
+    console.error(
+      `  ${rnxPublicBrand.commandName} box: no project here.\n` +
+        `  the box needs a directory inside a git repository that has a\n` +
+        `  package.json. it asks git which files belong to the project, so it\n` +
+        `  never walks node_modules or build output. run \`git init\` if this is\n` +
+        `  a new project.`,
+    )
+    return 1
+  }
+
+  const plane = new CheckoutFilePlane(root)
+  try {
+    await plane.refresh()
+  } catch (error) {
+    if (error instanceof CheckoutRequiresGitError) {
+      console.error(`  ${rnxPublicBrand.commandName} box: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+
+  let session: BoxShellSession | null = null
+  const client = createBoxClient(
+    createBoxHostProvider({
+      shell: {
+        commands: [
+          createRnxCommand({
+            root,
+            shellCwd: () => session?.cwd ?? PROJECT_MOUNT,
+          }),
+        ],
+        // just-bash's JavaScript rg reads every file body through the plane.
+        // see search-command.ts for the numbers.
+        builtInCommandOverrides: [createSearchCommand({ root })],
+      },
+    }),
+  )
+  const box = await client.create({
+    name: path.basename(root),
+    stack: terminalBoxStack,
+    source: plane,
+  })
+  session = await box.connect()
+
+  const relative = path.relative(root, process.cwd())
+  console.log(`  ...starting local box`)
+  console.log(`  ...mounting ${root} at ${PROJECT_MOUNT}`)
+
+  // authorize this checkout for the bridge daemon so a browser tab can reach
+  // this box's plane. deliberately NOT awaited: a box must not pay for a
+  // bridge that may not be there, and an older daemon never answers at all.
+  const shared = sharePlane(root, { port: opts.port })
+  // two boxes over one checkout is worth SAYING, not refusing. a person with
+  // two terminals in one project is doing something reasonable, and the plane
+  // re-reads the file list before every command, so neither box works from a
+  // stale one. what it does break is an agent mid-run, whose file set changes
+  // underneath it because something else is writing the tree. that is the wave
+  // case, and the wave's own isolation check is where a refusal belongs; this
+  // reports the fact so that check has something to refuse on.
+  void shared.settled.then((outcome) => {
+    if ('declined' in outcome) {
+      if (opts.verbose) console.log(`  ...plane not shared: ${outcome.declined}`)
+      return
+    }
+    if (outcome.holders > 1) {
+      console.error(
+        `\n  ${rnxPublicBrand.commandName} box: ${outcome.holders - 1} other box${
+          outcome.holders > 2 ? 'es are' : ' is'
+        } already open on this checkout.\n` +
+          `  writes from either land on the same files. that is fine for a person\n` +
+          `  with two terminals, and not fine for an agent, whose file set will\n` +
+          `  change underneath it mid-run.\n`,
+      )
+      return
+    }
+    if (opts.verbose) {
+      console.log(`  ...plane shared on the bridge (port ${outcome.port})`)
+    }
+  })
+
+  console.log(`  ...accessing shell\n`)
+  if (opts.verbose) {
+    console.log(`  ${plane.index().size} project files indexed\n`)
+  }
+
+  try {
+    // the checkout is shared with editors, agents, and the user's own terminal.
+    // BoxProjectFs arms a stale bit on each shell turn and refreshes the
+    // plane synchronously on the first actual file access, so commands that
+    // never touch project files pay nothing, while reads always see fresh disk state.
+    return await repl(session, relative)
+  } finally {
+    session.close()
+    shared?.close()
+  }
+}
+
+// the REPL drives whatever holds the shell. locally that is an in-process
+// BoxShell over this checkout; for a cloud box it is a socket to the box,
+// which holds both the files and the shell. same loop, because the only
+// difference is where exec runs.
+
+async function repl(
+  session: BoxShellSession,
+  startRelative: string,
+  beforeCommand?: () => Promise<void>,
+): Promise<number> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+  // enter where the user was standing, so `rnx box` from a subdirectory does
+  // not silently teleport them to the project root.
+  if (startRelative && !startRelative.startsWith('..')) {
+    await session.exec(`cd ${JSON.stringify(startRelative)}`)
+  }
+
+  const prompt = () => {
+    rl.setPrompt(`${session.cwd} > `)
+    rl.prompt()
+  }
+
+  // readline delivers a pasted block, or a piped script, as a burst of `line`
+  // events. run them one at a time in order — dropping the ones that arrive
+  // while a command is running would silently execute only the first line of
+  // a paste.
+  let queue: Promise<void> = Promise.resolve()
+  // stdin ended: stop printing prompts, but still finish what is already
+  // queued — piping a script in must run every line, not just the first.
+  let inputEnded = false
+  // the user typed `exit`: abandon anything still queued behind it.
+  let stopped = false
+  // the command running right now, so Ctrl-C interrupts it rather than the CLI.
+  let interrupt: AbortController | null = null
+
+  const run = async (command: string) => {
+    if (stopped) return
+    const controller = new AbortController()
+    interrupt = controller
+    try {
+      await beforeCommand?.()
+      const result = await session.exec(command, {
+        signal: controller.signal,
+        // written as it arrives rather than collected: a terminal shows a
+        // command's output while it runs, and stderr keeps its own stream so
+        // piping the shell's stdout somewhere still separates the two.
+        onOutput: (stream, chunk) => {
+          if (stream === 'stdout') process.stdout.write(chunk)
+          else process.stderr.write(chunk)
+        },
+      })
+      if (result.exitCode !== 0) console.log(`exit code: ${result.exitCode}`)
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error))
+    } finally {
+      interrupt = null
+    }
+    if (!inputEnded && !stopped) prompt()
+  }
+
+  return new Promise<number>((resolve) => {
+    prompt()
+
+    // Ctrl-C while a command is running interrupts the command. at an idle
+    // prompt there is nothing to interrupt, so it still leaves the shell,
+    // which is the only way out of a box that has stopped answering.
+    rl.on('SIGINT', () => {
+      if (interrupt) {
+        process.stdout.write('^C\n')
+        interrupt.abort()
+        return
+      }
+      stopped = true
+      rl.close()
+    })
+
+    rl.on('line', (line) => {
+      const command = line.trim()
+      if (!command) {
+        queue = queue.then(() => {
+          if (!inputEnded && !stopped) prompt()
+        })
+        return
+      }
+      if (command === 'exit' || command === 'quit') {
+        queue = queue.then(() => {
+          stopped = true
+          rl.close()
+        })
+        return
+      }
+      queue = queue.then(() => run(command))
+    })
+
+    rl.on('close', () => {
+      inputEnded = true
+      // let any already-queued command finish before the process exits.
+      queue.then(() => {
+        console.log()
+        resolve(0)
+      })
+    })
+  })
+}