rnxsim 0.1.376 → 0.1.378

package/cli/help-core.ts

@@ -0,0 +1,136 @@
+import { cliCommandMetas } from '@sootsim/skills/cli'
+import {
+  renderCliCommandHelp,
+  renderCliGroupHelp,
+  renderCliIndexHelp,
+} from '@sootsim/skills/cli/renderers'
+import { formatFlagHelp } from 'sootsim-engine/settings/cli-flags'
+import {
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+  DEFAULT_SOOTSIM_BRIDGE_URL,
+} from '../src/bridge-constants'
+import {
+  getRnxCommandAvailability,
+  getRnxFirstPositional,
+  getRnxCommandRegistration,
+  RNX_COMMAND_REGISTRY,
+} from './command-registry'
+import type { RnxBackendKind } from './command-contract'
+
+export interface RnxHelpOptions {
+  backend: RnxBackendKind
+  command?: string | null
+  commandArgs?: string[]
+  prefer?: 'command' | 'verb'
+  group?: string | null
+}
+
+const HELP_CONTEXT = {
+  bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+  defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
+}
+
+function backendLabel(command: string, args: readonly string[]): string {
+  const available = (['node', 'browser'] satisfies RnxBackendKind[]).filter(
+    (backend) => getRnxCommandAvailability(command, args, backend).available,
+  )
+  return `available backends: ${available.join(', ')}`
+}
+
+function renderWebHelp(): string {
+  return `rnx web — select or ensure the current branch's existing web preview
+
+usage:
+  rnx web
+
+The browser backend selects the Factory-owned web iframe. It never launches a
+browser, host process, or Cloudflare runtime.`
+}
+
+function renderFactoryBrowserLeaves(command: string): string | null {
+  switch (command) {
+    case 'do':
+      return `Factory browser leaves:
+  rnx do navigate /route`
+    case 'shell':
+      return `Factory browser leaves:
+  rnx shell appearance light|dark`
+    case 'assert':
+      return `Factory browser leaves:
+  rnx assert find (--testid <id>|--text <text>|--role <role>) [--exists|--empty] [--contains <text>]`
+    case 'screenshot':
+      return `Factory browser leaves:
+  rnx screenshot
+  rnx screenshot ask <question>
+  rnx screenshot appearance light|dark /route --by <query-kind> --value <target>
+  rnx screenshot motion <task-id> /route --trigger-by <kind> --trigger-value <target> --result-by <kind> --result-value <target> [--duration-ms <100..2000>]`
+    default:
+      return null
+  }
+}
+
+function renderRootAvailability(backend: RnxBackendKind): string {
+  const visibleCommands = new Set([...cliCommandMetas.map((meta) => meta.id), 'web'])
+  const visibleRegistry = RNX_COMMAND_REGISTRY.filter((entry) =>
+    visibleCommands.has(entry.name),
+  )
+  const available = visibleRegistry
+    .filter((entry) => getRnxCommandAvailability(entry.name, [], backend).available)
+    .map((entry) => entry.name)
+  const unavailable = visibleRegistry
+    .filter((entry) => !getRnxCommandAvailability(entry.name, [], backend).available)
+    .map((entry) => entry.name)
+
+  return `backend availability (${backend}):
+  available:   ${available.join(', ')}
+  unavailable: ${unavailable.join(', ')}
+
+Run \`rnx <command> --help\` for leaf availability and usage.`
+}
+
+export function renderRnxHelp(options: RnxHelpOptions): string {
+  const command = options.command ?? null
+  const commandArgs = options.commandArgs ?? []
+  if (!command) {
+    return `${renderCliIndexHelp(HELP_CONTEXT, formatFlagHelp()).trimEnd()}
+
+browser preview selector:
+  rnx web                     select the existing Factory web preview
+
+${renderRootAvailability(options.backend)}`
+  }
+
+  let body: string | null
+  if (command === 'web') {
+    body = renderWebHelp()
+  } else if (options.group === command && !options.prefer) {
+    body = renderCliGroupHelp(command, HELP_CONTEXT, formatFlagHelp())
+  } else {
+    const subVerb = getRnxFirstPositional(commandArgs)
+    const grouping = new Set(['do', 'get', 'debug', 'wait'])
+    const helpName = options.prefer === 'verb' && subVerb ? subVerb : command
+    body = renderCliCommandHelp(helpName, HELP_CONTEXT, {
+      prefer: options.prefer,
+      group: options.group,
+    })
+    if (!body && grouping.has(command)) {
+      body = renderCliGroupHelp(command, HELP_CONTEXT, formatFlagHelp())
+    }
+  }
+
+  if (!body) return `unknown command: ${command}`
+
+  const registration = getRnxCommandRegistration(command)
+  if (!registration) return body
+  const current = getRnxCommandAvailability(command, commandArgs, options.backend)
+  const currentLine = current.available
+    ? `${options.backend} backend: available`
+    : `${options.backend} backend: ${current.reason}`
+  const factoryLeaves =
+    options.backend === 'browser' ? renderFactoryBrowserLeaves(command) : null
+  return `${body.trimEnd()}
+
+${factoryLeaves ? `${factoryLeaves}\n\n` : ''}${backendLabel(command, commandArgs)}
+
+${currentLine}`
+}

package/cli/help.ts

@@ -1,61 +1,29 @@
-import {
-  renderCliCommandHelp,
-  renderCliGroupHelp,
-  renderCliIndexHelp,
-} from '@sootsim/skills/cli/renderers'
-import { formatFlagHelp } from 'sootsim-engine/settings/cli-flags'
 import { BETA_TAGLINE, IS_BETA } from '../src/beta'
-import {
-  DEFAULT_SOOTSIM_BRIDGE_PORT,
-  DEFAULT_SOOTSIM_BRIDGE_URL,
-} from '../src/bridge-constants'
 import { getCliVersion } from '../src/cli-version'
 import { rnxPublicBrand } from '../src/public-brand'
+import { renderRnxHelp } from './help-core'
 import { maybeHint } from './hints'
 import { getRuntimeSummary } from './runtime-summary'
 
-// header line shown at the top of `--help` so users can always tell what
-// they're running — the CLI npm version and the active engine runtime
-// version are independent, which is exactly the confusion `sootsim
-// upgrade` exists to clear up.
 function versionSummaryLine(): string {
   return `${rnxPublicBrand.commandName} CLI v${getCliVersion()} · ${getRuntimeSummary().primary}`
 }
 
-export function printHelp() {
-  const base = renderCliIndexHelp(
-    {
-      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
-      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
-    },
-    formatFlagHelp(),
-  )
+export function printHelp(): void {
   const betaLine = IS_BETA ? `\n${BETA_TAGLINE}\n` : ''
   console.log(
-    `${versionSummaryLine()}\n${betaLine}${base}
-`,
+    `${versionSummaryLine()}\n${betaLine}${renderRnxHelp({ backend: 'node' })}\n`,
   )
-  // once-ever nudge so users learn the clean teardown path before they need it.
-  // the npm preuninstall hook runs the same teardown automatically when it
-  // fires; this is the documented manual fallback.
   maybeHint('clean-uninstall')
 }
 
-// bare `sootsim` prints the registry-backed surface. setup/open own work.
-
-// print the help page for a grouping verb (do / get / debug / wait) built
-// entirely from the registry — no hardcoded strings. returns true if the
-// group was known, false if the caller should fall through.
 export function printGroupHelp(group: string): boolean {
-  const output = renderCliGroupHelp(
+  const output = renderRnxHelp({
+    backend: 'node',
+    command: group,
     group,
-    {
-      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
-      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
-    },
-    formatFlagHelp(),
-  )
-  if (!output) return false
+  })
+  if (output.startsWith('unknown command:')) return false
   console.log(`${output}\n`)
   return true
 }
@@ -63,18 +31,14 @@ export function printGroupHelp(group: string): boolean {
 export function printCommandHelp(
   name: string,
   options: { prefer?: 'command' | 'verb'; group?: string | null } = {},
-) {
-  const output = renderCliCommandHelp(
-    name,
-    {
-      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
-      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
-    },
-    options,
-  )
-  if (!output) {
-    console.log(`unknown command: ${name}`)
-    return
-  }
+): void {
+  const command = options.group ?? name
+  const output = renderRnxHelp({
+    backend: 'node',
+    command,
+    commandArgs: options.group ? [name] : [],
+    prefer: options.prefer,
+    group: options.group,
+  })
   console.log(`${output}\n`)
 }

package/cli/hints.ts

@@ -46,11 +46,11 @@ interface HintStateFile {
 const STATE_VERSION = 1 as const
 
 function identityStatePath(): string {
-  return join(tmpdir(), `sootsim-cli-hints-${getCliIdentityKey()}.json`)
+  return join(tmpdir(), `rnx-cli-hints-${getCliIdentityKey()}.json`)
 }
 
 function globalStatePath(): string {
-  return join(tmpdir(), `sootsim-cli-hints-global.json`)
+  return join(tmpdir(), `rnx-cli-hints-global.json`)
 }
 
 function readState(path: string): HintStateFile {
@@ -76,7 +76,7 @@ function writeState(path: string, state: HintStateFile) {
 }
 
 function modeFromEnv(): 'normal' | 'always' | 'off' {
-  const v = (process.env.SOOTSIM_HINTS || '').toLowerCase()
+  const v = (process.env.RNX_HINTS || '').toLowerCase()
   if (v === 'off' || v === '0' || v === 'false') return 'off'
   if (v === 'always' || v === 'verbose') return 'always'
   return 'normal'
@@ -119,7 +119,7 @@ function shouldShow(id: string, frequency: HintFrequency): boolean {
 export function maybeHint(id: string, ...args: unknown[]): boolean {
   const spec = registry.get(id)
   if (!spec) {
-    if (process.env.SOOTSIM_HINTS_DEBUG) {
+    if (process.env.RNX_HINTS_DEBUG) {
       console.error(`  [hints] no hint registered for id "${id}"`)
     }
     return false
@@ -210,7 +210,7 @@ defineHint<[]>('clean-uninstall', {
   // hint documents the explicit daemon cleanup command.
   frequency: 'once-ever',
   render: () => [
-    `to remove the background daemon and all ~/.sootsim data, run \`rnx daemon uninstall\`.`,
+    `to remove the background daemon and all ~/.rnx data, run \`rnx daemon uninstall\`.`,
     `the optional desktop app and its macOS preference plist are separate from the daemon.`,
   ],
 })

package/cli/inspect-notice-state.ts

@@ -23,7 +23,7 @@ interface InspectNoticeState {
 export function getInspectNoticeStatePath() {
   return resolve(
     process.env[INSPECT_NOTICE_PATH_ENV] ||
-      join(tmpdir(), 'sootsim-inspect-notice-state.json'),
+      join(tmpdir(), 'rnx-inspect-notice-state.json'),
   )
 }
 

package/cli/maestro-js.ts

@@ -17,7 +17,7 @@
 // divergences (deliberate, sootsim-side ergonomics — keep this list short):
 //   1. envBinding is seeded from the full process.env, not just MAESTRO_*.
 //      sootsim flows historically resolve `${SOOTSIM_*}` credentials from the
-//      shell environment and `sootsim maestro --env K=V` writes process.env.
+//      shell environment and `rnx maestro --env K=V` writes process.env.
 //   2. a *bare identifier* template (`${NAME}`) that evaluates to undefined
 //      throws a loud "missing variable" error instead of interpolating the
 //      literal text "undefined" into a tap target or login form. complex

package/cli/outbound-endpoints.ts

@@ -9,6 +9,7 @@ export type OutboundCategory =
   | 'local-development'
   | 'same-origin-runtime'
   | 'guest-app-network'
+  | 'release-delivery'
 
 export interface OutboundEndpointDeclaration {
   category: OutboundCategory
@@ -38,11 +39,18 @@ export const OUTBOUND_ENDPOINTS: Record<string, OutboundEndpointDeclaration> = {
     payload:
       'explicit auth, billing, preview, issue report, test, or generated-flow request; a stored login may refresh auth/subscription state',
   },
-  npm_update_check: {
+  cli_delivery: {
     category: 'explicit-user-action',
-    destination: 'https://registry.npmjs.org/rnxsim/latest',
+    destination:
+      'https://r2.rnxsim.com/rnx-cli/channels/stable and the selected executable/checksum',
+    preConsent: false,
+    payload: 'requested CLI version, platform, and architecture only',
+  },
+  cli_release_publish: {
+    category: 'release-delivery',
+    destination: 'configured R2 origin and https://r2.rnxsim.com/rnx-cli',
     preConsent: false,
-    payload: 'package update request only',
+    payload: 'release executables, checksums, version, and source identity',
   },
   release_notes: {
     category: 'explicit-user-action',
@@ -332,10 +340,20 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     { category: 'contrast_user_action', count: 1 },
   'packages/sootsim/cli/commands/screenshots-capture.ts :: fetch :: `${apiOrigin}/api/sootsim/screenshot-decks?org=${encodeURIComponent(org)}&repo=${encodeURIComponent(repo)}`':
     { category: 'contrast_user_action', count: 1 },
-  'packages/sootsim/cli/commands/upgrade.ts :: fetch :: REGISTRY_LATEST_URL': {
-    category: 'npm_update_check',
+  'packages/sootsim/cli/commands/upgrade.ts :: fetch :: url': {
+    category: 'cli_delivery',
     count: 1,
   },
+  'packages/sootsim/scripts/publish-cli-binaries.ts :: fetch :: `${url}?sha256=${digest}`':
+    {
+      category: 'cli_release_publish',
+      count: 1,
+    },
+  'packages/sootsim/scripts/publish-cli-binaries.ts :: fetch :: `${publicOrigin}/${channelKey}?sourceSha=${sourceSha}`':
+    {
+      category: 'cli_release_publish',
+      count: 1,
+    },
   'packages/sootsim/cli/commands/upload.ts :: fetch :: url': {
     category: 'presigned_upload',
     count: 1,

package/cli/parse-args.ts

@@ -1,5 +1,7 @@
 // shared CLI argument parser — handles global flags, commands, and per-command flags
 
+import { RNX_COMMAND_NAMES, RNX_NODE_COMMAND_NAMES } from './command-registry'
+
 export interface ParsedArgs {
   command: string | null
   commandArgs: string[]
@@ -7,6 +9,7 @@ export interface ParsedArgs {
   help: boolean
   version: boolean
   verbose: boolean
+  warnings: string[]
 }
 
 const GLOBAL_FLAGS: Record<
@@ -30,9 +33,9 @@ const GLOBAL_FLAGS: Record<
 
 // top-level verbs that route into runInspect. the surface is intentionally
 // tiny — everything else lives under one of the grouping verbs:
-//   - `sootsim get <noun>`        reads
-//   - `sootsim do <action>`       writes
-//   - `sootsim debug <tool>`      instrumentation (handled by runDebug)
+//   - `rnx get <noun>`        reads
+//   - `rnx do <action>`       writes
+//   - `rnx debug <tool>`      instrumentation (handled by runDebug)
 // `describe` and `find` stay at root as the most common entrypoints.
 // `list` stays at root because it's a sim-management read.
 export const TOP_LEVEL_RUNTIME_COMMANDS = new Set([
@@ -47,9 +50,9 @@ export const TOP_LEVEL_RUNTIME_COMMANDS = new Set([
   'shell',
 ])
 
-// grouping verbs that take a sub-verb (`sootsim wait ready`,
-// `sootsim do tap-id`). agents and humans very often type the hyphenated
-// form (`sootsim wait-ready`, `sootsim do-tap-id`) — it reads as one
+// grouping verbs that take a sub-verb (`rnx wait ready`,
+// `rnx do tap-id`). agents and humans very often type the hyphenated
+// form (`rnx wait-ready`, `rnx do-tap-id`) — it reads as one
 // command and matches the typed-tool names (rnx_wait_ready). bin.ts
 // normalizes `<verb>-<rest>` → `<verb> <rest>` for these so the intuitive
 // spelling just works instead of failing as "unknown command".
@@ -60,64 +63,9 @@ export const HYPHENATED_GROUPING_VERBS = new Set(['do', 'get', 'wait', 'shell',
 // `packages/sootsim-skills/src/cli/meta.ts` (or sit on the internal
 // allowlist in `test/sootsimCliRegistry.test.ts`), so help, website docs,
 // and agent skills can never drift from what the parser accepts.
-export const COMMANDS = new Set([
-  'detox',
-  'maestro',
-  'record',
-  'film',
-  'storage',
-  'permissions',
-  'perf',
-  'screenshot',
-  'state',
-  'reset',
-  'camera',
-  'mode',
-  'debug',
-  'timeline',
-  'what-happened',
-  'shell',
-  'assert',
-  'device',
-  'open',
-  // platform entrypoints — start a simulator on that platform. the execution
-  // environment (host, local box, cloud box) comes from the command context,
-  // not from a separate spelling per place.
-  'ios',
-  'android',
-  // the box environment: bare `box` is local, `box create` is cloud.
-  'box',
-  'list',
-  'use',
-  'claim',
-  'close',
-  'compat',
-  'report-issue',
-  'desktop',
-  'login',
-  'logout',
-  'auth',
-  'setup',
-  'serve',
-  'daemon',
-  'runtime',
-  'upgrade',
-  'version',
-  'skill',
-  'config',
-  'cleanup',
-  // stage config-plugin fonts into a build's asset manifest (run.sh build path)
-  'app-fonts',
-  // internal — not user-facing, spawned as a subprocess by electron main
-  // and by `sootsim agent start`.
-  'agent-wrapper',
-  // attached projects + local agent sessions.
-  'agent',
-  ...TOP_LEVEL_RUNTIME_COMMANDS,
-])
+export const COMMANDS = new Set(RNX_NODE_COMMAND_NAMES)
 
-export function parseArgs(argv: string[]): ParsedArgs {
-  const args = argv.slice(2)
+export function parseRnxArgs(args: string[]): ParsedArgs {
   const result: ParsedArgs = {
     command: null,
     commandArgs: [],
@@ -125,6 +73,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     help: false,
     version: false,
     verbose: false,
+    warnings: [],
   }
 
   let i = 0
@@ -154,14 +103,14 @@ export function parseArgs(argv: string[]): ParsedArgs {
         const val = args[i + 1]
         if (val === undefined || val.startsWith('-')) {
           // missing value — treat as error, pass through
-          console.error(`  warning: ${arg} requires a value`)
+          result.warnings.push(`  warning: ${arg} requires a value`)
           i++
           continue
         }
         if (def.type === 'number') {
           const num = Number(val)
           if (Number.isNaN(num)) {
-            console.error(`  warning: ${arg} requires a number, got "${val}"`)
+            result.warnings.push(`  warning: ${arg} requires a number, got "${val}"`)
             i += 2
             continue
           }
@@ -193,7 +142,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
           break
         }
       }
-      if (COMMANDS.has(arg)) {
+      if (RNX_COMMAND_NAMES.has(arg)) {
         result.command = arg
         const rest = args.slice(i + 1)
         // strip leading -- separator if present
@@ -217,3 +166,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
 
   return result
 }
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  return parseRnxArgs(argv.slice(2))
+}

package/cli/recording-access.ts

@@ -42,7 +42,7 @@ export interface RecordingEntitlementOptions {
    *  origin stored in the shared desktop session. */
   originOverride?: string
   /** allow GitHub installation/action auth to record for pr preview uploads.
-   *  this is intentionally opt-in so local `sootsim record` stays tied to
+   *  this is intentionally opt-in so local `rnx record` stays tied to
    *  the user's paid/trial desktop entitlement. */
   allowGitHubAuth?: boolean
 }

package/cli/registry.ts

@@ -1 +1,2 @@
 export * from '@sootsim/skills/cli'
+export * from './command-registry'

package/cli/run-registry.ts

@@ -99,7 +99,7 @@ export function resolveRunProvenance(): RunProvenance {
 
   const branch = contrastBranch ?? gitOutput('git rev-parse --abbrev-ref HEAD')
   // env slug wins when present; otherwise infer from the github remote so a
-  // a plain local `sootsim maestro test --preview` still lands on its repo's dashboard.
+  // a plain local `rnx maestro test --preview` still lands on its repo's dashboard.
   const remote = envOwner ? null : ownerRepoFromGitRemote()
   return {
     owner: envOwner ?? remote?.owner ?? null,

package/cli/run-rnx-core.ts

@@ -0,0 +1,148 @@
+import {
+  createRnxCommandInvocation,
+  getRnxCommandAvailability,
+  getRnxFirstPositional,
+} from './command-registry'
+import { renderRnxHelp } from './help-core'
+import { resolveHiddenRuntimeAlias } from './hidden-runtime-alias'
+import { parseRnxArgs } from './parse-args'
+import type {
+  CommandArtifact,
+  CommandExecutionResult,
+  CommandWriter,
+  RunRnxCoreOptions,
+  SemanticInvocation,
+} from './command-contract'
+
+interface CapturedCommandWriter {
+  writer: CommandWriter
+  stdout: string[]
+  stderr: string[]
+}
+
+function createCapturedWriter(writer?: CommandWriter): CapturedCommandWriter {
+  const stdout: string[] = []
+  const stderr: string[] = []
+  return {
+    stdout,
+    stderr,
+    writer: {
+      stdout(text) {
+        stdout.push(text)
+        writer?.stdout(text)
+      },
+      stderr(text) {
+        stderr.push(text)
+        writer?.stderr(text)
+      },
+    },
+  }
+}
+
+function result(
+  captured: CapturedCommandWriter,
+  exitCode: number,
+  invocations: SemanticInvocation[] = [],
+  artifacts: CommandArtifact[] = [],
+): CommandExecutionResult {
+  return {
+    exitCode,
+    stdout: captured.stdout.join(''),
+    stderr: captured.stderr.join(''),
+    invocations,
+    artifacts,
+  }
+}
+
+export async function runRnxCore(
+  argv: string[],
+  options: RunRnxCoreOptions,
+): Promise<CommandExecutionResult> {
+  const captured = createCapturedWriter(options.writer)
+  const signal = options.signal ?? new AbortController().signal
+  let parsed = parseRnxArgs(argv)
+  for (const warning of parsed.warnings) captured.writer.stderr(`${warning}\n`)
+
+  if (!parsed.command && parsed.commandArgs.length > 0) {
+    parsed = resolveHiddenRuntimeAlias(parsed)
+  }
+
+  if (parsed.version) {
+    captured.writer.stderr(
+      'rnx --version is unavailable in the browser backend; use the node backend.\n',
+    )
+    return result(captured, 1)
+  }
+
+  if (!parsed.command) {
+    if (parsed.commandArgs.length > 0) {
+      const attempted = getRnxFirstPositional(parsed.commandArgs) ?? parsed.commandArgs[0]
+      captured.writer.stderr(`unknown command: ${attempted}\n`)
+      return result(captured, 1)
+    }
+    captured.writer.stdout(`${renderRnxHelp({ backend: options.backend.kind })}\n`)
+    return result(captured, 0)
+  }
+
+  const command = parsed.command
+  const helpRequested =
+    parsed.help ||
+    parsed.commandArgs.includes('--help') ||
+    parsed.commandArgs.includes('-h')
+  if (helpRequested) {
+    const grouping = new Set(['do', 'get', 'debug', 'wait'])
+    const subVerb = getRnxFirstPositional(parsed.commandArgs)
+    captured.writer.stdout(
+      `${renderRnxHelp({
+        backend: options.backend.kind,
+        command,
+        commandArgs: parsed.commandArgs,
+        prefer: grouping.has(command) && subVerb ? 'verb' : undefined,
+        group: grouping.has(command) ? command : undefined,
+      })}\n`,
+    )
+    return result(captured, 0)
+  }
+
+  const availability = getRnxCommandAvailability(
+    command,
+    parsed.commandArgs,
+    options.backend.kind,
+  )
+  if (!availability.available) {
+    captured.writer.stderr(`${availability.reason ?? `rnx ${command} is unavailable`}\n`)
+    return result(captured, 1)
+  }
+
+  if (signal.aborted) {
+    captured.writer.stderr('rnx: command cancelled\n')
+    return result(captured, 1)
+  }
+
+  const invocation = createRnxCommandInvocation({
+    command,
+    args: parsed.commandArgs,
+    globalFlags: parsed.globalFlags,
+  })
+
+  try {
+    const execution = await options.backend.execute(invocation, {
+      writer: captured.writer,
+      signal,
+    })
+    return result(
+      captured,
+      execution.exitCode,
+      execution.invocations,
+      execution.artifacts,
+    )
+  } catch (error) {
+    const message = signal.aborted
+      ? 'command cancelled'
+      : error instanceof Error
+        ? error.message
+        : String(error)
+    captured.writer.stderr(`rnx: ${message}\n`)
+    return result(captured, 1)
+  }
+}