uxnan-bridge 0.0.1-alpha.20260621

package/dist/src/workspace/checkpoint-service.js

@@ -0,0 +1,219 @@
+/**
+ * Workspace checkpoints: capture / diff / apply a snapshot of the project's
+ * working tree, backed by git.
+ *
+ * A checkpoint is a full snapshot of the working tree (tracked changes AND
+ * untracked files) taken WITHOUT touching the user's index: a temporary
+ * `GIT_INDEX_FILE` is seeded from HEAD, `git add -A` stages the current tree
+ * into it, and `commit-tree` records a snapshot commit parented on HEAD. The
+ * commit is anchored under `refs/uxnan/checkpoints/<id>` so git won't GC it, and
+ * metadata is persisted in `~/.uxnan/checkpoints.json`.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.7.
+ *
+ * `applyCheckpoint` performs a TRUE worktree restore: it restores the snapshot's
+ * file contents (recreating deleted files, overwriting modified ones) AND deletes
+ * files created after the checkpoint, so the working tree matches the snapshot
+ * exactly (parity with the mobile `AiChangeSet` revert). It is worktree-only —
+ * the user's index and HEAD are untouched — and never removes gitignored files
+ * (they were excluded from the snapshot).
+ *
+ * Retention: on each `capture` the service prunes old checkpoints beyond a
+ * per-project count cap and/or a TTL, deleting both their `refs/uxnan/checkpoints/*`
+ * anchors and their `checkpoints.json` entries, so the set never grows unbounded.
+ *
+ * Limitation: checkpoint commits use a fixed internal identity (never pushed).
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { JsonRpcErrorCode, RpcError } from '@uxnan/shared';
+import { DAEMON_FILES } from '../daemon-state.js';
+import { runGit } from '../git/git-runner.js';
+const SNAPSHOT_ENV = {
+    GIT_AUTHOR_NAME: 'uxnan-bridge',
+    GIT_AUTHOR_EMAIL: 'bridge@uxnan.local',
+    GIT_COMMITTER_NAME: 'uxnan-bridge',
+    GIT_COMMITTER_EMAIL: 'bridge@uxnan.local',
+};
+const DEFAULT_RETENTION = { maxPerProject: 25, ttlDays: 0 };
+const MS_PER_DAY = 86_400_000;
+export class CheckpointService {
+    #state;
+    #retention;
+    constructor(state, retention = {}) {
+        this.#state = state;
+        this.#retention = { ...DEFAULT_RETENTION, ...retention };
+    }
+    async capture(cwd, options) {
+        const baseSha = (await runGit(cwd, ['rev-parse', 'HEAD'])).stdout.trim();
+        const id = randomUUID();
+        const indexFile = join(tmpdir(), `uxnan-ckpt-${id}.index`);
+        const env = { ...process.env, ...SNAPSHOT_ENV, GIT_INDEX_FILE: indexFile };
+        let commitSha;
+        try {
+            await runGit(cwd, ['read-tree', baseSha], { env });
+            await runGit(cwd, ['add', '-A'], { env });
+            const treeSha = (await runGit(cwd, ['write-tree'], { env })).stdout.trim();
+            const label = options.label ?? 'checkpoint';
+            commitSha = (await runGit(cwd, ['commit-tree', treeSha, '-p', baseSha, '-m', `uxnan-checkpoint ${label}`], {
+                env,
+            })).stdout.trim();
+        }
+        finally {
+            await rm(indexFile, { force: true });
+        }
+        await runGit(cwd, ['update-ref', `refs/uxnan/checkpoints/${id}`, commitSha]);
+        const record = {
+            id,
+            cwd,
+            baseSha,
+            commitSha,
+            createdAt: options.now,
+            ...(options.label !== undefined ? { label: options.label } : {}),
+            ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+        };
+        const records = await this.#list();
+        records.push(record);
+        const survivors = await this.#prune(records, options.now);
+        await this.#state.writeJson(DAEMON_FILES.checkpoints, survivors);
+        return toCheckpoint(record);
+    }
+    async diff(id) {
+        const record = await this.#require(id);
+        const range = [record.baseSha, record.commitSha];
+        const { stdout: diff } = await runGit(record.cwd, ['diff', ...range]);
+        const { stdout: nameStatus } = await runGit(record.cwd, ['diff', '--name-status', ...range]);
+        const files = nameStatus
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const parts = line.split('\t');
+            const code = parts[0] ?? '';
+            const path = parts[parts.length - 1] ?? '';
+            return { path, status: mapFileStatus(code) };
+        });
+        return { diff, files };
+    }
+    async apply(id) {
+        const record = await this.#require(id);
+        // Files that exist now but NOT in the snapshot — created after the checkpoint.
+        // Compute these BEFORE restoring (which only touches snapshot paths).
+        const extras = await this.#extrasOf(record);
+        // Restore snapshot contents: recreates deleted files, overwrites modified ones.
+        await runGit(record.cwd, ['restore', `--source=${record.commitSha}`, '--', '.']);
+        // Delete the extras so the worktree matches the snapshot exactly.
+        for (const rel of extras) {
+            await rm(join(record.cwd, rel), { force: true });
+        }
+    }
+    /**
+     * Paths present in the current worktree but absent from the checkpoint snapshot
+     * (the files to delete on restore). Snapshots the current tree into a temp index
+     * exactly like {@link capture} (HEAD + `add -A`, so .gitignore is respected and
+     * the user's real index is untouched), then diffs snapshot → now; `A` entries
+     * are the extras.
+     */
+    async #extrasOf(record) {
+        const headSha = (await runGit(record.cwd, ['rev-parse', 'HEAD'])).stdout.trim();
+        const indexFile = join(tmpdir(), `uxnan-ckpt-apply-${randomUUID()}.index`);
+        const env = { ...process.env, ...SNAPSHOT_ENV, GIT_INDEX_FILE: indexFile };
+        try {
+            await runGit(record.cwd, ['read-tree', headSha], { env });
+            await runGit(record.cwd, ['add', '-A'], { env });
+            const nowTree = (await runGit(record.cwd, ['write-tree'], { env })).stdout.trim();
+            const { stdout } = await runGit(record.cwd, [
+                'diff',
+                '--name-status',
+                '--no-renames',
+                record.commitSha,
+                nowTree,
+            ]);
+            const extras = [];
+            for (const line of stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed.length === 0)
+                    continue;
+                const parts = trimmed.split('\t');
+                if ((parts[0] ?? '')[0] !== 'A')
+                    continue;
+                const path = parts[parts.length - 1];
+                if (path)
+                    extras.push(path);
+            }
+            return extras;
+        }
+        finally {
+            await rm(indexFile, { force: true });
+        }
+    }
+    /**
+     * Drop checkpoints beyond the retention bounds: those older than the TTL, and
+     * the oldest-over-cap per project. Deletes each pruned checkpoint's git ref
+     * (best-effort — the repo/ref may be gone) and returns the survivors to persist.
+     */
+    async #prune(records, now) {
+        const { maxPerProject, ttlDays } = this.#retention;
+        const ttlCutoff = ttlDays > 0 ? now - ttlDays * MS_PER_DAY : undefined;
+        const removeIds = new Set();
+        const byCwd = new Map();
+        for (const record of records) {
+            if (ttlCutoff !== undefined && record.createdAt < ttlCutoff) {
+                removeIds.add(record.id);
+                continue;
+            }
+            const list = byCwd.get(record.cwd) ?? [];
+            list.push(record);
+            byCwd.set(record.cwd, list);
+        }
+        if (maxPerProject > 0) {
+            for (const list of byCwd.values()) {
+                list.sort((a, b) => b.createdAt - a.createdAt); // newest first
+                for (let i = maxPerProject; i < list.length; i += 1)
+                    removeIds.add(list[i].id);
+            }
+        }
+        if (removeIds.size === 0)
+            return records;
+        for (const record of records) {
+            if (!removeIds.has(record.id))
+                continue;
+            try {
+                await runGit(record.cwd, ['update-ref', '-d', `refs/uxnan/checkpoints/${record.id}`]);
+            }
+            catch {
+                // The ref or its repo is already gone — nothing to clean up.
+            }
+        }
+        return records.filter((record) => !removeIds.has(record.id));
+    }
+    async #list() {
+        return (await this.#state.readJson(DAEMON_FILES.checkpoints)) ?? [];
+    }
+    async #require(id) {
+        const record = (await this.#list()).find((r) => r.id === id);
+        if (!record) {
+            throw new RpcError(JsonRpcErrorCode.ResourceNotFound, `checkpoint not found: ${id}`);
+        }
+        return record;
+    }
+}
+function toCheckpoint(record) {
+    const checkpoint = { id: record.id, createdAt: record.createdAt };
+    if (record.label !== undefined)
+        checkpoint.label = record.label;
+    if (record.threadId !== undefined)
+        checkpoint.threadId = record.threadId;
+    return checkpoint;
+}
+function mapFileStatus(code) {
+    const c = code[0];
+    if (c === 'A')
+        return 'added';
+    if (c === 'D')
+        return 'deleted';
+    return 'modified';
+}
+//# sourceMappingURL=checkpoint-service.js.map

package/dist/src/workspace/checkpoint-service.js.map

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

package/dist/src/workspace/path-guard.d.ts

@@ -0,0 +1,7 @@
+export declare function isSensitiveName(name: string): boolean;
+/**
+ * Resolve `relPath` against `root` and ensure the result stays inside `root`.
+ * Rejects traversal (`..`), absolute escapes, the `.git` directory and sensitive
+ * file names. Returns the absolute path.
+ */
+export declare function resolveWithinRoot(root: string, relPath: string): string;

package/dist/src/workspace/path-guard.js

@@ -0,0 +1,51 @@
+/**
+ * Path-traversal protection and sensitive-file filtering for workspace access.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.9 (sanitization). The
+ * bridge never serves files outside the project root, nor secrets (.env, keys,
+ * credentials) or the .git internals.
+ */
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { JsonRpcErrorCode, RpcError } from '@uxnan/shared';
+const SENSITIVE_PATTERNS = [
+    /^\.env(\..+)?$/i,
+    /\.pem$/i,
+    /\.key$/i,
+    /\.p12$/i,
+    /\.pfx$/i,
+    /\.keystore$/i,
+    /^id_rsa/i,
+    /^id_ed25519/i,
+    /^id_ecdsa/i,
+    /^credentials\.json$/i,
+    /^\.npmrc$/i,
+];
+export function isSensitiveName(name) {
+    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(name));
+}
+function denied(message) {
+    return new RpcError(JsonRpcErrorCode.WorkspaceAccessDenied, message);
+}
+/**
+ * Resolve `relPath` against `root` and ensure the result stays inside `root`.
+ * Rejects traversal (`..`), absolute escapes, the `.git` directory and sensitive
+ * file names. Returns the absolute path.
+ */
+export function resolveWithinRoot(root, relPath) {
+    const resolvedRoot = resolve(root);
+    const target = resolve(resolvedRoot, relPath);
+    const rel = relative(resolvedRoot, target);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw denied('path escapes the project root');
+    }
+    const segments = rel.split(sep);
+    if (segments.includes('.git')) {
+        throw denied('access to the .git directory is not allowed');
+    }
+    const name = segments[segments.length - 1] ?? '';
+    if (isSensitiveName(name)) {
+        throw denied('access to a sensitive file is not allowed');
+    }
+    return target;
+}
+//# sourceMappingURL=path-guard.js.map

package/dist/src/workspace/path-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.js","sourceRoot":"","sources":["../../../src/workspace/path-guard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,kBAAkB,GAAa;IACnC,iBAAiB;IACjB,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,cAAc;IACd,UAAU;IACV,cAAc;IACd,YAAY;IACZ,sBAAsB;IACtB,YAAY;CACb,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,IAAI,QAAQ,CAAC,gBAAgB,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe;IAC7D,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAE3C,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,MAAM,CAAC,6CAA6C,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,CAAC,2CAA2C,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { ApplyResult, FileContent, ImageContent, PatchChange, WorkspaceListing } from '@uxnan/shared';
+export declare class WorkspaceService {
+    #private;
+    readFile(root: string, relPath: string): Promise<FileContent>;
+    readImage(root: string, relPath: string): Promise<ImageContent>;
+    list(root: string): Promise<WorkspaceListing>;
+    applyPatch(root: string, changes: PatchChange[]): Promise<ApplyResult>;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Workspace file operations, confined to the project root and stripped of
+ * sensitive files (see {@link resolveWithinRoot}). Paths returned to the phone
+ * are relative to the project root, never absolute.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.7 / §5.8.9.
+ */
+import { readFile, readdir, stat, mkdir, writeFile, rm } from 'node:fs/promises';
+import { dirname, extname, relative, resolve } from 'node:path';
+import { JsonRpcErrorCode, RpcError } from '@uxnan/shared';
+import { isSensitiveName, resolveWithinRoot } from './path-guard.js';
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const IMAGE_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+};
+export class WorkspaceService {
+    async readFile(root, relPath) {
+        const abs = resolveWithinRoot(root, relPath);
+        await this.#assertReadableFile(abs, MAX_FILE_BYTES);
+        const buffer = await readFile(abs);
+        const path = toRelative(root, abs);
+        if (isBinary(buffer)) {
+            return { path, content: buffer.toString('base64'), encoding: 'base64' };
+        }
+        return { path, content: buffer.toString('utf-8'), encoding: 'utf-8' };
+    }
+    async readImage(root, relPath) {
+        const abs = resolveWithinRoot(root, relPath);
+        const mimeType = IMAGE_MIME[extname(abs).toLowerCase()];
+        if (!mimeType) {
+            throw RpcError.invalidParams('not a supported image type');
+        }
+        await this.#assertReadableFile(abs, MAX_IMAGE_BYTES);
+        const buffer = await readFile(abs);
+        return { path: toRelative(root, abs), base64Data: buffer.toString('base64'), mimeType };
+    }
+    async list(root) {
+        const resolvedRoot = resolve(root);
+        let dirents;
+        try {
+            dirents = await readdir(resolvedRoot, { withFileTypes: true });
+        }
+        catch {
+            throw new RpcError(JsonRpcErrorCode.WorkspaceAccessDenied, 'directory not accessible');
+        }
+        const entries = [];
+        for (const dirent of dirents) {
+            if (dirent.name === '.git' || isSensitiveName(dirent.name))
+                continue;
+            const isDir = dirent.isDirectory();
+            const entry = { name: dirent.name, type: isDir ? 'dir' : 'file' };
+            if (!isDir) {
+                try {
+                    entry.size = (await stat(resolve(resolvedRoot, dirent.name))).size;
+                }
+                catch {
+                    // ignore unreadable entries' size
+                }
+            }
+            entries.push(entry);
+        }
+        entries.sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1);
+        return { cwd: '.', entries };
+    }
+    async applyPatch(root, changes) {
+        let applied = 0;
+        for (const change of changes) {
+            const abs = resolveWithinRoot(root, change.path);
+            if (change.op === 'delete') {
+                await rm(abs, { force: true });
+                applied += 1;
+                continue;
+            }
+            // add | modify
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, change.content ?? '', 'utf-8');
+            applied += 1;
+        }
+        return { success: true, applied };
+    }
+    async #assertReadableFile(abs, maxBytes) {
+        let info;
+        try {
+            info = await stat(abs);
+        }
+        catch {
+            throw new RpcError(JsonRpcErrorCode.ResourceNotFound, 'file not found');
+        }
+        if (!info.isFile()) {
+            throw RpcError.invalidParams('path is not a file');
+        }
+        if (info.size > maxBytes) {
+            throw new RpcError(JsonRpcErrorCode.BridgeError, 'file is too large to read');
+        }
+    }
+}
+function toRelative(root, abs) {
+    return relative(resolve(root), abs).split('\\').join('/');
+}
+function isBinary(buffer) {
+    const sample = buffer.subarray(0, 8000);
+    return sample.includes(0);
+}
+//# sourceMappingURL=workspace-service.js.map

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

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "uxnan-bridge",
+  "version": "0.0.1-alpha.20260621",
+  "description": "Uxnan Bridge — local control-plane daemon connecting the Uxnan mobile app to the developer's PC over E2EE.",
+  "license": "MPL-2.0",
+  "author": "Luis Donaldo Gamas Vazquez",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "uxnan-bridge": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "scripts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luisgamas/uxnan.git",
+    "directory": "bridge"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc && node --test --test-concurrency=1 \"dist/test/**/*.test.js\"",
+    "start": "node dist/src/cli.js start",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@uxnan/shared": "0.0.1-alpha.20260621",
+    "ajv": "^8.17.1",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.12",
+    "uxnan-relay": "*"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0",
+    "firebase-admin": "^13.0.0"
+  }
+}

package/scripts/extract-gemini-hook.mjs

@@ -0,0 +1,16 @@
+/**
+ * Writes the bridge's Gemini approval hook to a path passed on argv[2],
+ * then exits. Used by the end-to-end smoke test against the real `gemini`
+ * CLI to materialize the actual CJS script the bridge ships.
+ */
+import { writeGeminiApprovalHook } from '../dist/src/hooks/gemini-approval-hook.js';
+import { writeFileSync } from 'node:fs';
+
+const path = process.argv[2];
+if (!path) {
+  console.error('usage: extract-gemini-hook.mjs <output-path>');
+  process.exit(2);
+}
+const written = await writeGeminiApprovalHook(path);
+writeFileSync(written + '.sha', 'sentinel', 'utf-8');
+console.log(written);

package/scripts/fake-approval-bridge.mjs

@@ -0,0 +1,23 @@
+/**
+ * Spins up a fake bridge HTTP endpoint that ALWAYS returns `allow` after a
+ * short delay (so the gemini CLI's tool call gets a real round-trip), then
+ * prints the request it received and exits.
+ */
+import { createServer } from 'node:http';
+
+const server = createServer((req, res) => {
+  let body = '';
+  req.on('data', (c) => (body += c));
+  req.on('end', () => {
+    console.log(`[bridge] ${req.method} ${req.url} body=${body}`);
+    // Mimic the real bridge: hold the response for 250 ms (so the hook waits,
+    // exercising the same code path the real phone would) then return `allow`.
+    setTimeout(() => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ decision: 'allow' }));
+    }, 250);
+  });
+});
+server.listen(19999, '127.0.0.1', () => {
+  console.log('[bridge] listening on http://127.0.0.1:19999/agent-hook/approval');
+});

package/scripts/install-service-linux.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# install-service-linux.sh
+#
+# Installs a systemd USER unit so the uxnan-bridge daemon starts at login.
+# Requires the global CLI: npm install -g uxnan-bridge
+#
+# Remove:  systemctl --user disable --now uxnan-bridge.service && \
+#          rm "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/uxnan-bridge.service"
+set -euo pipefail
+
+BIN="$(command -v uxnan-bridge || true)"
+if [ -z "$BIN" ]; then
+  echo "uxnan-bridge not found on PATH. Run: npm install -g uxnan-bridge" >&2
+  exit 1
+fi
+
+UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+mkdir -p "$UNIT_DIR"
+
+cat > "$UNIT_DIR/uxnan-bridge.service" <<EOF
+[Unit]
+Description=Uxnan Bridge daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=$BIN start
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now uxnan-bridge.service
+echo "Enabled systemd user unit uxnan-bridge.service."
+echo "Tip: 'loginctl enable-linger \$USER' keeps it running after logout."

package/scripts/install-service-macos.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# install-service-macos.sh
+#
+# Installs a LaunchAgent so the uxnan-bridge daemon starts at login.
+# Requires the global CLI: npm install -g uxnan-bridge
+#
+# Remove:  launchctl unload ~/Library/LaunchAgents/dev.luisgamas.bridge.plist && \
+#          rm ~/Library/LaunchAgents/dev.luisgamas.bridge.plist
+set -euo pipefail
+
+BIN="$(command -v uxnan-bridge || true)"
+if [ -z "$BIN" ]; then
+  echo "uxnan-bridge not found on PATH. Run: npm install -g uxnan-bridge" >&2
+  exit 1
+fi
+
+mkdir -p "$HOME/Library/LaunchAgents" "$HOME/.uxnan/logs"
+PLIST="$HOME/Library/LaunchAgents/dev.luisgamas.bridge.plist"
+
+cat > "$PLIST" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>dev.luisgamas.bridge</string>
+  <key>ProgramArguments</key>
+  <array><string>$BIN</string><string>start</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>$HOME/.uxnan/logs/launchd.out.log</string>
+  <key>StandardErrorPath</key><string>$HOME/.uxnan/logs/launchd.err.log</string>
+</dict>
+</plist>
+EOF
+
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load "$PLIST"
+echo "Loaded LaunchAgent dev.luisgamas.bridge (starts at login)."

package/scripts/install-service-windows.ps1

@@ -0,0 +1,26 @@
+# install-service-windows.ps1
+#
+# Registers the uxnan-bridge daemon to start at user logon via Task Scheduler.
+# Requires the global CLI: npm install -g uxnan-bridge
+#
+# Usage:    powershell -ExecutionPolicy Bypass -File install-service-windows.ps1
+# Remove:   Unregister-ScheduledTask -TaskName 'UxnanBridge' -Confirm:$false
+
+$ErrorActionPreference = 'Stop'
+
+$bin = (Get-Command uxnan-bridge -ErrorAction SilentlyContinue).Source
+if (-not $bin) {
+  Write-Error "uxnan-bridge not found on PATH. Run: npm install -g uxnan-bridge"
+  exit 1
+}
+
+$action = New-ScheduledTaskAction -Execute $bin -Argument 'start'
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable `
+  -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero)
+
+Register-ScheduledTask -TaskName 'UxnanBridge' -Action $action -Trigger $trigger `
+  -Settings $settings -Description 'Uxnan Bridge daemon' -Force | Out-Null
+
+Write-Host "Registered scheduled task 'UxnanBridge' (starts at logon)."
+Write-Host "Start now with: Start-ScheduledTask -TaskName 'UxnanBridge'"