uxnan-bridge 0.0.1-alpha.20260621

package/dist/src/projects/project-registry.d.ts

@@ -0,0 +1,14 @@
+import { type AgentConfig, type Project } from '@uxnan/shared';
+/** Stable id derived from the absolute path, so it survives restarts. */
+export declare function projectIdFor(cwd: string): string;
+export declare class ProjectRegistry {
+    #private;
+    constructor(roots: string[], fallbackCwd?: string, projectAgents?: AgentConfig[]);
+    list(): Project[];
+    /** Find a project by id or by its absolute cwd. Throws if unknown. */
+    byId(projectId: string): Project;
+    /** Resolve the project that owns `cwd` (exact root match), else synthesize one. */
+    resolve(cwd: string): Project;
+    /** The pinned agent/model config for the project at `cwd`, if any. */
+    agentConfigFor(cwd: string): AgentConfig | undefined;
+}

package/dist/src/projects/project-registry.js

@@ -0,0 +1,60 @@
+/**
+ * Resolves the project directories the phone may open. For the MVP the bridge
+ * exposes its configured `workspaceRoots` (or its own cwd when none are set) as
+ * the list of projects; each project carries the absolute `cwd` that git and
+ * agent turns run in.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.5 (project resolution).
+ */
+import { createHash } from 'node:crypto';
+import { basename, resolve } from 'node:path';
+import { JsonRpcErrorCode, RpcError } from '@uxnan/shared';
+/** Stable id derived from the absolute path, so it survives restarts. */
+export function projectIdFor(cwd) {
+    return `proj_${createHash('sha1').update(resolve(cwd)).digest('hex').slice(0, 12)}`;
+}
+export class ProjectRegistry {
+    #roots;
+    /** Per-project agent/model pins, keyed by the resolved project `cwd`. */
+    #agentByCwd;
+    constructor(roots, fallbackCwd = process.cwd(), projectAgents = []) {
+        const resolved = roots.map((r) => resolve(r)).filter((r) => r.length > 0);
+        this.#roots = resolved.length > 0 ? resolved : [resolve(fallbackCwd)];
+        this.#agentByCwd = new Map(projectAgents
+            .filter((config) => typeof config.cwd === 'string' && config.cwd.length > 0)
+            .map((config) => [resolve(config.cwd), config]));
+    }
+    list() {
+        return this.#roots.map((cwd) => this.#toProject(cwd));
+    }
+    /** Find a project by id or by its absolute cwd. Throws if unknown. */
+    byId(projectId) {
+        const match = this.#roots.find((cwd) => projectIdFor(cwd) === projectId);
+        if (!match) {
+            throw new RpcError(JsonRpcErrorCode.ResourceNotFound, `unknown project: ${projectId}`);
+        }
+        return this.#toProject(match);
+    }
+    /** Resolve the project that owns `cwd` (exact root match), else synthesize one. */
+    resolve(cwd) {
+        const target = resolve(cwd);
+        const match = this.#roots.find((root) => root === target);
+        return this.#toProject(match ?? target);
+    }
+    /** The pinned agent/model config for the project at `cwd`, if any. */
+    agentConfigFor(cwd) {
+        return this.#agentByCwd.get(resolve(cwd));
+    }
+    #toProject(cwd) {
+        const resolved = resolve(cwd);
+        const pin = this.#agentByCwd.get(resolved);
+        return {
+            id: projectIdFor(resolved),
+            name: basename(resolved) || resolved,
+            cwd: resolved,
+            ...(pin?.agentId !== undefined ? { agentId: pin.agentId } : {}),
+            ...(pin?.model !== undefined ? { model: pin.model } : {}),
+        };
+    }
+}
+//# sourceMappingURL=project-registry.js.map

package/dist/src/projects/project-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-registry.js","sourceRoot":"","sources":["../../../src/projects/project-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/push/push-sender.d.ts

@@ -0,0 +1,21 @@
+import type { PushPlatform } from '@uxnan/shared';
+import type { Logger } from '../logger.js';
+export interface PushPayload {
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+}
+/** Delivers a single notification to one device token. */
+export interface PushSender {
+    send(token: string, platform: PushPlatform, payload: PushPayload): Promise<void>;
+}
+/** Documented default location for the Firebase service account (bridge/FOR-HUMAN.md). */
+export declare function defaultServiceAccountPath(): string;
+/**
+ * Build the bridge's direct FCM sender. Returns a {@link PushSender} when a
+ * Firebase service account is present and `firebase-admin` loads; returns `null`
+ * (no direct path) when the credential is missing or init fails — the caller then
+ * falls back to the relay. Kept async + dynamic so the bridge never hard-depends
+ * on `firebase-admin`.
+ */
+export declare function createBridgePushSender(logger: Logger): Promise<PushSender | null>;

package/dist/src/push/push-sender.js

@@ -0,0 +1,96 @@
+/**
+ * Bridge-side direct push delivery (FOR-DEV → *Direct FCM from the bridge*).
+ *
+ * Background push is sent **by the bridge itself** so it works on ANY transport —
+ * direct LAN, Tailscale, or relay — not only when a hosted relay is in the loop.
+ * Delivery goes through a {@link PushSender} seam so {@link PushService} can be
+ * unit-tested with a fake sender (no Firebase credentials required).
+ *
+ * The real FCM sender is loaded lazily and only when a Firebase service account is
+ * available (`UXNAN_FCM_SERVICE_ACCOUNT`, falling back to the documented
+ * `~/.uxnan/firebase-service-account.json`); without it the factory returns
+ * `null` and the bridge degrades to the relay fallback — or, with neither, a
+ * silent no-op (foreground local notifications still work, relay-free).
+ *
+ * Same trust model as the relay owning the credential today: a local, gitignored
+ * JSON the user provides (see bridge/FOR-HUMAN.md). Push payloads stay minimal —
+ * title + short body + thread/turn ids — no conversation plaintext beyond the
+ * already-truncated turn summary the relay path also carries.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+/** Documented default location for the Firebase service account (bridge/FOR-HUMAN.md). */
+export function defaultServiceAccountPath() {
+    return join(homedir(), '.uxnan', 'firebase-service-account.json');
+}
+/**
+ * Resolve the Firebase service-account path: the explicit `UXNAN_FCM_SERVICE_ACCOUNT`
+ * env var first, then the documented `~/.uxnan/firebase-service-account.json`. The
+ * default keeps the bridge plug-and-play — drop the JSON in place and push works
+ * without setting an env var.
+ */
+function resolveServiceAccountPath() {
+    const fromEnv = process.env['UXNAN_FCM_SERVICE_ACCOUNT'];
+    return fromEnv && fromEnv.trim() ? fromEnv.trim() : defaultServiceAccountPath();
+}
+/**
+ * Build the bridge's direct FCM sender. Returns a {@link PushSender} when a
+ * Firebase service account is present and `firebase-admin` loads; returns `null`
+ * (no direct path) when the credential is missing or init fails — the caller then
+ * falls back to the relay. Kept async + dynamic so the bridge never hard-depends
+ * on `firebase-admin`.
+ */
+export async function createBridgePushSender(logger) {
+    const serviceAccountPath = resolveServiceAccountPath();
+    let credentialRaw;
+    try {
+        credentialRaw = await readFile(serviceAccountPath, 'utf-8');
+    }
+    catch {
+        logger.info(`push: no Firebase service account at ${serviceAccountPath} — direct FCM disabled (relay fallback only)`);
+        return null;
+    }
+    try {
+        const sender = await loadFcmSender(credentialRaw, logger);
+        logger.info('push: direct FCM sender ready');
+        return sender;
+    }
+    catch (err) {
+        logger.warn(`push: failed to init direct FCM (${errorMessage(err)}) — falling back to relay/noop`);
+        return null;
+    }
+}
+async function loadFcmSender(credentialRaw, logger) {
+    // Dynamic import via a non-literal specifier so the optional `firebase-admin`
+    // dependency is not statically resolved at build time (it may not be installed).
+    // FOR-HUMAN: install `firebase-admin` + provide the service account.
+    const moduleName = 'firebase-admin';
+    // firebase-admin is CommonJS: under ESM dynamic import its API lands on the
+    // `.default` interop key, so reach through it (falling back to the namespace
+    // should a bundler ever hoist the named exports). Without this the admin object
+    // is undefined and FCM init silently degrades.
+    const imported = (await import(moduleName));
+    const admin = imported.default ?? imported;
+    const credential = JSON.parse(credentialRaw);
+    // Named app so this never collides with any other firebase-admin init in-process.
+    const app = admin.initializeApp({ credential: admin.credential.cert(credential) }, 'uxnan-bridge');
+    const messaging = admin.messaging(app);
+    return {
+        async send(token, platform, payload) {
+            await messaging.send({
+                token,
+                notification: { title: payload.title, body: payload.body },
+                ...(payload.data ? { data: payload.data } : {}),
+                // High priority so the phone wakes promptly while backgrounded.
+                android: { priority: 'high' },
+                apns: { headers: { 'apns-priority': '10' } },
+            });
+            logger.info(`push: delivered "${payload.title}" via direct FCM (${platform})`);
+        },
+    };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=push-sender.js.map

package/dist/src/push/push-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-sender.js","sourceRoot":"","sources":["../../../src/push/push-sender.ts"],"names":[],"mappings":"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"}

package/dist/src/push/push-service.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Bridge-side push coordination (architecture/02a §5.10.2; FOR-DEV → *Direct FCM
+ * from the bridge*).
+ *
+ * The phone registers its FCM/APNs token over the live session
+ * (`notifications/register`). The bridge keeps the real token and, when a turn
+ * ends with push enabled, delivers a background notification via two paths, in
+ * priority order:
+ *
+ *   1. **Direct FCM (PRIMARY)** — when a Firebase service account is present the
+ *      bridge sends straight to FCM via {@link PushSender}. Works on ANY transport
+ *      (direct LAN, Tailscale, or relay) — no hosted relay required.
+ *   2. **Relay fallback** — with no local credential (or the relay explicitly
+ *      enabled), the bridge forwards the token to the relay (`POST /push/register`),
+ *      keeps the returned `notificationSecret`, and asks the relay to deliver
+ *      (`POST /push/notify`). For setups that keep the credential on a hosted relay.
+ *
+ * Everything here is GATED: with neither a direct FCM sender nor a reachable relay,
+ * background push is a silent no-op (foreground local notifications still work).
+ * Without a registered token the bridge simply skips pushing. Direct delivery needs
+ * the user's Firebase service account (bridge/FOR-HUMAN.md); the relay path needs it
+ * on the relay (relay/FOR-HUMAN.md) — plus a real device to validate either.
+ *
+ * Persistence: registrations are keyed by `sessionId` and persisted to
+ * `~/.uxnan/push-state.json` (atomic write), so background push survives a
+ * bridge restart WITHOUT waiting for the phone to reconnect and re-register. The
+ * persisted entry carries the device token + platform (for the direct path) and,
+ * when used, the relay `notificationSecret` (for the fallback). Multiple
+ * registrations are kept, so several paired phones each receive background push;
+ * a turn-end pushes to all of them.
+ *
+ * Note: `register`/`updatePreferences`/`unregister` act on the *active* session
+ * (the one whose request is being served). With the MVP default
+ * `maxConcurrentSessions: 1` this is exact; with several concurrent sessions the
+ * "active" one is the most recently established — per-request session identity
+ * would be needed to disambiguate (FOR-DEV).
+ */
+import type { NotificationPreferences, PushPlatform, RegisterNotificationsResult } from '@uxnan/shared';
+import type { DaemonConfig } from '../daemon-config.js';
+import { type DaemonState } from '../daemon-state.js';
+import type { Logger } from '../logger.js';
+import type { PushSender } from './push-sender.js';
+export interface TurnEndInfo {
+    threadId: string;
+    turnId: string;
+    status: 'completed' | 'error';
+    /** Assistant text (completed) or error message, used to build the body. */
+    text?: string;
+}
+type FetchFn = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** Parameters for {@link PushService.register} — identifies the requesting phone. */
+export interface RegisterPushParams {
+    /** Relay session id of the phone making the request (its registration key). */
+    sessionId: string;
+    /** Trusted-device id of that phone, when known (enables prune-on-untrust). */
+    deviceId?: string;
+    pushToken: string;
+    platform: PushPlatform;
+    preferences?: NotificationPreferences;
+}
+export interface PushServiceOptions {
+    relayUrl: string;
+    config: DaemonConfig;
+    logger: Logger;
+    fetchFn?: FetchFn;
+    /** Daemon state for persisting registrations; omitted in unit tests (no-op). */
+    state?: DaemonState;
+    /**
+     * Direct FCM sender (PRIMARY push path). Present when a Firebase service account
+     * is configured (see {@link createBridgePushSender}); `undefined` → the bridge
+     * uses the relay fallback only. Injected by tests with a fake sender.
+     */
+    pushSender?: PushSender;
+}
+export declare class PushService {
+    #private;
+    constructor(options: PushServiceOptions);
+    /** True when the bridge can deliver push directly via FCM (credential present). */
+    get directPushAvailable(): boolean;
+    /**
+     * Load persisted registrations from `push-state.json`. Call once at startup so
+     * background push keeps working across a bridge restart. Best-effort: a missing
+     * or malformed file leaves the service empty.
+     */
+    load(): Promise<void>;
+    /** Called when a phone session is established. */
+    setActiveSession(sessionId: string): void;
+    /** Called when a session closes; the registration persists for background push. */
+    clearActiveSession(sessionId: string): void;
+    get activeSessionId(): string | undefined;
+    /**
+     * Handle `notifications/register` for a SPECIFIC phone session. Always stores the
+     * real device token locally (the direct FCM path needs it); additionally registers
+     * with the relay when the relay is enabled OR there is no direct sender, keeping
+     * the returned secret for the fallback path. Keyed by `sessionId`, so several
+     * concurrent phones each get their own registration. `registered` is true when at
+     * least one delivery path exists.
+     */
+    register(params: RegisterPushParams): Promise<RegisterNotificationsResult>;
+    /** Update a specific session's notification preferences. */
+    updatePreferences(sessionId: string, preferences: NotificationPreferences): void;
+    /** Drop a specific session's registration (its phone asked to stop pushes). */
+    unregister(sessionId: string): void;
+    /**
+     * Drop every registration owned by a trusted device — called when the device is
+     * removed via `bridge/removeTrustedDevice`, so a revoked phone stops receiving
+     * background push instead of lingering until it re-registers or is overwritten.
+     * Returns the number of registrations removed.
+     */
+    unregisterDevice(deviceId: string): number;
+    /** Fire-and-forget: push a turn-ended notification if enabled and registered. */
+    onTurnEnd(info: TurnEndInfo): void;
+}
+export {};

package/dist/src/push/push-service.js

@@ -0,0 +1,260 @@
+import { DAEMON_FILES } from '../daemon-state.js';
+const DEFAULT_PREFERENCES = { turnCompleted: true, turnError: true };
+export class PushService {
+    #httpBase;
+    #config;
+    #logger;
+    #fetch;
+    #state;
+    #pushSender;
+    #activeSessionId;
+    /** Registrations keyed by relay `sessionId` (one per paired phone). */
+    #registrations = new Map();
+    constructor(options) {
+        this.#httpBase = toHttpBase(options.relayUrl);
+        this.#config = options.config;
+        this.#logger = options.logger;
+        this.#fetch = options.fetchFn ?? globalThis.fetch;
+        this.#state = options.state;
+        this.#pushSender = options.pushSender;
+    }
+    /** True when the bridge can deliver push directly via FCM (credential present). */
+    get directPushAvailable() {
+        return this.#pushSender !== undefined;
+    }
+    /**
+     * Load persisted registrations from `push-state.json`. Call once at startup so
+     * background push keeps working across a bridge restart. Best-effort: a missing
+     * or malformed file leaves the service empty.
+     */
+    async load() {
+        if (!this.#state)
+            return;
+        try {
+            const persisted = await this.#state.readJson(DAEMON_FILES.pushState);
+            const registrations = persisted?.registrations;
+            if (!Array.isArray(registrations))
+                return;
+            for (const reg of registrations) {
+                if (isRegistration(reg))
+                    this.#registrations.set(reg.sessionId, reg);
+            }
+            if (this.#registrations.size > 0) {
+                this.#logger.info(`loaded ${this.#registrations.size} push registration(s)`);
+            }
+        }
+        catch (err) {
+            this.#logger.warn(`push-state load failed: ${errorMessage(err)}`);
+        }
+    }
+    /** Called when a phone session is established. */
+    setActiveSession(sessionId) {
+        this.#activeSessionId = sessionId;
+    }
+    /** Called when a session closes; the registration persists for background push. */
+    clearActiveSession(sessionId) {
+        if (this.#activeSessionId === sessionId)
+            this.#activeSessionId = undefined;
+    }
+    get activeSessionId() {
+        return this.#activeSessionId;
+    }
+    /**
+     * Handle `notifications/register` for a SPECIFIC phone session. Always stores the
+     * real device token locally (the direct FCM path needs it); additionally registers
+     * with the relay when the relay is enabled OR there is no direct sender, keeping
+     * the returned secret for the fallback path. Keyed by `sessionId`, so several
+     * concurrent phones each get their own registration. `registered` is true when at
+     * least one delivery path exists.
+     */
+    async register(params) {
+        const { sessionId, deviceId, pushToken, platform, preferences } = params;
+        const reg = {
+            sessionId,
+            ...(deviceId !== undefined ? { deviceId } : {}),
+            pushToken,
+            platform,
+            preferences: preferences ?? DEFAULT_PREFERENCES,
+        };
+        // Register with the relay only when it's the wanted/only path: the user enabled
+        // it, or there is no direct FCM sender to deliver. Best-effort — a relay that is
+        // down does not fail registration when direct FCM can still deliver.
+        if (this.#config.relayEnabled || !this.#pushSender) {
+            const secret = await this.#registerWithRelay(sessionId, pushToken, platform);
+            if (secret)
+                reg.notificationSecret = secret;
+        }
+        this.#registrations.set(sessionId, reg);
+        await this.#persist();
+        const direct = this.#pushSender !== undefined;
+        const viaRelay = reg.notificationSecret !== undefined;
+        if (direct || viaRelay) {
+            this.#logger.info(`push token registered (${direct ? 'direct FCM' : 'relay'})`);
+            return { registered: true };
+        }
+        this.#logger.warn('push token stored but no delivery path (no FCM creds, relay unavailable)');
+        return { registered: false };
+    }
+    /** Forward a token to the relay; returns the notify secret, or undefined on failure. */
+    async #registerWithRelay(sessionId, pushToken, platform) {
+        try {
+            const res = await this.#fetch(`${this.#httpBase}/push/register`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ sessionId, pushToken, platform }),
+            });
+            if (!res.ok) {
+                this.#logger.warn(`push register rejected by relay (${res.status})`);
+                return undefined;
+            }
+            const data = (await res.json());
+            return data.notificationSecret ?? undefined;
+        }
+        catch (err) {
+            this.#logger.warn(`push relay register failed: ${errorMessage(err)}`);
+            return undefined;
+        }
+    }
+    /** Update a specific session's notification preferences. */
+    updatePreferences(sessionId, preferences) {
+        const reg = this.#registrations.get(sessionId);
+        if (!reg)
+            return;
+        reg.preferences = preferences;
+        void this.#persist();
+    }
+    /** Drop a specific session's registration (its phone asked to stop pushes). */
+    unregister(sessionId) {
+        if (this.#registrations.delete(sessionId))
+            void this.#persist();
+    }
+    /**
+     * Drop every registration owned by a trusted device — called when the device is
+     * removed via `bridge/removeTrustedDevice`, so a revoked phone stops receiving
+     * background push instead of lingering until it re-registers or is overwritten.
+     * Returns the number of registrations removed.
+     */
+    unregisterDevice(deviceId) {
+        let removed = 0;
+        for (const [sessionId, reg] of this.#registrations) {
+            if (reg.deviceId === deviceId) {
+                this.#registrations.delete(sessionId);
+                removed += 1;
+            }
+        }
+        if (removed > 0) {
+            void this.#persist();
+            this.#logger.info(`pruned ${removed} push registration(s) for removed device`);
+        }
+        return removed;
+    }
+    /** Fire-and-forget: push a turn-ended notification if enabled and registered. */
+    onTurnEnd(info) {
+        void this.#maybePush(info).catch((err) => this.#logger.warn(`push notify failed: ${errorMessage(err)}`));
+    }
+    async #maybePush(info) {
+        if (!this.#config.pushEnabled)
+            return;
+        if (this.#registrations.size === 0)
+            return;
+        const { title, body } = buildNotification(info);
+        // Notify every registered phone whose preferences opt into this event.
+        await Promise.all([...this.#registrations.values()]
+            .filter((reg) => this.#wantsPush(info.status, reg.preferences))
+            .map((reg) => this.#notifyOne(reg, info, title, body)));
+    }
+    #wantsPush(status, prefs) {
+        if (status === 'completed')
+            return this.#config.pushOnAgentDone && prefs.turnCompleted;
+        return this.#config.pushOnAgentError && prefs.turnError;
+    }
+    async #notifyOne(reg, info, title, body) {
+        const data = { threadId: info.threadId, turnId: info.turnId };
+        // PRIMARY: deliver straight to FCM when a sender + token are available. Works
+        // on any transport; on failure we log rather than retry via the relay (the
+        // direct path has no dedupe, so a fallback could double-deliver).
+        if (this.#pushSender && reg.pushToken && reg.platform) {
+            try {
+                await this.#pushSender.send(reg.pushToken, reg.platform, { title, body, data });
+            }
+            catch (err) {
+                this.#logger.warn(`direct push delivery failed: ${errorMessage(err)}`);
+            }
+            return;
+        }
+        // FALLBACK: ask the relay to deliver (it holds the token + dedupes by turn).
+        if (reg.notificationSecret) {
+            const res = await this.#fetch(`${this.#httpBase}/push/notify`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    sessionId: reg.sessionId,
+                    notificationSecret: reg.notificationSecret,
+                    ...data,
+                    title,
+                    body,
+                }),
+            });
+            if (!res.ok)
+                this.#logger.warn(`push notify rejected by relay (${res.status})`);
+            return;
+        }
+        this.#logger.warn(`push skipped for ${reg.sessionId}: no delivery path`);
+    }
+    /** Atomically persist the current registrations (best-effort). */
+    async #persist() {
+        if (!this.#state)
+            return;
+        try {
+            const state = {
+                version: 1,
+                registrations: [...this.#registrations.values()],
+            };
+            await this.#state.writeJson(DAEMON_FILES.pushState, state);
+        }
+        catch (err) {
+            this.#logger.warn(`push-state persist failed: ${errorMessage(err)}`);
+        }
+    }
+}
+function isRegistration(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const reg = value;
+    // A usable registration needs at least one delivery path: a device token (direct
+    // FCM) or a relay secret (fallback). Older persisted entries had only the secret.
+    const hasPath = typeof reg['pushToken'] === 'string' || typeof reg['notificationSecret'] === 'string';
+    return (typeof reg['sessionId'] === 'string' &&
+        hasPath &&
+        typeof reg['preferences'] === 'object' &&
+        reg['preferences'] !== null);
+}
+function buildNotification(info) {
+    if (info.status === 'error') {
+        return { title: 'Turn failed', body: truncate(info.text) ?? 'The agent reported an error.' };
+    }
+    return { title: 'Turn completed', body: truncate(info.text) ?? 'Your agent finished a turn.' };
+}
+function truncate(text, max = 120) {
+    if (!text)
+        return undefined;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+/** Convert a relay ws(s):// URL into its http(s):// origin for the REST endpoints. */
+function toHttpBase(relayUrl) {
+    try {
+        const url = new URL(relayUrl);
+        const protocol = url.protocol === 'wss:' ? 'https:' : url.protocol === 'ws:' ? 'http:' : url.protocol;
+        return `${protocol}//${url.host}`;
+    }
+    catch {
+        return relayUrl.replace(/^ws/, 'http').replace(/\/$/, '');
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=push-service.js.map

package/dist/src/push/push-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-service.js","sourceRoot":"","sources":["../../../src/push/push-service.ts"],"names":[],"mappings":"AA2CA,OAAO,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AA+CpE,MAAM,mBAAmB,GAA4B,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAiB9F,MAAM,OAAO,WAAW;IACb,SAAS,CAAS;IAClB,OAAO,CAAe;IACtB,OAAO,CAAS;IAChB,MAAM,CAAU;IAChB,MAAM,CAA0B;IAChC,WAAW,CAAyB;IAC7C,gBAAgB,CAAqB;IACrC,uEAAuE;IAC9D,cAAc,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE1D,YAAY,OAA2B;QACrC,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,IAAK,UAAU,CAAC,KAA4B,CAAC;QAC1E,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IACxC,CAAC;IAED,mFAAmF;IACnF,IAAI,mBAAmB;QACrB,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAqB,YAAY,CAAC,SAAS,CAAC,CAAC;YACzF,MAAM,aAAa,GAAG,SAAS,EAAE,aAAa,CAAC;YAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;gBAAE,OAAO;YAC1C,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;gBAChC,IAAI,cAAc,CAAC,GAAG,CAAC;oBAAE,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACvE,CAAC;YACD,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,cAAc,CAAC,IAAI,uBAAuB,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,gBAAgB,CAAC,SAAiB;QAChC,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACpC,CAAC;IAED,mFAAmF;IACnF,kBAAkB,CAAC,SAAiB;QAClC,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;YAAE,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAC7E,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,MAA0B;QACvC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;QACzE,MAAM,GAAG,GAAiB;YACxB,SAAS;YACT,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,SAAS;YACT,QAAQ;YACR,WAAW,EAAE,WAAW,IAAI,mBAAmB;SAChD,CAAC;QACF,gFAAgF;QAChF,iFAAiF;QACjF,qEAAqE;QACrE,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7E,IAAI,MAAM;gBAAE,GAAG,CAAC,kBAAkB,GAAG,MAAM,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC;QAC9C,MAAM,QAAQ,GAAG,GAAG,CAAC,kBAAkB,KAAK,SAAS,CAAC;QACtD,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;YACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,0BAA0B,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;YAChF,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;QAC9F,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,kBAAkB,CACtB,SAAiB,EACjB,SAAiB,EACjB,QAAsB;QAEtB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,gBAAgB,EAAE;gBAC/D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;aACzD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oCAAoC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;gBACrE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAoC,CAAC;YACnE,OAAO,IAAI,CAAC,kBAAkB,IAAI,SAAS,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtE,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,iBAAiB,CAAC,SAAiB,EAAE,WAAoC;QACvE,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;QAC9B,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;IACvB,CAAC;IAED,+EAA+E;IAC/E,UAAU,CAAC,SAAiB;QAC1B,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC;YAAE,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClE,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,QAAgB;QAC/B,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACnD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC9B,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACtC,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;QACH,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,0CAA0C,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,iFAAiF;IACjF,SAAS,CAAC,IAAiB;QACzB,KAAK,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACvC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,uBAAuB,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAC9D,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,IAAiB;QAChC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW;YAAE,OAAO;QACtC,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC3C,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAChD,uEAAuE;QACvE,MAAM,OAAO,CAAC,GAAG,CACf,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;aAC9B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;aAC9D,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CACzD,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,MAA6B,EAAE,KAA8B;QACtE,IAAI,MAAM,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC,aAAa,CAAC;QACvF,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC,SAAS,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,UAAU,CACd,GAAiB,EACjB,IAAiB,EACjB,KAAa,EACb,IAAY;QAEZ,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC9D,8EAA8E;QAC9E,2EAA2E;QAC3E,kEAAkE;QAClE,IAAI,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACtD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAClF,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gCAAgC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzE,CAAC;YACD,OAAO;QACT,CAAC;QACD,6EAA6E;QAC7E,IAAI,GAAG,CAAC,kBAAkB,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,cAAc,EAAE;gBAC7D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,kBAAkB,EAAE,GAAG,CAAC,kBAAkB;oBAC1C,GAAG,IAAI;oBACP,KAAK;oBACL,IAAI;iBACL,CAAC;aACH,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kCAAkC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YAChF,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,GAAG,CAAC,SAAS,oBAAoB,CAAC,CAAC;IAC3E,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,IAAI,CAAC;YACH,MAAM,KAAK,GAAuB;gBAChC,OAAO,EAAE,CAAC;gBACV,aAAa,EAAE,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;aACjD,CAAC;YACF,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,8BAA8B,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;CACF;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,iFAAiF;IACjF,kFAAkF;IAClF,MAAM,OAAO,GACX,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,oBAAoB,CAAC,KAAK,QAAQ,CAAC;IACxF,OAAO,CACL,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ;QACpC,OAAO;QACP,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ;QACtC,GAAG,CAAC,aAAa,CAAC,KAAK,IAAI,CAC5B,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAiB;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,8BAA8B,EAAE,CAAC;IAC/F,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,6BAA6B,EAAE,CAAC;AACjG,CAAC;AAED,SAAS,QAAQ,CAAC,IAAwB,EAAE,GAAG,GAAG,GAAG;IACnD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AAC1E,CAAC;AAED,sFAAsF;AACtF,SAAS,UAAU,CAAC,QAAgB;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,QAAQ,GACZ,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvF,OAAO,GAAG,QAAQ,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/src/qr.d.ts

@@ -0,0 +1,17 @@
+import { type PairingPayload } from '@uxnan/shared';
+export interface GeneratePairingOptions {
+    /** Relay URL (remote fallback). Omit for a LAN/Tailscale-only QR. */
+    relayUrl?: string;
+    /** Direct `host:port` addresses the phone should try first (LAN/Tailscale). */
+    hosts?: string[];
+    macDeviceId: string;
+    macIdentityPublicKey: string;
+    displayName: string;
+    /** Current time in epoch ms (injected for testability). */
+    now: number;
+    /** Optional explicit session id; a random UUID is used otherwise. */
+    sessionId?: string;
+}
+export declare function generatePairingPayload(options: GeneratePairingOptions): PairingPayload;
+/** Render a pairing payload as an ASCII QR code (for terminal display). */
+export declare function renderPairingQr(payload: PairingPayload): Promise<string>;

package/dist/src/qr.js

@@ -0,0 +1,31 @@
+/**
+ * Pairing QR generation.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (qr) and §5.9.1 (Phase 1).
+ */
+import { randomUUID } from 'node:crypto';
+import qrcode from 'qrcode-terminal';
+import { PAIRING_QR_VERSION, defaultPairingExpiry, encodePairingQr, } from '@uxnan/shared';
+export function generatePairingPayload(options) {
+    const payload = {
+        v: PAIRING_QR_VERSION,
+        sessionId: options.sessionId ?? randomUUID(),
+        macDeviceId: options.macDeviceId,
+        macIdentityPublicKey: options.macIdentityPublicKey,
+        expiresAt: defaultPairingExpiry(options.now),
+        displayName: options.displayName,
+    };
+    if (options.relayUrl)
+        payload.relay = options.relayUrl;
+    if (options.hosts && options.hosts.length > 0)
+        payload.hosts = options.hosts;
+    return payload;
+}
+/** Render a pairing payload as an ASCII QR code (for terminal display). */
+export function renderPairingQr(payload) {
+    const data = encodePairingQr(payload);
+    return new Promise((resolve) => {
+        qrcode.generate(data, { small: true }, (output) => resolve(output));
+    });
+}
+//# sourceMappingURL=qr.js.map