@threadcrumbs/common 0.0.0-stage → 0.1.1

package/harnesses/opencode.mjs

@@ -0,0 +1,449 @@
+/**
+ * Harness adapter: OpenCode — sessions in a local SQLite database.
+ *
+ * Primary store is `opencode.db` (WAL mode, so concurrent readers are safe while
+ * the app runs): `~/.local/share/opencode/opencode.db`, overridable with
+ * `$OPENCODE_DB`. Only top-level sessions count as threads — child rows with
+ * `parent_id` set are the task tool's subagents, and OpenCode's own session list
+ * filters them the same way. Including them would stand hundreds of astronauts
+ * on the map that nobody ever talked to.
+ *
+ * Read-only, without exception, and no subprocess anywhere. There is no
+ * per-session deep link upstream, so opening a thread is honestly refused and
+ * starting one goes through the registered `opencode://new-session` handler.
+ */
+import path from 'node:path'
+import os from 'node:os'
+import { exists, findExecutable, num } from '../lib/fsutil.mjs'
+
+const HOME = os.homedir()
+
+/**
+ * Where `opencode.db` lives. `$OPENCODE_DB` wins when it names a file that is
+ * actually there — otherwise the XDG path, then the macOS Application Support
+ * fallback on darwin only. Resolved per call so pointing the var at a fixture
+ * (or installing the app) is picked up on the next poll. A relative
+ * `$OPENCODE_DB` is relative to OpenCode's data folder, as OpenCode reads it.
+ */
+async function dbPath() {
+  const named = process.env.OPENCODE_DB
+  const xdg = process.env.XDG_DATA_HOME
+  const dataDir = typeof xdg === 'string' && xdg ? path.join(xdg, 'opencode') : path.join(HOME, '.local', 'share', 'opencode')
+  const override = typeof named === 'string' && named ? path.resolve(dataDir, named) : ''
+  // When set, the override is the whole answer: a missing file means "absent",
+  // not "fall back to the default and read a database the user did not name".
+  // That is also what makes fixture tests isolate from the real store.
+  if (override) return (await exists(override)) ? override : ''
+  if (typeof xdg === 'string' && xdg) {
+    const p = path.join(xdg, 'opencode', 'opencode.db')
+    if (await exists(p)) return p
+  }
+  const shared = path.join(HOME, '.local', 'share', 'opencode', 'opencode.db')
+  if (await exists(shared)) return shared
+  if (process.platform === 'darwin') {
+    const mac = path.join(HOME, 'Library', 'Application Support', 'opencode', 'opencode.db')
+    if (await exists(mac)) return mac
+  }
+  return ''
+}
+
+/**
+ * `node:sqlite` is imported lazily and its absence is survivable.
+ *
+ * It needs Node 22.13, which `package.json` asks for — but asking is not
+ * enforcing, and a top level import would take the whole server down on an
+ * older Node rather than costing one harness. This way every other harness
+ * keeps working and `diagnostic()` explains the gap.
+ */
+let sqlitePromise
+const sqliteApi = () => (sqlitePromise ??= import('node:sqlite').catch(() => null))
+
+/** Prefixed, per the contract in `harnesses/README.md`. */
+const ID = (raw) => `opencode:${raw}`
+
+/** OpenCode writes nothing when it is killed, so an open turn needs a time bound too. */
+const ACTIVE_WINDOW_MS = 30 * 60 * 1000
+const CONTINUING = new Set(['tool-calls', 'unknown'])
+
+const clean = (v) => String(v || '').replace(/\s+/g, ' ').trim()
+
+function parseModel(raw) {
+  if (!raw) return { model: '', effort: '' }
+  try {
+    const m = typeof raw === 'string' ? JSON.parse(raw) : raw
+    return {
+      model: typeof m?.id === 'string' ? m.id : '',
+      effort: typeof m?.variant === 'string' ? m.variant : ''
+    }
+  } catch {
+    return { model: '', effort: '' }
+  }
+}
+
+function projectOf(directory) {
+  const dir = typeof directory === 'string' ? directory : ''
+  if (!dir) return { projectPath: '', project: 'unknown', cwd: '' }
+  // Both separators: a Windows directory arrives with either, and `basename`
+  // on one OS must still read a path written on another (tests use posix).
+  const base = path.basename(dir.replace(/\\/g, '/'))
+  return { projectPath: dir, project: base || 'unknown', cwd: dir }
+}
+
+/** First user text per session never changes, so it is kept forever. */
+const previewCache = new Map()
+
+async function firstUserText(db, sessionId) {
+  if (previewCache.has(sessionId)) return previewCache.get(sessionId)
+  let out = ''
+  try {
+    const msgs = db
+      .prepare(`SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created ASC LIMIT 8`)
+      .all(sessionId)
+    for (const m of msgs) {
+      let role = ''
+      try {
+        role = JSON.parse(m.data)?.role || ''
+      } catch {
+        continue
+      }
+      if (role !== 'user') continue
+      const parts = db
+        .prepare(`SELECT data FROM part WHERE message_id = ? ORDER BY time_created ASC LIMIT 8`)
+        .all(m.id)
+      for (const p of parts) {
+        try {
+          const d = JSON.parse(p.data)
+          if (d?.type === 'text' && typeof d.text === 'string' && clean(d.text)) {
+            out = clean(d.text)
+            break
+          }
+        } catch {
+          /* a part mid-write — skip it */
+        }
+      }
+      if (out) break
+    }
+  } catch {
+    out = ''
+  }
+  previewCache.set(sessionId, out)
+  return out
+}
+
+/** Costly facts kept against `time_updated`, so an unchanged session is read once. */
+const factsCache = new Map()
+
+/**
+ * Whether an error-status tool part means the run failed.
+ *
+ * Seen in production: `The user rejected permission to use this specific tool
+ * call.` and `Tool execution aborted` — both are the user stopping the turn,
+ * not the turn failing. Only a genuine failure reddens an astronaut.
+ */
+function isRealError(raw) {
+  let text = ''
+  try {
+    const d = typeof raw === 'string' ? JSON.parse(raw) : raw
+    const state = d?.state || {}
+    text = `${state.error || ''}\n${state.output || ''}`
+  } catch {
+    return true
+  }
+  return !/user rejected permission|permission.{0,20}denied|denied.{0,20}permission|execution aborted|aborted|cancelled/i.test(text)
+}
+
+async function sessionFacts(db, sessionId, timeUpdated) {
+  const hit = factsCache.get(sessionId)
+  if (hit && hit.timeUpdated === timeUpdated) return hit.facts
+  const facts = { running: false, hasError: false, sizeBytes: 0 }
+  try {
+    const msgBytes = db.prepare(`SELECT COALESCE(SUM(LENGTH(data)), 0) AS n FROM message WHERE session_id = ?`).get(sessionId)
+    const partBytes = db.prepare(`SELECT COALESCE(SUM(LENGTH(data)), 0) AS n FROM part WHERE session_id = ?`).get(sessionId)
+    facts.sizeBytes = num(msgBytes?.n) + num(partBytes?.n)
+  } catch {
+    facts.sizeBytes = 0
+  }
+  try {
+    const last = db
+      .prepare(`SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created DESC, rowid DESC LIMIT 1`)
+      .get(sessionId)
+    if (last?.data) {
+      const d = JSON.parse(last.data)
+      const completed = d?.time?.completed
+      const finished = typeof d?.finish === 'string' && d.finish
+      const msgError = typeof d?.error?.name === 'string' ? d.error.name : ''
+      const aborted = /abort/i.test(msgError)
+      // A trailing user message means the model speaks next — whatever the
+      // process is doing, it is not waiting on anyone. A turn that ended in
+      // error or abort is over too, even when it carries no finish stamp. A
+      // reply that finished on tool calls is completed, but its turn goes on.
+      const continuing = !msgError && CONTINUING.has(finished)
+      const open = d?.role === 'user' || (d?.role === 'assistant' && !msgError && (continuing || (!completed && !finished)))
+      facts.running = open && Date.now() - num(timeUpdated) < ACTIVE_WINDOW_MS
+      if (d?.role === 'assistant' && !open && (completed || finished || msgError)) {
+        if (aborted) {
+          // The user stopped the turn. Same as pressing escape elsewhere:
+          // an abandoned turn is not a failed one.
+          facts.hasError = false
+        } else if (msgError) {
+          // The turn itself failed (provider/auth error) — that is what the
+          // red eyes are for, even when no single tool part takes the blame.
+          facts.hasError = true
+        } else {
+          // Only the last turn counts: a historic tool error must not redden
+          // an astronaut forever. And a turn the *user* stopped is not a
+          // failure — a rejected permission or an aborted call is this
+          // harness's version of pressing escape.
+          const candidates = db
+            .prepare(
+              `SELECT data FROM part WHERE message_id IN (SELECT id FROM message WHERE session_id = ? ORDER BY time_created DESC LIMIT 3) AND data LIKE '%"status":"error"%' LIMIT 5`
+            )
+            .all(sessionId)
+          facts.hasError = candidates.some((row) => isRealError(row?.data))
+        }
+      }
+    }
+  } catch {
+    /* mid-write, or gone */
+  }
+  factsCache.set(sessionId, { timeUpdated, facts })
+  return facts
+}
+
+function toThread(r, prompt, facts, seen = { unread: false, lastFocusedAt: 0 }) {
+  const { projectPath, project, cwd } = projectOf(r.directory)
+  const { model, effort } = parseModel(r.model)
+  const title = clean(r.title) || prompt || 'Untitled thread'
+  return {
+    id: ID(r.id),
+    title: title.slice(0, 120),
+    preview: prompt.slice(0, 240),
+    project,
+    projectPath,
+    // OpenCode has no worktree concept of its own, and guessing one from
+    // the path would put a branch name on a thread that never had one.
+    worktree: '',
+    cwd,
+    gitBranch: '',
+    model,
+    effort,
+    createdAt: num(r.time_created),
+    lastActivityAt: num(r.time_updated),
+    // Legacy sessions have no focus history, so for them "have you looked at this" is unknowable — not false.
+    lastFocusedAt: seen.lastFocusedAt,
+    unread: seen.unread,
+    running: facts.running,
+    hasError: facts.hasError,
+    starred: false,
+    routine: '',
+    prState: '',
+    archived: r.time_archived !== null && r.time_archived !== undefined,
+    // Bytes, like every other harness: the field is a shared log scale
+    // across the whole map, and a token count would make OpenCode
+    // buildings taller than Claude ones for the same work.
+    sizeBytes: facts.sizeBytes,
+    source: typeof r.agent === 'string' ? r.agent : '',
+    canOpen: false,
+    ref: { sessionId: r.id, cwd }
+  }
+}
+
+const columnsOf = (db, table) => new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((r) => r.name))
+
+async function scanLegacySessions(db) {
+  // Undocumented private state that drifts between versions — probe every
+  // column before naming it, or one renamed column costs the whole harness.
+  const cols = columnsOf(db, 'session')
+  for (const need of ['id', 'directory', 'title', 'time_created', 'time_updated']) {
+    if (!cols.has(need)) return []
+  }
+  const rows = db
+    .prepare(
+      `SELECT id, directory, title, agent, model, time_created, time_updated, time_archived FROM session ${cols.has('parent_id') ? 'WHERE parent_id IS NULL' : ''} ORDER BY time_updated DESC`
+    )
+    .all()
+  const out = []
+  for (const r of rows) {
+    if (typeof r.id !== 'string' || !r.id) continue
+    const prompt = await firstUserText(db, r.id)
+    out.push(toThread(r, prompt, await sessionFacts(db, r.id, num(r.time_updated))))
+  }
+  return out
+}
+
+const TURN_MESSAGES = `'user', 'assistant', 'shell', 'synthetic', 'compaction', 'idle'`
+
+async function sessionMessageFacts(db, r) {
+  const key = `session_v2:${r.id}`
+  const timeUpdated = num(r.time_updated)
+  const hit = factsCache.get(key)
+  if (hit && hit.timeUpdated === timeUpdated) return hit.facts
+  const facts = { running: false, hasError: false, sizeBytes: 0 }
+  try {
+    facts.sizeBytes = num(db.prepare(`SELECT COALESCE(SUM(LENGTH(data)), 0) AS n FROM session_message WHERE session_id = ?`).get(r.id)?.n)
+    const last = db
+      .prepare(`SELECT type, data FROM session_message WHERE session_id = ? AND type IN (${TURN_MESSAGES}) ORDER BY seq DESC LIMIT 1`)
+      .get(r.id)
+    if (last) {
+      const ended = last.type === 'idle'
+      facts.running = !ended && Date.now() - timeUpdated < ACTIVE_WINDOW_MS
+      let outcome = typeof r.idle_outcome === 'string' ? r.idle_outcome : ''
+      if (ended && !outcome) {
+        try {
+          outcome = JSON.parse(last.data)?.outcome || ''
+        } catch {
+          outcome = ''
+        }
+      }
+      facts.hasError = ended && outcome === 'failed'
+    }
+  } catch {
+    /* mid-write, or gone */
+  }
+  factsCache.set(key, { timeUpdated, facts })
+  return facts
+}
+
+async function firstPrompt(db, sessionId) {
+  const key = `session_v2:${sessionId}`
+  if (previewCache.has(key)) return previewCache.get(key)
+  let out = ''
+  try {
+    const row = db.prepare(`SELECT data FROM session_message WHERE session_id = ? AND type = 'user' ORDER BY seq ASC LIMIT 1`).get(sessionId)
+    if (row?.data) out = clean(JSON.parse(row.data)?.text)
+  } catch {
+    out = ''
+  }
+  if (out) previewCache.set(key, out)
+  return out
+}
+
+async function scanSessions(db) {
+  const cols = columnsOf(db, 'session_v2')
+  for (const need of ['id', 'directory', 'time_created', 'time_updated']) {
+    if (!cols.has(need)) return []
+  }
+  const pick = (name) => (cols.has(name) ? name : `NULL AS ${name}`)
+  const rows = db
+    .prepare(
+      `SELECT id, directory, ${['title', 'agent', 'model', 'time_archived', 'time_idle', 'time_viewed', 'idle_outcome'].map(pick).join(', ')}, time_created, time_updated FROM session_v2 ${cols.has('parent_id') ? 'WHERE parent_id IS NULL' : ''} ORDER BY time_updated DESC`
+    )
+    .all()
+  const out = []
+  for (const r of rows) {
+    if (typeof r.id !== 'string' || !r.id) continue
+    const facts = await sessionMessageFacts(db, r)
+    const viewed = num(r.time_viewed)
+    const seen = { lastFocusedAt: viewed, unread: !facts.running && viewed > 0 && num(r.time_idle) > viewed }
+    out.push(toThread(r, await firstPrompt(db, r.id), facts, seen))
+  }
+  return out
+}
+
+async function scanThreads() {
+  const file = await dbPath()
+  if (!file) return []
+  const sqlite = await sqliteApi()
+  if (!sqlite?.DatabaseSync) return []
+
+  let db
+  try {
+    db = new sqlite.DatabaseSync(file, { readOnly: true })
+  } catch {
+    // A WAL database whose shared-memory file cannot be used refuses a
+    // read-only open. Losing one harness beats losing the scan.
+    return []
+  }
+  try {
+    const tables = new Set(
+      db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table'`).all().map((r) => r.name)
+    )
+    const byId = new Map()
+    if (tables.has('session') && tables.has('message') && tables.has('part')) {
+      for (const t of await scanLegacySessions(db)) byId.set(t.id, t)
+    }
+    if (tables.has('session_v2') && tables.has('session_message')) {
+      for (const t of await scanSessions(db)) {
+        const legacy = byId.get(t.id)
+        if (!legacy || t.lastActivityAt >= legacy.lastActivityAt) byId.set(t.id, t)
+      }
+    }
+    return [...byId.values()]
+  } catch {
+    return []
+  } finally {
+    try {
+      db.close()
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/**
+ * OpenCode registers `opencode://open-project` and `opencode://new-session`
+ * and nothing that addresses a single session — inventing a route would be a
+ * link that silently does nothing. Revealing the session list is the honest
+ * offer, and the UI greys the button and shows this instead.
+ */
+function openThread(ref) {
+  const id = ref?.sessionId
+  // The type check matters wherever an id came back from the page:
+  // `String([validId])` is that id, and it must not travel on as an array.
+  if (typeof id !== 'string' || !id) {
+    return { ok: false, error: 'No openable OpenCode session id on that thread' }
+  }
+  return {
+    ok: false,
+    error: 'OpenCode has no link to a single session — open the repo and pick it from the session list.'
+  }
+}
+
+/**
+ * Where the `opencode` CLI is, for a machine that needs the terminal fallback.
+ * PATH first, then the places its installers put it — never inside an
+ * application bundle.
+ */
+const CLI_DIRS = [path.join(HOME, '.local', 'bin'), path.join(HOME, '.opencode', 'bin'), '/usr/local/bin', '/usr/bin']
+const cliBinary = () => findExecutable('opencode', CLI_DIRS)
+
+const APP = Object.freeze({ name: 'OpenCode', download: 'https://opencode.ai/download' })
+
+async function newSession(dir) {
+  if (typeof dir !== 'string' || !path.isAbsolute(dir)) {
+    return { ok: false, error: 'That folder is not somewhere OpenCode can open' }
+  }
+  const url = `opencode://new-session?${new URLSearchParams({ directory: dir })}`
+  const bin = await cliBinary()
+  const command = bin ? { argv: [bin], cwd: dir } : undefined
+  return { ok: true, url, command, app: APP }
+}
+
+async function detect() {
+  return Boolean(await dbPath())
+}
+
+/**
+ * Why a present OpenCode might still look thin. Without this the old-Node case
+ * is invisible: the database is simply skipped, every thread is missing, and
+ * nothing says why.
+ */
+async function diagnostic() {
+  if (!(await dbPath())) return ''
+  if (!(await sqliteApi())?.DatabaseSync) {
+    return `OpenCode threads need Node 22.13 or newer for their sessions (running ${process.versions.node})`
+  }
+  return ''
+}
+
+export default {
+  id: 'opencode',
+  name: 'OpenCode',
+  app: APP,
+  detect,
+  diagnostic,
+  scanThreads,
+  openThread,
+  newSession,
+  paths: {}
+}

package/launch/index.mjs

@@ -0,0 +1,163 @@
+/**
+ * Opening a thread on this machine: the one part of this package that starts processes.
+ *
+ * A harness adapter in `../harnesses/` answers "open this thread" with `{ ok, url, command, pid }`
+ * and starts nothing itself. `present()` turns that answer into an action: it fronts the window a
+ * running session already has, hands a deep link to the OS, or runs the harness's CLI in a new
+ * terminal. The readers in `../harnesses/`, `../telemetry/`, and `../lib/` never import this
+ * folder, and `test/read-only.test.mjs` checks that.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { openAndConfirm } from './macos.mjs'
+import { schemeRegistered } from './registry.mjs'
+import { openInTerminal } from './terminal.mjs'
+import { focusWindowOfPid } from './windows.mjs'
+import { schemeHasHandler, schemeOf } from './xdg.mjs'
+
+/**
+ * Hand a `harness://…` deep link, or a folder, to whatever opens things on this OS. The opener
+ * gets an argument list, never a shell string.
+ *
+ * macOS's `open(1)` does both jobs, and `xdg-open` is the Linux equivalent. On Windows it is
+ * ShellExecute, reached through `rundll32 url.dll,FileProtocolHandler`: a registered protocol URL
+ * goes to its app and a folder opens in Explorer, with the argument passed through unchanged. Two
+ * other routes were tried and rejected. `explorer.exe <url>` drops any URL that has a query
+ * string, so `code/new?folder=…` never arrived, and `cmd /c start` parses its own argument line,
+ * where it expands the `%3A%5C` escapes in that same link.
+ *
+ * The spawn is guarded because the opener may not be installed (a headless Linux machine has no
+ * `xdg-open`), and an unhandled `error` event on a child process stops the whole server.
+ */
+const OPENERS = {
+  darwin: ['open'],
+  win32: ['rundll32', 'url.dll,FileProtocolHandler'],
+  linux: ['xdg-open'],
+}
+
+export function launch(target) {
+  const opener = OPENERS[process.platform]
+  if (!opener) return
+  const [cmd, ...args] = opener
+  const child = spawn(cmd, [...args, target], { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+}
+
+/**
+ * A folder can be opened only if it is still on this machine and still a directory. Paths come
+ * from a scan that may be minutes old, so a repo that has since been moved or deleted fails here
+ * rather than handing the opener a path that no longer exists. Absolute is judged by
+ * `path.isAbsolute` rather than a leading `/`, which no Windows path has.
+ */
+export async function resolveFolder(folder) {
+  if (typeof folder !== 'string' || !path.isAbsolute(folder)) return null
+  const dir = path.resolve(folder)
+  const stat = await fsp.stat(dir).catch(() => null)
+  return stat && stat.isDirectory() ? dir : null
+}
+
+/**
+ * `command.cwd` gets the same check as any other folder. There is no fallback directory on
+ * purpose: `claude --resume` looks a session up under the folder it ran in, and a terminal that
+ * opens on "No conversation found" and closes is worse than an error message.
+ */
+async function runInTerminal(command) {
+  if (!command.cwd) return { ok: false, error: 'That thread has no folder on record to resume in' }
+  const cwd = await resolveFolder(command.cwd)
+  if (!cwd) return { ok: false, error: 'The folder that thread ran in is not on this machine any more' }
+  const enterable = await fsp.access(cwd, fsp.constants.X_OK).then(() => true, () => false)
+  if (!enterable) return { ok: false, error: 'The folder that thread ran in cannot be entered' }
+  const opened = await openInTerminal(command.argv, cwd)
+  return opened.ok ? { ok: true, via: 'terminal' } : opened
+}
+
+/**
+ * Carry out a harness's answer to "open this" (`{ ok, url, command, pid }`) the way the caller
+ * asked for it, and report whether anything happened.
+ *
+ * A caller asking for a terminal never gets the desktop app instead, even when the CLI is missing:
+ * an app window appearing after choosing a terminal looks like the setting being ignored, while an
+ * error message says what to fix.
+ *
+ * Otherwise the URL goes to the opener only once something on this machine answers its scheme,
+ * and the adapter's `fallback` links are tried the same way when nothing does. When neither
+ * opens, Linux runs the harness's own CLI in a terminal if the adapter offered one, and every
+ * other case returns `missing`, naming the app to install. DECISIONS.md has the why.
+ */
+export async function present(
+  result,
+  via = 'app',
+  { platform = process.platform, answers = schemeAnswered, open = openUrl, wait = pause } = {}
+) {
+  if (!result || !result.ok) return { ok: false, error: result?.error || 'Nothing to open' }
+
+  if (via === 'terminal') {
+    if (!result.command) return { ok: false, error: "That harness's CLI was not found on this machine" }
+    return runInTerminal(result.command)
+  }
+
+  // A `pid` names a live process whose thread already has a window on this machine, such as a
+  // session running in a terminal. Fronting that window is tried before the URL, because the URL
+  // for these threads is `resume`, which imports the transcript into the desktop app as a second,
+  // untitled session. Only when no window can be found does the URL run.
+  if (result.pid && (await focusWindowOfPid(result.pid))) return { ok: true, focused: true }
+
+  if (!result.url) {
+    if (platform === 'linux' && result.command) return runInTerminal(result.command)
+    return { ok: false, error: 'That harness has no deep link to open on this platform' }
+  }
+
+  for (const { urls, note } of routesOf(result)) {
+    const [first, ...rest] = urls
+    if ((await answers(first, platform)) === false) continue
+    if ((await open(first, platform)) === false) continue
+    for (const url of rest) {
+      await wait(FALLBACK_STEP_MS)
+      await open(url, platform)
+    }
+    return { ok: true, url: urls.at(-1), note }
+  }
+  if (platform === 'linux' && result.command) return runInTerminal(result.command)
+  return missingApp(result)
+}
+
+const FALLBACK_STEP_MS = 2000
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function routesOf(result) {
+  const routes = [{ urls: [result.url], note: result.note }]
+  const { urls, note } = result.fallback || {}
+  if (Array.isArray(urls) && urls.length && urls.every((url) => typeof url === 'string' && schemeOf(url))) {
+    routes.push({ urls, note: typeof note === 'string' ? note : undefined })
+  }
+  return routes
+}
+
+const appLink = (app) => ({ name: typeof app?.name === 'string' ? app.name : '', download: typeof app?.download === 'string' ? app.download : '' })
+
+async function schemeAnswered(url, platform) {
+  if (platform === 'linux') return schemeHasHandler(url)
+  if (platform === 'win32') return schemeRegistered(schemeOf(url))
+  return null
+}
+
+async function openUrl(url, platform) {
+  if (platform === 'darwin') return openAndConfirm(url)
+  launch(url)
+  return null
+}
+
+function missingApp(result) {
+  const scheme = schemeOf(result.url)
+  const { name, download } = appLink(result.app)
+  const also = Array.isArray(result.app?.also) ? result.app.also.map(appLink).filter((app) => app.name && app.download) : []
+  return {
+    ok: false,
+    error: name ? `Opening this needs ${name}, which isn't on this computer` : `Nothing on this computer opens ${scheme}:// links`,
+    missing: { name, download, scheme, also },
+    terminal: Boolean(result.command),
+  }
+}

package/launch/macos.mjs

@@ -0,0 +1,21 @@
+import { spawn } from 'node:child_process'
+
+const OPEN_TIMEOUT_MS = 5000
+
+export function openAndConfirm(url, { timeoutMs = OPEN_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('open', [url], { stdio: 'ignore' })
+    const timer = setTimeout(() => {
+      child.unref()
+      resolve(null)
+    }, timeoutMs)
+    child.on('error', () => {
+      clearTimeout(timer)
+      resolve(null)
+    })
+    child.on('exit', (code) => {
+      clearTimeout(timer)
+      resolve(code === 0)
+    })
+  })
+}

package/launch/registry.mjs

@@ -0,0 +1,52 @@
+import { execFile } from 'node:child_process'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+const REG = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'reg.exe')
+const SCHEME = /^[a-z][a-z0-9+.-]*$/
+const REGISTRY_TIMEOUT_MS = 5000
+
+async function regQuery(args) {
+  try {
+    const { stdout } = await execFileAsync(REG, ['query', ...args], { timeout: REGISTRY_TIMEOUT_MS, windowsHide: true })
+    return stdout
+  } catch (err) {
+    if (err.code === 1) return null
+    throw err
+  }
+}
+
+export function defaultValue(output) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const value = /\sREG_(?:EXPAND_)?SZ\s+(.*\S)\s*$/.exec(line)
+    if (value) return value[1]
+  }
+  return ''
+}
+
+export function programOf(command, env = process.env) {
+  const text = String(command || '').trim()
+  const program = /^"([^"]+)"/.exec(text)?.[1] || /^(\S+\.exe)(?:\s|$)/i.exec(text)?.[1]
+  if (!program) return ''
+  const expanded = program.replace(/%([^%]+)%/g, (whole, name) => env[name] ?? whole)
+  if (expanded.includes('%') || !/^[\x20-\x7e]+$/.test(expanded) || !path.win32.isAbsolute(expanded)) return ''
+  return expanded
+}
+
+export async function schemeRegistered(scheme, { query = regQuery, stat = fsp.stat, env = process.env } = {}) {
+  if (!SCHEME.test(scheme)) return false
+  const key = `HKCR\\${scheme}`
+  try {
+    if ((await query([key, '/v', 'URL Protocol'])) == null) return false
+    const program = programOf(defaultValue(await query([`${key}\\shell\\open\\command`, '/ve'])), env)
+    if (!program) return true
+    return await stat(program).then(
+      () => true,
+      (err) => err.code !== 'ENOENT' && err.code !== 'ENOTDIR'
+    )
+  } catch {
+    return null
+  }
+}