rnxsim 0.1.313 → 0.1.314

package/cli/hidden-runtime-alias.ts

@@ -0,0 +1,19 @@
+import { getCliInspectVerbMetaByPath } from '@sootsim/skills/cli'
+import type { ParsedArgs } from './parse-args'
+
+const HIDDEN_RUNTIME_ALIAS_GROUPS = ['do', 'get'] as const
+
+export function resolveHiddenRuntimeAlias(parsed: ParsedArgs): ParsedArgs {
+  if (parsed.command) return parsed
+
+  const attempted = parsed.commandArgs.find((arg) => !arg.startsWith('-'))
+  if (!attempted) return parsed
+
+  for (const group of HIDDEN_RUNTIME_ALIAS_GROUPS) {
+    if (getCliInspectVerbMetaByPath(group, attempted)) {
+      return { ...parsed, command: group }
+    }
+  }
+
+  return parsed
+}

package/cli/hints.ts

@@ -0,0 +1,216 @@
+// configurable, identity-scoped hint registry for the sootsim CLI.
+//
+// two problems this solves:
+//   1. the CLI scatters "hint: ..." console.logs across many command files,
+//      each with slightly different wording.
+//   2. agents that loop over the same command (e.g. describe, find) see the
+//      same hint every invocation, which becomes noise.
+//
+// each hint declares its own frequency (always, once-per-identity, or a
+// cooldown), so hints that are informational-but-stale-quickly can still
+// re-fire while advice-like hints stay suppressed for the rest of the
+// CLI identity.
+//
+// suppression is keyed on `getCliIdentityKey()` so two agents / two terminals
+// don't share shown-sets.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+import { getCliIdentityKey } from './current-sim'
+
+export type HintFrequency =
+  | 'always'
+  | 'once-per-identity'
+  | 'once-ever'
+  | { cooldownMs: number }
+
+export interface HintSpec<Args extends unknown[] = unknown[]> {
+  frequency: HintFrequency
+  // returned string(s) are printed as-is, prefixed with two spaces.
+  // return null to skip (useful when render wants to decide conditionally).
+  render: (...args: Args) => string | string[] | null
+}
+
+const registry = new Map<string, HintSpec<any[]>>()
+
+export function defineHint<Args extends unknown[]>(id: string, spec: HintSpec<Args>) {
+  registry.set(id, spec as HintSpec<any[]>)
+}
+
+interface HintStateFile {
+  version: 1
+  shown: Record<string, number> // id -> last-shown timestamp (ms)
+}
+
+const STATE_VERSION = 1 as const
+
+function identityStatePath(): string {
+  return join(tmpdir(), `sootsim-cli-hints-${getCliIdentityKey()}.json`)
+}
+
+function globalStatePath(): string {
+  return join(tmpdir(), `sootsim-cli-hints-global.json`)
+}
+
+function readState(path: string): HintStateFile {
+  if (!existsSync(path)) return { version: STATE_VERSION, shown: {} }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    if (parsed?.version !== STATE_VERSION || !parsed?.shown) {
+      return { version: STATE_VERSION, shown: {} }
+    }
+    return parsed as HintStateFile
+  } catch {
+    return { version: STATE_VERSION, shown: {} }
+  }
+}
+
+function writeState(path: string, state: HintStateFile) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(state) + '\n')
+  } catch {
+    // best-effort only; losing shown state just means a hint re-fires once.
+  }
+}
+
+function modeFromEnv(): 'normal' | 'always' | 'off' {
+  const v = (process.env.SOOTSIM_HINTS || '').toLowerCase()
+  if (v === 'off' || v === '0' || v === 'false') return 'off'
+  if (v === 'always' || v === 'verbose') return 'always'
+  return 'normal'
+}
+
+function shouldShow(id: string, frequency: HintFrequency): boolean {
+  const mode = modeFromEnv()
+  if (mode === 'off') return false
+  if (mode === 'always') return true
+  if (frequency === 'always') return true
+
+  const now = Date.now()
+  if (frequency === 'once-per-identity') {
+    const state = readState(identityStatePath())
+    if (state.shown[id]) return false
+    state.shown[id] = now
+    writeState(identityStatePath(), state)
+    return true
+  }
+  if (frequency === 'once-ever') {
+    const state = readState(globalStatePath())
+    if (state.shown[id]) return false
+    state.shown[id] = now
+    writeState(globalStatePath(), state)
+    return true
+  }
+  if (typeof frequency === 'object' && 'cooldownMs' in frequency) {
+    const state = readState(identityStatePath())
+    const last = state.shown[id] ?? 0
+    if (now - last < frequency.cooldownMs) return false
+    state.shown[id] = now
+    writeState(identityStatePath(), state)
+    return true
+  }
+  return true
+}
+
+// print a registered hint. no-ops if suppressed for this identity/cooldown.
+// returns whether it was actually shown.
+export function maybeHint(id: string, ...args: unknown[]): boolean {
+  const spec = registry.get(id)
+  if (!spec) {
+    if (process.env.SOOTSIM_HINTS_DEBUG) {
+      console.error(`  [hints] no hint registered for id "${id}"`)
+    }
+    return false
+  }
+  if (!shouldShow(id, spec.frequency)) return false
+
+  const body = spec.render(...args)
+  if (body == null) return false
+  const lines = Array.isArray(body) ? body : [body]
+  // always stderr. every hint is advice about how to drive the CLI, never part
+  // of a command's result, and several commands (`describe`, `find`, every
+  // `do` verb) put a JSON document on stdout — a hint printed there corrupts it.
+  for (const line of lines) console.error(`  hint: ${line}`)
+  return true
+}
+
+export function resetHintsForIdentity() {
+  rmSync(identityStatePath(), { force: true })
+}
+
+export function resetGlobalHints() {
+  rmSync(globalStatePath(), { force: true })
+}
+
+export function listHints(): Array<{ id: string; frequency: HintFrequency }> {
+  return Array.from(registry.entries()).map(([id, spec]) => ({
+    id,
+    frequency: spec.frequency,
+  }))
+}
+
+// register the repo-wide hints here. keeping them centralised makes it easy
+// to audit wording + frequency policy in one place.
+defineHint<[number]>('app-still-loading', {
+  // re-fires once a minute because node count may genuinely change as the
+  // bundle boots — telling the user about it again is useful, not noisy.
+  frequency: { cooldownMs: 60_000 },
+  render: (nodeCount) =>
+    `app may still be loading (${nodeCount} nodes). run \`rnxsim wait ready\` first.`,
+})
+
+defineHint<[string]>('wait-selector-for-missing-testid', {
+  // advice is stable; once per CLI identity is enough.
+  frequency: 'once-per-identity',
+  render: (testId) => `rnxsim wait selector ${testId}`,
+})
+
+defineHint<[string[]]>('prefer-cli-over-eval', {
+  frequency: 'once-per-identity',
+  render: (suggestions) => {
+    if (!suggestions.length) return null
+    return [`try the CLI shortcut instead:`, ...suggestions.map((s) => `  ${s}`)]
+  },
+})
+
+defineHint<[]>('describe-use-filters', {
+  // shown when a describe run emits >=80 lines without any filter active —
+  // gentle nudge that there are better tools.
+  frequency: 'once-per-identity',
+  render: () => [
+    `describe output is long. narrow it with:`,
+    `  rnxsim describe --only '*Bottom Sheet*'`,
+    `  rnxsim describe --testid-like 'swap-*'`,
+    `  rnxsim describe --subtree <testID>`,
+  ],
+})
+
+defineHint<[]>('describe-filter-context', {
+  // filtered describe is useful search output, but it intentionally drops
+  // surrounding tree context. once per identity is enough to prevent agents
+  // treating a search hit as route proof.
+  frequency: 'once-per-identity',
+  render: () => [
+    `filtered describe is search output, not current-route proof.`,
+    `run \`rnxsim describe\` without filters after navigation; clipped nodes are marked \`(clipped:...)\`.`,
+  ],
+})
+
+defineHint<[string]>('subtree-root-not-found', {
+  frequency: 'always',
+  render: (id) =>
+    `no node with testID/id "${id}" — try \`rnxsim find --testid ${id}\` to discover available ids.`,
+})
+
+defineHint<[]>('clean-uninstall', {
+  // shown once on the first `sootsim --help` run so users learn the clean
+  // teardown path. package-manager uninstall hooks are best-effort, so the
+  // hint documents the explicit daemon cleanup command.
+  frequency: 'once-ever',
+  render: () => [
+    `to remove the background daemon and all ~/.sootsim data, run \`rnxsim daemon uninstall\`.`,
+    `the optional desktop app and its macOS preference plist are separate from the daemon.`,
+  ],
+})

package/cli/inspect-notice-state.ts

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join, resolve } from 'path'
+
+const INSPECT_NOTICE_STATE_VERSION = 1 as const
+const INSPECT_NOTICE_PATH_ENV = 'SOOTSIM_INSPECT_NOTICE_PATH'
+const INSPECT_NOTICE_ENTRY_TTL_MS = 5 * 60 * 1000
+
+export const INSPECT_NOTICE_COOLDOWN_MS = 15_000
+
+type InspectNoticeKind = 'console' | 'requests'
+
+interface InspectNoticeEntry {
+  signature: string
+  updatedAt: number
+}
+
+interface InspectNoticeState {
+  version: 1
+  entries: Record<string, InspectNoticeEntry>
+}
+
+export function getInspectNoticeStatePath() {
+  return resolve(
+    process.env[INSPECT_NOTICE_PATH_ENV] ||
+      join(tmpdir(), 'sootsim-inspect-notice-state.json'),
+  )
+}
+
+function pruneEntries(
+  entries: Record<string, InspectNoticeEntry>,
+  nowMs: number,
+): Record<string, InspectNoticeEntry> {
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, entry]) => {
+      return (
+        typeof entry?.signature === 'string' &&
+        Number.isFinite(entry?.updatedAt) &&
+        nowMs - entry.updatedAt <= INSPECT_NOTICE_ENTRY_TTL_MS
+      )
+    }),
+  )
+}
+
+function readInspectNoticeState(nowMs: number): InspectNoticeState {
+  const filepath = getInspectNoticeStatePath()
+  if (!existsSync(filepath)) {
+    return { version: INSPECT_NOTICE_STATE_VERSION, entries: {} }
+  }
+
+  try {
+    const parsed = JSON.parse(
+      readFileSync(filepath, 'utf8'),
+    ) as Partial<InspectNoticeState>
+    if (
+      parsed.version !== INSPECT_NOTICE_STATE_VERSION ||
+      !parsed.entries ||
+      typeof parsed.entries !== 'object'
+    ) {
+      rmSync(filepath, { force: true })
+      return { version: INSPECT_NOTICE_STATE_VERSION, entries: {} }
+    }
+    return {
+      version: INSPECT_NOTICE_STATE_VERSION,
+      entries: pruneEntries(parsed.entries as Record<string, InspectNoticeEntry>, nowMs),
+    }
+  } catch {
+    rmSync(filepath, { force: true })
+    return { version: INSPECT_NOTICE_STATE_VERSION, entries: {} }
+  }
+}
+
+function writeInspectNoticeState(state: InspectNoticeState) {
+  const filepath = getInspectNoticeStatePath()
+  mkdirSync(dirname(filepath), { recursive: true })
+  writeFileSync(filepath, JSON.stringify(state, null, 2) + '\n')
+}
+
+function getInspectNoticeKey(kind: InspectNoticeKind, scope: string) {
+  const normalizedScope = scope.trim() || 'default'
+  return `${kind}:${normalizedScope}`
+}
+
+export function shouldPrintInspectNotice(
+  kind: InspectNoticeKind,
+  scope: string,
+  signature: string,
+  opts: { nowMs?: number; cooldownMs?: number } = {},
+) {
+  const nowMs = opts.nowMs ?? Date.now()
+  const cooldownMs = opts.cooldownMs ?? INSPECT_NOTICE_COOLDOWN_MS
+  const state = readInspectNoticeState(nowMs)
+  const key = getInspectNoticeKey(kind, scope)
+  const previous = state.entries[key]
+
+  if (
+    previous &&
+    previous.signature === signature &&
+    nowMs - previous.updatedAt < cooldownMs
+  ) {
+    return false
+  }
+
+  state.entries[key] = {
+    signature,
+    updatedAt: nowMs,
+  }
+  writeInspectNoticeState(state)
+  return true
+}
+
+export function clearInspectNoticeState() {
+  rmSync(getInspectNoticeStatePath(), { force: true })
+}

package/cli/maestro-js.ts

@@ -0,0 +1,334 @@
+// maestro-compatible flow JS engine — mirrors maestro's GraalJsEngine
+// (maestro-client/src/main/java/maestro/js/GraalJsEngine.kt) on top of
+// node's vm module. one context per flow run, shared by the whole flow
+// including runFlow sub-flows, exactly like upstream:
+//
+//   globals: http, output (persistent map), maestro ({copiedText, platform}),
+//   json(), relativePoint(), env vars as bare globals (scope-stacked per
+//   sub-flow), console.log routed to the flow log. undeclared identifiers
+//   evaluate to undefined for `${MY_VAR || 'default'}` patterns (upstream uses
+//   a has-trapping Proxy as globalThis's prototype; node/V8 forbids that, so we
+//   get the same semantics from a with-scope proxy — see the constructor).
+//
+//   `${expr}` string templates are full JS evaluation at command-execution
+//   time (maestro-orchestra-models util/Env.kt): regex (?<!\\)\$\{([^$]*)},
+//   result stringified, `\${...}` escapes to a literal, blank exprs become ''.
+//
+// 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.
+//   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
+//      expressions keep upstream semantics (undefined -> "undefined").
+//   3. `faker` is not implemented — flows using it fail loudly rather than
+//      getting a half-faithful reimplementation of datafaker.
+
+import { spawnSync } from 'child_process'
+import * as vm from 'vm'
+
+const HTTP_TIMEOUT_MS = 300_000 // upstream: okhttp read/write/call timeout 5min
+
+// child process source for synchronous http from inside the vm context.
+// maestro's `http` API is synchronous (scripts do `var res = http.post(...)`),
+// and node has no sync fetch — so the request round-trips through a blocking
+// spawnSync of this script. stdin: JSON request; stdout: JSON response.
+const HTTP_CHILD_SRC = `
+let input = '';
+process.stdin.on('data', (c) => { input += c });
+process.stdin.on('end', async () => {
+  try {
+    const req = JSON.parse(input);
+    const res = await fetch(req.url, {
+      method: req.method,
+      headers: req.headers,
+      body: req.body === undefined || req.body === null ? undefined : req.body,
+    });
+    const body = await res.text();
+    const headers = {};
+    for (const [k, v] of res.headers.entries()) {
+      headers[k] = headers[k] ? headers[k] + ',' + v : v;
+    }
+    process.stdout.write(JSON.stringify({ ok: res.ok, status: res.status, body, headers }));
+  } catch (err) {
+    process.stdout.write(JSON.stringify({ __error: (err && err.message) || String(err) }));
+    process.exitCode = 1;
+  }
+});
+`
+
+interface HttpParams {
+  body?: string
+  headers?: Record<string, string>
+  method?: string
+  multipartForm?: unknown
+}
+
+function executeSyncHttp(
+  url: string,
+  method: string,
+  params?: HttpParams,
+): { ok: boolean; status: number; body: string; headers: Record<string, string> } {
+  if (params?.multipartForm) {
+    throw new Error('http: multipartForm is not supported by rnx yet')
+  }
+  // the http child must be hermetic: when the runner runs under `bun` (or any
+  // process with a debug inspector), the inherited BUN_INSPECT*/NODE_OPTIONS
+  // env makes the spawned `bun -e` attach to the parent's inspector/IPC socket
+  // and exit 1 with no output instead of running our fetch. scrub those so the
+  // child is a clean fetch worker regardless of how the parent was launched.
+  const childEnv = { ...process.env }
+  for (const key of Object.keys(childEnv)) {
+    if (key.startsWith('BUN_INSPECT') || key === 'NODE_OPTIONS') {
+      delete childEnv[key]
+    }
+  }
+  const child = spawnSync(process.execPath, ['-e', HTTP_CHILD_SRC], {
+    input: JSON.stringify({ url, method, headers: params?.headers, body: params?.body }),
+    encoding: 'utf8',
+    timeout: HTTP_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+    env: childEnv,
+  })
+  if (child.error) {
+    throw new Error(`http ${method} ${url} failed: ${child.error.message}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(child.stdout || '')
+  } catch {
+    throw new Error(
+      `http ${method} ${url} failed: no response (${(child.stderr || '').trim().slice(0, 200)})`,
+    )
+  }
+  const result = parsed as {
+    __error?: string
+    ok: boolean
+    status: number
+    body: string
+    headers: Record<string, string>
+  }
+  if (result.__error) {
+    throw new Error(`http ${method} ${url} failed: ${result.__error}`)
+  }
+  return result
+}
+
+// matches upstream Env.kt: negative-lookbehind for the \ escape, [^$]* body.
+const TEMPLATE_RE = /(?<!\\)\$\{([^$]*)\}/g
+const ESCAPED_TEMPLATE_RE = /\\(\$\{[^$]*\})/g
+const BARE_IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+export class MaestroJsContext {
+  private readonly context: vm.Context
+  private readonly envBinding = new Map<string, string>()
+  private readonly envScopeStack: Array<Map<string, string>> = []
+  // env keys currently materialized as context globals — cleared and re-set
+  // before each evaluation, mirroring upstream syncBindingsToContext.
+  private syncedEnvKeys = new Set<string>()
+  readonly output: Record<string, unknown> = {}
+  readonly maestro: { copiedText: string | null; platform: string }
+
+  constructor(opts: { platform?: string; onLog?: (msg: string) => void } = {}) {
+    this.maestro = { copiedText: null, platform: opts.platform ?? 'ios' }
+    const onLog = opts.onLog ?? ((msg: string) => console.log(`[flow]   js: ${msg}`))
+    const sandbox: Record<string, unknown> = {
+      output: this.output,
+      maestro: this.maestro,
+      http: {
+        get: (url: string, params?: HttpParams) => executeSyncHttp(url, 'GET', params),
+        post: (url: string, params?: HttpParams) => executeSyncHttp(url, 'POST', params),
+        put: (url: string, params?: HttpParams) => executeSyncHttp(url, 'PUT', params),
+        delete: (url: string, params?: HttpParams) =>
+          executeSyncHttp(url, 'DELETE', params),
+        request: (url: string, params?: HttpParams) =>
+          executeSyncHttp(url, (params?.method ?? 'GET').toUpperCase(), params),
+      },
+      console: {
+        log: (...args: unknown[]) =>
+          onLog(args.map((a) => (typeof a === 'string' ? a : stringifyJs(a))).join(' ')),
+      },
+    }
+    this.context = vm.createContext(sandbox)
+    // upstream GraalJsEngine resolves undeclared identifiers to undefined via
+    // a has-trapping Proxy installed as globalThis's prototype, enabling the
+    // `${VAR || 'default'}` idiom. node/V8's vm forbids a Proxy in the global
+    // prototype chain ("Proxy is not allowed in the global prototype chain"),
+    // so we get the identical semantics with a `with`-scope proxy instead:
+    // evalRaw wraps every script in `with(__maestroScope){…}`, and the proxy's
+    // has→true makes any bare identifier resolve through the scope (returning
+    // the real global, or undefined for a name that isn't defined) rather than
+    // throwing ReferenceError. plus the json/relativePoint helpers.
+    vm.runInContext(
+      `
+      globalThis.__maestroScope = new Proxy(globalThis, {
+        has() { return true },
+        get(target, key) { return target[key] },
+      })
+      function json(text) { return JSON.parse(text) }
+      function relativePoint(x, y) {
+        var xPercent = Math.ceil(x * 100) + '%'
+        var yPercent = Math.ceil(y * 100) + '%'
+        return xPercent + ',' + yPercent
+      }
+      `,
+      this.context,
+    )
+    // divergence #1: seed env from the shell so `${SOOTSIM_*}` keeps working.
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) this.envBinding.set(key, value)
+    }
+  }
+
+  putEnv(key: string, value: string) {
+    this.envBinding.set(key, value)
+  }
+
+  setCopiedText(text: string | null) {
+    this.maestro.copiedText = text
+  }
+
+  enterEnvScope() {
+    this.envScopeStack.push(new Map(this.envBinding))
+  }
+
+  leaveEnvScope() {
+    const previous = this.envScopeStack.pop()
+    if (previous) {
+      this.envBinding.clear()
+      for (const [k, v] of previous) this.envBinding.set(k, v)
+    }
+  }
+
+  // evaluate a JS snippet in the shared context. mirrors upstream
+  // evalWithIIFE: the script is embedded in a template literal and run
+  // through eval inside an IIFE so var/let/const stay scoped to this
+  // evaluation while the last expression's value is returned.
+  evaluate(script: string, opts: { env?: Record<string, string> } = {}): unknown {
+    const env = opts.env
+    if (env && Object.keys(env).length > 0) {
+      this.enterEnvScope()
+      try {
+        for (const [k, v] of Object.entries(env)) this.envBinding.set(k, v)
+        return this.evalRaw(script)
+      } finally {
+        this.leaveEnvScope()
+      }
+    }
+    return this.evalRaw(script)
+  }
+
+  private evalRaw(script: string): unknown {
+    this.syncEnvToContext()
+    const escaped = script
+      .replace(/\\/g, '\\\\')
+      .replace(/`/g, '\\`')
+      .replace(/\$\{/g, '\\${')
+    // `with(__maestroScope)` gives undeclared identifiers the upstream
+    // undefined semantics (see constructor); the IIFE + direct eval keep
+    // var/let/const scoped to this evaluation while returning the last value.
+    return vm.runInContext(
+      `(function(){ with(__maestroScope){ return eval(\`${escaped}\`) } })()`,
+      this.context,
+    )
+  }
+
+  private syncEnvToContext() {
+    const globals = vm.runInContext('globalThis', this.context) as Record<string, unknown>
+    for (const key of this.syncedEnvKeys) {
+      if (!this.envBinding.has(key)) delete globals[key]
+    }
+    this.syncedEnvKeys = new Set()
+    for (const [key, value] of this.envBinding) {
+      try {
+        globals[key] = value
+        this.syncedEnvKeys.add(key)
+      } catch {
+        // non-writable global (e.g. a frozen builtin name in env) — skip
+      }
+    }
+  }
+
+  // upstream Env.kt String.evaluateScripts: replace every unescaped `${expr}`
+  // with the stringified evaluation result, then unescape `\${...}`.
+  evaluateStringTemplate(value: string): string {
+    const replaced = value.replace(TEMPLATE_RE, (_match, expr: string) => {
+      if (expr.trim().length === 0) return ''
+      const result = this.evaluate(expr)
+      // divergence #2: a bare `${NAME}` that comes back undefined is a flow
+      // bug 100% of the time — fail loudly instead of typing "undefined".
+      if (result === undefined && BARE_IDENTIFIER_RE.test(expr.trim())) {
+        throw new Error(`missing variable for flow placeholder: ${expr.trim()}`)
+      }
+      return stringifyJs(result)
+    })
+    return replaced.replace(ESCAPED_TEMPLATE_RE, (_match, inner: string) => inner)
+  }
+
+  // walk a parsed step and evaluate every string template. nested command
+  // lists are skipped — each nested command evaluates its own strings when
+  // it executes (matching upstream per-command evaluateScripts timing, and
+  // required for values that change between iterations, e.g. copyTextFrom
+  // inside repeat).
+  interpolateStep<T>(step: T): T {
+    return this.interpolateValue(step, null) as T
+  }
+
+  private interpolateValue(value: unknown, parentKey: string | null): unknown {
+    if (typeof value === 'string') {
+      // evalScript IS the evaluation — the runner template-evaluates it in
+      // its handler. interpolating here too would run the script twice.
+      if (parentKey === 'evalScript') return value
+      return this.evaluateStringTemplate(value)
+    }
+    if (Array.isArray(value)) {
+      if (
+        parentKey === 'commands' ||
+        parentKey === 'onFlowStart' ||
+        parentKey === 'onFlowComplete'
+      ) {
+        return value
+      }
+      return value.map((entry) => this.interpolateValue(entry, parentKey))
+    }
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [
+          key,
+          this.interpolateValue(entry, key),
+        ]),
+      )
+    }
+    return value
+  }
+}
+
+function stringifyJs(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value)
+    } catch {
+      return String(value)
+    }
+  }
+  return String(value)
+}
+
+// upstream Orchestra.evaluateCondition scriptCondition semantics: the value
+// arrives already template-evaluated; false when blank / "false" (any case) /
+// "undefined" / "null" / numerically zero. yaml may also hand us a real
+// boolean or number before stringification — normalize first.
+export function scriptConditionIsTruthy(value: unknown): boolean {
+  if (value === undefined || value === null) return false
+  if (typeof value === 'boolean') return value
+  const text = String(value)
+  if (text.trim().length === 0) return false
+  if (text.toLowerCase() === 'false') return false
+  if (text === 'undefined' || text === 'null') return false
+  const num = Number(text)
+  if (!Number.isNaN(num) && num === 0) return false
+  return true
+}

package/cli/open-url.ts

@@ -0,0 +1,8 @@
+export {
+  buildOpenUrlCommand,
+  launchUrl,
+  openUrl,
+  type OpenUrlCommand,
+  type OpenUrlLaunchResult,
+  type OpenUrlOptions,
+} from '../src/host/open-url'