peachsim 0.1.1644 → 0.1.1653

package/cli/commands/coverage.ts

@@ -0,0 +1,550 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { VERIFIED_SURFACES } from '@peach/compat/verified-map'
+import {
+  VERIFIED_AXES,
+  VERIFIED_SOURCE_API_ROOTS,
+  verifiedSourceApiDoors,
+  type VerifiedSurface,
+} from '@peach/compat/verified-map-types'
+import { resolveCompatVersionRange } from '@peach/compat/version-range'
+import { z } from 'zod'
+import { resolveCapabilityReferences } from '../../../../scripts/lib/capability-reference-resolution'
+import {
+  capabilitySourceExclusion,
+  collectCapabilityReferences,
+  type CapabilityReferenceCandidate,
+} from '../../../../scripts/lib/capability-source-references'
+import { withTypeScriptSourceParser } from '../../../../scripts/lib/native-typescript-parser'
+import inventoryData from '../../../peach-compat/src/generated/capability-inventory.json'
+import { coverageParserPath } from './coverage-parser'
+import { readProjectManifest, resolveManifestVersions } from './detect'
+import type { ProjectManifest } from './projectReportContract'
+
+const SOURCE_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+])
+// validate the snapshot fields this consumer reads, without changing proof schemas.
+const inventorySchema = z.object({
+  generatedAt: z.string(),
+  sourceApiSnapshots: z.array(
+    z.object({
+      exportName: z.string(),
+      module: z.string(),
+      sourceApiVersion: z.string(),
+    }),
+  ),
+  rows: z.array(
+    z.object({
+      id: z.string(),
+      packageName: z.string(),
+      upstreamKind: z.enum([
+        'event',
+        'export',
+        'imperative-method',
+        'native-module',
+        'prop',
+        'subsystem',
+      ]),
+      upstreamName: z.string(),
+      supportedVersionRange: z.string(),
+      exactTestedVersion: z.string(),
+      platforms: z.array(z.enum(['ios', 'android'])),
+      publicReferencePaths: z
+        .array(
+          z.object({
+            module: z.string(),
+            exportName: z.string(),
+            memberName: z.string().nullable(),
+          }),
+        )
+        .optional(),
+    }),
+  ),
+})
+
+export interface CoverageGraphRequest {
+  entry?: string
+  platform: 'ios' | 'android'
+}
+
+interface FinalGraph {
+  source: 'contrast-bundler-final-build'
+  entry: string | null
+  entrySource: 'requested' | 'manifest' | 'conventional' | null
+  platform: 'ios' | 'android'
+  modules: number
+  projectModules: number
+  packageModules: number
+  nullDependencySlots: { project: number; package: number }
+  warnings: number
+  complete: true | null
+  unsupportedAliases: string[]
+  artifactVersions: Record<string, string>
+}
+
+// the project's own modules of the final build, as app-relative paths. the build
+// is the canonical Contrast bundler compile, which returns the final graph
+// without running the project, so no second build configuration or resolver
+// exists and no app code executes. package modules are artifacts and are
+// counted, never scanned.
+async function readFinalGraph(
+  app: string,
+  request: CoverageGraphRequest,
+): Promise<{ error: string } | { graph: FinalGraph; projectModules: Set<string> }> {
+  const { compileProject } = await import('../../../contrast-bundler/compile/project')
+  let compiled: ReturnType<typeof compileProject>
+  try {
+    compiled = compileProject({
+      dir: app,
+      entry: request.entry,
+      platform: request.platform,
+    })
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) }
+  }
+  const { report, closure } = compiled
+  // a build that did not reach `compiled` is a failed build even when it kept a
+  // closure: the graph reaches files the toolchain could not transform.
+  if (report.stage !== 'compiled' || !closure) {
+    return { error: report.error ?? `the build stopped at stage ${report.stage}` }
+  }
+  const projectPrefix = '/app/'
+  const modulePrefix = '/app/node_modules/'
+  const projectModules = new Set<string>()
+  let packageModules = 0
+  let projectNullSlots = 0
+  let packageNullSlots = 0
+  for (const module of closure.bundle.modules) {
+    const nulls = module.dependencies.filter((dependency) => dependency == null).length
+    if (module.path.startsWith(projectPrefix) && !module.path.startsWith(modulePrefix)) {
+      projectModules.add(module.path.slice(projectPrefix.length))
+      projectNullSlots += nulls
+    } else {
+      packageModules++
+      packageNullSlots += nulls
+    }
+  }
+  const graph: FinalGraph = {
+    source: 'contrast-bundler-final-build',
+    entry: report.entry?.slice(projectPrefix.length) ?? null,
+    entrySource: report.entrySource,
+    platform: request.platform,
+    modules: closure.bundle.modules.length,
+    projectModules: projectModules.size,
+    packageModules,
+    // null slots are informational: a NODE_ENV-excluded branch is a known absent
+    // edge and an unresolved optional require is not, so only the bundler's own
+    // entryClosures.complete decides.
+    nullDependencySlots: { project: projectNullSlots, package: packageNullSlots },
+    warnings: closure.bundle.warnings.length,
+    complete: closure.entryClosures.complete ? true : null,
+    unsupportedAliases: report.unsupportedAliases,
+    // artifact versions of the packages the closure compiled, not the repository's
+    // installed or locked versions.
+    artifactVersions: report.versions,
+  }
+  return { graph, projectModules }
+}
+
+export async function createCoverageReport(
+  appDirectory: string,
+  requestedSources: readonly string[] = [],
+  graphRequest?: CoverageGraphRequest,
+) {
+  const app = resolve(appDirectory)
+  const manifest = readProjectManifest(app)
+  if (!manifest) throw new Error(`coverage needs a package.json in ${app}`)
+  const inventory = inventorySchema.parse(inventoryData)
+  const versionOwners = new Map<string, ReturnType<typeof resolveManifestVersions>>()
+  const lockfiles = new Map<string, Map<string, string>>()
+  const sourceOwners = new Map<string, string>()
+  const packageOwners = new Map<string, string>()
+  const ownerManifests = new Map<string, ProjectManifest | null>()
+  const surfaces: readonly VerifiedSurface[] = VERIFIED_SURFACES
+  const sourceRoots = (requestedSources.length ? requestedSources : ['.']).map((path) => {
+    const local = relative(app, resolve(app, path)).split(sep).join('/') || '.'
+    if (local === '..' || local.startsWith('../') || isAbsolute(local))
+      throw new Error('--source must stay inside the app directory')
+    let ancestor = app
+    for (const part of local.split('/')) {
+      ancestor = join(ancestor, part)
+      if (lstatSync(ancestor).isSymbolicLink())
+        throw new Error('--source cannot traverse symbolic links')
+    }
+    return local
+  })
+  const files = new Map<string, string>()
+  const unknowns: { path: string; reason: string }[] = []
+  const pending = [...sourceRoots]
+  let entries = 0
+  let bytes = 0
+  let limited = false
+  while (pending.length) {
+    const path = pending.pop()
+    if (path === undefined || files.has(path)) continue
+    if (++entries > 100_000) {
+      limited = true
+      break
+    }
+    try {
+      const full = resolve(app, path)
+      const stat = lstatSync(full)
+      if (stat.isSymbolicLink()) {
+        unknowns.push({ path, reason: 'symbolic link was not followed' })
+        continue
+      }
+      if (stat.isDirectory()) {
+        if (
+          capabilitySourceExclusion(
+            `${path === '.' ? '' : `${path}/`}__source.ts`,
+            sourceRoots,
+          )
+        )
+          continue
+        const children = readdirSync(full)
+          .filter((child) => !child.startsWith('.'))
+          .sort()
+          .reverse()
+        pending.push(
+          ...children.map((child) => (path === '.' ? child : `${path}/${child}`)),
+        )
+        continue
+      }
+      if (
+        !SOURCE_EXTENSIONS.has(extname(path)) ||
+        capabilitySourceExclusion(path, sourceRoots)
+      )
+        continue
+      if (
+        files.size >= 2_000 ||
+        stat.size > 4 * 1024 * 1024 ||
+        bytes + stat.size > 32 * 1024 * 1024
+      ) {
+        limited = true
+        unknowns.push({ path, reason: 'source size limit' })
+        continue
+      }
+      const content = readFileSync(full, 'utf8')
+      bytes += Buffer.byteLength(content)
+      files.set(path, content)
+      let directory = dirname(full)
+      const traversed: string[] = []
+      while (!packageOwners.has(directory)) {
+        traversed.push(directory)
+        if (existsSync(join(directory, 'package.json'))) {
+          const ownerManifest = readProjectManifest(directory)
+          packageOwners.set(directory, directory)
+          ownerManifests.set(directory, ownerManifest)
+          if (!ownerManifest)
+            unknowns.push({
+              path: relative(app, directory),
+              reason: 'invalid package manifest; dependency versions remain unknown',
+            })
+          break
+        }
+        if (directory === app) throw new Error(`missing package owner for ${path}`)
+        directory = dirname(directory)
+      }
+      const owner = packageOwners.get(directory)
+      if (!owner) throw new Error(`missing package owner for ${path}`)
+      for (const traversedDirectory of traversed)
+        packageOwners.set(traversedDirectory, owner)
+      sourceOwners.set(path, owner)
+    } catch (error) {
+      unknowns.push({
+        path,
+        reason: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+  const final = graphRequest ? await readFinalGraph(app, graphRequest) : undefined
+  if (final && 'error' in final)
+    unknowns.push({
+      path: graphRequest?.entry ?? '(entry)',
+      reason: `final build graph unavailable: ${final.error}`,
+    })
+  const graph = final && 'graph' in final ? final : undefined
+  const parserPath = files.size ? await coverageParserPath() : undefined
+  const candidates: CapabilityReferenceCandidate[] = files.size
+    ? await withTypeScriptSourceParser(async (parse) => {
+        // one snapshot holds the repository. each file keeps its own lexical bindings.
+        return parse(files, async (sources, projects) => {
+          const candidates: CapabilityReferenceCandidate[] = []
+          for (const [path, source] of files) {
+            candidates.push(
+              ...(await collectCapabilityReferences(
+                async (_files, analyze) => analyze(sources, projects),
+                source,
+                path,
+                null,
+                'repository',
+                VERIFIED_SOURCE_API_ROOTS,
+              )),
+            )
+          }
+          return candidates
+        })
+      }, parserPath)
+    : []
+  const referencedPackages = new Map<string, Set<string>>()
+  for (const reference of candidates) {
+    const owner = sourceOwners.get(reference.path)
+    if (!owner) continue
+    const names = referencedPackages.get(owner) ?? new Set<string>()
+    names.add(reference.packageName)
+    referencedPackages.set(owner, names)
+  }
+  for (const [owner, names] of referencedPackages) {
+    const ownerManifest = ownerManifests.get(owner)
+    if (!ownerManifest) continue
+    const dependencies = Object.fromEntries(
+      Object.entries({
+        ...ownerManifest.dependencies,
+        ...ownerManifest.devDependencies,
+      }).filter(([name]) => names.has(name)),
+    )
+    versionOwners.set(owner, resolveManifestVersions(owner, { dependencies }, lockfiles))
+  }
+  const definitions = new Map(inventory.rows.map((row) => [row.id, row]))
+  const references = resolveCapabilityReferences(
+    inventory.rows,
+    candidates,
+    verifiedSourceApiDoors(
+      surfaces.flatMap((surface) => surface.features.flatMap((f) => f.frontDoors)),
+    ),
+  ).map((reference) => {
+    const owner = sourceOwners.get(reference.path)
+    const dependency = owner
+      ? versionOwners.get(owner)?.[reference.packageName]
+      : undefined
+    const row =
+      reference.state === 'attributed'
+        ? definitions.get(reference.capabilityId)
+        : undefined
+    // a source API door has no inventory row. its chain was read from one
+    // installed package version, which says nothing about native proof.
+    const sourceApi =
+      reference.state === 'attributed' && !row
+        ? inventory.sourceApiSnapshots.find(
+            (snapshot) =>
+              snapshot.module === reference.module &&
+              snapshot.exportName === reference.exportName,
+          )
+        : undefined
+    const versionStatus =
+      !dependency ||
+      dependency.source === 'declared' ||
+      !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(dependency.version)
+        ? 'unknown'
+        : sourceApi
+          ? dependency.version === sourceApi.sourceApiVersion
+            ? 'matched'
+            : 'mismatched'
+          : row
+            ? resolveCompatVersionRange([row.supportedVersionRange], dependency.version)
+                .status
+            : 'unknown'
+    const features =
+      reference.state === 'attributed'
+        ? surfaces
+            .flatMap((surface) => surface.features)
+            .filter((feature) =>
+              feature.frontDoors.some((door) => door === reference.capabilityId),
+            )
+            .map((feature) => feature.id)
+        : []
+    return {
+      ...reference,
+      // 'in-final-graph': the file is a project module of the final build.
+      // 'not-in-final-graph' is evidence of unreachability only when
+      // graph.complete is true. null: no graph was requested or built.
+      graphReach: graph
+        ? graph.projectModules.has(reference.path)
+          ? 'in-final-graph'
+          : 'not-in-final-graph'
+        : null,
+      artifactVersion: graph?.graph.artifactVersions[reference.packageName] ?? null,
+      packageOwner: owner ? relative(app, owner).split(sep).join('/') || '.' : null,
+      packageVersion: dependency ?? null,
+      versionStatus,
+      supportedVersionRange: row?.supportedVersionRange ?? null,
+      exactTestedVersion: row?.exactTestedVersion ?? null,
+      sourceApiVersion: sourceApi?.sourceApiVersion ?? null,
+      platformApplicable: sourceApi ? true : (row?.platforms.includes('ios') ?? null),
+      features,
+      mapping:
+        reference.state === 'excluded'
+          ? 'excluded'
+          : reference.state !== 'attributed'
+            ? 'unknown-api'
+            : versionStatus !== 'matched'
+              ? 'unknown-version'
+              : !(sourceApi || row?.platforms.includes('ios'))
+                ? 'other-platform'
+                : features.length
+                  ? 'mapped'
+                  : 'unmapped-feature',
+    }
+  })
+  const reached = new Set(
+    references
+      .filter((reference) => reference.mapping === 'mapped')
+      .flatMap((reference) => reference.features),
+  )
+  const features = surfaces
+    .flatMap((surface) => surface.features)
+    .filter((feature) => reached.has(feature.id))
+    .map((feature) => ({
+      id: feature.id,
+      title: feature.title,
+      reachability: 'possible',
+      unknownAxes: Object.keys(VERIFIED_AXES).filter(
+        (axis) => !Object.keys(feature.axes).includes(axis),
+      ),
+      axes: feature.axes,
+      settings: feature.settings ?? [],
+      graphReach: graph
+        ? references.some(
+            (reference) =>
+              reference.mapping === 'mapped' &&
+              reference.graphReach === 'in-final-graph' &&
+              reference.features.includes(feature.id),
+          )
+          ? 'in-final-graph'
+          : 'not-in-final-graph'
+        : null,
+      verification: 'unknown',
+      reason: 'source references do not select device, OS, settings or interaction cells',
+      proofUrl: 'https://peachsim.com/conformance',
+    }))
+  return {
+    schemaVersion: 1,
+    input: {
+      kind: 'repository-source',
+      app,
+      sources: sourceRoots,
+      files: files.size,
+      bytes,
+      limited,
+      fingerprint: createHash('sha256')
+        .update(JSON.stringify([...files]))
+        .digest('hex'),
+    },
+    registry: {
+      source: 'cli-capability-snapshot',
+      generatedAt: inventory.generatedAt,
+      fingerprint: createHash('sha256')
+        .update(JSON.stringify(inventoryData))
+        .digest('hex'),
+      runtimePinned: false,
+    },
+    summary: {
+      references: references.length,
+      mappedReferences: references.filter((reference) => reference.mapping === 'mapped')
+        .length,
+      unknownReferences: references.filter(
+        (reference) =>
+          reference.mapping === 'unknown-api' ||
+          reference.mapping === 'unknown-version' ||
+          reference.mapping === 'unmapped-feature',
+      ).length,
+      possibleFeatures: features.length,
+      mapped: null,
+      verified: null,
+    },
+    graph: graph?.graph ?? null,
+    references,
+    features,
+    unknowns,
+    limitations: [
+      ...(graphRequest
+        ? [
+            'The final build graph is one entry on one platform. Project modules a framework loads without a static import from that entry, such as file-system routes, are not in it. Package modules are transformed artifacts and are counted, not scanned; their features and library internals stay unknown. Artifact versions come from the compiled package set, not the repository lockfile, and do not change version status.',
+            'A file outside the final graph is evidence of unreachability only when graph.complete is true. An unresolved optional require, a missing entry or a file the toolchain could not transform leaves it unknown; null slots from NODE_ENV-excluded branches do not. Attribution applicability still follows the iOS inventory on every platform.',
+          ]
+        : []),
+      'Application source is scanned conservatively, without compiling or executing the app. Source roots do not establish entrypoint reachability.',
+      'Transitive library source, computed loading, cross-file aliases and runtime values are not resolved. Their feature and scenario reach remains unknown.',
+      'Declared dependency ranges alone are not exact package versions. The installed or unambiguous lockfile version must match the inventory range.',
+      'This CLI inventory snapshot is not pinned to a selected runtime. Native fidelity and scenario verification remain unknown; no aggregate percentage is established.',
+      'Swift source indexing is not included in this React Native source scan.',
+    ],
+  }
+}
+
+export async function runCoverage(args: string[]): Promise<number> {
+  let app = process.cwd()
+  let json = false
+  const sources: string[] = []
+  let graph = false
+  let entry: string | undefined
+  let platform: 'ios' | 'android' = 'ios'
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+    if (arg === '--graph') {
+      graph = true
+      continue
+    }
+    if (arg === '--entry' || arg === '--platform') {
+      const value = args[++index]
+      if (!value || value.startsWith('-')) throw new Error(`${arg} needs a value`)
+      if (arg === '--entry') entry = value
+      else if (value === 'ios' || value === 'android') platform = value
+      else throw new Error('--platform must be ios or android')
+      continue
+    }
+    if (arg === '--app' || arg === '--source') {
+      const value = args[++index]
+      if (!value || value.startsWith('-')) throw new Error(`${arg} needs a path`)
+      if (arg === '--app') app = resolve(value)
+      else sources.push(value)
+    } else throw new Error(`unknown coverage argument: ${arg}`)
+  }
+  if (!graph && (entry || platform !== 'ios'))
+    throw new Error('--entry and --platform need --graph')
+  const report = await createCoverageReport(
+    app,
+    sources,
+    graph ? { entry, platform } : undefined,
+  )
+  if (json) console.log(JSON.stringify(report, null, 2))
+  else {
+    console.log(
+      `Scanned ${report.input.files} source files: ${report.summary.mappedReferences} mapped references, ${report.summary.unknownReferences} unknown or unmapped references.`,
+    )
+    console.log(
+      `Possible features: ${report.summary.possibleFeatures}. Mapped share: unknown. Verified share: unknown.`,
+    )
+    if (report.graph)
+      console.log(
+        `Final graph (${report.graph.platform}): ${report.graph.projectModules} project modules, ${report.graph.packageModules} package modules; complete: ${report.graph.complete ?? 'unknown'}.`,
+      )
+    for (const feature of report.features)
+      console.log(
+        `  ${feature.id}${feature.graphReach ? ` (${feature.graphReach})` : ''}: verification unknown; unknown axes: ${feature.unknownAxes.join(', ') || 'none'}`,
+      )
+    for (const reference of report.references.filter(
+      (reference) =>
+        !['mapped', 'excluded', 'other-platform'].includes(reference.mapping),
+    ))
+      console.log(
+        `  ${reference.path}:${reference.start} ${reference.module} ${reference.exportName}${reference.memberName ? `.${reference.memberName}` : ''}: ${reference.mapping}`,
+      )
+    for (const issue of report.unknowns) console.log(`  ${issue.path}: ${issue.reason}`)
+    for (const limitation of report.limitations) console.log(`  ${limitation}`)
+  }
+  return !report.input.files || report.input.limited || report.unknowns.length ? 1 : 0
+}

package/cli/commands/debug.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 // peach debug — drive __sootsimDebug.* from the terminal
 //
 // connects to a running peach instance via the WebSocket bridge and forwards
@@ -17,8 +18,6 @@
 //   peach debug flags
 //
 // all commands print JSON by default so they pipe cleanly into jq.
-
-import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import { printBridgeFailureDiagnostics } from '../bridge-diagnostics'
 import { rethrowIfExit, peachExit } from '../run-rnx'
 import {
@@ -29,17 +28,19 @@ import {
 } from '../ws-bridge'
 import {
   callDebugBridge,
+  inspectDebugChannels,
   inspectDebugFind,
   inspectDebugFlags,
   inspectDebugRecent,
   inspectDebugStatus,
   setDebugChannels,
+  toggleDebugChannel,
 } from './inspect/core'
 import { callTestBridge } from './inspect/shared'
 import type {
   ImageAuditReport,
   ImageAuditRow,
-} from '../../../peach-engine/src/render-worker/compositor-protocol'
+} from '#peach-cli-contract/render-worker/compositor-protocol'
 import type { PeachDebugSnapshotOperation } from '@peach/globals'
 
 interface DebugOptions {
@@ -487,35 +488,25 @@ export async function runDebug(args: string[], opts: DebugOptions) {
           console.error('  usage: peach debug toggle <channel>')
           peachExit(1)
         }
-        const result = await callDebugBridge(
-          bridge,
-          `toggle(${JSON.stringify(channel)})`,
-          true,
-        )
-        if (!args.includes('--host')) {
-          await callDebugBridge(
-            bridge,
-            `${result ? 'enable' : 'disable'}(${JSON.stringify(channel)})`,
-          )
-        }
+        const result = await toggleDebugChannel(bridge, channel, args.includes('--host'))
         console.log(fmt({ [channel]: result }, pretty))
         break
       }
 
       case 'status': {
-        const result = await inspectDebugStatus(bridge)
+        const result = await inspectDebugStatus(bridge, args.includes('--host'))
         console.log(fmt(result, pretty))
         break
       }
 
       case 'channels': {
-        const result = await call(bridge, 'window.__sootsimDebug.channels()')
+        const result = await inspectDebugChannels(bridge, args.includes('--host'))
         console.log(fmt(result, pretty))
         break
       }
 
       case 'flags': {
-        const result = await inspectDebugFlags(bridge)
+        const result = await inspectDebugFlags(bridge, args.includes('--host'))
         console.log(fmt(result, pretty))
         break
       }
@@ -615,7 +606,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
       case 'find': {
         const target = rest[0]
         if (target === 'sheets' || target === 'portals' || target === 'boundaries') {
-          const result = await inspectDebugFind(bridge, target)
+          const result = await inspectDebugFind(bridge, target, args.includes('--host'))
           console.log(fmt(result, pretty))
         } else {
           console.error('  usage: peach debug find <sheets|portals|boundaries>')

package/cli/commands/desktop.ts

@@ -1,3 +1,5 @@
+import { getRnxPositionals } from '../command-registry'
+import { peachExit } from '../run-rnx'
 import { runElectron } from './electron'
 import { runInstallDesktop, runUninstallDesktop } from './install-desktop'
 
@@ -6,6 +8,8 @@ interface DesktopOptions {
   device?: string
 }
 
+const DESKTOP_VALUE_FLAGS = new Set(['--profile', '--channel'])
+
 function printHelp(): void {
   console.log(`
 peach desktop — launch or install the desktop companion
@@ -31,15 +35,23 @@ export async function runDesktop(args: string[], opts: DesktopOptions): Promise<
     return
   }
 
-  const sub = args.find((arg) => !arg.startsWith('-'))
-  if (sub === 'uninstall') {
-    await runUninstallDesktop(args.filter((arg) => arg !== 'uninstall'))
+  const positionals = getRnxPositionals(args, DESKTOP_VALUE_FLAGS)
+  const sub = positionals[0]
+  if (sub === 'uninstall' || sub === 'install') {
+    const index = args.findIndex(
+      (arg, i) => arg === sub && !DESKTOP_VALUE_FLAGS.has(args[i - 1]),
+    )
+    const rest = [...args.slice(0, index), ...args.slice(index + 1)]
+    if (sub === 'uninstall') await runUninstallDesktop(rest)
+    else await runInstallDesktop(rest)
     return
   }
-  if (sub === 'install') {
-    const index = args.indexOf(sub)
-    await runInstallDesktop([...args.slice(0, index), ...args.slice(index + 1)])
-    return
+
+  const unknown = positionals.filter((arg) => !arg.startsWith('peach://'))
+  if (unknown.length > 0) {
+    console.error(`  peach desktop: unknown argument: ${unknown[0]}`)
+    console.error('  run peach desktop --help for usage')
+    peachExit(1)
   }
 
   await runElectron(args, opts)