rnxsim 0.1.441 → 0.1.443

package/cli/commands/box.ts

@@ -5,8 +5,13 @@
 // --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 fs from 'node:fs/promises'
 import path from 'node:path'
 import { createInterface } from 'node:readline'
 import { BoxClientError, createBoxClient } from '@rnx/box/client'
@@ -15,21 +20,23 @@ import { PROJECT_MOUNT } from '@rnx/box/shell'
 import { terminalBoxStack } from '@rnx/box/stack'
 import {
   BoxTemplateRegistry,
+  prebuiltBundleBoxTemplate,
   sourceControlBoxTemplate,
   terminalBoxTemplate,
 } from '@rnx/box/template'
 import {
-  cloudBoxBrowserLiveView,
   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 { 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'
@@ -50,49 +57,13 @@ const API_ORIGIN_ENV = 'RNX_API_ORIGIN'
 const BOX_TEMPLATES = new BoxTemplateRegistry([
   terminalBoxTemplate,
   sourceControlBoxTemplate,
+  prebuiltBundleBoxTemplate,
 ])
 
-function usage(): void {
-  const rnx = rnxPublicBrand.commandName
-  console.log(`
-  ${rnx} box — start a local box and enter its shell
-
-  usage:
-    ${rnx} box                     start a local box over the current checkout
-    ${rnx} box create              create a cloud box and enter its shell
-    ${rnx} box create --name=<n>   create a named cloud box
-    ${rnx} box create --template=<id>
-                                   create from a registered Box template
-    ${rnx} box create --endpoint=<url>
-                                   the box service to create it in, or set
-                                   ${ENDPOINT_ENV}
-    ${rnx} box create --json       create without entering the shell
-    ${rnx} box connect <id>        enter the shell of a cloud box you own
-    ${rnx} box connect <id> --json print its reference without a shell
-    ${rnx} box send                send the running local app to a nano box
-    ${rnx} box send --name=<n>     name the box it creates
-    ${rnx} box send --no-auth      leave the signed-in session behind
-    ${rnx} box open <id>           watch a cloud box in your browser
-    ${rnx} box open <id> --print   print the viewing URL instead of opening it
-    ${rnx} box ls                  cloud boxes running on this account
-    ${rnx} box stop --name=<n>     stop a cloud box and its billing
-    ${rnx} box delete --name=<n>   stop it and wipe its files
-
-  a local box mounts this checkout at ${PROJECT_MOUNT}, gives you a shell with
-  ls, cat, find, rg, sed, pipes and redirects, and registers ${rnx} itself as a
-  shell command. writes go straight to the checkout — there is no second copy.
-`)
-}
-
 export async function runBox(
   args: string[],
   opts: BoxCommandOptions = {},
 ): Promise<number> {
-  if (args.includes('--help') || args.includes('-h')) {
-    usage()
-    return 0
-  }
-
   // 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.
@@ -107,6 +78,7 @@ export async function runBox(
 
   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)
@@ -153,17 +125,113 @@ function apiOrigin(args: string[], auth: CliAuth): string {
   ).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 ios --remote` 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
-  const rnx = rnxPublicBrand.commandName
   console.error(
-    `  ${rnx} box ${label}: no cloud box service to talk to.\n` +
+    `  ${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.
@@ -209,12 +277,8 @@ async function runCloudBoxStop(args: string[], purge: boolean): Promise<number>
   const label = purge ? 'delete' : 'stop'
   const endpoint = requireEndpoint(args, label)
   if (!endpoint) return 1
-  const name =
-    flag(args, 'name') ?? path.basename(findRepositoryPackageRoot(process.cwd()) ?? '')
-  if (!name) {
-    console.error(`  ${rnx} box ${label}: which box? pass --name=<n>.`)
-    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)
@@ -228,6 +292,10 @@ async function runCloudBoxStop(args: string[], purge: boolean): Promise<number>
     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`
@@ -279,14 +347,8 @@ async function runCloudBoxList(args: string[]): Promise<number> {
 async function runCloudBoxConnect(args: string[]): Promise<number> {
   const rnx = rnxPublicBrand.commandName
   const json = args.includes('--json')
-  // the first positional is `connect`; the second is the Box.
-  const boxId = args.filter((arg) => !arg.startsWith('-'))[1]
-  if (!boxId) {
-    console.error(
-      `  ${rnx} box connect: which box? pass its ID or name, as \`${rnx} box ls\` prints it.`,
-    )
-    return 1
-  }
+  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
@@ -344,23 +406,21 @@ async function runCloudBoxConnect(args: string[]): Promise<number> {
 /**
  * watch a cloud box in a browser.
  *
- * the box is already running its page in a headless Browser Run tab; this
- * attaches a viewer to that same tab rather than starting a second one. the
- * URL it mints is a short-lived bearer capability, so it is handed straight to
- * the browser and this output is the only place it ever exists.
+ * 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')
-  // the first positional is `open`; the second is the Box.
-  const boxId = args.filter((arg) => !arg.startsWith('-'))[1] ?? flag(args, 'name')
-  if (!boxId) {
-    console.error(
-      `  ${rnx} box open: which box? pass its ID or name, as \`${rnx} box ls\` prints it.`,
-    )
-    return 1
-  }
+  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
@@ -377,7 +437,8 @@ async function runCloudBoxOpen(args: string[]): Promise<number> {
     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.
+    // 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,
@@ -385,25 +446,32 @@ async function runCloudBoxOpen(args: string[]): Promise<number> {
     if (!browser.reused && !json && !print) {
       console.log(`  ...started this box's browser`)
     }
-    const view = await cloudBoxBrowserLiveView({
-      connectUrl,
-      accessToken: reference.token,
-      mode: 'tab',
+    const box = await createBoxClient(
+      createCloudBoxProvider({
+        endpoint: reference.endpoint,
+        authority: { kind: 'attach' },
+      }),
+    ).attach({
+      reference: { boxId: reference.boxId, accessToken: reference.token },
     })
-    if (json) {
-      console.log(
-        JSON.stringify({
-          url: view.url,
-          expiresAt: new Date(Date.now() + view.expiresInMs).toISOString(),
-        }),
+    // 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(view.url)
+      console.log(url)
       return 0
     }
-    return await openInBrowser(view.url)
+    return await openInBrowser(url)
   } catch (error) {
     if (error instanceof BoxClientError) {
       console.error(`  ${rnx} box open: ${error.message}`)
@@ -421,7 +489,7 @@ async function runCloudBoxOpen(args: string[]): Promise<number> {
  * `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.
  */
-async function openInBrowser(url: string): Promise<number> {
+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))
@@ -431,6 +499,49 @@ async function openInBrowser(url: string): Promise<number> {
   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 ios
+ * --remote` 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,
@@ -447,7 +558,20 @@ async function runCloudBoxCreate(
     return 1
   }
 
-  const templateName = flag(args, 'template') ?? sourceControlBoxTemplate.name
+  // --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 })
@@ -458,27 +582,55 @@ async function runCloudBoxCreate(
     return 1
   }
 
-  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 plane = new CheckoutFilePlane(root, { trackedOnly: true })
-  try {
-    await plane.refresh()
-  } catch (error) {
-    if (error instanceof CheckoutRequiresGitError) {
-      console.error(`  ${rnx} box create: ${error.message}`)
+  // 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)
+    let read: Buffer
+    try {
+      read = await fs.readFile(resolved)
+    } catch (error) {
+      console.error(
+        `  ${rnx} box create: could not read the bundle at ${resolved}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
       return 1
     }
-    throw error
+    if (read.byteLength === 0) {
+      console.error(`  ${rnx} box create: the bundle at ${resolved} is empty.`)
+      return 1
+    }
+    source = { bundle: new Uint8Array(read) }
+    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') ?? 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.
@@ -487,25 +639,28 @@ async function runCloudBoxCreate(
   const accountId = cloudAccountIdOrExit(auth)
 
   if (!json) console.log(`  ...creating cloud box ${name}`)
-  const client = createBoxClient(
-    createCloudBoxProvider({
-      endpoint,
-      authority: { kind: 'account', apiOrigin: apiOrigin(args, auth), apiKey, accountId },
-    }),
-  )
+  const connection = {
+    endpoint,
+    apiOrigin: apiOrigin(args, auth),
+    apiKey,
+    accountId,
+  }
   let session: BoxShellSession | null = null
   let heartbeat: { stop: () => void } | null = null
   try {
-    const box = await client.create({
-      name,
-      stack: template.stack,
-      template: template.provenance,
-      source: plane,
-      onProgress:
-        opts.verbose && !json
-          ? (seeded, total) => console.log(`  ...seeded ${seeded}/${total} files`)
-          : undefined,
-    })
+    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({
@@ -516,7 +671,11 @@ async function runCloudBoxCreate(
       return 0
     }
     console.log(`  ...created Box ${box.id}`)
-    console.log(`  ...seeded ${box.description.files} project files`)
+    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}`)