@threadcrumbs/threadnauts 0.0.0-stage → 1.0.0

package/server/lib/terminal.mjs

@@ -0,0 +1,213 @@
+/**
+ * Put a command in a new terminal window.
+ *
+ * Only `server/api.mjs` uses this, and Windows is handed on to `win-terminal.mjs` at the door.
+ * It is split out because it is a page of terminal-emulator trivia with nothing to do with HTTP,
+ * and nothing in here knows about a particular harness — an adapter never imports it. An adapter
+ * hands the server an argv; the server decides whether a terminal is the right place for it.
+ */
+import { spawn } from 'node:child_process'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { findExecutable } from '@threadcrumbs/common/lib/fsutil'
+import { openInTerminalWindows } from './win-terminal.mjs'
+
+/**
+ * How each terminal wants "run this command in this directory". The command comes after the
+ * terminal's own end-of-options marker where it has one, so nothing in it is ever read as a
+ * flag; the working directory is also set on the spawn itself, which is all the xterm family
+ * needs and what the D-Bus terminals forward to their server anyway.
+ *
+ * Only terminals whose flags are documented are listed. `tilix` is deliberately absent: its `-e`
+ * takes one string that it re-splits itself, which would mean building a shell string.
+ */
+const TERMINALS = {
+  'gnome-terminal': (dir, cmd) => [`--working-directory=${dir}`, '--', ...cmd],
+  kgx: (dir, cmd) => [`--working-directory=${dir}`, '--', ...cmd],
+  ptyxis: (dir, cmd) => [`--working-directory=${dir}`, '--', ...cmd],
+  konsole: (dir, cmd) => ['--workdir', dir, '-e', ...cmd],
+  'xfce4-terminal': (dir, cmd) => [`--working-directory=${dir}`, '-x', ...cmd],
+  'mate-terminal': (dir, cmd) => [`--working-directory=${dir}`, '-x', ...cmd],
+  kitty: (dir, cmd) => [`--directory=${dir}`, ...cmd],
+  alacritty: (dir, cmd) => ['--working-directory', dir, '-e', ...cmd],
+  ghostty: (dir, cmd) => [`--working-directory=${dir}`, '-e', ...cmd],
+  wezterm: (dir, cmd) => ['start', '--cwd', dir, '--', ...cmd],
+  foot: (dir, cmd) => [`--working-directory=${dir}`, ...cmd],
+  terminator: (dir, cmd) => [`--working-directory=${dir}`, '-x', ...cmd],
+  xterm: (_dir, cmd) => ['-e', ...cmd],
+  uxterm: (_dir, cmd) => ['-e', ...cmd],
+  urxvt: (_dir, cmd) => ['-e', ...cmd],
+  rxvt: (_dir, cmd) => ['-e', ...cmd],
+  st: (_dir, cmd) => ['-e', ...cmd],
+}
+
+const GENERAL_ORDER = [
+  'gnome-terminal', 'konsole', 'xfce4-terminal', 'mate-terminal', 'kitty', 'alacritty', 'ghostty',
+  'wezterm', 'foot', 'terminator', 'ptyxis', 'kgx', 'xterm', 'uxterm', 'urxvt', 'rxvt', 'st',
+]
+
+/**
+ * A terminal that ships with the desktop first. `XDG_CURRENT_DESKTOP` is a colon list, such as
+ * `ubuntu:GNOME`, and GNOME gets the three it has shipped over the years in the order they are
+ * most likely to be the one actually configured.
+ */
+function desktopOrder() {
+  const parts = (process.env.XDG_CURRENT_DESKTOP || '').toLowerCase().split(':')
+  if (parts.includes('kde')) return ['konsole']
+  if (parts.includes('xfce')) return ['xfce4-terminal']
+  if (parts.includes('mate')) return ['mate-terminal']
+  if (parts.some((p) => ['gnome', 'ubuntu', 'unity', 'cinnamon', 'x-cinnamon'].includes(p))) {
+    return ['gnome-terminal', 'kgx', 'ptyxis']
+  }
+  return []
+}
+
+/**
+ * Is there anywhere for a window to appear? Deliberately loose: only the plainly headless case
+ * is refused here, so that it gets a message saying so, and anything less clear-cut is left to
+ * the launch itself, whose exit code is the real answer. Wayland clients find their socket
+ * without the variable being set, so the runtime dir is checked too.
+ */
+async function hasDisplay() {
+  if (process.env.DISPLAY || process.env.WAYLAND_DISPLAY) return true
+  const run = process.env.XDG_RUNTIME_DIR
+  if (!run) return false
+  try {
+    return (await fsp.readdir(run)).some((name) => name.startsWith('wayland-'))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * A terminal that refuses does so at once — well under 50 ms on a GNOME desktop — while a window
+ * takes longer than this to come up. A refusal slower than this is knowingly reported as a
+ * success: the alternative, treating every late non-zero exit as a failure, would open a second
+ * terminal whenever the command inside the first one ended quickly.
+ */
+const REFUSAL_MS = 300
+/** After this a foreground terminal (xterm, Debian's `--wait` wrapper) is plainly up. */
+const GRACE_MS = 1500
+/**
+ * And a ceiling on the whole walk. Each candidate can cost `GRACE_MS`, and on a machine with
+ * several terminals installed and a broken display, each one can fail only after that long, which
+ * would otherwise hold the request for the sum of them while the page shows a spinner. The walk
+ * stops at this budget and reports the failure instead.
+ */
+const WALK_BUDGET_MS = 4000
+
+/**
+ * Spawn a terminal and say whether it actually came up. The D-Bus terminals hand the window to a
+ * service and exit 0 at once; when they cannot — no display, a flag they reject — they exit
+ * non-zero just as fast, and that is the failure worth reporting instead of a toast that says
+ * "opened". A non-zero exit that arrives *later* is different: the window came up and the command
+ * inside it has ended, which is the user's to see and no reason to open a second terminal on top.
+ */
+function trySpawn(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(cmd, args, { cwd, stdio: 'ignore', detached: true })
+    } catch (err) {
+      resolve({ ok: false, error: err?.message || String(err) })
+      return
+    }
+    const startedAt = Date.now()
+    let timer = null
+    let settled = false
+    const done = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+    child.on('error', (err) => done({ ok: false, error: err?.message || String(err) }))
+    child.on('exit', (code, signal) => {
+      if (code === 0 || Date.now() - startedAt >= REFUSAL_MS) return done({ ok: true })
+      const how = signal ? `signal ${signal}` : `code ${code}`
+      done({ ok: false, error: `${path.basename(cmd)} exited with ${how}` })
+    })
+    timer = setTimeout(() => {
+      child.unref()
+      done({ ok: true })
+    }, GRACE_MS)
+  })
+}
+
+/**
+ * Run `argv` in a new terminal window with `cwd` as its working directory.
+ *
+ * The caller has already resolved both: `argv[0]` is an absolute executable and `cwd` an
+ * existing directory. Which terminal is up to the machine — `THREADNAUTS_TERMINAL` if set, then
+ * `$TERMINAL`, then the desktop's own, then whatever is installed, then Debian's
+ * `x-terminal-emulator` alternative. That last is tried by name and given `-e`, the one form
+ * Debian policy guarantees, because on Ubuntu it is a wrapper script that knows no other flags —
+ * pass it `--working-directory` and it opens an empty window. Which is also why a real
+ * `gnome-terminal` is looked for first.
+ *
+ * A named terminal the table does not know is skipped rather than guessed at: `-e` means "the
+ * rest of the line" to xterm and "one string, which I will split" to tilix, and guessing wrong
+ * opens a window on the wrong command — worse than moving on to a terminal we do know.
+ *
+ * On macOS the desktop walk finds nothing, so only a named terminal works there — kitty,
+ * alacritty, ghostty and wezterm take the same flags on both. Terminal.app and iTerm are not
+ * driven: `open -a` cannot hand them an argv without a shell string in between.
+ */
+export async function openInTerminal(argv, cwd) {
+  // Windows shares none of the trivia below — no PATH walk over sixteen emulators, no display
+  // to check — so it is a different file entirely, reached through the same door. The caller
+  // asks for a terminal and does not learn which platform it is on.
+  if (process.platform === 'win32') return openInTerminalWindows(argv, cwd)
+
+  const wellFormed = Array.isArray(argv) && argv.length > 0 && argv.every((a) => typeof a === 'string' && a)
+  if (!wellFormed || !path.isAbsolute(argv[0]) || typeof cwd !== 'string' || !path.isAbsolute(cwd)) {
+    return { ok: false, error: 'Invalid launch command' }
+  }
+  // A macOS session always has a window server; only Linux can be headless in a way worth naming.
+  if (process.platform === 'linux' && !(await hasDisplay())) {
+    return { ok: false, error: 'No graphical display to open a terminal on' }
+  }
+
+  const preferred = [
+    process.env.THREADNAUTS_TERMINAL || '',
+    process.env.TERMINAL || '',
+    ...desktopOrder(),
+    ...GENERAL_ORDER,
+    'x-terminal-emulator',
+  ]
+  const names = [...new Set(preferred.filter(Boolean))]
+  const deadline = Date.now() + WALK_BUDGET_MS
+  const tried = new Set()
+  let lastError = ''
+  let ranOut = false
+
+  for (const name of names) {
+    if (Date.now() >= deadline) {
+      ranOut = true
+      break
+    }
+    const resolved = await findExecutable(name)
+    if (!resolved || tried.has(resolved)) continue
+    tried.add(resolved)
+
+    const base = path.basename(name)
+    let args
+    if (base === 'x-terminal-emulator') args = ['-e', ...argv]
+    else if (TERMINALS[base]) args = TERMINALS[base](cwd, argv)
+    else continue
+
+    const result = await trySpawn(resolved, args, cwd)
+    if (result.ok) return { ok: true }
+    lastError = result.error
+  }
+
+  if (ranOut) {
+    return { ok: false, error: 'Gave up waiting for a terminal to open — is the display responding?' }
+  }
+  return {
+    ok: false,
+    error: lastError
+      ? `Could not open a terminal (${lastError})`
+      : 'No terminal emulator found — set THREADNAUTS_TERMINAL or $TERMINAL, or install one (gnome-terminal, kitty, xterm)',
+  }
+}

package/server/lib/user-data.mjs

@@ -0,0 +1,11 @@
+import os from 'node:os'
+import path from 'node:path'
+
+export function userDataDir({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (platform === 'win32') {
+    return path.win32.join(env.APPDATA || path.win32.join(home, 'AppData', 'Roaming'), 'Threadnauts')
+  }
+  if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'Threadnauts')
+  const xdg = env.XDG_DATA_HOME && path.posix.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : ''
+  return path.posix.join(xdg || path.posix.join(home, '.local', 'share'), 'threadnauts')
+}

package/server/lib/win-terminal.mjs

@@ -0,0 +1,88 @@
+/**
+ * Windows plumbing: how you put a command in a terminal window here.
+ *
+ * The counterpart to `openInTerminal` in `terminal.mjs`, and deliberately a separate file for the
+ * same reason that one is: it is a page of platform trivia with nothing to do with HTTP, and
+ * nothing in it knows about a particular harness. An adapter hands the server an argv; the
+ * server decides whether a terminal is the right place for it.
+ *
+ * Two terminals, tried in order. Windows Terminal is the one worth having — it takes the
+ * working directory as a flag and the command as trailing arguments, so nothing in the argv
+ * is ever read as a flag of its own. Plain `cmd.exe` is the fallback that is on every machine.
+ */
+import { spawn } from 'node:child_process'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { findExecutable } from '@threadcrumbs/common/lib/fsutil'
+
+/**
+ * `start` is a cmd builtin rather than a program, so it cannot be spawned directly — it has to
+ * be reached through `cmd /c`. `start` takes its first quoted argument as the new window's
+ * title, which is why the empty string is there: without it the first real argument disappears
+ * and the window opens on whatever the second one happened to be.
+ *
+ * `/k` keeps the window open after the command exits. That is the point of the feature — you
+ * are meant to keep typing in it — and it is also what makes a failure visible instead of a
+ * window that flashes and is gone before you read the error.
+ */
+const TERMINALS = {
+  'wt.exe': (cwd, argv) => ['-d', cwd, ...argv],
+  'cmd.exe': (_cwd, argv) => ['/c', 'start', '', 'cmd.exe', '/k', ...argv],
+}
+
+const ORDER = ['wt.exe', 'cmd.exe']
+
+function trySpawn(bin, args, cwd) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      // Detached and unref'd: the terminal has to outlive this request, and it must not hold
+      // the dev server open when you stop it.
+      child = spawn(bin, args, { cwd, detached: true, stdio: 'ignore', windowsHide: false })
+    } catch (err) {
+      return resolve({ ok: false, error: String(err && err.message ? err.message : err) })
+    }
+    // A spawn that is going to fail does so immediately; one that survives the tick is running.
+    const settled = setTimeout(() => {
+      child.unref()
+      resolve({ ok: true })
+    }, 120)
+    child.once('error', (err) => {
+      clearTimeout(settled)
+      resolve({ ok: false, error: String(err && err.message ? err.message : err) })
+    })
+  })
+}
+
+/**
+ * Open `argv` in a terminal sitting in `cwd`.
+ *
+ * Both arguments are validated the same way `openInTerminal` validates them, and for the same
+ * reason: this function will hand what it is given to the OS, so a relative path or an empty
+ * string is refused here rather than resolved against whatever directory the server happens to
+ * be running in.
+ */
+export async function openInTerminalWindows(argv, cwd) {
+  const wellFormed = Array.isArray(argv) && argv.length > 0 && argv.every((a) => typeof a === 'string' && a)
+  if (!wellFormed || !path.isAbsolute(argv[0]) || typeof cwd !== 'string' || !path.isAbsolute(cwd)) {
+    return { ok: false, error: 'Invalid launch command' }
+  }
+  const usable = await fsp.stat(cwd).then((st) => st.isDirectory(), () => false)
+  if (!usable) return { ok: false, error: 'That folder is not a directory any more' }
+
+  let lastError = ''
+  for (const name of ORDER) {
+    const resolved = await findExecutable(name)
+    if (!resolved) continue
+    const result = await trySpawn(resolved, TERMINALS[name](cwd, argv), cwd)
+    if (result.ok) return { ok: true }
+    lastError = result.error
+  }
+
+  return {
+    ok: false,
+    error: lastError
+      ? `Could not open a terminal (${lastError})`
+      : 'No terminal found — install Windows Terminal, or check that cmd.exe is on your PATH',
+  }
+}

package/server/lib/windows.mjs

@@ -0,0 +1,95 @@
+/**
+ * Windows desktop plumbing: put the window that hosts a given process in front.
+ *
+ * The sibling of `xdg.mjs`, for the same reason — a page of OS trivia with nothing to do with
+ * HTTP, and nothing in here knows about a particular harness. An adapter hands the server a pid;
+ * the server decides whether fronting its window is the right way to answer "open this".
+ *
+ * The pid itself has no window — it is a CLI process. The window belongs to whatever terminal is
+ * hosting it, which is some ancestor: the shell's parent is Windows Terminal, VS Code, an IDE.
+ * So the walk goes *up* the parent chain until a process with a real main window appears, and
+ * fronts that. The Claude desktop app is deliberately stepped over: a process hosted by the app
+ * itself is the app's to present, and the deep link does that better than raw window fronting.
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Enumerating every process (`Get-CimInstance Win32_Process`) is the slow half, a second or two
+ * on a busy machine; the rest is instant. The budget covers that with room, because past it the
+ * caller falls back to the deep link — a worse answer than a fronted window, but never a hang.
+ */
+const FOCUS_TIMEOUT_MS = 8000
+
+/** How many parents to visit before concluding nothing on the chain owns a window. */
+const MAX_HOPS = 16
+
+/**
+ * `SetForegroundWindow` alone is refused when the caller is a background process — Windows
+ * reserves focus-stealing for whoever the user is interacting with. A transient Alt keypress
+ * (0xA4, down then up) is the documented-by-folklore exemption: a process that just sent input
+ * counts as interacting. Restore-first matters too: fronting a minimized window leaves it
+ * minimized, just "active" in the taskbar.
+ */
+const script = (pid) => `
+$ErrorActionPreference = 'SilentlyContinue'
+$parent = @{}
+foreach ($p in Get-CimInstance Win32_Process) { $parent[[int]$p.ProcessId] = [int]$p.ParentProcessId }
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class WindowFocus {
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool ShowWindowAsync(IntPtr h, int cmd);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll")] public static extern void keybd_event(byte key, byte scan, uint flags, UIntPtr extra);
+}
+'@
+$cur = ${pid}
+for ($i = 0; $i -lt ${MAX_HOPS} -and $cur -gt 0; $i++) {
+  $proc = Get-Process -Id $cur
+  if ($proc -and $proc.MainWindowHandle -ne [IntPtr]::Zero) {
+    # The first *windowed* ancestor decides. The Claude app means the thread is the app's own —
+    # its deep link presents it better; explorer is the chain's root, and fronting a stray File
+    # Explorer window would be plain wrong. Either way: stop, let the caller fall back.
+    if ($proc.ProcessName -eq 'claude' -or $proc.ProcessName -eq 'explorer') { exit 1 }
+    $h = $proc.MainWindowHandle
+    if ([WindowFocus]::IsIconic($h)) { [WindowFocus]::ShowWindowAsync($h, 9) | Out-Null }
+    [WindowFocus]::keybd_event(0xA4, 0, 0, [UIntPtr]::Zero)
+    [WindowFocus]::keybd_event(0xA4, 0, 2, [UIntPtr]::Zero)
+    [WindowFocus]::SetForegroundWindow($h) | Out-Null
+    'focused'
+    exit 0
+  }
+  if (-not $parent.ContainsKey($cur)) { break }
+  $next = $parent[$cur]
+  if ($next -eq $cur) { break }
+  $cur = $next
+}
+exit 1
+`
+
+/**
+ * Front the window hosting `pid`. True only when a window was actually found and told to come
+ * forward; false covers everything else — wrong platform, a chain with no window on it (a
+ * detached process, or one hosted by the Claude desktop app), or PowerShell being unavailable.
+ * The caller treats false as "use the URL instead", so failing quietly is the whole contract.
+ */
+export async function focusWindowOfPid(pid) {
+  if (process.platform !== 'win32') return false
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    // -EncodedCommand sidesteps every quoting rule cmd and PowerShell disagree on.
+    const encoded = Buffer.from(script(pid), 'utf16le').toString('base64')
+    const { stdout } = await execFileAsync(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+      { timeout: FOCUS_TIMEOUT_MS, windowsHide: true }
+    )
+    return stdout.includes('focused')
+  } catch {
+    return false
+  }
+}

package/server/lib/xdg.mjs

@@ -0,0 +1,44 @@
+/**
+ * Linux desktop plumbing: does anything on this machine answer a URL scheme?
+ *
+ * Only `server/api.mjs` uses this, and only on Linux. It is split out because it is a page of
+ * desktop-environment trivia with nothing to do with HTTP, and nothing in here knows about a
+ * particular harness — an adapter never imports it.
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/** The scheme of a URL, or '' if it does not parse. */
+export function schemeOf(url) {
+  try {
+    return new URL(url).protocol.replace(/:$/, '')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Is a desktop app registered for this URL's scheme?
+ *
+ * `xdg-mime query default x-scheme-handler/<scheme>` is what `xdg-open` itself consults. It
+ * checks that a `mimeapps.list` entry still points at an installed .desktop file, which is the
+ * common stale case — an uninstalled app leaves its line behind — though its `mimeinfo.cache`
+ * fallback takes an entry on trust, exactly as xdg-open would.
+ *
+ * Anything that stops the query counts as "no handler": the alternative is handing xdg-open a
+ * URL nothing answers, which fails silently and reaches the page as "Opened".
+ */
+export async function schemeHasHandler(url) {
+  const scheme = schemeOf(url)
+  if (!/^[a-z][a-z0-9+.-]*$/.test(scheme)) return false
+  try {
+    // Bounded: on KDE the query goes through the trader, which can sit on a D-Bus timeout.
+    const args = ['query', 'default', `x-scheme-handler/${scheme}`]
+    const { stdout } = await execFileAsync('xdg-mime', args, { timeout: 5000 })
+    return stdout.trim().length > 0
+  } catch {
+    return false
+  }
+}

package/server/license.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { paidThrough, renewalDue } from '@threadcrumbs/common/license'
+import { cloudUrl, licenseStore, threadcrumbsDataDir, trustedKeys } from '@threadcrumbs/common/license/store'
+
+const ENTITLEMENT = 'threadnauts.pro'
+const CLOUD_TIMEOUT_MS = 15000
+
+const runningFromCheckout = fs.existsSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.git'))
+
+export function licensing({ store, cloudUrl, fetch = globalThis.fetch }) {
+  const describe = (license, at) => ({
+    proThrough: license ? paidThrough(license, ENTITLEMENT, at) : 0,
+    renewalDue: Boolean(license) && renewalDue(license, at),
+  })
+
+  async function status() {
+    const { license, at } = await store.current()
+    return describe(license, at)
+  }
+
+  async function ask(route, body) {
+    if (!cloudUrl) return { error: 'unavailable' }
+    let response
+    try {
+      response = await fetch(`${cloudUrl}${route}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(CLOUD_TIMEOUT_MS),
+      })
+    } catch {
+      return { error: 'offline' }
+    }
+    const data = await response.json().catch(() => null)
+    if (response.ok && typeof data?.license === 'string') return { license: data.license }
+    return { error: typeof data?.error === 'string' ? data.error : 'unavailable' }
+  }
+
+  async function keep(answer) {
+    if (answer.error) return { ...(await status()), error: answer.error }
+    const saved = await store.save(answer.license)
+    if (!saved.ok) return { ...(await status()), error: 'license_rejected' }
+    return describe(saved.license, saved.at)
+  }
+
+  async function activate(key) {
+    const trimmed = typeof key === 'string' ? key.trim() : ''
+    if (!trimmed) return { ...(await status()), error: 'key_missing' }
+    return keep(await ask('/v1/license', { key: trimmed, device: await store.device() }))
+  }
+
+  async function renew() {
+    const { token, license, at } = await store.current()
+    if (!token || !renewalDue(license, at)) return describe(license, at)
+    return keep(await ask('/v1/license/renew', { license: token }))
+  }
+
+  return { status, activate, renew }
+}
+
+export function localLicensing({ env = process.env, development = runningFromCheckout, fetch } = {}) {
+  return licensing({
+    store: licenseStore({ dir: threadcrumbsDataDir({ env }), keys: trustedKeys({ env, development }) }),
+    cloudUrl: cloudUrl({ env, development }),
+    fetch,
+  })
+}

package/server/pro-content.mjs

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { LICENSE_GRACE, paidThrough } from '@threadcrumbs/common/license'
+import { cloudUrl, licenseStore, threadcrumbsDataDir, trustedKeys } from '@threadcrumbs/common/license/store'
+
+const ENTITLEMENT = 'threadnauts.pro'
+const APP = 'threadnauts'
+const DOWNLOAD_TIMEOUT_MS = 60000
+const RENAME_TRIES = 10
+const PAUSE_MS = 20
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const DIST = path.join(here, '..', 'dist')
+const runningFromCheckout = fs.existsSync(path.join(here, '..', '.git'))
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex')
+const pause = () => new Promise((resolve) => setTimeout(resolve, PAUSE_MS))
+
+function readManifest(file) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const files = Array.isArray(manifest?.files) ? manifest.files : []
+    return files.every((f) => typeof f?.path === 'string' && /^assets\/[A-Za-z0-9._-]+$/.test(f.path) && /^[0-9a-f]{64}$/.test(f.sha256)) ? files : []
+  } catch {
+    return null
+  }
+}
+
+export function proContent({ store, cloudUrl, cacheDir, manifestFile = path.join(DIST, 'pro-manifest.json'), localBuild = null, fetch = globalThis.fetch }) {
+  let downloading = null
+  let listed
+  const manifest = () => (listed === undefined ? (listed = readManifest(manifestFile)) : listed)
+  const cached = (file) => path.join(cacheDir, file.path)
+
+  async function verified(file) {
+    const bytes = await fsp.readFile(cached(file)).catch(() => null)
+    return bytes && sha256(bytes) === file.sha256 ? bytes : null
+  }
+
+  async function present(files) {
+    for (const file of files) {
+      if (!(await verified(file))) return false
+    }
+    return true
+  }
+
+  async function keep(file, bytes) {
+    if (sha256(bytes) !== file.sha256) return false
+    const target = cached(file)
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`
+    try {
+      await fsp.mkdir(path.dirname(target), { recursive: true })
+      await fsp.writeFile(temp, bytes)
+      for (let attempt = 1; ; attempt++) {
+        try {
+          await fsp.rename(temp, target)
+          return true
+        } catch (err) {
+          if (attempt >= RENAME_TRIES || !['EPERM', 'EACCES', 'EBUSY'].includes(err.code)) throw err
+          await pause()
+        }
+      }
+    } catch (err) {
+      await fsp.rm(temp, { force: true })
+      throw err
+    }
+  }
+
+  async function copyLocalBuild(files) {
+    if (!localBuild) return false
+    for (const file of files) {
+      if (await present([file])) continue
+      let bytes
+      try {
+        bytes = await fsp.readFile(path.join(localBuild, file.path))
+      } catch {
+        return false
+      }
+      if (!(await keep(file, bytes).catch(() => false))) return false
+    }
+    return true
+  }
+
+  async function download(files) {
+    if (await copyLocalBuild(files)) return { ready: true }
+    const { token, license, at } = await store.current()
+    if (!token || paidThrough(license, ENTITLEMENT, at) <= 0) return { ready: false, error: 'no_license' }
+    if (at > license.exp + LICENSE_GRACE) return { ready: false, error: 'license_expired' }
+    if (!cloudUrl) return { ready: false, error: 'unavailable' }
+    for (const file of files) {
+      if (await present([file])) continue
+      let bytes
+      try {
+        const response = await fetch(`${cloudUrl}/v1/content/${APP}/${file.path}`, {
+          headers: { authorization: `Bearer ${token}`, 'x-threadcrumbs-device': license.dev },
+          signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+        })
+        if (!response.ok) {
+          const data = await response.json().catch(() => null)
+          return { ready: false, error: typeof data?.error === 'string' ? data.error : 'unavailable' }
+        }
+        bytes = Buffer.from(await response.arrayBuffer())
+      } catch {
+        return { ready: false, error: 'offline' }
+      }
+      const kept = await keep(file, bytes).catch(() => null)
+      if (kept === null) return { ready: false, error: 'not_saved' }
+      if (!kept) return { ready: false, error: 'corrupt' }
+    }
+    return { ready: true }
+  }
+
+  async function status() {
+    const files = manifest()
+    if (files === null) return { ready: true }
+    if (await present(files)) return { ready: true }
+    downloading ??= download(files)
+      .catch(() => ({ ready: false, error: 'unavailable' }))
+      .finally(() => {
+        downloading = null
+      })
+    return downloading
+  }
+
+  async function file(pathname) {
+    const wanted = manifest()?.find((f) => `/${f.path}` === pathname)
+    if (!wanted) return null
+    return (await verified(wanted)) ?? ((await status()).ready ? verified(wanted) : null)
+  }
+
+  return { status, file }
+}
+
+export function localProContent({ env = process.env, development = runningFromCheckout, fetch } = {}) {
+  const dir = threadcrumbsDataDir({ env })
+  return proContent({
+    store: licenseStore({ dir, keys: trustedKeys({ env, development }) }),
+    cloudUrl: cloudUrl({ env, development }),
+    cacheDir: path.join(dir, 'content', APP),
+    localBuild: development ? path.join(here, '..', 'pro-dist') : null,
+    fetch,
+  })
+}