patchwork-os 0.2.0-alpha.0

package/dist/tools/handoffNote.d.ts

@@ -0,0 +1,106 @@
+interface HandoffNote {
+    note: string;
+    updatedAt: number;
+    updatedBy: string;
+    auto?: boolean;
+}
+export declare function readNote(workspace?: string, configDir?: string): Promise<HandoffNote | null>;
+export declare function writeNote(note: string, workspace?: string, configDir?: string, _auto?: boolean): Promise<void>;
+export declare function createSetHandoffNoteTool(_sessionId: string, deps?: {
+    workspace?: string;
+    configDir?: string;
+}): {
+    schema: {
+        name: string;
+        annotations: {
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+        };
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {
+                note: {
+                    type: string;
+                    maxLength: number;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+        outputSchema: {
+            type: "object";
+            properties: {
+                saved: {
+                    type: string;
+                };
+                updatedAt: {
+                    type: string;
+                };
+                message: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    handler: (args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    } | {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: true;
+    }>;
+};
+export declare function createGetHandoffNoteTool(deps?: {
+    workspace?: string;
+    configDir?: string;
+}): {
+    schema: {
+        name: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {};
+            required: never[];
+        };
+        outputSchema: {
+            type: "object";
+            properties: {
+                note: {
+                    type: string[];
+                };
+                message: {
+                    type: string;
+                };
+                updatedAt: {
+                    type: string;
+                };
+                updatedBy: {
+                    type: string;
+                };
+                age: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    handler: (_args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    }>;
+};
+export {};

package/dist/tools/handoffNote.js

@@ -0,0 +1,232 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { error, successStructured } from "./utils.js";
+function getGlobalNotePath(configDir) {
+    return path.join(configDir, "ide", "handoff-note.json");
+}
+function workspaceScopedNotePath(workspace, configDir) {
+    // Normalize before hashing so trailing slashes and relative paths don't
+    // produce different hashes for the same workspace across restarts.
+    const normalizedWorkspace = path.resolve(workspace);
+    const hash = crypto
+        .createHash("sha256")
+        .update(normalizedWorkspace)
+        .digest("hex")
+        .slice(0, 12);
+    return path.join(configDir, "ide", `handoff-note-${hash}.json`);
+}
+function resolveConfigDir() {
+    const envVal = process.env.CLAUDE_CONFIG_DIR;
+    if (envVal) {
+        // path.resolve() canonicalizes the value, neutralizing any `../..` traversal
+        // sequences that could appear in untrusted env (e.g. Docker EnvironmentFile).
+        return path.resolve(envVal);
+    }
+    return path.join(os.homedir(), ".claude");
+}
+// In-memory read cache: path → { value, expiresAt }
+// Eliminates redundant disk reads when getHandoffNote is called repeatedly
+// within a short window (e.g. automation hooks, session start sequences).
+const READ_CACHE_TTL_MS = 30_000; // 30 seconds
+const noteReadCache = new Map();
+function getCachedNote(notePath) {
+    const entry = noteReadCache.get(notePath);
+    if (!entry)
+        return undefined; // cache miss
+    if (Date.now() > entry.expiresAt) {
+        noteReadCache.delete(notePath);
+        return undefined; // expired
+    }
+    return entry.value; // cache hit (may be null for "file not found")
+}
+const NOTE_READ_CACHE_MAX_SIZE = 50;
+function setCachedNote(notePath, value) {
+    // Evict oldest entry when cache is at capacity (handles multi-workspace scenarios).
+    if (!noteReadCache.has(notePath) &&
+        noteReadCache.size >= NOTE_READ_CACHE_MAX_SIZE) {
+        const oldest = noteReadCache.keys().next().value;
+        if (oldest !== undefined)
+            noteReadCache.delete(oldest);
+    }
+    noteReadCache.set(notePath, {
+        value,
+        expiresAt: Date.now() + READ_CACHE_TTL_MS,
+    });
+}
+function invalidateCachedNote(notePath) {
+    noteReadCache.delete(notePath);
+}
+/** Maximum handoff note size enforced at read time (matches write-time cap). */
+const MAX_NOTE_READ_CHARS = 10_000;
+function readNoteFromPath(notePath) {
+    const cached = getCachedNote(notePath);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const raw = fs.readFileSync(notePath, "utf-8");
+        const result = JSON.parse(raw);
+        // Enforce read-time cap: a manually edited or oversized file must not inject
+        // unbounded content into Claude's context via contextBundle or getHandoffNote.
+        if (typeof result.note === "string" &&
+            result.note.length > MAX_NOTE_READ_CHARS) {
+            // Spread to codepoints before slicing so multibyte chars aren't split mid-sequence.
+            result.note =
+                [...result.note].slice(0, MAX_NOTE_READ_CHARS).join("") +
+                    "\n[truncated]";
+        }
+        setCachedNote(notePath, result);
+        return result;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            // File genuinely missing — cache null so we don't hammer the FS.
+            setCachedNote(notePath, null);
+        }
+        else {
+            // Parse error, permission error, etc. — log and do NOT cache so the
+            // next call retries from disk (avoids silently returning "no note" for
+            // a temporarily corrupt file).
+            console.error(`[readNoteFromPath] Failed to read/parse handoff note at ${notePath}:`, err);
+        }
+        return null;
+    }
+}
+export async function readNote(workspace, configDir) {
+    const dir = configDir ?? resolveConfigDir();
+    if (workspace) {
+        const scoped = readNoteFromPath(workspaceScopedNotePath(workspace, dir));
+        if (scoped !== null)
+            return scoped;
+    }
+    return readNoteFromPath(getGlobalNotePath(dir));
+}
+export async function writeNote(note, workspace, configDir, _auto) {
+    const dir = configDir ?? resolveConfigDir();
+    const content = {
+        note,
+        updatedAt: Date.now(),
+        updatedBy: "cli",
+        ...(_auto === true ? { auto: true } : {}),
+    };
+    const contentJson = JSON.stringify(content, null, 2);
+    // Determine primary write path
+    const primaryPath = workspace
+        ? workspaceScopedNotePath(workspace, dir)
+        : getGlobalNotePath(dir);
+    fs.mkdirSync(path.dirname(primaryPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(primaryPath, contentJson, { mode: 0o600 });
+    // Invalidate cache so next read reflects the new value immediately.
+    invalidateCachedNote(primaryPath);
+    // Also update cache with the freshly written value to avoid a disk read.
+    setCachedNote(primaryPath, content);
+    // Do NOT dual-write to global path when a workspace is provided — this
+    // would allow workspace A's note to leak into workspace B via the global
+    // fallback read path (cross-workspace prompt injection vector).
+}
+export function createSetHandoffNoteTool(_sessionId, deps = {}) {
+    return {
+        schema: {
+            name: "setHandoffNote",
+            annotations: { destructiveHint: true, idempotentHint: true },
+            description: "Save context note that persists across sessions. Use when switching between CLI and Desktop.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    note: {
+                        type: "string",
+                        maxLength: 10_000,
+                        description: "Context summary: what you worked on, key findings, and next step.",
+                    },
+                },
+                required: ["note"],
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    saved: { type: "boolean" },
+                    updatedAt: { type: "number" },
+                    message: { type: "string" },
+                },
+                required: ["saved", "updatedAt"],
+            },
+        },
+        handler: async (args) => {
+            const note = args.note;
+            if (typeof note !== "string") {
+                return error("note must be a string");
+            }
+            if (note.length > 10_000) {
+                return error(`Note exceeds maximum length of 10,000 characters (got ${note.length}).`);
+            }
+            try {
+                await writeNote(note, deps.workspace, deps.configDir);
+            }
+            catch (err) {
+                return error(`Failed to write handoff note: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return successStructured({ saved: true, updatedAt: Date.now() });
+        },
+    };
+}
+export function createGetHandoffNoteTool(deps = {}) {
+    // Pre-compute note paths once at factory time — avoids repeated sha256 hash,
+    // path.resolve, and env-var lookups on every handler invocation.
+    const configDir = deps.configDir ?? resolveConfigDir();
+    const scopedNotePath = deps.workspace
+        ? workspaceScopedNotePath(deps.workspace, configDir)
+        : null;
+    const globalNotePath = getGlobalNotePath(configDir);
+    return {
+        schema: {
+            name: "getHandoffNote",
+            annotations: { readOnlyHint: true },
+            description: "Retrieve handoff note from prior session (Desktop or CLI). Call at session start to resume.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    note: { type: ["string", "null"] },
+                    message: { type: "string" },
+                    updatedAt: { type: "number" },
+                    updatedBy: { type: "string" },
+                    age: { type: "string" },
+                },
+                required: ["note"],
+            },
+        },
+        handler: async (_args) => {
+            // Use pre-computed paths; cache handles repeated reads without disk I/O.
+            let note = null;
+            if (scopedNotePath !== null) {
+                note = readNoteFromPath(scopedNotePath);
+            }
+            if (note === null) {
+                note = readNoteFromPath(globalNotePath);
+            }
+            if (!note) {
+                return successStructured({
+                    note: null,
+                    message: "No handoff note found. Use setHandoffNote to save context.",
+                });
+            }
+            const ageMs = Date.now() - note.updatedAt;
+            const ageMinutes = Math.round(ageMs / 60_000);
+            const ageLabel = ageMinutes < 60
+                ? `${ageMinutes}m ago`
+                : `${Math.round(ageMinutes / 60)}h ago`;
+            return successStructured({
+                note: note.note,
+                updatedAt: note.updatedAt,
+                updatedBy: note.updatedBy,
+                age: ageLabel,
+            });
+        },
+    };
+}
+//# sourceMappingURL=handoffNote.js.map

package/dist/tools/handoffNote.js.map

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

package/dist/tools/headless/lspClient.d.ts

@@ -0,0 +1,26 @@
+export declare class HeadlessLspClient {
+    private proc;
+    private pending;
+    private nextId;
+    private initialized;
+    private initPromise;
+    private buffer;
+    private openedFiles;
+    /** True when the client has a live process and completed initialization. */
+    get isReady(): boolean;
+    /** Initialize: spawn process, send initialize + initialized. Idempotent. */
+    initialize(workspaceRoot: string): Promise<void>;
+    private _doInit;
+    /** Parse and dispatch complete LSP messages from the buffer. */
+    private _drain;
+    /** Send a JSON-RPC request and wait for the response. */
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    /** Send a JSON-RPC notification (no response expected). */
+    private _sendNotification;
+    /** Open a file in the LSP server (required before hover/definition/references). */
+    openFile(uri: string, languageId: string, text: string): Promise<void>;
+    /** Kill the process and clear all pending requests. */
+    dispose(): void;
+}
+export declare function getHeadlessLspClient(): HeadlessLspClient;
+export declare function disposeHeadlessLspClient(): void;

package/dist/tools/headless/lspClient.js

@@ -0,0 +1,221 @@
+/**
+ * Headless LSP client: JSON-RPC 2.0 over stdio to typescript-language-server.
+ *
+ * Content-Length framing (LSP wire format):
+ *   "Content-Length: N\r\n\r\n<N bytes of JSON>"
+ *
+ * Lifecycle:
+ *   1. spawn typescript-language-server --stdio
+ *   2. send initialize request, wait for response
+ *   3. send initialized notification
+ *   4. openFile (textDocument/didOpen) before any hover/definition/references
+ *   5. call request() for individual LSP requests
+ *   6. dispose() kills the process and clears pending map
+ */
+import { spawn } from "node:child_process";
+export class HeadlessLspClient {
+    proc = null;
+    pending = new Map();
+    nextId = 1;
+    initialized = false;
+    initPromise = null;
+    buffer = "";
+    openedFiles = new Set();
+    /** True when the client has a live process and completed initialization. */
+    get isReady() {
+        return this.initialized && this.proc !== null;
+    }
+    /** Initialize: spawn process, send initialize + initialized. Idempotent. */
+    async initialize(workspaceRoot) {
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this._doInit(workspaceRoot);
+        return this.initPromise;
+    }
+    async _doInit(workspaceRoot) {
+        let proc;
+        try {
+            proc = spawn("typescript-language-server", ["--stdio"], {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            this.initPromise = null;
+            throw new Error(`typescript-language-server not available: install with npm install -g typescript-language-server typescript. Original: ${String(err)}`);
+        }
+        this.proc = proc;
+        // Accumulate stdout into buffer and dispatch complete messages
+        proc.stdout?.on("data", (chunk) => {
+            this.buffer += chunk.toString("utf-8");
+            this._drain();
+        });
+        proc.on("exit", () => {
+            this.proc = null;
+            this.initialized = false;
+            this.initPromise = null;
+            // Reject all pending requests
+            for (const [, { reject }] of this.pending) {
+                reject(new Error("LSP process exited"));
+            }
+            this.pending.clear();
+        });
+        proc.on("error", (err) => {
+            this.proc = null;
+            this.initialized = false;
+            this.initPromise = null;
+            for (const [, { reject }] of this.pending) {
+                reject(err);
+            }
+            this.pending.clear();
+        });
+        // Send initialize request
+        const rootUri = `file://${workspaceRoot}`;
+        await this.request("initialize", {
+            processId: process.pid,
+            rootUri,
+            capabilities: {
+                textDocument: {
+                    hover: { contentFormat: ["markdown", "plaintext"] },
+                    definition: { linkSupport: false },
+                    references: {},
+                },
+            },
+            initializationOptions: {},
+        }, 15_000);
+        // Send initialized notification (no response expected)
+        this._sendNotification("initialized", {});
+        this.initialized = true;
+    }
+    /** Parse and dispatch complete LSP messages from the buffer. */
+    _drain() {
+        while (true) {
+            const headerEnd = this.buffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                break;
+            const header = this.buffer.slice(0, headerEnd);
+            const match = header.match(/Content-Length:\s*(\d+)/i);
+            if (!match) {
+                // Skip malformed header
+                this.buffer = this.buffer.slice(headerEnd + 4);
+                continue;
+            }
+            const contentLength = Number.parseInt(match[1], 10);
+            const bodyStart = headerEnd + 4;
+            const bodyEnd = bodyStart + contentLength;
+            if (this.buffer.length < bodyEnd)
+                break; // incomplete body — wait for more data
+            const body = this.buffer.slice(bodyStart, bodyEnd);
+            this.buffer = this.buffer.slice(bodyEnd);
+            let msg;
+            try {
+                msg = JSON.parse(body);
+            }
+            catch {
+                continue; // skip unparseable message
+            }
+            if (typeof msg.id === "number") {
+                const pending = this.pending.get(msg.id);
+                if (pending) {
+                    this.pending.delete(msg.id);
+                    pending.resolve(msg);
+                }
+            }
+        }
+    }
+    /** Send a JSON-RPC request and wait for the response. */
+    async request(method, params, timeoutMs = 10_000) {
+        if (!this.proc?.stdin) {
+            throw new Error("LSP process not running");
+        }
+        const id = this.nextId++;
+        const msg = { jsonrpc: "2.0", id, method, params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`LSP request ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (res) => {
+                    clearTimeout(timer);
+                    if (res.error) {
+                        reject(new Error(`LSP error ${res.error.code}: ${res.error.message}`));
+                    }
+                    else {
+                        resolve(res.result);
+                    }
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            const body = JSON.stringify(msg);
+            const header = `Content-Length: ${Buffer.byteLength(body, "utf-8")}\r\n\r\n`;
+            try {
+                this.proc?.stdin?.write(header + body);
+            }
+            catch (err) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                reject(err);
+            }
+        });
+    }
+    /** Send a JSON-RPC notification (no response expected). */
+    _sendNotification(method, params) {
+        if (!this.proc?.stdin)
+            return;
+        const msg = { jsonrpc: "2.0", method, params };
+        const body = JSON.stringify(msg);
+        const header = `Content-Length: ${Buffer.byteLength(body, "utf-8")}\r\n\r\n`;
+        try {
+            this.proc.stdin.write(header + body);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /** Open a file in the LSP server (required before hover/definition/references). */
+    async openFile(uri, languageId, text) {
+        if (this.openedFiles.has(uri))
+            return; // already open
+        this.openedFiles.add(uri);
+        this._sendNotification("textDocument/didOpen", {
+            textDocument: { uri, languageId, version: 1, text },
+        });
+        // Small delay to let the server index the file
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    /** Kill the process and clear all pending requests. */
+    dispose() {
+        for (const [, { reject }] of this.pending) {
+            reject(new Error("LSP client disposed"));
+        }
+        this.pending.clear();
+        this.openedFiles.clear();
+        this.initialized = false;
+        this.initPromise = null;
+        try {
+            this.proc?.kill();
+        }
+        catch {
+            // ignore
+        }
+        this.proc = null;
+    }
+}
+// ---- Singleton management ----
+let _client = null;
+export function getHeadlessLspClient() {
+    if (!_client) {
+        _client = new HeadlessLspClient();
+    }
+    return _client;
+}
+export function disposeHeadlessLspClient() {
+    if (_client) {
+        _client.dispose();
+        _client = null;
+    }
+}
+//# sourceMappingURL=lspClient.js.map

package/dist/tools/headless/lspClient.js.map

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

package/dist/tools/headless/lspFallback.d.ts

@@ -0,0 +1,28 @@
+export interface LspLocation {
+    uri: string;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+}
+/**
+ * textDocument/definition
+ * line and character are 1-based (bridge convention), converted to 0-based for LSP.
+ */
+export declare function lspDefinition(filePath: string, line: number, character: number, workspaceRoot: string): Promise<LspLocation[]>;
+/**
+ * textDocument/references
+ * line and character are 1-based, converted to 0-based for LSP.
+ */
+export declare function lspReferences(filePath: string, line: number, character: number, workspaceRoot: string): Promise<LspLocation[]>;
+/**
+ * textDocument/hover → returns extracted markdown/text string, or null.
+ * line and character are 1-based, converted to 0-based for LSP.
+ */
+export declare function lspHover(filePath: string, line: number, character: number, workspaceRoot: string): Promise<string | null>;