codemode-lsp 0.1.1 → 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

@@ -46102,6 +46102,25 @@ function buildTracedLsp(api2, trace, makeSandboxError, wrapAsync, opNames) {
   return traced;
 }
 var hostPath = { join: join2, basename, dirname: dirname4, extname };
+var UNCAPTURED_STATEMENT_NAMES = {
+  IfStatement: "an if statement",
+  ForStatement: "a for loop",
+  ForOfStatement: "a for...of loop",
+  ForInStatement: "a for...in loop",
+  WhileStatement: "a while loop",
+  DoWhileStatement: "a do...while loop",
+  TryStatement: "a try/catch block",
+  SwitchStatement: "a switch statement",
+  BlockStatement: "a block",
+  VariableDeclaration: "a variable declaration",
+  FunctionDeclaration: "a function declaration",
+  ClassDeclaration: "a class declaration"
+};
+function describeUncapturedStatement(type) {
+  if (type === "ReturnStatement")
+    return;
+  return UNCAPTURED_STATEMENT_NAMES[type] ?? `a ${type}`;
+}
 function isExpressionStatement(node) {
   return node.type === "ExpressionStatement";
 }
@@ -46137,8 +46156,14 @@ function normalizeCode(code) {
     return { source: `${head}
 return (${expr});` };
   }
-  return { source: `${trimmed}
-return undefined;` };
+  return {
+    source: `${trimmed}
+return undefined;`,
+    ...last ? (() => {
+      const described = describeUncapturedStatement(last.type);
+      return described ? { uncapturedLastStatement: described } : {};
+    })() : {}
+  };
 }
 function capText(text, cap, marker) {
   if (text.length <= cap)
@@ -46249,7 +46274,9 @@ 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 { source } = normalizeCode(code);
+  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}
 })()`;
@@ -46290,7 +46317,7 @@ ${source}
   }
   let result;
   try {
-    result = serializeResult(value);
+    result = value === undefined && uncapturedLastStatement ? `undefined — note: the script's last statement is ${uncapturedLastStatement}, ` + "which produces no capturable value. Only a top-level trailing " + "expression becomes the result — end the script with a bare " + "expression (e.g. `({ count })`), or use a top-level `return`." : serializeResult(value);
   } catch (error51) {
     throw new SandboxError({
       error: error51 instanceof Error ? error51.message : String(error51),
@@ -46391,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[]>;
@@ -46465,17 +46492,25 @@ 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}`;
-  return `${interfaces}
+${LSP_WRITE_OP_SIGNATURES}
 
-declare const lsp: {
+${helpOp}`;
+  return `declare const lsp: {
 ${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\`,
@@ -46484,36 +46519,45 @@ instead of across many tool calls. The sandbox provides \`lsp\`,
 setTimeout). The tool returns { result, logs, changes }, where \`result\` is the
 script's last expression, JSON-serialized.
 
-## API
-
-{{types}}
-
-{{writeSemantics}}
-
-## Examples
-
-{{examples}}
-
 ## Rules
 
-- The last expression is the return value — end the script with the value you
-  want back, e.g. \`({ count })\`.
+- The last TOP-LEVEL expression is the return value — end the script with a
+  bare expression, e.g. \`({ count })\`. An expression inside a trailing
+  if/for/try block is NOT captured; use a top-level \`return\` from inside
+  blocks.
 - Every \`lsp.*\` call returns a Promise — always \`await\` it. An un-awaited
   call inside the result serializes as \`{}\`.
 - \`.filter()\`/\`.map()\` callbacks cannot be async — use \`for...of\` with \`await\`.
-- Globs match the whole workspace-relative path: \`listFiles("src/**")\` for a
-  directory (a bare directory name like \`"src"\` is treated as \`src/**\`),
-  \`listFiles()\` for every file. \`searchText\`'s second argument is a glob
-  string — there is no options object; filter results in your script.
+- \`searchText\`/\`listFiles\` cover the whole workspace (minus .gitignore);
+  scope with a glob, which matches the full workspace-relative path:
+  \`listFiles("src/**")\` for a directory (a bare name like \`"src"\` is treated
+  as \`src/**\`), \`listFiles()\` for every file. \`searchText\`'s second argument
+  is a glob string — there is no options object; filter results in your script.
 - Symbol paths are slash-separated (\`MyClass/myMethod\`); discover exact paths
   with \`getSymbols(file)\` rather than guessing. Symbol ops always take the
   pair \`(file, symbolPath)\` — a \`SymbolInfo.path\` belongs to the file you
-  called \`getSymbols\` on.
+  called \`getSymbols\` on, and round-trips into findReferences/goToDefinition/
+  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.`;
+- Diagnostics cover files touched this session only, never the whole project.
+  \`Diagnostic.range\` is zero-based; every other line/column is 1-based.
+
+## API
+
+{{types}}
+
+{{writeSemantics}}
+
+## Examples
+
+{{examples}}`;
 var WRITE_SEMANTICS = `Write operations available: writes are buffered during the script and applied
 atomically (flushed to disk) only when the whole script succeeds; if it throws,
 every buffered write is rolled back and the codebase is unchanged. The tool
@@ -46528,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
@@ -46565,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) => ({
@@ -46629,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.1",
+  "version": "0.1.3",
   "description": "MCP server exposing a single code-mode tool backed by LSP",
   "keywords": [
     "mcp",