@gtc6244/immediacy-daemon 0.1.0

package/dist/src/daemon-identity.js

@@ -0,0 +1,97 @@
+/**
+ * DaemonIdentity — this daemon's stable id + human name.
+ *
+ * A client can talk to several daemons at once (it dials each tunnel/host
+ * independently — daemons never talk to each other), and labels each by name.
+ * This store gives the daemon a stable `daemonId` (minted once, persisted) and a
+ * human `name` that defaults to the machine hostname and can be changed over the
+ * wire (`daemon.rename`). Persisted to `~/.immediacy/daemon.json`.
+ *
+ * No secret material, so the file is world-readable (0644) like config.json —
+ * but it keeps the same serialized atomic-rename persist() so a concurrent
+ * rename can't tear the file.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PROTOCOL_VERSION } from "./protocol.js";
+const IDENTITY_FILE = process.env.DAEMON_IDENTITY_FILE ??
+    join(homedir(), ".immediacy", "daemon.json");
+/** A name a malicious/confused client can't blow up to a multi-KB blob. */
+const MAX_NAME_LEN = 200;
+/** The daemon package version, read once from the repo-root VERSION file. */
+function readVersion() {
+    // This module lives at daemon/src/daemon-identity.ts, so ../../VERSION.
+    try {
+        const p = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "VERSION");
+        return readFileSync(p, "utf8").trim() || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export class DaemonIdentity {
+    daemonId = "";
+    name = "";
+    version = readVersion();
+    /** Serializes writes so two concurrent rename() calls can't interleave. */
+    writeChain = Promise.resolve();
+    /**
+     * Load the persisted identity, minting a fresh id (and a hostname-derived
+     * default name) on first run and writing it back so it stays stable.
+     */
+    async load() {
+        let stored = {};
+        try {
+            stored = JSON.parse(await readFile(IDENTITY_FILE, "utf8"));
+        }
+        catch {
+            /* no prior state — first run */
+        }
+        this.daemonId =
+            typeof stored.daemonId === "string" && stored.daemonId.trim()
+                ? stored.daemonId
+                : randomUUID();
+        this.name =
+            typeof stored.name === "string" && stored.name.trim()
+                ? stored.name.trim().slice(0, MAX_NAME_LEN)
+                : hostname();
+        // Persist so a freshly minted id/name survives the next restart.
+        await this.persist();
+        console.log(`[daemon] identity "${this.name}" (${this.daemonId})`);
+    }
+    /** Set the human name (trimmed, non-empty, length-capped) and persist. */
+    async rename(name) {
+        const trimmed = name.trim().slice(0, MAX_NAME_LEN);
+        if (!trimmed)
+            throw new Error("daemon name is empty");
+        this.name = trimmed;
+        await this.persist();
+    }
+    /** The wire payload for `daemon.info` (pushed on connect / rename / get). */
+    info() {
+        return {
+            daemonId: this.daemonId,
+            name: this.name,
+            hostname: hostname(),
+            version: this.version,
+            protocolVersion: PROTOCOL_VERSION,
+        };
+    }
+    persist() {
+        const snapshot = JSON.stringify({ daemonId: this.daemonId, name: this.name }, null, 2);
+        this.writeChain = this.writeChain
+            .catch(() => { })
+            .then(async () => {
+            await mkdir(dirname(IDENTITY_FILE), { recursive: true });
+            const tmp = `${IDENTITY_FILE}.${process.pid}.tmp`;
+            await writeFile(tmp, snapshot);
+            await rename(tmp, IDENTITY_FILE);
+        });
+        return this.writeChain;
+    }
+}
+//# sourceMappingURL=daemon-identity.js.map

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

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

package/dist/src/envelope.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Envelope construction + the shared ProtocolError.
+ *
+ * The (de)serialization seam lives in `crypto.ts` (`clearCodec` / `boxCodec` →
+ * `parseEnvelope`), because whether `payload` is cleartext or a sealed NaCl box
+ * is a per-socket codec decision. This module only stamps outbound envelopes.
+ */
+import { Envelope, MessageType, PayloadFor } from "./protocol.js";
+/** Build a fully-stamped envelope ready to send. */
+export declare function make<T extends MessageType>(type: T, ws: string | null, payload: PayloadFor<T>): Envelope<T>;
+export declare class ProtocolError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}

package/dist/src/envelope.js

@@ -0,0 +1,28 @@
+/**
+ * Envelope construction + the shared ProtocolError.
+ *
+ * The (de)serialization seam lives in `crypto.ts` (`clearCodec` / `boxCodec` →
+ * `parseEnvelope`), because whether `payload` is cleartext or a sealed NaCl box
+ * is a per-socket codec decision. This module only stamps outbound envelopes.
+ */
+import { randomUUID } from "node:crypto";
+import { PROTOCOL_VERSION, } from "./protocol.js";
+/** Build a fully-stamped envelope ready to send. */
+export function make(type, ws, payload) {
+    return {
+        v: PROTOCOL_VERSION,
+        id: randomUUID(),
+        ts: Date.now(),
+        ws,
+        type,
+        payload,
+    };
+}
+export class ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAIL,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,oDAAoD;AACpD,MAAM,UAAU,IAAI,CAClB,IAAO,EACP,EAAiB,EACjB,OAAsB;IAEtB,OAAO;QACL,CAAC,EAAE,gBAAgB;QACnB,EAAE,EAAE,UAAU,EAAE;QAChB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;QACd,EAAE;QACF,IAAI;QACJ,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE7B;IADT,YACS,IAAY,EACnB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAQ;IAIrB,CAAC;CACF"}

package/dist/src/events.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Internal system-event bus.
+ *
+ * The daemon already fans events out to *clients* via the write-only `Hub`
+ * (`hub.broadcast`), but nothing in-process can subscribe to "an agent finished"
+ * or "a PR was opened". The cron/jobs feature needs exactly that: a reactive
+ * ("N minutes after X") trigger has to observe identifiable actions as they
+ * happen. This is the single in-process pub/sub seam for those domain events.
+ *
+ * It is deliberately tiny and decoupled: `WorkspaceManager` is handed one and
+ * emits onto it at the chokepoints where an action completes; `JobScheduler`
+ * is handed the same instance and subscribes. Neither knows about the other.
+ */
+import { EventEmitter } from "node:events";
+/**
+ * Identifiable actions a reactive job can key off.
+ *
+ * `agent.error` is INTERNAL-ONLY: it is not a `JobSystemEvent` (protocol.ts), so
+ * no user-defined "after" trigger can select it. The scheduler subscribes to it
+ * solely to finalize a dispatched run whose agent turn ended in failure — an
+ * errored turn emits no `agent.done`, so without this the run (and any ephemeral
+ * worktree) would dangle forever.
+ */
+export type SystemEventKind = "agent.done" | "agent.error" | "pr.created" | "issue.created" | "commit" | "push" | "workspace.created";
+export interface SystemEvent {
+    kind: SystemEventKind;
+    /** The workspace the action happened in. */
+    ws: string;
+    /**
+     * Event-specific detail, interpolated into a reactive job's prompt via
+     * `{{key}}` placeholders (e.g. `{{url}}` for pr.created, `{{summary}}` for
+     * agent.done). Always strings so templating stays trivial.
+     */
+    context?: Record<string, string>;
+}
+/** Thin typed wrapper over EventEmitter so call sites stay honest. */
+export declare class SystemEvents extends EventEmitter {
+    emitSystem(e: SystemEvent): void;
+    onSystem(fn: (e: SystemEvent) => void): this;
+}

package/dist/src/events.js

@@ -0,0 +1,24 @@
+/**
+ * Internal system-event bus.
+ *
+ * The daemon already fans events out to *clients* via the write-only `Hub`
+ * (`hub.broadcast`), but nothing in-process can subscribe to "an agent finished"
+ * or "a PR was opened". The cron/jobs feature needs exactly that: a reactive
+ * ("N minutes after X") trigger has to observe identifiable actions as they
+ * happen. This is the single in-process pub/sub seam for those domain events.
+ *
+ * It is deliberately tiny and decoupled: `WorkspaceManager` is handed one and
+ * emits onto it at the chokepoints where an action completes; `JobScheduler`
+ * is handed the same instance and subscribes. Neither knows about the other.
+ */
+import { EventEmitter } from "node:events";
+/** Thin typed wrapper over EventEmitter so call sites stay honest. */
+export class SystemEvents extends EventEmitter {
+    emitSystem(e) {
+        this.emit("system", e);
+    }
+    onSystem(fn) {
+        return this.on("system", fn);
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/src/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgC3C,sEAAsE;AACtE,MAAM,OAAO,YAAa,SAAQ,YAAY;IAC5C,UAAU,CAAC,CAAc;QACvB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,QAAQ,CAAC,EAA4B;QACnC,OAAO,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/src/forward.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Forwarded TCP streams — the daemon side of dev-server preview.
+ *
+ * A client (the macOS app) runs a loopback listener; each browser connection it
+ * accepts becomes a `forward.open` here. We dial `127.0.0.1:<port>` on the
+ * daemon box and pipe bytes in both directions as base64 `forward.data` frames,
+ * multiplexed over the one WSS connection by `streamId`. This is a raw TCP
+ * bridge (not HTTP-aware), so HTTP, WebSocket HMR, and SSE all pass through
+ * unchanged — the dev server sees an ordinary local client.
+ *
+ * Streams are per-socket, like the terminal PTY: the reply bytes go back to the
+ * exact client socket that opened the stream, and every stream that socket owns
+ * is torn down when it disconnects (`reapClient`).
+ *
+ * Security: the daemon opens no inbound port and only ever dials loopback, and
+ * only ports the `isOwned` check confirms belong to the named workspace's
+ * worktree (see `ports.ts`). An `open` for any other port is refused immediately.
+ */
+import type { WebSocket } from "ws";
+import type { Hub } from "./hub.js";
+export declare class ForwardManager {
+    private hub;
+    /** Gate: is `port` currently a worktree-owned listening port for `ws`? */
+    private isOwned;
+    private streams;
+    constructor(hub: Hub, 
+    /** Gate: is `port` currently a worktree-owned listening port for `ws`? */
+    isOwned: (ws: string, port: number) => boolean);
+    /**
+     * A client accepted a local connection and wants it bridged. Validates the
+     * port against the worktree-owned set, dials loopback, and wires both
+     * directions. Any failure closes the stream back to the client with a reason.
+     */
+    open(client: WebSocket, ws: string, streamId: string, port: number): void;
+    /** Pause a stream's source read until its client-bound WS queue drains. */
+    private pauseUntilDrained;
+    /** A chunk of browser→server bytes for an open stream. */
+    data(streamId: string, b64: string): void;
+    /** The client closed its end; drop the daemon-side socket (no echo back). */
+    close(streamId: string): void;
+    /** Tear down every stream owned by a socket that just disconnected. */
+    reapClient(client: WebSocket): void;
+    /** Refuse before a socket ever existed: just tell the client it's closed. */
+    private refuse;
+    /**
+     * The daemon-side socket ended (remote close, error, or write failure). Notify
+     * the client so it closes the matching browser connection, then forget it.
+     * Idempotent — a socket 'error' immediately followed by 'close' only fires once.
+     */
+    private teardown;
+}

package/dist/src/forward.js

@@ -0,0 +1,170 @@
+/**
+ * Forwarded TCP streams — the daemon side of dev-server preview.
+ *
+ * A client (the macOS app) runs a loopback listener; each browser connection it
+ * accepts becomes a `forward.open` here. We dial `127.0.0.1:<port>` on the
+ * daemon box and pipe bytes in both directions as base64 `forward.data` frames,
+ * multiplexed over the one WSS connection by `streamId`. This is a raw TCP
+ * bridge (not HTTP-aware), so HTTP, WebSocket HMR, and SSE all pass through
+ * unchanged — the dev server sees an ordinary local client.
+ *
+ * Streams are per-socket, like the terminal PTY: the reply bytes go back to the
+ * exact client socket that opened the stream, and every stream that socket owns
+ * is torn down when it disconnects (`reapClient`).
+ *
+ * Security: the daemon opens no inbound port and only ever dials loopback, and
+ * only ports the `isOwned` check confirms belong to the named workspace's
+ * worktree (see `ports.ts`). An `open` for any other port is refused immediately.
+ */
+import net from "node:net";
+import { logger } from "./log.js";
+/** Cap on concurrent forwarded streams — a backstop against a runaway client. */
+const MAX_STREAMS = 512;
+/** Refuse dials to anything but a normal user port. */
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+/**
+ * Pause reading the dev server once more than this many bytes are queued to the
+ * client over the WS but not yet flushed. Bounds daemon memory when the tunnel
+ * is slower than a fast local dev server (large asset / SSE download).
+ */
+const CLIENT_HIGH_WATER = 1 << 20; // 1 MiB
+/** Re-check the client-bound queue this often while a stream is paused. */
+const DRAIN_POLL_MS = 25;
+/** Abort a dial that accepts the SYN but never establishes / stalls. */
+const CONNECT_TIMEOUT_MS = 10_000;
+export class ForwardManager {
+    hub;
+    isOwned;
+    streams = new Map();
+    constructor(hub, 
+    /** Gate: is `port` currently a worktree-owned listening port for `ws`? */
+    isOwned) {
+        this.hub = hub;
+        this.isOwned = isOwned;
+    }
+    /**
+     * A client accepted a local connection and wants it bridged. Validates the
+     * port against the worktree-owned set, dials loopback, and wires both
+     * directions. Any failure closes the stream back to the client with a reason.
+     */
+    open(client, ws, streamId, port) {
+        if (!streamId || this.streams.has(streamId))
+            return;
+        if (this.streams.size >= MAX_STREAMS) {
+            this.refuse(client, streamId, "too many forwarded streams");
+            return;
+        }
+        if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
+            this.refuse(client, streamId, "invalid port");
+            return;
+        }
+        if (!this.isOwned(ws, port)) {
+            this.refuse(client, streamId, `port ${port} is not an active dev server for this workspace`);
+            return;
+        }
+        const sock = net.connect({ host: "127.0.0.1", port });
+        const stream = { sock, client, ws, port };
+        this.streams.set(streamId, stream);
+        // A dial that never establishes (SYN accepted, connection stalls) would
+        // otherwise pin a stream slot until the client disconnects.
+        const connectTimer = setTimeout(() => {
+            if (!stream.connected)
+                this.teardown(streamId, "connect timed out");
+        }, CONNECT_TIMEOUT_MS);
+        connectTimer.unref?.();
+        sock.on("connect", () => {
+            stream.connected = true;
+            clearTimeout(connectTimer);
+            logger.debug("forward", "stream open", { ws, data: { port } });
+        });
+        sock.on("data", (chunk) => {
+            this.hub.sendTo(client, "forward.data", null, {
+                streamId,
+                data: chunk.toString("base64"),
+            });
+            // Backpressure on the ACTUAL congested resource: bytes queued to the
+            // client over the WS. If the tunnel is slower than the dev server, pause
+            // reading the source until that queue drains — bounds daemon memory.
+            if (client.bufferedAmount > CLIENT_HIGH_WATER)
+                this.pauseUntilDrained(streamId);
+        });
+        sock.on("error", (err) => this.teardown(streamId, err.message));
+        sock.on("close", () => this.teardown(streamId));
+    }
+    /** Pause a stream's source read until its client-bound WS queue drains. */
+    pauseUntilDrained(streamId) {
+        const stream = this.streams.get(streamId);
+        if (!stream || stream.sock.isPaused())
+            return;
+        stream.sock.pause();
+        const check = () => {
+            const s = this.streams.get(streamId);
+            if (!s || s.sock.destroyed)
+                return; // stream gone — nothing to resume
+            if (s.client.bufferedAmount > CLIENT_HIGH_WATER) {
+                setTimeout(check, DRAIN_POLL_MS).unref?.();
+            }
+            else {
+                s.sock.resume();
+            }
+        };
+        setTimeout(check, DRAIN_POLL_MS).unref?.();
+    }
+    /** A chunk of browser→server bytes for an open stream. */
+    data(streamId, b64) {
+        const stream = this.streams.get(streamId);
+        if (!stream || stream.sock.destroyed)
+            return;
+        try {
+            stream.sock.write(Buffer.from(b64, "base64"));
+        }
+        catch (err) {
+            // A synchronous throw is rare (write-after-end) — the async failure path
+            // is the 'error' handler → teardown. Log so it isn't silently swallowed.
+            logger.debug("forward", "stream write failed", {
+                data: { streamId, message: err instanceof Error ? err.message : String(err) },
+            });
+            this.teardown(streamId, "write failed");
+        }
+    }
+    /** The client closed its end; drop the daemon-side socket (no echo back). */
+    close(streamId) {
+        const stream = this.streams.get(streamId);
+        if (!stream)
+            return;
+        this.streams.delete(streamId);
+        stream.sock.destroy();
+    }
+    /** Tear down every stream owned by a socket that just disconnected. */
+    reapClient(client) {
+        for (const [id, stream] of this.streams) {
+            if (stream.client === client) {
+                this.streams.delete(id);
+                stream.sock.destroy();
+            }
+        }
+    }
+    /** Refuse before a socket ever existed: just tell the client it's closed. */
+    refuse(client, streamId, error) {
+        logger.debug("forward", "refused stream", { data: { streamId, error } });
+        this.hub.sendTo(client, "forward.close", null, { streamId, error });
+    }
+    /**
+     * The daemon-side socket ended (remote close, error, or write failure). Notify
+     * the client so it closes the matching browser connection, then forget it.
+     * Idempotent — a socket 'error' immediately followed by 'close' only fires once.
+     */
+    teardown(streamId, error) {
+        const stream = this.streams.get(streamId);
+        if (!stream)
+            return;
+        this.streams.delete(streamId);
+        stream.sock.destroy();
+        this.hub.sendTo(stream.client, "forward.close", null, {
+            streamId,
+            ...(error ? { error } : {}),
+        });
+    }
+}
+//# sourceMappingURL=forward.js.map

package/dist/src/forward.js.map

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

package/dist/src/fs-scope.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Filesystem containment check, shared by every path that must confine a target
+ * to a worktree: the Claude permission gate (`agent/workspace-scope.ts`) and the
+ * in-app file viewer (`worktree.ts`). One implementation so the two can't drift —
+ * in particular so both are symlink-safe.
+ */
+/**
+ * True when `target` (absolute or relative to `root`) resolves inside `root`.
+ *
+ * Canonicalizes with `realpathSync` so a symlink inside the worktree that points
+ * outside it cannot pass: `path.resolve` only normalizes `..`/`.` textually and
+ * does NOT follow links, so `<worktree>/link/x` (link → /etc) would otherwise
+ * look in-tree. We realpath the deepest existing ancestor of the target (the
+ * target itself may not exist yet, e.g. a Write to a new file) and re-check
+ * containment against the realpath'd root.
+ */
+export declare function isInside(root: string, target: string): boolean;

package/dist/src/fs-scope.js

@@ -0,0 +1,47 @@
+/**
+ * Filesystem containment check, shared by every path that must confine a target
+ * to a worktree: the Claude permission gate (`agent/workspace-scope.ts`) and the
+ * in-app file viewer (`worktree.ts`). One implementation so the two can't drift —
+ * in particular so both are symlink-safe.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+/**
+ * True when `target` (absolute or relative to `root`) resolves inside `root`.
+ *
+ * Canonicalizes with `realpathSync` so a symlink inside the worktree that points
+ * outside it cannot pass: `path.resolve` only normalizes `..`/`.` textually and
+ * does NOT follow links, so `<worktree>/link/x` (link → /etc) would otherwise
+ * look in-tree. We realpath the deepest existing ancestor of the target (the
+ * target itself may not exist yet, e.g. a Write to a new file) and re-check
+ * containment against the realpath'd root.
+ */
+export function isInside(root, target) {
+    const base = canonical(resolve(root));
+    const absLexical = isAbsolute(target) ? resolve(target) : resolve(resolve(root), target);
+    const abs = canonical(absLexical);
+    const rel = relative(base, abs);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Resolve symlinks in the deepest existing prefix of `p`, re-appending the
+ * not-yet-existing tail. Returns `p` unchanged if nothing on the path exists.
+ */
+function canonical(p) {
+    let dir = p;
+    const tail = [];
+    while (!existsSync(dir)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return p; // reached the root without finding anything
+        tail.unshift(dir.slice(parent.length + 1));
+        dir = parent;
+    }
+    try {
+        return tail.length ? resolve(realpathSync(dir), ...tail) : realpathSync(dir);
+    }
+    catch {
+        return p;
+    }
+}
+//# sourceMappingURL=fs-scope.js.map

package/dist/src/fs-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-scope.js","sourceRoot":"","sources":["../../src/fs-scope.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,MAAc;IACnD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACzF,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,CAAS;IAC1B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,CAAC,CAAC,CAAC,4CAA4C;QAC1E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3C,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/src/github.d.ts

@@ -0,0 +1,70 @@
+/**
+ * GitHub integration via the `gh` CLI.
+ *
+ * Why gh, not a stored token: the daemon runs on the user's Mac where `gh` is
+ * already authenticated. Reusing it means the GitHub token never touches the
+ * phone, the wire, or this source — it stays in gh's keychain (§ no secrets in
+ * source / single-user). The daemon just shells out.
+ *
+ * Flow: list the user's repos → user picks one → `cloneInto` clones it into the
+ * project's managed directory → the normal worktree path forks off that clone.
+ */
+import type { GithubRepo, GithubStatusResultPayload, IssueSummary, PullRequestSummary } from "./protocol.js";
+/**
+ * Legacy clone cache. New GitHub projects clone into the managed projects root
+ * (see projects.ts); this constant survives only so pre-existing project
+ * records whose repo path points here are still recognised as cached clones.
+ */
+export declare const REPO_CACHE: string;
+/** Is `gh` installed AND logged in? Drives whether the app shows the picker. */
+export declare function status(): Promise<GithubStatusResultPayload>;
+/**
+ * List every repo the authenticated user can access, most-recently-pushed
+ * first.
+ *
+ * Why `gh api /user/repos` and not `gh repo list`: `gh repo list` only returns
+ * repos the user *owns*, so repos where they're a collaborator or org member
+ * never reach the picker. `/user/repos?affiliation=owner,collaborator,
+ * organization_member` returns the full set the account has access to. We reshape
+ * the REST fields into our `GhRepoJson` shape (jq runs per page; `--paginate`
+ * follows Link headers, so output is newline-delimited JSON objects).
+ */
+export declare function listRepos(limit?: number): Promise<GithubRepo[]>;
+/**
+ * Clone a GitHub repo into `dest` via `gh` (uses gh's auth, so private repos
+ * work). The caller owns `dest` — it lives in the managed projects root, so the
+ * client never chooses where the clone lands.
+ */
+export declare function cloneInto(fullName: string, dest: string): Promise<void>;
+/**
+ * List a project's open pull requests, newest first. Runs `gh` with the repo
+ * clone as its cwd so it targets that repo's `origin` without us threading the
+ * `fullName` through — the same keychain-auth stance as the rest of this file.
+ * Returns [] rather than throwing when `gh` is absent/unauthenticated or the
+ * project has no GitHub remote, so the picker just shows "no open PRs".
+ */
+export declare function listPullRequests(repoPath: string): Promise<PullRequestSummary[]>;
+/**
+ * Resolve an open PR's head branch name. Used by the "create worktree from PR"
+ * flow to know which ref to check out. Throws (unlike the list calls) because
+ * the caller can't proceed without it.
+ */
+export declare function prHeadRef(repoPath: string, prNumber: number): Promise<string>;
+/**
+ * List a project's open issues (with bodies), newest first. Bodies ride along
+ * so the "create worktree from an issue" flow can seed and let the user confirm
+ * the new worktree's task without a second round-trip. Best-effort like
+ * {@link listPullRequests} — returns [] on any `gh` failure.
+ */
+export declare function listIssues(repoPath: string): Promise<IssueSummary[]>;
+/**
+ * Open a GitHub issue in the workspace's repo via `gh issue create` and return
+ * its URL — the mirror of `prCreate`. The agent's produced plan/document is the
+ * `body`. Runs with the worktree as cwd so `gh` targets the right repo.
+ */
+export declare function createIssue(repoPath: string, title: string, body: string): Promise<string>;
+/**
+ * Best-effort refresh of an existing clone's base branch. Never throws, so a
+ * daemon that's offline keeps using the clone it already has.
+ */
+export declare function refreshRepo(repoPath: string): Promise<void>;