pi-remote-control 1.0.0

package/src/extension/index.ts

@@ -0,0 +1,422 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { RemoteTuiCommand } from "../active-session-registry.js";
+import type { RemoteCompactResultEvent } from "../types.js";
+import { loadDaemonConfig } from "../config.js";
+import { getDaemonStateDir } from "../paths.js";
+import { collectRuntimeStatus } from "../runtime-status.js";
+import { projectIdForPath } from "../session-index.js";
+
+export { collectRuntimeStatus } from "../runtime-status.js";
+
+export default function remoteControlExtension(pi: ExtensionAPI): void {
+  const activeSessionIds = new Set<string>();
+  const pollTimers = new Map<string, NodeJS.Timeout>();
+  const runtimeStatusCache = new Map<string, string>();
+  const forward = (event: unknown, ctx: ExtensionContext) => {
+    const sessionId = daemonSessionId(ctx);
+    if (activeSessionIds.has(sessionId)) {
+      void postTuiEvent(sessionId, enrichTuiEventForDaemon(event, ctx));
+      void postRuntimeStatusIfChanged(pi, ctx, sessionId, runtimeStatusCache);
+    }
+  };
+  const resetLocalState = (ctx: ExtensionContext) => {
+    const sessionId = daemonSessionId(ctx);
+    runtimeStatusCache.delete(sessionId);
+    deactivateLocalSession(ctx, sessionId, activeSessionIds, pollTimers);
+  };
+  const cleanup = async (ctx: ExtensionContext) => {
+    const sessionId = daemonSessionId(ctx);
+    resetLocalState(ctx);
+    await unregisterTuiSession(sessionId).catch(() => undefined);
+  };
+
+  registerEventForwarders(pi, forward, cleanup, resetLocalState);
+
+  pi.registerCommand("remote-control", {
+    description: "Toggle Pi remote control for this TUI session",
+    handler: async (_args, ctx) => {
+      try {
+        await ensureDaemonStarted(pi);
+      } catch (error) {
+        ctx.ui.notify(`${error instanceof Error ? error.message : String(error)}; see /tmp/pi-remote-control.log`, "error");
+        return;
+      }
+      const sessionId = daemonSessionId(ctx);
+      if (activeSessionIds.has(sessionId)) {
+        try {
+          await unregisterTuiSession(sessionId);
+        } catch (error) {
+          ctx.ui.notify(`Remote control disable failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+          return;
+        }
+        runtimeStatusCache.delete(sessionId);
+        deactivateLocalSession(ctx, sessionId, activeSessionIds, pollTimers);
+        ctx.ui.notify("Remote control disabled for this session", "info");
+        return;
+      }
+
+      let response: Response;
+      try {
+        response = await fetch(`${await daemonBaseUrl()}/v1/tui/sessions`, {
+          method: "POST",
+          headers: await tuiHeaders(),
+          body: JSON.stringify(toRegistration(pi, ctx)),
+        });
+      } catch (error) {
+        ctx.ui.notify(`Remote control enable failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+        return;
+      }
+      if (!response.ok) {
+        ctx.ui.notify(`Remote control enable failed: HTTP ${response.status}`, "error");
+        return;
+      }
+      runtimeStatusCache.set(sessionId, comparableRuntimeStatus(collectRuntimeStatus(pi, ctx)));
+      activateLocalSession(pi, ctx, sessionId, activeSessionIds, pollTimers, runtimeStatusCache);
+      ctx.ui.notify("Remote control enabled for this session", "info");
+    },
+  });
+
+  pi.registerCommand("remote-control-pair", {
+    description: "Display a QR pairing link for Pi Remote Control",
+    handler: async (_args, ctx) => {
+      try {
+        await ensureDaemonStarted(pi);
+      } catch (error) {
+        ctx.ui.notify(`${error instanceof Error ? error.message : String(error)}; see /tmp/pi-remote-control.log`, "error");
+        return;
+      }
+      const cli = cliCommand();
+      const result = await pi.exec(cli.command, [...cli.args, "pair"]);
+      const stdout = result.stdout.trim();
+      const stderr = result.stderr.trim();
+      const output = stdout || stderr || `pi-remote-control pair exited ${result.code}`;
+      ctx.ui.notify(output, result.code === 0 ? "info" : "error");
+    },
+  });
+}
+
+function registerEventForwarders(
+  pi: ExtensionAPI,
+  forward: (event: unknown, ctx: ExtensionContext) => void,
+  cleanup: (ctx: ExtensionContext) => void | Promise<void>,
+  resetLocalState: (ctx: ExtensionContext) => void,
+): void {
+  pi.on("session_start", (_event, ctx) => resetLocalState(ctx));
+  pi.on("session_shutdown", (_event, ctx) => cleanup(ctx));
+  pi.on("turn_start", forward);
+  pi.on("turn_end", forward);
+  pi.on("message_start", forward);
+  pi.on("message_update", forward);
+  pi.on("message_end", forward);
+  pi.on("tool_execution_start", forward);
+  pi.on("tool_execution_update", forward);
+  pi.on("tool_execution_end", forward);
+  pi.on("agent_start", forward);
+  pi.on("agent_end", forward);
+}
+
+export function enrichTuiEventForDaemon(event: unknown, ctx: Pick<ExtensionContext, "sessionManager">): unknown {
+  const record = asRecord(event);
+  if (record.type !== "message_start" && record.type !== "message_update" && record.type !== "message_end") return event;
+  const message = asRecord(record.message);
+  const entry = [...ctx.sessionManager.getEntries()].reverse().find((candidate) => {
+    const candidateRecord = asRecord(candidate);
+    return candidateRecord.type === "message" && messagesMatch(candidateRecord.message, message);
+  });
+  const entryRecord = asRecord(entry);
+  const id = readString(entryRecord.id);
+  if (!id) return event;
+  return {
+    ...record,
+    id,
+    timestamp: readString(entryRecord.timestamp) ?? record.timestamp,
+    message: { ...message, id },
+  };
+}
+
+function messagesMatch(left: unknown, right: unknown): boolean {
+  const leftRecord = asRecord(left);
+  const rightRecord = asRecord(right);
+  if (leftRecord.role !== rightRecord.role) return false;
+  if (leftRecord.timestamp !== undefined && rightRecord.timestamp !== undefined) return leftRecord.timestamp === rightRecord.timestamp;
+  return JSON.stringify(leftRecord.content) === JSON.stringify(rightRecord.content);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function setRemoteControlStatus(ctx: ExtensionContext): void {
+  ctx.ui.setStatus("remote-control", ctx.ui.theme.fg("success", "Remote Control Active"));
+}
+
+function clearRemoteControlStatus(ctx: ExtensionContext): void {
+  ctx.ui.setStatus("remote-control", undefined);
+}
+
+async function unregisterTuiSession(sessionId: string): Promise<void> {
+  await fetch(`${await daemonBaseUrl()}/v1/tui/sessions/${encodeURIComponent(sessionId)}`, {
+    method: "DELETE",
+    headers: await tuiHeaders(false),
+  });
+}
+
+function activateLocalSession(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  sessionId: string,
+  activeSessionIds: Set<string>,
+  pollTimers: Map<string, NodeJS.Timeout>,
+  runtimeStatusCache: Map<string, string>,
+): void {
+  activeSessionIds.add(sessionId);
+  setRemoteControlStatus(ctx);
+  if (pollTimers.has(sessionId)) return;
+  const timer = setInterval(() => void pollRemoteCommands(pi, ctx, sessionId, activeSessionIds, pollTimers, runtimeStatusCache).catch(() => undefined), 1000);
+  timer.unref?.();
+  pollTimers.set(sessionId, timer);
+}
+
+function deactivateLocalSession(
+  ctx: ExtensionContext,
+  sessionId: string,
+  activeSessionIds: Set<string>,
+  pollTimers: Map<string, NodeJS.Timeout>,
+): void {
+  activeSessionIds.delete(sessionId);
+  clearInterval(pollTimers.get(sessionId));
+  pollTimers.delete(sessionId);
+  clearRemoteControlStatus(ctx);
+}
+
+async function ensureDaemonStarted(pi: ExtensionAPI): Promise<void> {
+  const cli = cliCommand();
+  const status = await pi.exec(cli.command, [...cli.args, "status"]);
+  if (status.code === 0) return;
+
+  const shellLine = `nohup ${shellQuote(cli.command)} ${[...cli.args, "start"].map(shellQuote).join(" ")} </dev/null >/tmp/pi-remote-control.log 2>&1 &`;
+  await pi.exec("sh", ["-lc", shellLine]);
+  await waitForDaemonReady();
+}
+
+async function waitForDaemonReady(attempts = Number.parseInt(process.env.PI_REMOTE_CONTROL_READY_ATTEMPTS ?? "100", 10), delayMs = 100): Promise<void> {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      const response = await fetch(`${await daemonBaseUrl()}/v1/health`);
+      if (response.ok) return;
+    } catch {
+      // The daemon may not have bound its HTTP port yet.
+    }
+    await delay(delayMs);
+  }
+  throw new Error("pi-remote-control did not become ready");
+}
+
+async function delay(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function toRegistration(pi: unknown, ctx: ExtensionCommandContext): unknown {
+  const cwd = ctx.cwd;
+  const piSessionId = ctx.sessionManager.getSessionId();
+  const sessionFile = ctx.sessionManager.getSessionFile() ?? "";
+  return {
+    id: daemonSessionId(ctx),
+    piSessionId,
+    project: { id: projectIdForPath(cwd), name: basename(cwd), path: cwd },
+    sessionFile,
+    name: ctx.sessionManager.getSessionName(),
+    pid: process.pid,
+    messageCount: ctx.sessionManager.getEntries().length,
+    entries: ctx.sessionManager.getEntries(),
+    isStreaming: !ctx.isIdle(),
+    runtimeStatus: collectRuntimeStatus(pi, ctx),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function daemonSessionId(ctx: Pick<ExtensionContext, "sessionManager">): string {
+  return `sess_${ctx.sessionManager.getSessionId()}`;
+}
+
+async function pollRemoteCommands(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  sessionId: string,
+  activeSessionIds: Set<string>,
+  pollTimers: Map<string, NodeJS.Timeout>,
+  runtimeStatusCache: Map<string, string>,
+): Promise<void> {
+  const response = await fetch(`${await daemonBaseUrl()}/v1/tui/sessions/${encodeURIComponent(sessionId)}/commands`, {
+    headers: await tuiHeaders(false),
+  });
+  if (response.status === 404) {
+    await reRegisterTuiSessionAfterHeartbeatMiss(pi, ctx, sessionId, activeSessionIds, pollTimers, runtimeStatusCache);
+    return;
+  }
+  if (!response.ok) return;
+  const body = (await response.json()) as { commands?: RemoteTuiCommand[] };
+  for (const command of body.commands ?? []) handleRemoteCommand(pi, ctx, command, sessionId);
+}
+
+async function reRegisterTuiSessionAfterHeartbeatMiss(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  sessionId: string,
+  activeSessionIds: Set<string>,
+  pollTimers: Map<string, NodeJS.Timeout>,
+  runtimeStatusCache: Map<string, string>,
+): Promise<void> {
+  if (!activeSessionIds.has(sessionId)) return;
+
+  let response: Response;
+  try {
+    response = await fetch(`${await daemonBaseUrl()}/v1/tui/sessions`, {
+      method: "POST",
+      headers: await tuiHeaders(),
+      body: JSON.stringify(toRegistration(pi, ctx)),
+    });
+  } catch {
+    disconnectLocalSession(ctx, sessionId, activeSessionIds, pollTimers);
+    return;
+  }
+
+  if (response.ok) {
+    runtimeStatusCache.set(sessionId, comparableRuntimeStatus(collectRuntimeStatus(pi, ctx)));
+    return;
+  }
+  disconnectLocalSession(ctx, sessionId, activeSessionIds, pollTimers);
+}
+
+function disconnectLocalSession(
+  ctx: ExtensionContext,
+  sessionId: string,
+  activeSessionIds: Set<string>,
+  pollTimers: Map<string, NodeJS.Timeout>,
+): void {
+  if (!activeSessionIds.has(sessionId)) return;
+  deactivateLocalSession(ctx, sessionId, activeSessionIds, pollTimers);
+  ctx.ui.notify("Remote control disconnected; run /remote-control to re-enable", "warning");
+}
+
+export function handleRemoteCommand(pi: Pick<ExtensionAPI, "sendUserMessage">, ctx: Pick<ExtensionCommandContext, "abort" | "compact" | "isIdle">, command: RemoteTuiCommand, sessionId?: string): void {
+  if (command.type === "remote_prompt") {
+    pi.sendUserMessage(command.text, remotePromptDeliveryOptions(ctx, command.streamingBehavior));
+    return;
+  }
+  if (command.type === "remote_abort") ctx.abort();
+  if (command.type === "remote_compact") handleRemoteCompactCommand(ctx, command.requestId, sessionId);
+}
+
+function remotePromptDeliveryOptions(ctx: Pick<ExtensionCommandContext, "isIdle">, streamingBehavior: "steer" | "followUp" | null | undefined): { deliverAs: "steer" | "followUp" } | undefined {
+  if (streamingBehavior) return { deliverAs: streamingBehavior };
+  return ctx.isIdle() ? undefined : { deliverAs: "followUp" };
+}
+
+function handleRemoteCompactCommand(ctx: Pick<ExtensionCommandContext, "compact">, requestId: string, sessionId: string | undefined): void {
+  const postResult = (event: RemoteCompactResultEvent) => {
+    if (sessionId) void postTuiEvent(sessionId, event).catch(() => undefined);
+  };
+  try {
+    ctx.compact({
+      onComplete: (result) => postResult(toRemoteCompactSuccessEvent(requestId, result)),
+      onError: (error) => postResult(toRemoteCompactErrorEvent(requestId, error)),
+    });
+  } catch (error) {
+    postResult(toRemoteCompactErrorEvent(requestId, error));
+  }
+}
+
+function toRemoteCompactSuccessEvent(requestId: string, result: unknown): RemoteCompactResultEvent {
+  const record = asRecord(result);
+  return {
+    type: "remote_compact_result",
+    requestId,
+    ok: true,
+    summary: readString(record.summary) ?? "",
+    firstKeptEntryId: readString(record.firstKeptEntryId) ?? "",
+    tokensBefore: readNumber(record.tokensBefore) ?? 0,
+  };
+}
+
+function toRemoteCompactErrorEvent(requestId: string, error: unknown): RemoteCompactResultEvent {
+  return {
+    type: "remote_compact_result",
+    requestId,
+    ok: false,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+async function postTuiEvent(sessionId: string, event: unknown): Promise<void> {
+  await fetch(`${await daemonBaseUrl()}/v1/tui/sessions/${encodeURIComponent(sessionId)}/events`, {
+    method: "POST",
+    headers: await tuiHeaders(),
+    body: JSON.stringify(event),
+  });
+}
+
+async function postRuntimeStatusIfChanged(pi: unknown, ctx: ExtensionContext, sessionId: string, runtimeStatusCache: Map<string, string>): Promise<void> {
+  const status = collectRuntimeStatus(pi, ctx);
+  const comparable = comparableRuntimeStatus(status);
+  if (runtimeStatusCache.get(sessionId) === comparable) return;
+  runtimeStatusCache.set(sessionId, comparable);
+  await postTuiEvent(sessionId, { type: "runtime_status", status });
+}
+
+function comparableRuntimeStatus(status: ReturnType<typeof collectRuntimeStatus>): string {
+  const { updatedAt: _updatedAt, ...rest } = status;
+  return JSON.stringify(rest);
+}
+
+async function daemonBaseUrl(): Promise<string> {
+  if (process.env.PI_REMOTE_CONTROL_LOCAL_URL) return process.env.PI_REMOTE_CONTROL_LOCAL_URL;
+
+  try {
+    const config = await loadDaemonConfig(getDaemonStateDir());
+    return bindAddressToBaseUrl(config.bindAddress);
+  } catch {
+    return "http://127.0.0.1:17373";
+  }
+}
+
+function bindAddressToBaseUrl(bindAddress: string): string {
+  const index = bindAddress.lastIndexOf(":");
+  if (index === -1) return `http://127.0.0.1:17373`;
+  const port = bindAddress.slice(index + 1);
+  return `http://127.0.0.1:${port}`;
+}
+
+async function tuiHeaders(includeContentType = true): Promise<Record<string, string>> {
+  const headers: Record<string, string> = includeContentType ? { "content-type": "application/json" } : {};
+  const token = process.env.PI_REMOTE_CONTROL_DEV_TOKEN;
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+function cliCommand(): { command: string; args: string[] } {
+  const extensionDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = resolve(extensionDir, "..", "..");
+  const sourceRunner = resolve(packageRoot, "src", "cli-runner.cjs");
+  if (existsSync(sourceRunner)) return { command: process.execPath, args: [sourceRunner] };
+
+  const distCli = resolve(packageRoot, "dist", "cli.js");
+  if (existsSync(distCli)) return { command: process.execPath, args: [distCli] };
+
+  return { command: "pi-remote-control", args: [] };
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from "./auth/pairing.js";
+export * from "./auth/tokens.js";
+export * from "./config.js";
+export * from "./lock.js";
+export * from "./paths.js";
+export * from "./active-session-registry.js";
+export * from "./persistence/daemon-store.js";
+export * from "./persistence/schema.js";
+export * from "./server/http.js";
+export * from "./session-index.js";
+export * from "./session-transcript.js";
+export * from "./transcript-message.js";
+export * from "./transcript-pagination.js";
+export * from "./transcript-preview.js";
+export * from "./transcript-stream.js";
+export * from "./types.js";

package/src/lock.ts

@@ -0,0 +1,26 @@
+import { open, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+export type DaemonLock = {
+  path: string;
+  release(): Promise<void>;
+};
+
+export async function acquireDaemonLock(stateDir: string, pid = process.pid): Promise<DaemonLock | undefined> {
+  const path = join(stateDir, "daemon.lock");
+  let handle;
+  try {
+    handle = await open(path, "wx", 0o600);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") return undefined;
+    throw error;
+  }
+
+  await handle.writeFile(`${pid}\n`, "utf8");
+  await handle.close();
+
+  return {
+    path,
+    release: () => rm(path, { force: true }),
+  };
+}

package/src/pairing-link.ts

@@ -0,0 +1,15 @@
+export type PairingLinkOptions = {
+  advertisedBaseUrl?: string;
+  pairCode: string;
+  expiresAt: string;
+};
+
+export function buildPairingLink(options: PairingLinkOptions): string {
+  if (!options.advertisedBaseUrl) throw new Error("advertisedBaseUrl is required for QR pairing");
+  const params = new URLSearchParams({
+    baseUrl: options.advertisedBaseUrl,
+    code: options.pairCode,
+    expiresAt: options.expiresAt,
+  });
+  return `pi-remote://pair?${params.toString()}`;
+}

package/src/paths.ts

@@ -0,0 +1,21 @@
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { chmod, mkdir } from "node:fs/promises";
+
+export type StateDirOptions = {
+  env?: NodeJS.ProcessEnv;
+  homeDir?: string;
+};
+
+export function getDaemonStateDir(options: StateDirOptions = {}): string {
+  const env = options.env ?? process.env;
+  if (env.PI_REMOTE_CONTROL_DIR) return resolve(env.PI_REMOTE_CONTROL_DIR);
+
+  const home = options.homeDir ?? homedir();
+  return join(home, ".pi", "remote-control");
+}
+
+export async function ensureDaemonStateDir(path: string): Promise<void> {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  await chmod(path, 0o700);
+}

package/src/persistence/daemon-store.ts

@@ -0,0 +1,56 @@
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+import { createPairingCode, hashPairingCode, canClaimPairingCode } from "../auth/pairing.js";
+import { issueDeviceToken, verifyDeviceToken } from "../auth/tokens.js";
+import type { PairClaimResponse, PairCodeResponse } from "../server/http.js";
+import type { PairingCode } from "../types.js";
+import { migrateSchemaSql } from "./schema.js";
+
+export type DaemonStore = {
+  close(): void;
+  createPairingCode(now: Date, ttlMs: number): Promise<PairCodeResponse>;
+  claimPairingCode(rawCode: string, deviceName: string, now: Date): Promise<PairClaimResponse | undefined>;
+  authenticateToken(rawToken: string): Promise<boolean>;
+};
+
+export function openDaemonStore(stateDir: string): DaemonStore {
+  const database = new DatabaseSync(join(stateDir, "daemon.sqlite"));
+  for (const sql of migrateSchemaSql(0)) database.exec(sql);
+
+  return {
+    close() {
+      database.close();
+    },
+
+    async createPairingCode(now: Date, ttlMs: number): Promise<PairCodeResponse> {
+      const pair = createPairingCode(now, ttlMs);
+      database
+        .prepare("insert into pairing_codes (id, code_hash, created_at, expires_at, consumed_at) values (?, ?, ?, ?, null)")
+        .run(pair.id, pair.codeHash, pair.createdAt, pair.expiresAt);
+      return { pairCode: pair.rawCode, expiresAt: pair.expiresAt };
+    },
+
+    async claimPairingCode(rawCode: string, deviceName: string, now: Date): Promise<PairClaimResponse | undefined> {
+      const row = database
+        .prepare("select id, code_hash as codeHash, created_at as createdAt, expires_at as expiresAt, consumed_at as consumedAt from pairing_codes where code_hash = ? order by created_at desc limit 1")
+        .get(hashPairingCode(rawCode)) as PairingCode | undefined;
+      if (!row || !canClaimPairingCode(row, rawCode, now)) return undefined;
+
+      const token = issueDeviceToken();
+      const deviceId = `dev_${Date.now().toString(36)}`;
+      database.prepare("update pairing_codes set consumed_at = ? where id = ?").run(now.toISOString(), row.id);
+      database
+        .prepare("insert into devices (id, name, token_hash, created_at, last_seen_at, revoked_at) values (?, ?, ?, ?, null, null)")
+        .run(deviceId, deviceName, token.tokenHash, now.toISOString());
+      return { deviceId, token: token.rawToken, daemonName: "pi-remote-control" };
+    },
+
+    async authenticateToken(rawToken: string): Promise<boolean> {
+      const rows = database.prepare("select token_hash as tokenHash from devices where revoked_at is null").all() as Array<{ tokenHash: string }>;
+      for (const row of rows) {
+        if (await verifyDeviceToken(rawToken, row.tokenHash)) return true;
+      }
+      return false;
+    },
+  };
+}

package/src/persistence/schema.ts

@@ -0,0 +1,21 @@
+export const SCHEMA_VERSION = 1;
+
+export function createSchemaSql(): string[] {
+  return [
+    "create table if not exists meta (key text primary key, value text not null)",
+    "create table if not exists devices (id text primary key, name text not null, token_hash text not null unique, created_at text not null, last_seen_at text, revoked_at text)",
+    "create table if not exists pairing_codes (id text primary key, code_hash text not null unique, created_at text not null, expires_at text not null, consumed_at text)",
+  ];
+}
+
+export function migrateSchemaSql(fromVersion: number, toVersion = SCHEMA_VERSION): string[] {
+  if (fromVersion === toVersion) return [];
+  if (fromVersion !== 0 || toVersion !== SCHEMA_VERSION) {
+    throw new Error(`Unsupported schema migration: ${fromVersion} -> ${toVersion}`);
+  }
+
+  return [
+    ...createSchemaSql(),
+    `insert or replace into meta (key, value) values ('schema_version', '${SCHEMA_VERSION}')`,
+  ];
+}

package/src/qr.ts

@@ -0,0 +1,23 @@
+import qrcode from "qrcode-terminal";
+
+export type PairingDisplay = {
+  expiresAt: string;
+  pairingLink: string;
+  qrCode?: string;
+};
+
+export function renderPairingQr(pairingLink: string): string {
+  let rendered = "";
+  qrcode.generate(pairingLink, { small: true }, (qr) => {
+    rendered = qr.trimEnd();
+  });
+  return rendered;
+}
+
+export function formatPairingDisplay(display: PairingDisplay): string[] {
+  return [
+    "Scan with Pi iOS app:",
+    display.qrCode ?? renderPairingQr(display.pairingLink),
+    `Expires at: ${display.expiresAt}`,
+  ];
+}