codemode-lsp 0.1.2 → 0.1.3

package/README.md

@@ -72,7 +72,10 @@ The API surface is 16 functions plus `getDiagnostics`: 8 read ops (`readFile`,
 `deleteSymbol`, `writeFile`, `deleteFile`). Symbols are addressed by
 slash-separated paths (`MyClass/myMethod`) discovered via `getSymbols`. The
 full type definitions are embedded in the tool description, generated straight
-from the source (`bun run generate:types`).
+from the source (`bun run generate:types`). If a client truncates the
+description, the script `await lsp.help()` returns the complete reference —
+the description's first lines advertise this, so an agent can always recover
+the full API without probing.
 
 See `PRD.md` for the complete spec.
 

package/dist/index.js

@@ -46274,6 +46274,8 @@ async function runSandbox(code, options) {
   };
   const opNames = options.readonly ? [...READ_OP_NAMES] : [...READ_OP_NAMES, ...WRITE_OP_NAMES];
   sandbox.lsp = buildTracedLsp(options.lsp, trace, makeSandboxError, wrapAsync, opNames);
+  const helpText = options.helpText ?? "No extended help is available; the tool description is the full reference.";
+  sandbox.lsp.help = wrapAsync(async () => helpText);
   const { source, uncapturedLastStatement } = normalizeCode(code);
   const wrapped = `(async () => {
 ${source}
@@ -46416,11 +46418,11 @@ var LSP_READ_OP_SIGNATURES = `  /** File contents as a raw string (no line numbe
   getSymbolBody(file: string, symbolPath: string): Promise<string>;
   /** Document symbol tree (file outline). Every path is a usable handle. */
   getSymbols(file: string): Promise<SymbolInfo[]>;
-  /** Workspace-wide symbol search; the index warms lazily, so early calls may be empty — getSymbols(file) is exhaustive. */
+  /** Workspace-wide symbol search; matches substrings, so filter for exact \`name\`. The index warms lazily — early calls may be empty; getSymbols(file) is exhaustive. */
   findSymbol(query: string): Promise<WorkspaceSymbolInfo[]>;
   /** All references to a symbol across the workspace (incl. the declaration). */
   findReferences(file: string, symbolPath: string): Promise<Reference[]>;
-  /** Jump to a symbol's definition. */
+  /** Jump to the definition of a symbol DEFINED in \`file\` — imports/callees in a body are not addressable; resolve those names with findSymbol. */
   goToDefinition(file: string, symbolPath: string): Promise<Location>;
   /** Regex search across project files — escape metacharacters for literal text; optional second arg is a glob string. */
   searchText(pattern: string, glob?: string): Promise<SearchResult[]>;
@@ -46490,10 +46492,16 @@ function renderLspTypes(readonly3) {
   const interfaces = readonly3 ? LSP_COMMON_INTERFACES : `${LSP_COMMON_INTERFACES}
 
 ${LSP_WRITE_INTERFACES}`;
-  const ops = readonly3 ? LSP_READ_OP_SIGNATURES : `${LSP_READ_OP_SIGNATURES}
+  const helpOp = `  /** This full API reference as a string — call it if this description was truncated. */
+  help(): Promise<string>;`;
+  const ops = readonly3 ? `${LSP_READ_OP_SIGNATURES}
+
+${helpOp}` : `${LSP_READ_OP_SIGNATURES}
 
   // Write operations — buffered, applied atomically when the script succeeds.
-${LSP_WRITE_OP_SIGNATURES}`;
+${LSP_WRITE_OP_SIGNATURES}
+
+${helpOp}`;
   return `declare const lsp: {
 ${ops}
 };
@@ -46501,6 +46509,8 @@ ${ops}
 ${interfaces}`;
 }
 var TEMPLATE = `Execute JavaScript to perform semantic code operations via LSP (TypeScript).
+If this description looks truncated, run the script \`await lsp.help()\` — it
+returns this complete reference. Ops — {{opInventory}}.
 
 Write one script that chains lsp.* calls — filter, loop, and branch in code
 instead of across many tool calls. The sandbox provides \`lsp\`,
@@ -46530,6 +46540,10 @@ script's last expression, JSON-serialized.
   the write ops.
 - \`searchText\` patterns are regexes — escape metacharacters for literal text:
   \`searchText("new NotFoundError\\\\(")\`.
+- \`goToDefinition\` only addresses symbols DEFINED in the given file — it cannot
+  follow an imported or called name into another module. To resolve a name to
+  its definition anywhere in the workspace, use \`findSymbol(name)\` and filter
+  for an exact \`name\` match (it also returns substring matches).
 - File paths are relative to the workspace root; anything outside it is
   rejected.
 - Diagnostics cover files touched this session only, never the whole project.
@@ -46558,7 +46572,8 @@ ${example.code}
 \`\`\``).join(`
 
 `);
-  return TEMPLATE.replace("{{types}}", renderLspTypes(readonly3)).replace("{{writeSemantics}}", readonly3 ? READONLY_SEMANTICS : WRITE_SEMANTICS).replace("{{examples}}", examples);
+  const opInventory = readonly3 ? `read: ${READ_OP_NAMES.join(", ")}` : `read: ${READ_OP_NAMES.join(", ")}; write: ${WRITE_OP_NAMES.join(", ")}`;
+  return TEMPLATE.replace("{{opInventory}}", opInventory).replace("{{types}}", renderLspTypes(readonly3)).replace("{{writeSemantics}}", readonly3 ? READONLY_SEMANTICS : WRITE_SEMANTICS).replace("{{examples}}", examples);
 }
 
 // src/mcp-server.ts
@@ -46595,7 +46610,8 @@ function createExecuteRunner(deps) {
         const { result, logs } = await runSandbox(code, {
           lsp: deps.api,
           timeoutMs: deps.timeoutMs,
-          readonly: deps.readonly
+          readonly: deps.readonly,
+          helpText: deps.helpText ?? buildToolDescription(deps.readonly ?? false)
         });
         const flushed = buffer.flush();
         const changes = flushed.map((change) => ({
@@ -46659,20 +46675,22 @@ function createServer(options = {}) {
   warmup.catch(() => {
     return;
   });
+  const description = buildToolDescription(readonly3);
   const { execute } = createExecuteRunner({
     api: api2,
     client,
     timeoutMs,
     warmup,
     rootDir,
-    readonly: readonly3
+    readonly: readonly3,
+    helpText: description
   });
   const server = new McpServer({
     name: "codemode-lsp",
     version: "0.1.0"
   });
   server.registerTool("execute", {
-    description: buildToolDescription(readonly3),
+    description,
     inputSchema: {
       code: exports_external.string().describe("JavaScript to run in the LSP sandbox. The last expression is the return value.")
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemode-lsp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server exposing a single code-mode tool backed by LSP",
   "keywords": [
     "mcp",