@cjhyy/code-shell-capability-coding 0.8.0

package/dist/lsp/client.js

@@ -0,0 +1,192 @@
+/**
+ * LSP client — JSON-RPC over stdio communication with coding language servers.
+ */
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+export class LSPClient extends EventEmitter {
+    command;
+    args;
+    cwd;
+    process;
+    nextId = 1;
+    pending = new Map();
+    // The LSP framing uses byte-counted Content-Length, so we buffer bytes,
+    // not characters. Joining chunks as strings (`data.toString()` + string
+    // concat) can split a multibyte UTF-8 codepoint across chunks and de-
+    // synchronize against Content-Length. Stay in Buffer-land until we've
+    // sliced out exactly the right body length.
+    buffer = Buffer.alloc(0);
+    contentLength = -1;
+    initialized = false;
+    constructor(command, args = [], cwd) {
+        super();
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+    }
+    async start() {
+        this.process = spawn(this.command, this.args, {
+            cwd: this.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.process.stdout?.on("data", (data) => this.handleData(data));
+        this.process.stderr?.on("data", (_data) => {
+            // LSP servers often log to stderr — ignore
+        });
+        this.process.on("exit", (code) => {
+            this.emit("exit", code);
+            this.rejectAll(new Error(`LSP server exited with code ${code}`));
+        });
+        // Don't keep the event loop alive solely for the LSP child.
+        // Call after listeners are wired so event registration doesn't re-ref.
+        this.process.unref();
+    }
+    async initialize(rootUri) {
+        const result = await this.request("initialize", {
+            processId: process.pid,
+            rootUri,
+            capabilities: {
+                textDocument: {
+                    definition: { dynamicRegistration: false },
+                    references: { dynamicRegistration: false },
+                    hover: { contentFormat: ["plaintext", "markdown"] },
+                    documentSymbol: { dynamicRegistration: false },
+                    completion: { dynamicRegistration: false },
+                },
+                workspace: {
+                    symbol: { dynamicRegistration: false },
+                },
+            },
+        });
+        await this.notify("initialized", {});
+        this.initialized = true;
+        return result;
+    }
+    async request(method, params) {
+        if (!this.process?.stdin)
+            throw new Error("LSP server not started");
+        const id = this.nextId++;
+        const message = { jsonrpc: "2.0", id, method, params };
+        const content = JSON.stringify(message);
+        const header = `Content-Length: ${Buffer.byteLength(content)}\r\n\r\n`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`LSP request "${method}" timed out`));
+                }
+            }, 30000);
+            // Don't let the timer keep the event loop alive by itself
+            timer.unref?.();
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            this.process.stdin.write(header + content);
+        });
+    }
+    async notify(method, params) {
+        if (!this.process?.stdin)
+            throw new Error("LSP server not started");
+        const message = { jsonrpc: "2.0", method, params };
+        const content = JSON.stringify(message);
+        const header = `Content-Length: ${Buffer.byteLength(content)}\r\n\r\n`;
+        this.process.stdin.write(header + content);
+    }
+    async shutdown() {
+        if (!this.process)
+            return;
+        try {
+            await this.request("shutdown", {});
+            await this.notify("exit", {});
+        }
+        catch {
+            // Force kill
+        }
+        this.process.stdout?.removeAllListeners();
+        this.process.stderr?.removeAllListeners();
+        this.process.removeAllListeners();
+        this.process.kill();
+        this.process = undefined;
+        // Drain pending requests
+        for (const { reject } of this.pending.values()) {
+            reject(new Error("LSP server shut down"));
+        }
+        this.pending.clear();
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    get isAlive() {
+        return this.process !== undefined && !this.process.killed;
+    }
+    handleData(data) {
+        // Append the new chunk as bytes. Buffer.concat avoids the UTF-8
+        // boundary corruption that string concatenation produces — a
+        // multibyte codepoint split across two TCP/pipe chunks decodes to
+        // U+FFFD, mangles the buffer length count, and breaks framing.
+        this.buffer = Buffer.concat([this.buffer, data]);
+        while (true) {
+            if (this.contentLength < 0) {
+                // Search for the header terminator in bytes, not chars.
+                const headerEnd = this.buffer.indexOf("\r\n\r\n");
+                if (headerEnd < 0)
+                    break;
+                // Headers are ASCII per spec, so toString("ascii") is safe and
+                // avoids paying for a UTF-8 decode on the framing band.
+                const header = this.buffer.slice(0, headerEnd).toString("ascii");
+                const match = header.match(/Content-Length:\s*(\d+)/i);
+                if (!match) {
+                    this.buffer = this.buffer.subarray(headerEnd + 4);
+                    continue;
+                }
+                this.contentLength = parseInt(match[1], 10);
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+            }
+            // Content-Length is a BYTE count — compare against the buffer's
+            // byte length, not its character length. Pre-fix this compared
+            // string lengths; with multibyte responses (e.g. CJK identifiers,
+            // emoji in diagnostics) we'd block waiting for bytes that had
+            // already arrived.
+            if (this.buffer.length < this.contentLength)
+                break;
+            const bodyBytes = this.buffer.subarray(0, this.contentLength);
+            this.buffer = this.buffer.subarray(this.contentLength);
+            this.contentLength = -1;
+            // Decode the full body in one shot — at this point we have the
+            // exact byte count, so the UTF-8 boundary issue is fully gone.
+            const content = bodyBytes.toString("utf8");
+            try {
+                const message = JSON.parse(content);
+                if ("id" in message && this.pending.has(message.id)) {
+                    const { resolve, reject } = this.pending.get(message.id);
+                    this.pending.delete(message.id);
+                    if (message.error) {
+                        reject(new Error(`LSP error: ${message.error.message}`));
+                    }
+                    else {
+                        resolve(message.result);
+                    }
+                }
+                else if ("method" in message && !("id" in message)) {
+                    this.emit("notification", message);
+                }
+            }
+            catch {
+                // Skip malformed messages
+            }
+        }
+    }
+    rejectAll(error) {
+        for (const { reject } of this.pending.values()) {
+            reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/dist/lsp/manager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LSP Server Manager — manages lifecycle of language server instances.
+ * Lazy initialization: servers start only when needed.
+ */
+import { LSPClient } from "./client.js";
+type ServerState = "stopped" | "starting" | "ready" | "error";
+export declare class LSPServerManager {
+    private servers;
+    private rootUri;
+    constructor(cwd: string);
+    /**
+     * Get or start a language server by name.
+     */
+    getClient(serverName: string): Promise<LSPClient | undefined>;
+    /**
+     * Start a specific language server.
+     */
+    private startServer;
+    /**
+     * Check if any LSP server is connected.
+     */
+    isConnected(): boolean;
+    /**
+     * List server statuses.
+     */
+    listServers(): Array<{
+        name: string;
+        language: string;
+        state: ServerState;
+        error?: string;
+    }>;
+    /**
+     * Shutdown all servers.
+     */
+    shutdownAll(): Promise<void>;
+}
+export declare function isCommandAvailable(command: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function initializeLSPManager(cwd: string): LSPServerManager;
+/**
+ * Manager for `cwd`, creating it on first use.
+ *
+ * Lazy by design: spawning language servers eagerly at startup would cost every
+ * session a process it may never use. Callers that only want to observe existing
+ * state pass `{ create: false }`.
+ */
+export declare function getLSPManager(cwd?: string, options?: {
+    create?: boolean;
+}): LSPServerManager | undefined;
+/** Shut down and forget one workspace's servers (session/workspace teardown). */
+export declare function shutdownLSPManager(cwd: string): Promise<void>;
+/** Shut down every workspace's servers (process teardown). */
+export declare function shutdownAllLSPManagers(): Promise<void>;
+export {};

package/dist/lsp/manager.js

@@ -0,0 +1,248 @@
+/**
+ * LSP Server Manager — manages lifecycle of language server instances.
+ * Lazy initialization: servers start only when needed.
+ */
+import { LSPClient } from "./client.js";
+import { BUILTIN_LSP_SERVERS } from "./servers.js";
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, extname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { rootUriToPath } from "./root-path.js";
+export class LSPServerManager {
+    servers = new Map();
+    rootUri;
+    constructor(cwd) {
+        this.rootUri = pathToFileURL(cwd).href;
+        // Register all built-in servers
+        for (const config of BUILTIN_LSP_SERVERS) {
+            this.servers.set(config.name, { config, client: undefined, state: "stopped" });
+        }
+    }
+    /**
+     * Get or start a language server by name.
+     */
+    async getClient(serverName) {
+        const managed = this.servers.get(serverName);
+        if (!managed)
+            return undefined;
+        if (managed.state === "ready" && managed.client?.isAlive) {
+            return managed.client;
+        }
+        if (managed.state === "starting") {
+            // Wait for it to be ready
+            await new Promise((r) => setTimeout(r, 2000));
+            return managed.client;
+        }
+        // Try to start
+        return this.startServer(serverName);
+    }
+    /**
+     * Start a specific language server.
+     */
+    async startServer(name) {
+        const managed = this.servers.get(name);
+        if (!managed)
+            return undefined;
+        // Check if command is available
+        if (!isCommandAvailable(managed.config.command)) {
+            managed.state = "error";
+            managed.error = `${managed.config.command} not found. Install: ${managed.config.installHint}`;
+            return undefined;
+        }
+        managed.state = "starting";
+        try {
+            const client = new LSPClient(managed.config.command, managed.config.args, rootUriToPath(this.rootUri));
+            await client.start();
+            await client.initialize(this.rootUri);
+            managed.client = client;
+            managed.state = "ready";
+            return client;
+        }
+        catch (err) {
+            managed.state = "error";
+            managed.error = err.message;
+            return undefined;
+        }
+    }
+    /**
+     * Check if any LSP server is connected.
+     */
+    isConnected() {
+        for (const server of this.servers.values()) {
+            if (server.state === "ready" && server.client?.isAlive)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * List server statuses.
+     */
+    listServers() {
+        return [...this.servers.values()].map((s) => ({
+            name: s.config.name,
+            language: s.config.language,
+            state: s.state,
+            error: s.error,
+        }));
+    }
+    /**
+     * Shutdown all servers.
+     */
+    async shutdownAll() {
+        for (const server of this.servers.values()) {
+            if (server.client?.isAlive) {
+                try {
+                    await server.client.shutdown();
+                }
+                catch {
+                    // Force killed
+                }
+            }
+            server.state = "stopped";
+            server.client = undefined;
+        }
+    }
+}
+export function isCommandAvailable(command, env = process.env) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return false;
+    const hasPathSeparator = trimmed.includes("/") || trimmed.includes("\\");
+    // A bare command with whitespace is not executable via spawn(command, args)
+    // anyway. Reject it up front so a configured command can never be interpreted
+    // as shell syntax such as `pylsp; touch /tmp/pwned`.
+    if (!hasPathSeparator && /\s/.test(trimmed))
+        return false;
+    if (hasPathSeparator) {
+        return candidateCommandNames(trimmed, env).some(isExecutableFile);
+    }
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of candidateCommandNames(trimmed, env)) {
+            if (isExecutableFile(join(dir, name)))
+                return true;
+        }
+    }
+    return false;
+}
+function candidateCommandNames(command, env) {
+    if (process.platform !== "win32" || extname(command))
+        return [command];
+    const pathext = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD")
+        .split(";")
+        .map((extension) => extension.trim())
+        .filter(Boolean);
+    return [command, ...pathext.map((extension) => `${command}${extension}`)];
+}
+function isExecutableFile(filePath) {
+    try {
+        const st = statSync(filePath);
+        if (!st.isFile())
+            return false;
+        if (process.platform !== "win32") {
+            accessSync(filePath, constants.X_OK);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One manager per workspace root.
+ *
+ * This used to be a single process-wide singleton that only existed if some host
+ * called `initializeLSPManager()` — and NO host ever did. The `LSP` tool was
+ * registered and advertised to the agent, but its first act is
+ * `getLSPManager()`, so every invocation returned "LSP is not initialized".
+ * The capability was dead on arrival in every product surface.
+ *
+ * Keying by root also fixes the design problem behind the singleton: an agent
+ * can work across several workspaces in one process (worktrees, sub-agents), and
+ * a language server is rooted at exactly one directory.
+ */
+const managers = new Map();
+/**
+ * Use order, as a monotonic counter rather than a clock.
+ *
+ * `Date.now()` has millisecond resolution, so several workspaces touched in the
+ * same tick would tie and the LRU sort would pick an arbitrary victim — possibly
+ * the one being actively used.
+ */
+const useOrder = new Map();
+let useTick = 0;
+/**
+ * Most workspaces to keep language servers alive for at once.
+ *
+ * Per-workspace managers removed the single-cwd bug, but replaced it with a map
+ * that only ever grows: a long-lived Desktop session that touches many
+ * worktrees would accumulate a language server per root. Evicting the
+ * least-recently-used keeps the process bounded — an evicted workspace simply
+ * pays a cold start the next time it is used.
+ */
+const MAX_LIVE_WORKSPACES = 4;
+export function initializeLSPManager(cwd) {
+    useOrder.set(cwd, ++useTick);
+    const existing = managers.get(cwd);
+    if (existing)
+        return existing;
+    const created = new LSPServerManager(cwd);
+    managers.set(cwd, created);
+    evictLeastRecentlyUsed();
+    return created;
+}
+/** Shut down the oldest workspaces once the live set exceeds its cap. */
+function evictLeastRecentlyUsed() {
+    if (managers.size <= MAX_LIVE_WORKSPACES)
+        return;
+    const ordered = [...managers.keys()].sort((left, right) => (useOrder.get(left) ?? 0) - (useOrder.get(right) ?? 0));
+    for (const cwd of ordered.slice(0, managers.size - MAX_LIVE_WORKSPACES)) {
+        const manager = managers.get(cwd);
+        managers.delete(cwd);
+        useOrder.delete(cwd);
+        // Fire-and-forget: eviction must not make the caller wait on a shutdown
+        // handshake with a server it is no longer using.
+        void manager?.shutdownAll().catch(() => undefined);
+    }
+}
+/**
+ * Manager for `cwd`, creating it on first use.
+ *
+ * Lazy by design: spawning language servers eagerly at startup would cost every
+ * session a process it may never use. Callers that only want to observe existing
+ * state pass `{ create: false }`.
+ */
+export function getLSPManager(cwd, options = {}) {
+    if (cwd === undefined) {
+        // Back-compat for callers with no workspace context: return the sole manager
+        // when exactly one exists, otherwise nothing (ambiguous).
+        return managers.size === 1 ? [...managers.values()][0] : undefined;
+    }
+    const existing = managers.get(cwd);
+    if (existing) {
+        // Refresh recency on READ too — a workspace being actively used must not be
+        // the LRU victim just because it was created long ago.
+        useOrder.set(cwd, ++useTick);
+        return existing;
+    }
+    if (options.create === false)
+        return undefined;
+    return initializeLSPManager(cwd);
+}
+/** Shut down and forget one workspace's servers (session/workspace teardown). */
+export async function shutdownLSPManager(cwd) {
+    const manager = managers.get(cwd);
+    if (!manager)
+        return;
+    managers.delete(cwd);
+    useOrder.delete(cwd);
+    await manager.shutdownAll();
+}
+/** Shut down every workspace's servers (process teardown). */
+export async function shutdownAllLSPManagers() {
+    const all = [...managers.values()];
+    managers.clear();
+    useOrder.clear();
+    await Promise.all(all.map((manager) => manager.shutdownAll()));
+}

package/dist/lsp/root-path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Convert an LSP `file://` root URI to a platform filesystem path.
+ *
+ * The LSP manager used `rootUri.replace("file://", "")`, which only strips the
+ * first occurrence and leaves percent-encoding intact, and on Windows turns
+ * `file:///C:/x` into the invalid `/C:/x`. fileURLToPath does the proper
+ * platform conversion (drive letters, percent-decoding, UNC).
+ */
+export declare function rootUriToPath(rootUri: string): string;

package/dist/lsp/root-path.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Convert an LSP `file://` root URI to a platform filesystem path.
+ *
+ * The LSP manager used `rootUri.replace("file://", "")`, which only strips the
+ * first occurrence and leaves percent-encoding intact, and on Windows turns
+ * `file:///C:/x` into the invalid `/C:/x`. fileURLToPath does the proper
+ * platform conversion (drive letters, percent-decoding, UNC).
+ */
+export function rootUriToPath(rootUri) {
+    return fileURLToPath(rootUri);
+}

package/dist/lsp/servers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Coding capability language server configurations.
+ */
+export interface LSPServerConfig {
+    name: string;
+    language: string;
+    extensions: string[];
+    command: string;
+    args: string[];
+    installHint: string;
+}
+export declare const BUILTIN_LSP_SERVERS: LSPServerConfig[];
+/**
+ * Detect which LSP server to use based on file extension.
+ */
+export declare function detectLSPServer(filePath: string): LSPServerConfig | undefined;

package/dist/lsp/servers.js

@@ -0,0 +1,60 @@
+/**
+ * Coding capability language server configurations.
+ */
+export const BUILTIN_LSP_SERVERS = [
+    {
+        name: "typescript",
+        language: "typescript",
+        extensions: [".ts", ".tsx", ".js", ".jsx"],
+        command: "typescript-language-server",
+        args: ["--stdio"],
+        installHint: "npm install -g typescript-language-server typescript",
+    },
+    {
+        name: "python",
+        language: "python",
+        extensions: [".py"],
+        command: "pylsp",
+        args: [],
+        installHint: "pip install python-lsp-server",
+    },
+    {
+        name: "go",
+        language: "go",
+        extensions: [".go"],
+        command: "gopls",
+        args: ["serve"],
+        installHint: "go install golang.org/x/tools/gopls@latest",
+    },
+    {
+        name: "rust",
+        language: "rust",
+        extensions: [".rs"],
+        command: "rust-analyzer",
+        args: [],
+        installHint: "rustup component add rust-analyzer",
+    },
+    {
+        name: "json",
+        language: "json",
+        extensions: [".json"],
+        command: "vscode-json-languageserver",
+        args: ["--stdio"],
+        installHint: "npm install -g vscode-langservers-extracted",
+    },
+    {
+        name: "css",
+        language: "css",
+        extensions: [".css", ".scss", ".less"],
+        command: "vscode-css-languageserver",
+        args: ["--stdio"],
+        installHint: "npm install -g vscode-langservers-extracted",
+    },
+];
+/**
+ * Detect which LSP server to use based on file extension.
+ */
+export function detectLSPServer(filePath) {
+    const ext = filePath.slice(filePath.lastIndexOf("."));
+    return BUILTIN_LSP_SERVERS.find((s) => s.extensions.includes(ext));
+}

package/dist/prompt/coding.md

@@ -0,0 +1,42 @@
+# Coding assistant capability
+
+The default job in this preset is software engineering in the current working directory.
+
+## Reading before writing
+
+- Do not propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first. Understand existing code before suggesting modifications.
+- Read code before editing it, prefer modifying existing files, and avoid unrelated refactors.
+
+## Investigation has a budget — looking is not acting
+
+- Read, search, and investigate freely, but treat read-only exploration as a means to action, not an end in itself. After about 3 read-only tool calls (Read/Grep/Glob) on the same question, you should either (a) make a change, (b) run a command with side effects (Bash, debug log, repro), or (c) ask the user a specific question. Continuing to read more files usually means your current strategy isn't working — change strategy instead.
+- Never re-read a file (or the same line range of a file) you've already read in this conversation. The content is already in your context. If you've re-derived the same conclusion twice from the same code, the answer isn't in static reading — switch to runtime verification.
+- For bug reports where static analysis hasn't pinpointed the cause in 2-3 reads, the right next step is almost always to add a debug log line and ask the user to reproduce, or to inspect runtime state — not to read more files.
+- Don't narrate the same code path twice in your reasoning. If you've already traced "input X → parser Y → handler Z" once and concluded "this looks correct", stop. Do not re-trace it from a different angle hoping for a different answer. Trust your first analysis and move to verification.
+- These rules are enforced at runtime by an investigation guard. A second read of the same target prepends a `<system-reminder>` to that tool's result; a third read of the same target is hard-blocked with an error. Four or more consecutive read-only calls without a side-effecting action also surface a reminder, and several consecutive turns of read-only work with no text update to the user surface another. When you see one of these reminders, treat it as a signal that your current strategy isn't producing new information — switch to a side-effecting verification (Bash, debug log, repro, edit) or ask the user a specific question rather than reading more.
+
+## Code quality discipline
+
+- Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
+- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.
+- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is what the task actually requires — no speculative abstractions, but no half-finished implementations either. Three similar lines of code is better than a premature abstraction.
+- Avoid backwards-compatibility hacks like renaming unused \_vars, re-exporting types, adding // removed comments for removed code, etc. If you are certain that something is unused, you can delete it completely.
+
+## Security
+
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it. Prioritize writing safe, secure, and correct code.
+
+## Git
+
+- When referencing specific functions or pieces of code include the pattern file_path:line_number to allow the user to easily navigate to the source code location.
+- When referencing GitHub issues or pull requests, use the owner/repo#123 format so they render as clickable links.
+
+## Opening URLs and local previews
+
+- To show the user a web page or a local dev-server preview, print the address in your reply as a bare URL or a markdown link (e.g. `http://localhost:5173` or [预览](http://localhost:5173)) — do NOT wrap it in backticks. The desktop app turns a link in your answer into a clickable link that opens inside its built-in browser panel; backtick-wrapped URLs render as plain code and are not clickable.
+- Do NOT run shell commands to open a URL (`open <url>` on macOS, `xdg-open` on Linux, `start <url>` on Windows). Those launch the user's external system browser and bypass the in-app browser panel. Start the dev server, then just tell the user the address as a link.
+
+## Coding tools
+
+- Use git/worktree/LSP/notebook tools when they help, but treat them as optional helpers rather than core assumptions.
+- If the user asks for help or feedback, point them to /help and the project repository.

package/dist/quota/credentials.d.ts

@@ -0,0 +1,3 @@
+import type { QuotaCredentials } from "./types.js";
+/** Resolve all tokens from their standard local locations. Never throws. */
+export declare function resolveQuotaCredentials(): Promise<QuotaCredentials>;