uxnan-bridge 0.0.1-alpha.20260621

package/dist/src/daemon-config.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Daemon configuration shape and defaults.
+ *
+ * Source: uxnandesktop/architecture/02e-bridge-integration.md §6.1.
+ */
+import { type AgentConfig, type AgentId } from '@uxnan/shared';
+/**
+ * Headless permission posture for agents that gate tool use (e.g. Claude Code):
+ *  - `default`           → no flag (tools needing approval are auto-denied headless);
+ *  - `acceptEdits`       → file edits auto-apply, other tools stay gated;
+ *  - `bypassPermissions` → all tools run without approval (full autonomy).
+ */
+export type AgentPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions';
+/**
+ * An explicit model to surface in the phone's model picker, declared in config.
+ *
+ * Use this to pin concrete, versioned models alongside an agent's own
+ * auto-updating aliases — e.g. for Claude Code, the `opus`/`sonnet`/`haiku`
+ * aliases always track the latest, and pinning `claude-opus-4-7` here adds an
+ * older-but-available version to the picker. `id` is passed verbatim to the
+ * CLI's `--model`/`-m` flag.
+ */
+export interface AgentModelSpec {
+    /** Exact model id passed to the agent (e.g. `claude-opus-4-8`). */
+    id: string;
+    /** Human-facing label shown in the picker (defaults to `id`). */
+    displayName?: string;
+    /** Optional one-line description shown under the label. */
+    description?: string;
+}
+/** Per-agent overrides (binary location + default model + permissions). */
+export interface AgentSettings {
+    /** Absolute path to the agent CLI/binary; resolved from PATH/standard locations when omitted. */
+    binaryPath?: string;
+    /** Default model the agent uses (e.g. `provider/model` for OpenCode). */
+    model?: string;
+    /**
+     * Extra explicit models to show in the picker **in addition** to the ones the
+     * agent reports itself. For Claude Code (which exposes only the moving
+     * `opus`/`sonnet`/`haiku` aliases), this is how you pin concrete versions
+     * (e.g. `claude-opus-4-7`) so users can deliberately select an older model.
+     * Entries may be a bare id string or an {@link AgentModelSpec}. Currently
+     * consumed by the Claude Code adapter; ignored by agents that enumerate their
+     * own models (OpenCode, Codex).
+     */
+    models?: (string | AgentModelSpec)[];
+    /**
+     * Headless permission posture for agents that support it (Claude Code).
+     * Defaults to `acceptEdits` when omitted. Ignored by agents that don't gate tools.
+     */
+    permissionMode?: AgentPermissionMode;
+    /**
+     * Opt-in interactive tool approvals (Claude Code only): inject a `PreToolUse`
+     * hook (via `--settings`) so every tool round-trips to the bridge and the user
+     * approves/rejects it on the phone (`turn/send { approvalResponse }`). Requires
+     * `lanEnabled` (the hook calls the bridge's local HTTP endpoint). Default false.
+     */
+    interactiveApprovals?: boolean;
+}
+export interface DaemonConfig {
+    relayUrl: string;
+    /**
+     * Use a relay as an off-LAN fallback. **Default `false`** — the bridge is
+     * LAN/Tailscale-direct out of the box (no hosting), and the pairing QR
+     * advertises only the direct `hosts` (see {@link lanEnabled}). The relay is
+     * **optional and self-hosted**: set `true` (and point {@link relayUrl} at your
+     * own relay) to also fall back through it for users who don't run a mesh VPN.
+     * See `docs/connectivity.md` and `relay/docs/deploy.md`.
+     */
+    relayEnabled: boolean;
+    lanEnabled: boolean;
+    lanPort: number;
+    /**
+     * Advertise the bridge on the LAN via mDNS/Bonjour (`_uxnan._tcp`) so the phone
+     * can discover it for manual-code pairing without typing the host. **Default
+     * `true`**; only effective when {@link lanEnabled}. Best-effort — a failed bind
+     * (port 5353 busy) degrades silently.
+     */
+    mdnsEnabled: boolean;
+    pushEnabled: boolean;
+    pushOnAgentDone: boolean;
+    pushOnAgentError: boolean;
+    autoReconnect: boolean;
+    maxConcurrentSessions: number;
+    sessionTimeoutMinutes: number;
+    /** Agent the bridge uses when a thread does not pick one. */
+    defaultAgent: AgentId;
+    /**
+     * Keep at most N newest workspace checkpoints per project (`cwd`); older ones
+     * are pruned (ref + metadata) on the next capture. `0` = unlimited.
+     */
+    checkpointMaxPerProject: number;
+    /** Delete workspace checkpoints older than N days on capture. `0` = no TTL. */
+    checkpointTtlDays: number;
+    /**
+     * Absolute project directories the phone may open. Empty → the bridge's own
+     * working directory is exposed as the single project.
+     */
+    workspaceRoots: string[];
+    /**
+     * Absolute base directories the phone may BROWSE under via `workspace/browseDirs`
+     * (descend into sub-folders, pick any directory as a thread's cwd) without
+     * escaping the root. Empty → falls back to {@link workspaceRoots}, then the
+     * user's home directory. Set this to e.g. your `Documents` folder.
+     */
+    browseRoots: string[];
+    /** Per-agent settings keyed by {@link AgentId}. */
+    agents: Partial<Record<AgentId, AgentSettings>>;
+    /**
+     * Per-project agent/model pins, identified by each entry's absolute `cwd`
+     * (the project directory). When a thread starts in a project (or browsed
+     * folder) whose path matches an entry and the phone did NOT pass an explicit
+     * `agentId`/`model`, the bridge uses the pinned `agentId` (and `model`, when it
+     * matches that agent). Lets a repo always open with e.g. Codex without the
+     * phone choosing each time. Reuses the shared {@link AgentConfig}; only
+     * `cwd`/`agentId`/`model` are consumed today (binaryPath/extraArgs are not yet
+     * wired — see FOR-DEV.md).
+     */
+    projectAgents: AgentConfig[];
+}
+export declare const DEFAULT_DAEMON_CONFIG: DaemonConfig;
+/** Merge a partial (e.g. loaded from disk) over the defaults. */
+export declare function resolveDaemonConfig(partial?: Partial<DaemonConfig> | null): DaemonConfig;

package/dist/src/daemon-config.js

@@ -0,0 +1,64 @@
+/**
+ * Daemon configuration shape and defaults.
+ *
+ * Source: uxnandesktop/architecture/02e-bridge-integration.md §6.1.
+ */
+import { DEFAULT_LAN_PORT, DEFAULT_RELAY_URL } from '@uxnan/shared';
+export const DEFAULT_DAEMON_CONFIG = {
+    relayUrl: DEFAULT_RELAY_URL,
+    // Relay is optional + self-hosted; off by default (LAN/Tailscale-direct).
+    relayEnabled: false,
+    lanEnabled: true,
+    lanPort: DEFAULT_LAN_PORT,
+    mdnsEnabled: true,
+    pushEnabled: true,
+    pushOnAgentDone: true,
+    pushOnAgentError: true,
+    autoReconnect: true,
+    maxConcurrentSessions: 1,
+    sessionTimeoutMinutes: 30,
+    defaultAgent: 'opencode',
+    checkpointMaxPerProject: 25,
+    checkpointTtlDays: 0,
+    workspaceRoots: [],
+    browseRoots: [],
+    projectAgents: [],
+    // Seed Claude Code with a few concrete, currently-available versions so the
+    // picker shows exact models out of the box, alongside the auto-updating
+    // `opus`/`sonnet`/`haiku` aliases. Curate this list as models are released or
+    // retired — the aliases always cover "latest" regardless. See docs/agents.md.
+    agents: {
+        'claude-code': {
+            models: [
+                { id: 'claude-fable-5', displayName: 'Fable 5' },
+                { id: 'claude-opus-4-8', displayName: 'Opus 4.8' },
+                { id: 'claude-opus-4-7', displayName: 'Opus 4.7' },
+                { id: 'claude-sonnet-4-6', displayName: 'Sonnet 4.6' },
+                { id: 'claude-haiku-4-5', displayName: 'Haiku 4.5' },
+            ],
+        },
+    },
+};
+/** Merge a partial (e.g. loaded from disk) over the defaults. */
+export function resolveDaemonConfig(partial) {
+    const merged = { ...DEFAULT_DAEMON_CONFIG, ...(partial ?? {}) };
+    // Deep-merge per-agent settings so a partial override (e.g. setting just
+    // `permissionMode` for one agent) preserves seeded defaults like Claude
+    // Code's `models` rather than wiping the whole agents map. Set an explicit
+    // empty value (e.g. `models: []`) to clear a seeded default.
+    const ids = new Set([
+        ...Object.keys(DEFAULT_DAEMON_CONFIG.agents),
+        ...Object.keys(partial?.agents ?? {}),
+    ]);
+    const agents = {};
+    for (const id of ids) {
+        const key = id;
+        agents[key] = {
+            ...DEFAULT_DAEMON_CONFIG.agents[key],
+            ...(partial?.agents?.[key] ?? {}),
+        };
+    }
+    merged.agents = agents;
+    return merged;
+}
+//# sourceMappingURL=daemon-config.js.map

package/dist/src/daemon-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-config.js","sourceRoot":"","sources":["../../src/daemon-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAkC,MAAM,eAAe,CAAC;AAwHpG,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,QAAQ,EAAE,iBAAiB;IAC3B,0EAA0E;IAC1E,YAAY,EAAE,KAAK;IACnB,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,gBAAgB;IACzB,WAAW,EAAE,IAAI;IACjB,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,IAAI;IACtB,aAAa,EAAE,IAAI;IACnB,qBAAqB,EAAE,CAAC;IACxB,qBAAqB,EAAE,EAAE;IACzB,YAAY,EAAE,UAAU;IACxB,uBAAuB,EAAE,EAAE;IAC3B,iBAAiB,EAAE,CAAC;IACpB,cAAc,EAAE,EAAE;IAClB,WAAW,EAAE,EAAE;IACf,aAAa,EAAE,EAAE;IACjB,4EAA4E;IAC5E,wEAAwE;IACxE,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,EAAE;QACN,aAAa,EAAE;YACb,MAAM,EAAE;gBACN,EAAE,EAAE,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE;gBAChD,EAAE,EAAE,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE;gBAClD,EAAE,EAAE,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE;gBAClD,EAAE,EAAE,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE;gBACtD,EAAE,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE;aACrD;SACF;KACF;CACF,CAAC;AAEF,iEAAiE;AACjE,MAAM,UAAU,mBAAmB,CAAC,OAAsC;IACxE,MAAM,MAAM,GAAG,EAAE,GAAG,qBAAqB,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;IAChE,yEAAyE;IACzE,wEAAwE;IACxE,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAS;QAC1B,GAAG,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC;QAC5C,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;KACtC,CAAC,CAAC;IACH,MAAM,MAAM,GAA4C,EAAE,CAAC;IAC3D,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,EAAa,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,GAAG;YACZ,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG,CAAC;YACpC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SAClC,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/daemon-state.d.ts

@@ -0,0 +1,27 @@
+import { type DaemonConfig } from './daemon-config.js';
+export declare const DAEMON_FILES: {
+    readonly config: "daemon-config.json";
+    readonly status: "bridge-status.json";
+    readonly pairing: "pairing-session.json";
+    readonly pairingCode: "pairing-code.json";
+    readonly trustedPhones: "trusted-phones.json";
+    readonly managedWorktrees: "managed-worktrees.json";
+    readonly pushState: "push-state.json";
+    readonly lock: "bridge.lock";
+    readonly checkpoints: "checkpoints.json";
+    readonly threads: "threads.json";
+};
+export declare class DaemonState {
+    readonly baseDir: string;
+    constructor(baseDir?: string);
+    get logsDir(): string;
+    pathFor(file: string): string;
+    ensureDir(): Promise<void>;
+    readJson<T>(file: string): Promise<T | null>;
+    /** Atomically write JSON: write to a temp sibling, then rename over the target. */
+    writeJson(file: string, data: unknown): Promise<void>;
+    readConfig(): Promise<DaemonConfig>;
+    writeConfig(config: DaemonConfig): Promise<void>;
+    /** Write the default config if none exists yet; returns the effective config. */
+    initConfig(): Promise<DaemonConfig>;
+}

package/dist/src/daemon-state.js

@@ -0,0 +1,76 @@
+/**
+ * Persistent daemon state under `~/.uxnan/` (non-secret files only).
+ *
+ * Secrets (the Ed25519 private identity) live in a {@link SecretStore}, never in
+ * these JSON files. Writes are atomic (temp file + rename).
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.3.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_DAEMON_CONFIG, resolveDaemonConfig } from './daemon-config.js';
+export const DAEMON_FILES = {
+    config: 'daemon-config.json',
+    status: 'bridge-status.json',
+    pairing: 'pairing-session.json',
+    pairingCode: 'pairing-code.json',
+    trustedPhones: 'trusted-phones.json',
+    managedWorktrees: 'managed-worktrees.json',
+    pushState: 'push-state.json',
+    lock: 'bridge.lock',
+    checkpoints: 'checkpoints.json',
+    threads: 'threads.json',
+};
+export class DaemonState {
+    baseDir;
+    constructor(baseDir = join(homedir(), '.uxnan')) {
+        this.baseDir = baseDir;
+    }
+    get logsDir() {
+        return join(this.baseDir, 'logs');
+    }
+    pathFor(file) {
+        return join(this.baseDir, file);
+    }
+    async ensureDir() {
+        await mkdir(this.baseDir, { recursive: true });
+        await mkdir(this.logsDir, { recursive: true });
+    }
+    async readJson(file) {
+        try {
+            const raw = await readFile(this.pathFor(file), 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    /** Atomically write JSON: write to a temp sibling, then rename over the target. */
+    async writeJson(file, data) {
+        await this.ensureDir();
+        const target = this.pathFor(file);
+        const tmp = `${target}.${randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8');
+        await rename(tmp, target);
+    }
+    async readConfig() {
+        const partial = await this.readJson(DAEMON_FILES.config);
+        return resolveDaemonConfig(partial);
+    }
+    async writeConfig(config) {
+        await this.writeJson(DAEMON_FILES.config, config);
+    }
+    /** Write the default config if none exists yet; returns the effective config. */
+    async initConfig() {
+        const existing = await this.readJson(DAEMON_FILES.config);
+        if (existing)
+            return resolveDaemonConfig(existing);
+        await this.writeConfig(DEFAULT_DAEMON_CONFIG);
+        return DEFAULT_DAEMON_CONFIG;
+    }
+}
+//# sourceMappingURL=daemon-state.js.map

package/dist/src/daemon-state.js.map

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

package/dist/src/git/git-runner.d.ts

@@ -0,0 +1,24 @@
+export declare class GitCommandError extends Error {
+    readonly stderr: string;
+    readonly code: number | null;
+    constructor(message: string, stderr: string, code: number | null);
+}
+export interface RunGitResult {
+    stdout: string;
+    stderr: string;
+}
+export declare function runGit(cwd: string, args: string[], options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunGitResult>;
+/**
+ * Runs the GitHub CLI (`gh`) the same safe way as git (no shell). Used for PR
+ * creation; surfaces a {@link GitCommandError} when `gh` is missing or fails
+ * (e.g. not authenticated), so the caller can show an actionable message.
+ */
+export declare function runGh(cwd: string, args: string[], options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunGitResult>;
+/** Strip the project cwd and the user's home directory from text sent to the phone. */
+export declare function sanitizePaths(text: string, cwd: string): string;

package/dist/src/git/git-runner.js

@@ -0,0 +1,63 @@
+/**
+ * Runs git locally via `child_process.execFile` (no shell → no command
+ * injection). Arguments are passed as an array; user-provided values are
+ * validated by the handlers (see `requireSafe`).
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.6.
+ */
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_BUFFER = 16 * 1024 * 1024;
+export class GitCommandError extends Error {
+    stderr;
+    code;
+    constructor(message, stderr, code) {
+        super(message);
+        this.name = 'GitCommandError';
+        this.stderr = stderr;
+        this.code = code;
+    }
+}
+export function runGit(cwd, args, options = {}) {
+    return runFile('git', cwd, args, options);
+}
+/**
+ * Runs the GitHub CLI (`gh`) the same safe way as git (no shell). Used for PR
+ * creation; surfaces a {@link GitCommandError} when `gh` is missing or fails
+ * (e.g. not authenticated), so the caller can show an actionable message.
+ */
+export function runGh(cwd, args, options = {}) {
+    return runFile('gh', cwd, args, options);
+}
+function runFile(file, cwd, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile(file, args, {
+            cwd,
+            timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            maxBuffer: MAX_BUFFER,
+            windowsHide: true,
+            ...(options.env ? { env: options.env } : {}),
+        }, (error, stdout, stderr) => {
+            if (error) {
+                const rawCode = error.code;
+                const code = typeof rawCode === 'number' ? rawCode : null;
+                const detail = sanitizePaths(stderr || stdout || error.message, cwd);
+                reject(new GitCommandError(`${file} ${args[0] ?? ''} failed`, detail, code));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+/** Strip the project cwd and the user's home directory from text sent to the phone. */
+export function sanitizePaths(text, cwd) {
+    let out = text;
+    if (cwd)
+        out = out.split(cwd).join('.');
+    const home = homedir();
+    if (home)
+        out = out.split(home).join('~');
+    return out.trim();
+}
+//# sourceMappingURL=git-runner.js.map

package/dist/src/git/git-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-runner.js","sourceRoot":"","sources":["../../../src/git/git-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,UAAU,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpC,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAS;IACf,IAAI,CAAgB;IAE7B,YAAY,OAAe,EAAE,MAAc,EAAE,IAAmB;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAOD,MAAM,UAAU,MAAM,CACpB,GAAW,EACX,IAAc,EACd,UAA2D,EAAE;IAE7D,OAAO,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CACnB,GAAW,EACX,IAAc,EACd,UAA2D,EAAE;IAE7D,OAAO,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,OAAO,CACd,IAAY,EACZ,GAAW,EACX,IAAc,EACd,UAA2D,EAAE;IAE7D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,IAAI,EACJ,IAAI,EACJ;YACE,GAAG;YACH,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB;YAChD,SAAS,EAAE,UAAU;YACrB,WAAW,EAAE,IAAI;YACjB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,OAAO,GAAI,KAA+B,CAAC,IAAI,CAAC;gBACtD,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC1D,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,IAAI,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBACrE,MAAM,CAAC,IAAI,eAAe,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;gBAC7E,OAAO;YACT,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9B,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,IAAI,GAAG;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,IAAI;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC"}

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

@@ -0,0 +1,76 @@
+import type { GitBranchList, GitBranchResult, GitCommitResult, GitDiff, GitPrResult, GitPullResult, GitPushResult, GitRepoStatus, GitWorktreeResult } from '@uxnan/shared';
+export declare class GitService {
+    #private;
+    status(cwd: string): Promise<GitRepoStatus>;
+    /**
+     * Returns the working-tree diff. With `path`, returns just that file's diff —
+     * for an untracked file (no diff vs HEAD) it synthesises an all-additions
+     * unified diff from the file contents so the phone can render it.
+     */
+    diff(cwd: string, path?: string): Promise<GitDiff>;
+    commit(cwd: string, message: string, paths?: string[]): Promise<GitCommitResult>;
+    /**
+     * Undoes the most recent commit, keeping its changes in the working tree
+     * (`git reset --soft HEAD~1`) so the user can re-stage/re-commit before
+     * pushing. Non-destructive: no file content is lost.
+     */
+    undoCommit(cwd: string): Promise<void>;
+    /** Lists the current branch plus all local and remote branches. */
+    branches(cwd: string): Promise<GitBranchList>;
+    /** Stages the given paths (`git add`). */
+    stage(cwd: string, paths: string[]): Promise<void>;
+    /** Unstages the given paths, keeping working-tree changes (`git restore --staged`). */
+    unstage(cwd: string, paths: string[]): Promise<void>;
+    /**
+     * Discards working-tree changes for the given paths. Tracked files are
+     * restored from HEAD (index + worktree); untracked files are deleted. This is
+     * destructive and irreversible — callers must confirm first.
+     */
+    discard(cwd: string, paths: string[]): Promise<void>;
+    /**
+     * Opens a pull request via the GitHub CLI (`gh pr create`). Requires `gh` to
+     * be installed and authenticated; failures surface as {@link GitCommandError}
+     * with an actionable message. Returns the PR URL.
+     */
+    createPr(cwd: string, title: string, body?: string, base?: string, head?: string): Promise<GitPrResult>;
+    push(cwd: string, remote: string, branch: string): Promise<GitPushResult>;
+    pull(cwd: string, remote?: string, branch?: string): Promise<GitPullResult>;
+    checkout(cwd: string, branch: string): Promise<void>;
+    /**
+     * Switches to {@link target}, keeping each branch's work independent.
+     *
+     * - `carryChanges: true` → the working-tree changes follow you to the target
+     *   (`git checkout` moves them; a conflict surfaces as an error).
+     * - `carryChanges: false` → the current branch's changes are stashed under a
+     *   branch-tagged label so they stay put and are NOT lost. On switching back
+     *   that branch's stash is automatically restored.
+     *
+     * Either way, any changes previously *left* on the target branch are restored
+     * after checkout.
+     */
+    switchBranch(cwd: string, target: string, carryChanges: boolean): Promise<void>;
+    createBranch(cwd: string, name: string): Promise<GitBranchResult>;
+    createWorktree(cwd: string, branch: string, path: string): Promise<GitWorktreeResult>;
+    /**
+     * Revert [commit] (e.g. `HEAD`, a sha) — creates a NEW commit that undoes it,
+     * preserving history (unlike `undoCommit`'s soft reset). `--no-edit` keeps the
+     * default revert message; fails (and surfaces) on a conflict.
+     */
+    revert(cwd: string, commit: string): Promise<void>;
+    /**
+     * Delete a local branch. With `force: false` this is `git branch -d`, which
+     * **refuses** a branch not fully merged (the safe default — the error is
+     * surfaced to the phone); `force: true` is `-D` (delete regardless).
+     */
+    deleteBranch(cwd: string, branch: string, force: boolean): Promise<void>;
+    /**
+     * Remove a worktree. With `force: false`, `git worktree remove` **refuses** a
+     * worktree with uncommitted/untracked changes (safe default — surfaced);
+     * `force: true` adds `--force`. Also prunes stale admin entries afterward.
+     *
+     * `git` refuses to remove the worktree you are *standing in*, so we run the
+     * removal from the repo's MAIN worktree (resolved via `worktree list`),
+     * letting the phone remove the very worktree backing the active thread.
+     */
+    removeWorktree(cwd: string, path: string, force: boolean): Promise<void>;
+}