@sprid/cli 0.1.2

package/src/post/screen/simkit.swift

@@ -0,0 +1,328 @@
+// simkit - the two things a screen-recorded reel needs that no CLI on this
+// machine provides: a human-shaped touch, and a rasterised caption.
+//
+// **Why CGEvent and not idb/Maestro.** Both are real dependencies (a Python
+// companion, a JVM) and both send a LINEAR interpolation, which is the one
+// thing that makes a scripted scroll read as scripted: iOS computes momentum
+// from the velocity at the instant the finger lifts, so a gesture that
+// decelerates into its endpoint produces a dead scroll with no inertia. A
+// posted CGEvent stream costs nothing to install and lets the velocity curve be
+// the thing we control.
+//
+// Synthetic input requires Accessibility permission for the automation host.
+// Verify it with a tap before recording.
+//
+// Build: swiftc -O -o simkit simkit.swift   (cached by the caller)
+
+import Foundation
+import CoreGraphics
+import AppKit
+
+// ---------------------------------------------------------------------------
+// args
+// ---------------------------------------------------------------------------
+
+let ARGV = CommandLine.arguments
+func opt(_ n: String) -> String? {
+    guard let i = ARGV.firstIndex(of: "--" + n), i + 1 < ARGV.count else { return nil }
+    return ARGV[i + 1]
+}
+func num(_ n: String, _ d: Double) -> Double { Double(opt(n) ?? "") ?? d }
+func has(_ n: String) -> Bool { ARGV.contains("--" + n) }
+func all(_ n: String) -> [String] {
+    var out: [String] = []
+    var i = 0
+    while i < ARGV.count { if ARGV[i] == "--" + n, i + 1 < ARGV.count { out.append(ARGV[i+1]); i += 1 }; i += 1 }
+    return out
+}
+func die(_ m: String, _ code: Int32 = 2) -> Never {
+    FileHandle.standardError.write((m + "\n").data(using: .utf8)!)
+    exit(code)
+}
+
+// ---------------------------------------------------------------------------
+// the window, and where the device screen sits inside it
+// ---------------------------------------------------------------------------
+
+struct Rect { var x: Double; var y: Double; var w: Double; var h: Double }
+
+func simulatorWindow() -> Rect? {
+    guard let list = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else { return nil }
+    var best: Rect?
+    for w in list {
+        guard (w[kCGWindowOwnerName as String] as? String) == "Simulator",
+              let b = w[kCGWindowBounds as String] as? [String: Any] else { continue }
+        let r = Rect(x: b["X"] as? Double ?? 0, y: b["Y"] as? Double ?? 0,
+                     w: b["Width"] as? Double ?? 0, h: b["Height"] as? Double ?? 0)
+        if r.w < 120 || r.h < 120 { continue }
+        if best == nil || r.w * r.h > best!.w * best!.h { best = r }
+    }
+    return best
+}
+
+/// Where the device screen sits inside the window.
+///
+/// **Measured, not assumed** (2026-09-05). Dragging a known fraction of the
+/// screen and reading the pixel shift back out of a device screenshot at three
+/// distances solves two unknowns at once: the screen's height in window points,
+/// and UIScrollView's pan slop. 0.05/0.10/0.15 of height moved a list
+/// 109/247/382 device px, whose differences give **910 points of screen** in a
+/// 931-point window - the device fills everything below a 21-point title bar -
+/// and **9.2 points of slop** before a scroll starts tracking at all.
+///
+/// The first pass here read the single-distance version as 874 points and
+/// "confirmed" a centred device with a drawn bezel. It was the slop: a constant
+/// loss fits any scale if you only measure one distance. Two would have been
+/// enough; three is what makes it obvious.
+///
+/// The caller owns this model - it passes `--rect` from its own calibration -
+/// and this is only the default.
+func defaultDeviceRect(_ win: Rect, aspect: Double, titleBar: Double) -> Rect {
+    let inner = Rect(x: win.x, y: win.y + titleBar, w: win.w, h: win.h - titleBar)
+    if inner.w / inner.h > aspect {
+        let w = inner.h * aspect
+        return Rect(x: inner.x + (inner.w - w) / 2, y: inner.y, w: w, h: inner.h)
+    }
+    let h = inner.w / aspect
+    return Rect(x: inner.x, y: inner.y + (inner.h - h) / 2, w: inner.w, h: h)
+}
+
+// ---------------------------------------------------------------------------
+// posting
+// ---------------------------------------------------------------------------
+
+let src = CGEventSource(stateID: .hidSystemState)
+func post(_ type: CGEventType, _ p: CGPoint) {
+    CGEvent(mouseEventSource: src, mouseType: type, mouseCursorPosition: p, mouseButton: .left)?
+        .post(tap: .cghidEventTap)
+}
+func sleepMs(_ ms: Double) { if ms > 0 { usleep(useconds_t(ms * 1000)) } }
+
+var rng = SystemRandomNumberGenerator()
+func jit(_ a: Double) -> Double { a <= 0 ? 0 : Double.random(in: -a...a, using: &rng) }
+
+/// Ease-in-out: a deliberate drag that arrives and stops. For pulling a sheet
+/// to a position, not for scrolling.
+func easeInOut(_ t: Double) -> Double { t < 0.5 ? 2*t*t : 1 - pow(-2*t + 2, 2)/2 }
+/// **A flick still moving at the moment of release.** This is the whole reason
+/// this file exists: iOS reads the last few milliseconds of travel as the
+/// throw velocity, so a curve that decelerates hands it zero and the list stops
+/// dead under the finger.
+func easeInHold(_ t: Double) -> Double { pow(t, 1.55) }
+
+// ---------------------------------------------------------------------------
+// gestures
+// ---------------------------------------------------------------------------
+
+let HZ = 120.0
+
+func tap(_ p: CGPoint, holdMs: Double) {
+    post(.mouseMoved, CGPoint(x: p.x + jit(7), y: p.y + jit(7)))   // the approach
+    sleepMs(Double.random(in: 45...90, using: &rng))
+    post(.mouseMoved, p)
+    sleepMs(Double.random(in: 20...45, using: &rng))
+    post(.leftMouseDown, p)
+    let steps = max(1, Int(holdMs / (1000/HZ)))
+    for _ in 0..<steps {                                            // a finger is never still
+        post(.leftMouseDragged, CGPoint(x: p.x + jit(0.9), y: p.y + jit(0.9)))
+        sleepMs(1000/HZ)
+    }
+    post(.leftMouseUp, p)
+}
+
+func swipe(_ a: CGPoint, _ b: CGPoint, durationMs: Double, flick: Bool, bow: Double, settleMs: Double) {
+    post(.mouseMoved, CGPoint(x: a.x + jit(10), y: a.y + jit(10)))
+    sleepMs(Double.random(in: 60...120, using: &rng))
+    post(.mouseMoved, a)
+    sleepMs(Double.random(in: 25...55, using: &rng))
+    post(.leftMouseDown, a)
+    sleepMs(Double.random(in: 12...28, using: &rng))                // press, then travel
+
+    let dx = b.x - a.x, dy = b.y - a.y
+    let dist = (dx*dx + dy*dy).squareRoot()
+    let nx = dist > 0 ? -dy/dist : 0, ny = dist > 0 ? dx/dist : 0
+    let bowPx = bow * dist * (Bool.random(using: &rng) ? 1 : -1)    // nobody drags a straight line
+
+    let steps = max(4, Int(durationMs / (1000/HZ)))
+    for i in 1...steps {
+        let t = Double(i) / Double(steps)
+        let e = flick ? easeInHold(t) : easeInOut(t)
+        let arc = sin(e * .pi) * bowPx
+        post(.leftMouseDragged, CGPoint(x: a.x + dx*e + nx*arc + jit(0.7),
+                                        y: a.y + dy*e + ny*arc + jit(0.7)))
+        sleepMs(1000/HZ)
+    }
+    if !flick { sleepMs(settleMs) }
+    post(.leftMouseUp, b)
+}
+
+// ---------------------------------------------------------------------------
+// text: a caption card, rasterised
+// ---------------------------------------------------------------------------
+
+func registerFont(_ path: String) -> String? {
+    let url = URL(fileURLWithPath: path)
+    CTFontManagerRegisterFontsForURL(url as CFURL, .process, nil)
+    guard let d = CGDataProvider(url: url as CFURL), let cg = CGFont(d) else { return nil }
+    return cg.postScriptName as String?
+}
+
+func hexColor(_ hex: String, _ alpha: Double = 1) -> NSColor {
+    var s = hex.hasPrefix("#") ? String(hex.dropFirst()) : hex
+    if s.count == 3 { s = s.map { "\($0)\($0)" }.joined() }
+    let v = UInt32(s, radix: 16) ?? 0xFFFFFF
+    return NSColor(srgbRed: Double((v >> 16) & 255)/255, green: Double((v >> 8) & 255)/255,
+                   blue: Double(v & 255)/255, alpha: alpha)
+}
+
+func renderText() {
+    let lines = all("line")
+    guard !lines.isEmpty else { die("text needs at least one --line") }
+    guard let outPath = opt("out") else { die("text needs --out") }
+    let width = num("w", 980)
+    let size = num("size", 78)
+    let tracking = num("tracking", -1)
+    let lineGap = num("linegap", 10)
+    let strokeW = num("stroke", 13)
+    let padX = num("padx", 34), padY = num("pady", 20)
+    let radius = num("radius", 22)
+    let pillAlpha = num("pill", 0)
+
+    var font: NSFont?
+    if let f = opt("font-file"), let ps = registerFont(f) { font = NSFont(name: ps, size: size) }
+    if font == nil, let n = opt("font") { font = NSFont(name: n, size: size) }
+    let f = font ?? NSFont.systemFont(ofSize: size, weight: .heavy)
+
+    let para = NSMutableParagraphStyle()
+    para.alignment = .center
+    para.lineSpacing = lineGap
+    para.lineBreakMode = .byWordWrapping
+
+    let shadow = NSShadow()
+    shadow.shadowColor = NSColor(white: 0, alpha: 0.45)
+    shadow.shadowBlurRadius = num("shadow", 12)
+    shadow.shadowOffset = NSSize(width: 0, height: -num("shadowy", 4))
+
+    var attrs: [NSAttributedString.Key: Any] = [
+        .font: f,
+        .foregroundColor: hexColor(opt("color") ?? "ffffff"),
+        .paragraphStyle: para,
+        .kern: tracking,
+        .shadow: shadow,
+    ]
+    // A NEGATIVE stroke width is fill-and-stroke; a positive one is stroke only
+    // and renders hollow text, which is the classic way to lose an hour here.
+    if strokeW > 0 {
+        attrs[.strokeWidth] = -strokeW
+        attrs[.strokeColor] = hexColor(opt("stroke-color") ?? "000000")
+    }
+
+    let text = NSAttributedString(string: lines.joined(separator: "\n"), attributes: attrs)
+    let textW = width - padX * 2
+    let bounds = text.boundingRect(with: NSSize(width: textW, height: 4000),
+                                   options: [.usesLineFragmentOrigin, .usesFontLeading])
+    let h = ceil(bounds.height) + padY * 2 + strokeW
+    let w = width
+
+    guard let rep = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: Int(w), pixelsHigh: Int(h),
+                                     bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true, isPlanar: false,
+                                     colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0)
+    else { die("could not allocate a bitmap") }
+    NSGraphicsContext.saveGraphicsState()
+    NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: rep)
+    NSColor.clear.setFill()
+    NSRect(x: 0, y: 0, width: w, height: h).fill()
+
+    if pillAlpha > 0 {
+        let pillW = min(w, ceil(bounds.width) + padX * 2)
+        let r = NSRect(x: (w - pillW) / 2, y: 0, width: pillW, height: h)
+        hexColor(opt("pill-color") ?? "000000", pillAlpha).setFill()
+        NSBezierPath(roundedRect: r, xRadius: radius, yRadius: radius).fill()
+    }
+    text.draw(with: NSRect(x: padX, y: padY, width: textW, height: h - padY * 2),
+              options: [.usesLineFragmentOrigin, .usesFontLeading])
+
+    NSGraphicsContext.restoreGraphicsState()
+    guard let png = rep.representation(using: .png, properties: [:]) else { die("png encode failed") }
+    try? png.write(to: URL(fileURLWithPath: outPath))
+    print("\(Int(w)) \(Int(h))")
+}
+
+/// The touch indicator. A screen recording has no finger in it, and without one
+/// the viewer cannot tell a tap from the app moving on its own.
+func renderDot() {
+    guard let outPath = opt("out") else { die("dot needs --out") }
+    let r = num("r", 54)
+    let s = Int(r * 2)
+    guard let rep = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: s, pixelsHigh: s,
+                                     bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true, isPlanar: false,
+                                     colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0)
+    else { die("could not allocate a bitmap") }
+    NSGraphicsContext.saveGraphicsState()
+    NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: rep)
+    NSColor.clear.setFill()
+    NSRect(x: 0, y: 0, width: Double(s), height: Double(s)).fill()
+    // Soft, not a hard puck: iOS' own touch indicator is a low-contrast disc and
+    // a hard white circle reads as a cursor.
+    let steps = 26
+    for i in stride(from: steps, through: 1, by: -1) {
+        let t = Double(i) / Double(steps)
+        let rr = r * t
+        NSColor(white: 1, alpha: 0.055 * pow(1 - t, 0.6)).setFill()
+        NSBezierPath(ovalIn: NSRect(x: r - rr, y: r - rr, width: rr * 2, height: rr * 2)).fill()
+    }
+    NSColor(white: 1, alpha: 0.30).setFill()
+    NSBezierPath(ovalIn: NSRect(x: r * 0.42, y: r * 0.42, width: r * 1.16, height: r * 1.16)).fill()
+    NSColor(white: 1, alpha: 0.34).setStroke()
+    let ring = NSBezierPath(ovalIn: NSRect(x: r * 0.42, y: r * 0.42, width: r * 1.16, height: r * 1.16))
+    ring.lineWidth = 2.5
+    ring.stroke()
+    NSGraphicsContext.restoreGraphicsState()
+    guard let png = rep.representation(using: .png, properties: [:]) else { die("png encode failed") }
+    try? png.write(to: URL(fileURLWithPath: outPath))
+    print("\(s) \(s)")
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+guard ARGV.count > 1 else { die("usage: simkit window|tap|swipe|park|text|dot [options]") }
+let cmd = ARGV[1]
+
+if cmd == "text" { renderText(); exit(0) }
+if cmd == "dot" { renderDot(); exit(0) }
+
+guard let win = simulatorWindow() else { die("No Simulator window on screen. Is Simulator.app open?", 3) }
+let dev: Rect = {
+    if let r = opt("rect") {
+        let p = r.split(separator: ",").map { Double($0) ?? 0 }
+        if p.count == 4 { return Rect(x: p[0], y: p[1], w: p[2], h: p[3]) }
+        die("--rect wants x,y,w,h in screen points")
+    }
+    return defaultDeviceRect(win, aspect: num("aspect", 402.0/874.0), titleBar: num("titlebar", 21))
+}()
+func pt(_ nx: Double, _ ny: Double) -> CGPoint { CGPoint(x: dev.x + nx * dev.w, y: dev.y + ny * dev.h) }
+
+if !has("no-activate") {
+    for app in NSWorkspace.shared.runningApplications where app.localizedName == "Simulator" {
+        app.activate(options: [])
+    }
+    sleepMs(num("activate-wait", 220))
+}
+
+switch cmd {
+case "window":
+    print("window \(win.x) \(win.y) \(win.w) \(win.h)")
+    print("device \(dev.x) \(dev.y) \(dev.w) \(dev.h)")
+case "tap":
+    tap(pt(num("x", 0.5), num("y", 0.5)), holdMs: num("hold", Double.random(in: 55...100, using: &rng)))
+case "swipe":
+    swipe(pt(num("x1", 0.5), num("y1", 0.72)), pt(num("x2", 0.5), num("y2", 0.28)),
+          durationMs: num("duration", 260), flick: !has("precise"),
+          bow: num("bow", 0.025), settleMs: num("settle", 90))
+case "park":
+    post(.mouseMoved, CGPoint(x: win.x + win.w + 60, y: win.y + 20))
+default:
+    die("unknown command \(cmd)")
+}

package/src/profiles.mjs

@@ -0,0 +1,61 @@
+// App Profiles over REST, and the three ways to say which one:
+// `--app <slug>`, the only one there is, or the slug in ./.sprid/app.json.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { UsageError } from "./args.mjs";
+
+export function readLocalApp(cwd) {
+  const p = resolve(cwd, ".sprid", "app.json");
+  if (!existsSync(p)) return null;
+  try {
+    return { path: p, data: JSON.parse(readFileSync(p, "utf8")) };
+  } catch (e) {
+    throw new UsageError(`${p} is not valid JSON: ${e.message}`);
+  }
+}
+
+export async function listProfiles(ctx, workspaceId) {
+  const res = await ctx.api().get(`/api/app-profiles?workspaceId=${workspaceId}`);
+  return res?.profiles ?? [];
+}
+
+export async function resolveProfile(ctx, workspaceId, { required = true } = {}) {
+  const profiles = await listProfiles(ctx, workspaceId);
+  const want = ctx.flags.app || readLocalApp(ctx.cwd)?.data?.appId || readLocalApp(ctx.cwd)?.data?.slug || null;
+  if (want) {
+    const hit = profiles.find((p) => p.slug === want || String(p.id) === String(want));
+    if (!hit) {
+      throw new UsageError(
+        `No App Profile "${want}" in this workspace${profiles.length ? ` (have: ${profiles.map((p) => p.slug).join(", ")})` : ""}. Run \`sprid init\` first.`,
+      );
+    }
+    return hit;
+  }
+  if (profiles.length === 1) return profiles[0];
+  if (!required) return null;
+  if (profiles.length === 0) throw new UsageError("No App Profile yet. Run `sprid init` in the app's repo.");
+  throw new UsageError(`Which app? Pass --app <slug> (${profiles.map((p) => p.slug).join(", ")}), or run from the repo with .sprid/app.json.`);
+}
+
+export async function patchProfile(ctx, workspaceId, id, body) {
+  return ctx.api().patch(`/api/app-profiles/${id}?workspaceId=${workspaceId}`, body);
+}
+
+export async function createProfile(ctx, workspaceId, body) {
+  return ctx.api().post(`/api/app-profiles`, { workspaceId, ...body });
+}
+
+export function readKeyFile(path, cwd) {
+  const p = resolve(cwd, expandHome(path));
+  if (!existsSync(p)) throw new UsageError(`Key file not found: ${p}`);
+  const text = readFileSync(p, "utf8");
+  if (!text.trim()) throw new UsageError(`Key file is empty: ${p}`);
+  return text;
+}
+
+export function expandHome(p) {
+  if (p === "~") return process.env.HOME || p;
+  if (p.startsWith("~/")) return join(process.env.HOME || "", p.slice(2));
+  return p;
+}

package/src/release.ts

@@ -0,0 +1,2 @@
+export { defineReleaseConfig } from '@sprid/release/config';
+export type { AppReleaseConfig } from '@sprid/release/config';

package/src/screenshots.ts

@@ -0,0 +1 @@
+export type { AsoConfig, ReviewConfig } from '@sprid/shots/types';

package/src/updates.mjs

@@ -0,0 +1,152 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const REGISTRY = 'https://registry.npmjs.org';
+// The unscoped name `sprid` is refused by npm's similarity filter, so the
+// package is scoped while the command stays `sprid`. The registry path needs
+// the slash encoded; every other reference is the literal package name.
+const PACKAGE = '@sprid/cli';
+const PACKAGE_PATH = '@sprid%2fcli';
+const DAY = 86_400_000;
+const read = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+const real = path => { try { return realpathSync(path); } catch { return null; } };
+export const stableVersion = value => typeof value === 'string' && /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/.test(value);
+export function compareVersions(a, b) {
+  if (!stableVersion(a) || !stableVersion(b)) throw new Error('Expected a stable x.y.z version.');
+  const x = a.split('.').map(Number), y = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return Math.sign(x[i] - y[i]);
+  return 0;
+}
+export function compatibleUpdate(current, next) {
+  if (!stableVersion(current) || !stableVersion(next) || compareVersions(next, current) <= 0) return false;
+  const [a, b] = current.split('.').map(Number), [x, y] = next.split('.').map(Number);
+  return a === x && (a > 0 || (b === y && b > 0));
+}
+function atomicJson(path, data) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try { writeFileSync(tmp, JSON.stringify(data) + '\n', { mode: 0o600, flag: 'wx' }); renameSync(tmp, path); }
+  finally { rmSync(tmp, { force: true }); }
+}
+export function stateDirectory(env = process.env) { return join(env.HOME || homedir(), '.sprid', 'updates'); }
+
+/** Registry failure is data, never a reason to block unrelated work. No auth is sent. */
+export async function checkVersion({ current, env = process.env, fetchImpl = globalThis.fetch, now = Date.now(), force = false, offline = false } = {}) {
+  const path = join(stateDirectory(env), 'latest.json');
+  const cached = read(path);
+  const fresh = cached && Number.isFinite(cached.checkedAt) && now >= cached.checkedAt && now - cached.checkedAt < DAY;
+  let record = cached;
+  if (!offline && (force || !fresh)) {
+    try {
+      const res = await fetchImpl(`${REGISTRY}/${PACKAGE_PATH}/latest`, { redirect: 'error', signal: AbortSignal.timeout(2000), headers: { Accept: 'application/json' } });
+      if (!res.ok) { await res.body?.cancel(); throw new Error('registry unavailable'); }
+      const reader = res.body.getReader(); let size = 0; const chunks = [];
+      try {
+        while (true) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > 131072) throw new Error('registry response too large'); chunks.push(Buffer.from(value)); }
+      } finally { await reader.cancel().catch(() => {}); }
+      const data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (data.name !== PACKAGE || !stableVersion(data.version)) throw new Error('invalid registry version');
+      record = { checkedAt: now, version: data.version, available: true };
+    } catch { record = { checkedAt: now, version: stableVersion(cached?.version) ? cached.version : null, available: false }; }
+    try { atomicJson(path, record); } catch { /* A read-only home must not prevent checking. */ }
+  }
+  const recommended = stableVersion(record?.version) ? record.version : null;
+  const verified = !offline && record?.available === true && Number.isFinite(record.checkedAt) && now >= record.checkedAt && now - record.checkedAt < DAY;
+  const updateAvailable = Boolean(recommended && stableVersion(current) && compareVersions(recommended, current) > 0);
+  return { current, recommended, check: verified ? 'verified' : 'unavailable', cached: Boolean(cached) && record === cached, checkedAt: record?.checkedAt ?? null,
+    updateAvailable, compatible: updateAvailable && compatibleUpdate(current, recommended),
+    requiresApproval: updateAvailable && !compatibleUpdate(current, recommended),
+    source: `${REGISTRY}/${PACKAGE_PATH}/latest` };
+}
+
+async function execute(command, args, options) {
+  return exec(command, args, { timeout: 120000, maxBuffer: 4 * 1024 * 1024, ...options });
+}
+export const runProcess = execute;
+
+/** Identify the running package, never a similarly named package in cwd. */
+export async function detectInstallation({ packageRoot = PACKAGE_ROOT, env = process.env, runner = execute, platform = process.platform } = {}) {
+  const root = real(packageRoot);
+  const unsupported = reason => ({ kind: 'unsupported', packageRoot: root, reason });
+  if (!root || read(join(root, 'package.json'))?.name !== PACKAGE) return unsupported('Cannot identify this Sprid installation.');
+  if (platform === 'win32') return unsupported('On Windows, update through the package manager that installed Sprid.');
+  // A checkout or npm link must never be overwritten by the updater.
+  if (!root.split(/[\\/]/).includes('node_modules')) return unsupported('Source checkout or linked installation. Update its source instead.');
+  for (let dir = dirname(root); dirname(dir) !== dir; dir = dirname(dir)) {
+    if (dir.split(/[\\/]/).includes('_npx')) return unsupported('Temporary npx installation. Start a new npx invocation with the desired version.');
+    const pkg = read(join(dir, 'package.json'));
+    const field = ['dependencies', 'devDependencies', 'optionalDependencies'].find(key => typeof pkg?.[key]?.[PACKAGE] === 'string');
+    if (!field || real(join(dir, 'node_modules', '@sprid', 'cli')) !== root) continue;
+    const declared = pkg[field][PACKAGE];
+    if (!/^[~^]?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(declared)) return unsupported('Sprid is linked or uses a custom package source. Update that declaration manually.');
+    let manager = null, lockRoot = dir;
+    for (let cursor = dir; dirname(cursor) !== cursor; cursor = dirname(cursor)) {
+      const manifest = read(join(cursor, 'package.json'));
+      const declaredManager = manifest?.packageManager?.match(/^(npm|pnpm|yarn|bun)@/)?.[1];
+      const locks = [['npm', 'package-lock.json'], ['npm', 'npm-shrinkwrap.json'], ['pnpm', 'pnpm-lock.yaml'], ['yarn', 'yarn.lock'], ['bun', 'bun.lock'], ['bun', 'bun.lockb']].filter(([, file]) => existsSync(join(cursor, file))).map(([name]) => name);
+      const unique = [...new Set(locks)];
+      if (unique.length > 1 || (declaredManager && unique.length && !unique.includes(declaredManager))) return unsupported('Conflicting package managers or lockfiles. Resolve them before updating.');
+      if (declaredManager || unique.length) { manager = declaredManager || unique[0]; lockRoot = cursor; break; }
+    }
+    if (!manager) return unsupported('No packageManager or lockfile identifies the project package manager.');
+    return { kind: 'local', packageRoot: root, projectRoot: dir, lockRoot, manager, field };
+  }
+  try {
+    const options = { cwd: env.HOME || homedir(), env, timeout: 3000 };
+    const { stdout: globalRoot } = await runner('npm', ['root', '--global'], options);
+    const { stdout: prefix } = await runner('npm', ['prefix', '--global'], options);
+    if (real(join(globalRoot.trim(), '@sprid', 'cli')) === root && real(prefix.trim())) return { kind: 'global', manager: 'npm', packageRoot: root, prefix: real(prefix.trim()) };
+  } catch { /* No usable npm on this PATH. */ }
+  return unsupported('Installation is not an identified npm global or project dependency. Update with its original package manager.');
+}
+function keyFor(installation) { return createHash('sha256').update(installation.projectRoot || installation.packageRoot || '').digest('hex'); }
+export function autoEnabled(installation, env = process.env) {
+  return read(join(stateDirectory(env), `${keyFor(installation)}.json`))?.auto === true;
+}
+export function setAuto(installation, enabled, env = process.env) {
+  if (installation.kind === 'unsupported') throw new Error(installation.reason);
+  atomicJson(join(stateDirectory(env), `${keyFor(installation)}.json`), { auto: enabled });
+}
+export function installationCommand(installation, version) {
+  if (installation.kind === 'unsupported' || !stableVersion(version)) return null;
+  const target = `${PACKAGE}@${version}`;
+  if (installation.kind === 'global') return { command: 'npm', args: ['install', '--global', '--prefix', installation.prefix, '--ignore-scripts', `--registry=${REGISTRY}`, target] };
+  const dev = installation.field === 'devDependencies', optional = installation.field === 'optionalDependencies';
+  if (installation.manager === 'npm') return { command: 'npm', args: ['install', '--save-exact', '--ignore-scripts', `--registry=${REGISTRY}`, ...(dev ? ['--save-dev'] : optional ? ['--save-optional'] : ['--save-prod']), target] };
+  if (installation.manager === 'pnpm') return { command: 'pnpm', args: ['add', '--save-exact', '--ignore-scripts', '--ignore-pnpmfile', `--registry=${REGISTRY}`, ...(installation.projectRoot === installation.lockRoot && existsSync(join(installation.lockRoot, 'pnpm-workspace.yaml')) ? ['--workspace-root'] : []), ...(dev ? ['--save-dev'] : optional ? ['--save-optional'] : ['--save-prod']), target] };
+  if (installation.manager === 'bun') return { command: 'bun', args: ['add', '--exact', '--ignore-scripts', `--registry=${REGISTRY}`, ...(dev ? ['--dev'] : optional ? ['--optional'] : []), target] };
+  // Yarn's build-suppression flag depends on its major version, resolved before execution.
+  return { command: 'yarn', args: ['add', '--exact', ...(dev ? ['--dev'] : optional ? ['--optional'] : []), target] };
+}
+export async function performUpdate(installation, version, { env = process.env, runner = execute } = {}) {
+  const plan = installationCommand(installation, version);
+  if (!plan) throw new Error(installation.reason || 'Invalid update target.');
+  const state = stateDirectory(env), lock = join(state, `${keyFor(installation)}.lock`);
+  mkdirSync(state, { recursive: true, mode: 0o700 });
+  try { mkdirSync(lock, { mode: 0o700 }); } catch { throw new Error(`Another update may be running. If it was interrupted, remove ${lock} before retrying.`); }
+  try {
+    const options = { cwd: installation.projectRoot || env.HOME || homedir(), env: { ...env, npm_config_ignore_scripts: 'true' } };
+    if (plan.command === 'yarn') {
+      const { stdout } = await runner('yarn', ['--version'], { ...options, timeout: 3000 });
+      if (!stableVersion(stdout.trim())) throw new Error('Cannot identify Yarn version.');
+      const major = Number(stdout.trim().split('.')[0]);
+      plan.args.push(major >= 4 ? '--mode=skip-build' : major >= 2 ? '--mode=skip-builds' : '--ignore-scripts');
+    }
+    try { await runner(plan.command, plan.args, options); }
+    catch { throw new Error('Package manager update failed. Installation or lockfiles may have changed; inspect them before retrying.'); }
+    // Resolve again after pnpm changes a node_modules symlink to a new store path.
+    const root = installation.kind === 'local' ? real(join(installation.projectRoot, 'node_modules', '@sprid', 'cli')) : installation.packageRoot;
+    const installed = root && read(join(root, 'package.json'));
+    if (installed?.version !== version) throw new Error('Update verification failed: installed package has the wrong version.');
+    const { stdout } = await runner(process.execPath, [join(root, 'bin.mjs'), '--version'], options);
+    if (stdout.trim() !== version) throw new Error('Update verification failed: the installed CLI reports a different version.');
+    return { updated: true, version, restartRequired: true };
+  } finally { rmSync(lock, { recursive: true, force: true }); }
+}