@morphllm/gitmorph-sdk 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,429 @@
+# @morphllm/gitmorph-sdk
+
+Agent-native TypeScript SDK for reading, searching, and navigating Git repositories through [GitMorph](https://gitmorph.com). No cloning. Every operation is a single HTTP call against a server-side mirror.
+
+Built for AI coding agents that need to understand codebases: read files with line ranges, grep across repos, glob for file patterns, list directories, walk commits. All server-side, all fast.
+
+```bash
+npm install @morphllm/gitmorph-sdk
+```
+
+## Quick start
+
+```ts
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+
+const gm = new GitMorph();
+const repo = gm.repo("facebook/react");
+
+// Read a file
+const file = await repo.readFile("package.json");
+
+// Grep for a pattern
+const results = await repo.grep({ pattern: "useState" });
+
+// Glob for files
+const tsFiles = await repo.glob({ patterns: ["**/*.ts"] });
+```
+
+## Give your agent access to any repo
+
+Paste this into Claude Code (or any agent with tool-use) to give it read access to any mirrored repository:
+
+````
+You have access to the @morphllm/gitmorph-sdk for reading Git repositories without cloning.
+The SDK is already installed and authenticated via ~/.config/gm/config.json.
+
+To use it, write a quick TypeScript script and run it with `npx tsx`:
+
+```ts
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+const gm = new GitMorph();
+const repo = gm.repo("owner/repo");
+```
+
+Available methods on `repo`:
+- `repo.readFile(path, { ref?, lines?: [{ start, end }] })` - read a file, optionally specific line ranges (1-indexed, inclusive)
+- `repo.getFileContents(paths[], { ref? })` - batch read multiple files in one call
+- `repo.grep({ pattern, language?, caseSensitive?, maxMatches?, page? })` - server-side code search within the repo
+- `repo.glob({ patterns[], ref?, prefix?, sizes?, limit? })` - find files matching glob patterns (e.g. `["**/*.ts", "!**/*.test.ts"]`)
+- `repo.listDir({ path?, ref?, recursive? })` - list directory contents
+- `repo.listBranches({ page?, limit? })` - list branches
+- `repo.listCommits({ sha?, path?, since?, until?, page?, limit? })` - list commits
+
+Available methods on `gm` (instance-wide):
+- `gm.grepAll({ pattern, language?, page?, limit?, sortByStars? })` - search code across ALL repos
+- `gm.mirror(source, options?)` - mirror a GitHub/GitLab/Gitea repo (e.g. `gm.mirror("facebook/react")`)
+- `gm.getRepositoryInfo("owner/repo")` - get repo metadata
+
+Use these to explore, search, and read code. Prefer grep and glob over listing directories manually.
+````
+
+## Drop-in LLM tools
+
+The SDK ships framework-native tool adapters under subpath exports. Import, pass to your agent, go. No hand-written schemas, no dispatcher wiring.
+
+Every adapter exposes the same factories:
+
+- `createGitmorphTools(gm, opts?)` — multi-repo; every tool takes `repo: "owner/name"`.
+- `createGitmorphRepoTools(gm, "owner/name", opts?)` — pinned to one repo; tools drop the `repo` arg.
+
+Each adapter is an optional peer dependency — you only install what you use.
+
+### Vercel AI SDK
+
+```bash
+npm install ai zod
+```
+
+```ts
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+import { createGitmorphRepoTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { generateText } from "ai";
+
+const gm = new GitMorph();
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-6"),
+  system: GITMORPH_SYSTEM_PROMPT,
+  tools: createGitmorphRepoTools(gm, "facebook/react"),
+  prompt: "What testing framework does this repo use? Read package.json to confirm.",
+  maxSteps: 5,
+});
+```
+
+Pass `only` as a `const` tuple to narrow the return type — autocomplete shows exactly the tools you asked for:
+
+```ts
+const tools = createGitmorphTools(gm, { only: ["gm_grep", "gm_read_file"] as const });
+// tools has exactly { gm_grep: Tool; gm_read_file: Tool }
+```
+
+### Anthropic SDK
+
+```bash
+npm install @anthropic-ai/sdk zod zod-to-json-schema
+```
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/anthropic";
+
+const anthropic = new Anthropic();
+const gm = new GitMorph();
+const { tools, handleToolUse } = createGitmorphTools(gm, { cacheControl: true });
+
+const messages: Anthropic.Messages.MessageParam[] = [
+  { role: "user", content: "Find every useEffect in facebook/react" },
+];
+
+let msg = await anthropic.messages.create({
+  model: "claude-sonnet-4-6",
+  max_tokens: 4096,
+  system: GITMORPH_SYSTEM_PROMPT,
+  tools,
+  messages,
+});
+
+while (msg.stop_reason === "tool_use") {
+  const uses = msg.content.filter((b): b is Anthropic.Messages.ToolUseBlock => b.type === "tool_use");
+  const results = await Promise.all(uses.map(handleToolUse));
+  messages.push({ role: "assistant", content: msg.content });
+  messages.push({ role: "user", content: results });
+  msg = await anthropic.messages.create({
+    model: "claude-sonnet-4-6",
+    max_tokens: 4096,
+    system: GITMORPH_SYSTEM_PROMPT,
+    tools,
+    messages,
+  });
+}
+```
+
+`handleToolUse` never throws. Errors become `tool_result` blocks with `is_error: true` so the model can recover in the next turn. `cacheControl: true` attaches Anthropic prompt caching to the tool list — stable tool sets become a cached prefix of every request.
+
+### OpenAI SDK
+
+```bash
+npm install openai zod zod-to-json-schema
+```
+
+```ts
+import OpenAI from "openai";
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/openai";
+
+const openai = new OpenAI();
+const gm = new GitMorph();
+const { tools, handleToolCall } = createGitmorphTools(gm);
+
+const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+  { role: "system", content: GITMORPH_SYSTEM_PROMPT },
+  { role: "user", content: "Find every useEffect in facebook/react" },
+];
+
+for (let step = 0; step < 10; step++) {
+  const res = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
+  const msg = res.choices[0]!.message;
+  messages.push(msg);
+  if (!msg.tool_calls?.length) break;
+  const results = await Promise.all(msg.tool_calls.map(handleToolCall));
+  messages.push(...results);
+}
+```
+
+### MCP (Claude Desktop / Cursor / Claude Code)
+
+Zero-code path. Add GitMorph to your MCP client's config:
+
+```json
+{
+  "mcpServers": {
+    "gitmorph": {
+      "command": "npx",
+      "args": ["-y", "@morphllm/gitmorph-sdk", "mcp"],
+      "env": { "GM_TOKEN": "gm_..." }
+    }
+  }
+}
+```
+
+No install. No global CLI. The `bin` entry in this package registers `gitmorph-mcp`, and `npx -y` runs it directly. Auth resolves from the `env` block, from `~/.config/gm/config.json`, or from your shell environment.
+
+To embed the MCP server in your own Node process:
+
+```ts
+import { GitMorph } from "@morphllm/gitmorph-sdk";
+import { startGitmorphMcpServer } from "@morphllm/gitmorph-sdk/mcp";
+
+await startGitmorphMcpServer(new GitMorph());
+```
+
+### Tool reference
+
+All adapters expose the same 9 tools by default (`gm_mirror` is opt-in via `includeMirror: true`):
+
+| Tool | Purpose |
+|------|---------|
+| `gm_read_file` | Read a file, optionally a specific line range |
+| `gm_read_files` | Batch-read multiple files in one call |
+| `gm_grep` | Search file contents within one repo (regex or keyword) |
+| `gm_glob` | Find files by path pattern (`**/*.ts`) |
+| `gm_list_dir` | List entries in a directory |
+| `gm_list_branches` | List branches with head commits |
+| `gm_list_commits` | List commits, filterable by path or date range |
+| `gm_grep_all` | Search code across all mirrored repositories |
+| `gm_get_repo_info` | Fetch metadata for a repository |
+| `gm_mirror` | *Opt-in.* Mirror a GitHub/GitLab/Gitea repo into GitMorph |
+
+### Customizing
+
+Every factory accepts the same options:
+
+```ts
+createGitmorphTools(gm, {
+  only: ["gm_grep", "gm_read_file"] as const,  // whitelist (narrows the return type)
+  exclude: ["gm_list_branches"],               // drop specific tools
+  rename: { gm_grep: "search_code" },          // rename to match your agent's naming scheme
+  includeMirror: false,                         // enable the opt-in gm_mirror tool
+  maxOutputBytes: 262_144,                      // cap per-call output (Anthropic/OpenAI/MCP)
+});
+```
+
+`GITMORPH_SYSTEM_PROMPT` is re-exported from every subpath — append it to your system message to give the model explicit guidance on when to reach for each tool.
+
+## Auth
+
+Credentials resolve in order:
+
+1. Constructor options: `new GitMorph({ token: "...", host: "..." })`
+2. Environment variables: `GM_TOKEN`, `GM_HOST`
+3. Config file: `~/.config/gm/config.json`
+
+The host defaults to `gitmorph.com` if not set.
+
+## API reference
+
+### `GitMorph` (client)
+
+| Method | Description |
+|--------|-------------|
+| `gm.repo("owner/repo")` | Get a repo handle for file/search operations |
+| `gm.getRepositoryInfo("owner/repo")` | Repo metadata (branches, stars, language, etc.) |
+| `gm.mirror(source, opts?)` | Mirror a repo from GitHub/GitLab/Gitea into GitMorph |
+| `gm.grepAll({ pattern, ... })` | Search code across all repos on the instance |
+
+### `GitMorphRepo` (per-repo operations)
+
+| Method | Description |
+|--------|-------------|
+| `repo.readFile(path, opts?)` | Read a file, optionally specific line ranges |
+| `repo.getFileContents(paths[], opts?)` | Batch read multiple files in one call |
+| `repo.grep({ pattern, ... })` | Server-side code search within this repo |
+| `repo.glob({ patterns[], ... })` | Find files matching glob patterns |
+| `repo.listDir(opts?)` | List directory contents (optionally recursive) |
+| `repo.listBranches(opts?)` | List branches with latest commit info |
+| `repo.listCommits(opts?)` | List commits with filtering by path, date range |
+
+### Read files
+
+```ts
+// Full file
+const file = await repo.readFile("src/index.ts");
+// file.content, file.totalLines
+
+// Specific line ranges (1-indexed, inclusive)
+const snippet = await repo.readFile("src/index.ts", {
+  ref: "main",
+  lines: [{ start: 10, end: 25 }, { start: 100, end: 110 }],
+});
+```
+
+### Batch read
+
+```ts
+const files = await repo.getFileContents([
+  "package.json",
+  "tsconfig.json",
+  "src/index.ts",
+]);
+// Returns (FileContentEntry | null)[] -- null for files that don't exist
+```
+
+### Grep (single repo)
+
+```ts
+const result = await repo.grep({
+  pattern: "createServer",
+  language: "TypeScript",
+  caseSensitive: true,
+  maxMatches: 20,
+});
+
+for (const match of result.matches) {
+  console.log(`${match.path}:${match.lineNumber}  ${match.lineContent}`);
+  // match.submatches[] has character offsets within the line
+}
+```
+
+### Grep all (cross-repo)
+
+```ts
+const result = await gm.grepAll({
+  pattern: "fastApply",
+  language: "TypeScript",
+  sortByStars: true,
+  limit: 10,
+});
+
+for (const match of result.matches) {
+  console.log(`${match.repoName}  ${match.filename}`);
+  for (const line of match.lines) {
+    console.log(`  L${line.num}: ${line.content}`);
+  }
+}
+```
+
+### Glob
+
+```ts
+const result = await repo.glob({
+  patterns: ["src/**/*.ts", "!**/*.test.ts", "!**/*.spec.ts"],
+  prefix: "src/",
+  limit: 500,
+});
+
+for (const entry of result.entries) {
+  console.log(`${entry.path}  ${entry.size} bytes`);
+}
+```
+
+### List directory
+
+```ts
+// Top-level
+const root = await repo.listDir();
+
+// Subdirectory, recursive
+const src = await repo.listDir({ path: "src", recursive: true, ref: "develop" });
+
+for (const entry of src.entries) {
+  console.log(`${entry.type === "dir" ? "d" : "f"}  ${entry.path}`);
+}
+```
+
+### Branches
+
+```ts
+const branches = await repo.listBranches({ limit: 50 });
+for (const b of branches) {
+  console.log(`${b.name}  ${b.commit.id.slice(0, 8)}  ${b.commit.message}`);
+}
+```
+
+### Commits
+
+```ts
+const commits = await repo.listCommits({
+  sha: "main",
+  path: "src/",
+  since: "2025-01-01T00:00:00Z",
+  limit: 20,
+});
+
+for (const c of commits) {
+  console.log(`${c.sha.slice(0, 8)}  ${c.author.name}  ${c.message}`);
+}
+```
+
+### Mirror
+
+```ts
+// Shorthand (defaults to GitHub)
+const { repository, repo } = await gm.mirror("facebook/react");
+
+// Full URL with options
+const { repository } = await gm.mirror("https://gitlab.com/org/repo", {
+  private: true,
+  issues: true,
+  pullRequests: true,
+  releases: true,
+});
+
+// repo is a GitMorphRepo handle, ready to use immediately
+const files = await repo.glob({ patterns: ["**/*.ts"] });
+```
+
+## Error handling
+
+All errors extend `GitMorphError`:
+
+```ts
+import {
+  GitMorphError,
+  ApiError,
+  AuthenticationError,
+  GrepError,
+  MirrorError,
+} from "@morphllm/gitmorph-sdk";
+
+try {
+  await repo.readFile("missing.txt");
+} catch (err) {
+  if (err instanceof ApiError) {
+    console.log(err.status, err.url); // 404, https://gitmorph.com/api/v1/...
+  }
+}
+```
+
+| Error class | When |
+|-------------|------|
+| `AuthenticationError` | No token found in options, env, or config file |
+| `ApiError` | HTTP error from the API (has `.status` and `.url`) |
+| `GrepError` | Invalid grep pattern or search failure |
+| `MirrorError` | Mirror/migrate operation failed |
+
+## License
+
+MIT

package/dist/ai/index.d.ts

@@ -0,0 +1,48 @@
+import { Tool } from 'ai';
+import { G as GitMorph } from '../client-B_I_0i1T.js';
+import { G as GitmorphToolName, D as DEFAULT_TOOL_NAMES, C as CreateToolsOptions } from '../instructions-BE0g1eFs.js';
+export { a as DefaultGitmorphToolName, b as GITMORPH_SYSTEM_PROMPT } from '../instructions-BE0g1eFs.js';
+import 'zod';
+
+/** Map a tuple of tool names to a `{ name: Tool }` record. */
+type AiToolMap<Names extends string> = {
+    readonly [K in Names]: Tool;
+};
+/**
+ * Create Vercel AI SDK tools for a {@link GitMorph} client.
+ *
+ * Repo-scoped tools take a `repo: "owner/name"` argument. For a single-repo
+ * chat, pin the repo with {@link createGitmorphRepoTools} to drop that field.
+ *
+ * Pass `only` as a `const` tuple to narrow the return type to exactly those
+ * tools — autocomplete will show just what you asked for.
+ *
+ * @example
+ * ```ts
+ * import { GitMorph } from "@morphllm/gitmorph-sdk";
+ * import { createGitmorphTools } from "@morphllm/gitmorph-sdk/ai";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * import { generateText } from "ai";
+ *
+ * const gm = new GitMorph();
+ * const { text } = await generateText({
+ *   model: anthropic("claude-sonnet-4-6"),
+ *   tools: createGitmorphTools(gm),
+ *   prompt: "What testing framework does facebook/react use?",
+ *   maxSteps: 5,
+ * });
+ * ```
+ */
+declare function createGitmorphTools<const Only extends readonly GitmorphToolName[] = typeof DEFAULT_TOOL_NAMES>(gm: GitMorph, opts?: CreateToolsOptions<Only>): AiToolMap<Only[number]>;
+/**
+ * Pinned variant — every tool operates on a single repository; no `repo`
+ * argument in any tool's schema.
+ *
+ * @example
+ * ```ts
+ * const tools = createGitmorphRepoTools(gm, "facebook/react");
+ * ```
+ */
+declare function createGitmorphRepoTools<const Only extends readonly GitmorphToolName[] = typeof DEFAULT_TOOL_NAMES>(gm: GitMorph, slug: string, opts?: CreateToolsOptions<Only>): AiToolMap<Only[number]>;
+
+export { CreateToolsOptions, DEFAULT_TOOL_NAMES, GitmorphToolName, createGitmorphRepoTools, createGitmorphTools };

package/dist/ai/index.js

@@ -0,0 +1,25 @@
+import { resolveToolSet } from '../chunk-A3AOZFPE.js';
+export { DEFAULT_TOOL_NAMES, GITMORPH_SYSTEM_PROMPT } from '../chunk-A3AOZFPE.js';
+import { tool } from 'ai';
+
+function createGitmorphTools(gm, opts = {}) {
+  return toAiTools(resolveToolSet(gm, opts));
+}
+function createGitmorphRepoTools(gm, slug, opts = {}) {
+  return toAiTools(resolveToolSet(gm, opts, slug));
+}
+function toAiTools(normalized) {
+  const out = {};
+  for (const t of normalized) {
+    out[t.name] = tool({
+      description: t.description,
+      inputSchema: t.schema,
+      execute: (input) => t.execute(input)
+    });
+  }
+  return out;
+}
+
+export { createGitmorphRepoTools, createGitmorphTools };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ai/index.ts"],"names":[],"mappings":";;;;AA8CO,SAAS,mBAAA,CAGd,EAAA,EACA,IAAA,GAAiC,EAAC,EACT;AACzB,EAAA,OAAO,SAAA,CAAU,cAAA,CAAe,EAAA,EAAI,IAAI,CAAC,CAAA;AAC3C;AAWO,SAAS,uBAAA,CAGd,EAAA,EACA,IAAA,EACA,IAAA,GAAiC,EAAC,EACT;AACzB,EAAA,OAAO,SAAA,CAAU,cAAA,CAAe,EAAA,EAAI,IAAA,EAAM,IAAI,CAAC,CAAA;AACjD;AAEA,SAAS,UAAU,UAAA,EAAoD;AACrE,EAAA,MAAM,MAA4B,EAAC;AACnC,EAAA,KAAA,MAAW,KAAK,UAAA,EAAY;AAC1B,IAAA,GAAA,CAAI,CAAA,CAAE,IAAI,CAAA,GAAI,IAAA,CAAK;AAAA,MACjB,aAAa,CAAA,CAAE,WAAA;AAAA,MACf,aAAa,CAAA,CAAE,MAAA;AAAA,MACf,OAAA,EAAS,CAAC,KAAA,KAAmB,CAAA,CAAE,QAAQ,KAAK;AAAA,KAC7C,CAAA;AAAA,EACH;AACA,EAAA,OAAO,GAAA;AACT","file":"index.js","sourcesContent":["import { tool, type Tool } from \"ai\";\nimport type { GitMorph } from \"../client.js\";\nimport {\n  resolveToolSet,\n  type CreateToolsOptions,\n  type NormalizedTool,\n} from \"../tools/core.js\";\nimport {\n  DEFAULT_TOOL_NAMES,\n  type DefaultGitmorphToolName,\n  type GitmorphToolName,\n} from \"../tools/registry.js\";\n\nexport { GITMORPH_SYSTEM_PROMPT } from \"../tools/instructions.js\";\nexport { DEFAULT_TOOL_NAMES } from \"../tools/registry.js\";\nexport type { CreateToolsOptions } from \"../tools/core.js\";\nexport type { GitmorphToolName, DefaultGitmorphToolName } from \"../tools/registry.js\";\n\n/** Map a tuple of tool names to a `{ name: Tool }` record. */\ntype AiToolMap<Names extends string> = { readonly [K in Names]: Tool };\n\n/**\n * Create Vercel AI SDK tools for a {@link GitMorph} client.\n *\n * Repo-scoped tools take a `repo: \"owner/name\"` argument. For a single-repo\n * chat, pin the repo with {@link createGitmorphRepoTools} to drop that field.\n *\n * Pass `only` as a `const` tuple to narrow the return type to exactly those\n * tools — autocomplete will show just what you asked for.\n *\n * @example\n * ```ts\n * import { GitMorph } from \"@morphllm/gitmorph-sdk\";\n * import { createGitmorphTools } from \"@morphllm/gitmorph-sdk/ai\";\n * import { anthropic } from \"@ai-sdk/anthropic\";\n * import { generateText } from \"ai\";\n *\n * const gm = new GitMorph();\n * const { text } = await generateText({\n *   model: anthropic(\"claude-sonnet-4-6\"),\n *   tools: createGitmorphTools(gm),\n *   prompt: \"What testing framework does facebook/react use?\",\n *   maxSteps: 5,\n * });\n * ```\n */\nexport function createGitmorphTools<\n  const Only extends readonly GitmorphToolName[] = typeof DEFAULT_TOOL_NAMES,\n>(\n  gm: GitMorph,\n  opts: CreateToolsOptions<Only> = {},\n): AiToolMap<Only[number]> {\n  return toAiTools(resolveToolSet(gm, opts)) as AiToolMap<Only[number]>;\n}\n\n/**\n * Pinned variant — every tool operates on a single repository; no `repo`\n * argument in any tool's schema.\n *\n * @example\n * ```ts\n * const tools = createGitmorphRepoTools(gm, \"facebook/react\");\n * ```\n */\nexport function createGitmorphRepoTools<\n  const Only extends readonly GitmorphToolName[] = typeof DEFAULT_TOOL_NAMES,\n>(\n  gm: GitMorph,\n  slug: string,\n  opts: CreateToolsOptions<Only> = {},\n): AiToolMap<Only[number]> {\n  return toAiTools(resolveToolSet(gm, opts, slug)) as AiToolMap<Only[number]>;\n}\n\nfunction toAiTools(normalized: NormalizedTool[]): Record<string, Tool> {\n  const out: Record<string, Tool> = {};\n  for (const t of normalized) {\n    out[t.name] = tool({\n      description: t.description,\n      inputSchema: t.schema,\n      execute: (input: unknown) => t.execute(input),\n    });\n  }\n  return out;\n}\n"]}

package/dist/anthropic/index.d.ts

@@ -0,0 +1,85 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { G as GitMorph } from '../client-B_I_0i1T.js';
+import { G as GitmorphToolName, C as CreateToolsOptions } from '../instructions-BE0g1eFs.js';
+export { D as DEFAULT_TOOL_NAMES, a as DefaultGitmorphToolName, b as GITMORPH_SYSTEM_PROMPT } from '../instructions-BE0g1eFs.js';
+import 'zod';
+
+/** Extra options for the Anthropic adapter on top of the shared set. */
+interface AnthropicToolOptions<Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[]> extends CreateToolsOptions<Only> {
+    /**
+     * Attach `cache_control: { type: "ephemeral" }` to the last tool so the
+     * tool definitions become a cached prefix of every request. Stable tool
+     * sets benefit from this for free — default off, flip on for production
+     * agent loops that send many messages.
+     *
+     * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     */
+    cacheControl?: boolean;
+}
+/** One element of `msg.content` when `msg.stop_reason === "tool_use"`. */
+interface ToolUseBlock {
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+/**
+ * Return value of {@link createGitmorphTools} for Anthropic. `tools` is a
+ * drop-in for `messages.create({ tools })`; `handleToolUse` consumes one
+ * `tool_use` block and returns a ready-to-send `tool_result`.
+ */
+interface GitmorphAnthropicTools {
+    readonly tools: Anthropic.Messages.Tool[];
+    /**
+     * Execute a tool_use block and return a tool_result content block. Never
+     * throws — errors become `is_error: true` results the model can recover
+     * from in the next turn.
+     */
+    handleToolUse(block: ToolUseBlock): Promise<Anthropic.Messages.ToolResultBlockParam>;
+}
+/**
+ * Create Anthropic SDK tools + dispatcher for a {@link GitMorph} client.
+ *
+ * @example
+ * ```ts
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { GitMorph } from "@morphllm/gitmorph-sdk";
+ * import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/anthropic";
+ *
+ * const anthropic = new Anthropic();
+ * const gm = new GitMorph();
+ * const { tools, handleToolUse } = createGitmorphTools(gm, { cacheControl: true });
+ *
+ * const messages: Anthropic.Messages.MessageParam[] = [
+ *   { role: "user", content: "Find every useEffect in facebook/react" },
+ * ];
+ *
+ * let msg = await anthropic.messages.create({
+ *   model: "claude-sonnet-4-6",
+ *   max_tokens: 4096,
+ *   system: GITMORPH_SYSTEM_PROMPT,
+ *   tools,
+ *   messages,
+ * });
+ *
+ * while (msg.stop_reason === "tool_use") {
+ *   const toolUses = msg.content.filter((b): b is Anthropic.Messages.ToolUseBlock => b.type === "tool_use");
+ *   const results = await Promise.all(toolUses.map(handleToolUse));
+ *   messages.push({ role: "assistant", content: msg.content });
+ *   messages.push({ role: "user", content: results });
+ *   msg = await anthropic.messages.create({ model: "claude-sonnet-4-6", max_tokens: 4096, system: GITMORPH_SYSTEM_PROMPT, tools, messages });
+ * }
+ * ```
+ */
+declare function createGitmorphTools<const Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[]>(gm: GitMorph, opts?: AnthropicToolOptions<Only>): GitmorphAnthropicTools;
+/**
+ * Pinned variant — every tool operates on a single repository. Tools drop
+ * the `repo` argument.
+ *
+ * @example
+ * ```ts
+ * const { tools, handleToolUse } = createGitmorphRepoTools(gm, "facebook/react");
+ * ```
+ */
+declare function createGitmorphRepoTools<const Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[]>(gm: GitMorph, slug: string, opts?: AnthropicToolOptions<Only>): GitmorphAnthropicTools;
+
+export { type AnthropicToolOptions, CreateToolsOptions, type GitmorphAnthropicTools, GitmorphToolName, type ToolUseBlock, createGitmorphRepoTools, createGitmorphTools };

package/dist/anthropic/index.js

@@ -0,0 +1,64 @@
+import { toJsonSchema, clampOutput } from '../chunk-FXEX72CO.js';
+import { resolveToolSet } from '../chunk-A3AOZFPE.js';
+export { DEFAULT_TOOL_NAMES, GITMORPH_SYSTEM_PROMPT } from '../chunk-A3AOZFPE.js';
+
+// src/anthropic/index.ts
+function createGitmorphTools(gm, opts = {}) {
+  return build(resolveToolSet(gm, opts), opts);
+}
+function createGitmorphRepoTools(gm, slug, opts = {}) {
+  return build(resolveToolSet(gm, opts, slug), opts);
+}
+function build(normalized, opts) {
+  const byName = new Map(normalized.map((t) => [t.name, t]));
+  const maxBytes = opts.maxOutputBytes;
+  const tools = normalized.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: toJsonSchema(t.schema)
+  }));
+  if (opts.cacheControl && tools.length > 0) {
+    tools[tools.length - 1].cache_control = { type: "ephemeral" };
+  }
+  const handleToolUse = async (block) => {
+    const def = byName.get(block.name);
+    if (!def) return errorResult(block.id, `Unknown tool: ${block.name}`);
+    const parsed = def.schema.safeParse(block.input);
+    if (!parsed.success) {
+      return errorResult(
+        block.id,
+        `Invalid input for ${block.name}: ${parsed.error.message}`
+      );
+    }
+    try {
+      const result = await def.execute(parsed.data);
+      return {
+        type: "tool_result",
+        tool_use_id: block.id,
+        content: clampOutput(result, maxBytes)
+      };
+    } catch (err) {
+      return errorResult(block.id, describeError(err));
+    }
+  };
+  return { tools, handleToolUse };
+}
+function errorResult(tool_use_id, message) {
+  return {
+    type: "tool_result",
+    tool_use_id,
+    is_error: true,
+    content: message
+  };
+}
+function describeError(err) {
+  if (err instanceof Error) {
+    const name = err.name && err.name !== "Error" ? `${err.name}: ` : "";
+    return `${name}${err.message}`;
+  }
+  return typeof err === "string" ? err : JSON.stringify(err);
+}
+
+export { createGitmorphRepoTools, createGitmorphTools };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/anthropic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/anthropic/index.ts"],"names":[],"mappings":";;;;;AAyFO,SAAS,mBAAA,CAGd,EAAA,EACA,IAAA,GAAmC,EAAC,EACZ;AACxB,EAAA,OAAO,KAAA,CAAM,cAAA,CAAe,EAAA,EAAI,IAAI,GAAG,IAAI,CAAA;AAC7C;AAWO,SAAS,uBAAA,CAGd,EAAA,EACA,IAAA,EACA,IAAA,GAAmC,EAAC,EACZ;AACxB,EAAA,OAAO,MAAM,cAAA,CAAe,EAAA,EAAI,IAAA,EAAM,IAAI,GAAG,IAAI,CAAA;AACnD;AAIA,SAAS,KAAA,CACP,YACA,IAAA,EACwB;AACxB,EAAA,MAAM,MAAA,GAAS,IAAI,GAAA,CAAI,UAAA,CAAW,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,IAAA,EAAM,CAAC,CAAC,CAAC,CAAA;AACzD,EAAA,MAAM,WAAW,IAAA,CAAK,cAAA;AAEtB,EAAA,MAAM,KAAA,GAAmC,UAAA,CAAW,GAAA,CAAI,CAAC,CAAA,MAAO;AAAA,IAC9D,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,aAAa,CAAA,CAAE,WAAA;AAAA,IACf,YAAA,EAAc,YAAA,CAAa,CAAA,CAAE,MAAM;AAAA,GACrC,CAAE,CAAA;AAEF,EAAA,IAAI,IAAA,CAAK,YAAA,IAAgB,KAAA,CAAM,MAAA,GAAS,CAAA,EAAG;AAGzC,IAAC,KAAA,CAAM,MAAM,MAAA,GAAS,CAAC,EAEpB,aAAA,GAAgB,EAAE,MAAM,WAAA,EAAY;AAAA,EACzC;AAEA,EAAA,MAAM,aAAA,GAAyD,OAC7D,KAAA,KACG;AACH,IAAA,MAAM,GAAA,GAAM,MAAA,CAAO,GAAA,CAAI,KAAA,CAAM,IAAI,CAAA;AACjC,IAAA,IAAI,CAAC,KAAK,OAAO,WAAA,CAAY,MAAM,EAAA,EAAI,CAAA,cAAA,EAAiB,KAAA,CAAM,IAAI,CAAA,CAAE,CAAA;AAEpE,IAAA,MAAM,MAAA,GAAS,GAAA,CAAI,MAAA,CAAO,SAAA,CAAU,MAAM,KAAK,CAAA;AAC/C,IAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,MAAA,OAAO,WAAA;AAAA,QACL,KAAA,CAAM,EAAA;AAAA,QACN,qBAAqB,KAAA,CAAM,IAAI,CAAA,EAAA,EAAK,MAAA,CAAO,MAAM,OAAO,CAAA;AAAA,OAC1D;AAAA,IACF;AAEA,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,MAAM,GAAA,CAAI,OAAA,CAAQ,OAAO,IAAI,CAAA;AAC5C,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,aAAA;AAAA,QACN,aAAa,KAAA,CAAM,EAAA;AAAA,QACnB,OAAA,EAAS,WAAA,CAAY,MAAA,EAAQ,QAAQ;AAAA,OACvC;AAAA,IACF,SAAS,GAAA,EAAK;AACZ,MAAA,OAAO,WAAA,CAAY,KAAA,CAAM,EAAA,EAAI,aAAA,CAAc,GAAG,CAAC,CAAA;AAAA,IACjD;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,EAAE,OAAO,aAAA,EAAc;AAChC;AAEA,SAAS,WAAA,CACP,aACA,OAAA,EACyC;AACzC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,aAAA;AAAA,IACN,WAAA;AAAA,IACA,QAAA,EAAU,IAAA;AAAA,IACV,OAAA,EAAS;AAAA,GACX;AACF;AAEA,SAAS,cAAc,GAAA,EAAsB;AAC3C,EAAA,IAAI,eAAe,KAAA,EAAO;AACxB,IAAA,MAAM,IAAA,GAAO,IAAI,IAAA,IAAQ,GAAA,CAAI,SAAS,OAAA,GAAU,CAAA,EAAG,GAAA,CAAI,IAAI,CAAA,EAAA,CAAA,GAAO,EAAA;AAClE,IAAA,OAAO,CAAA,EAAG,IAAI,CAAA,EAAG,GAAA,CAAI,OAAO,CAAA,CAAA;AAAA,EAC9B;AACA,EAAA,OAAO,OAAO,GAAA,KAAQ,QAAA,GAAW,GAAA,GAAM,IAAA,CAAK,UAAU,GAAG,CAAA;AAC3D","file":"index.js","sourcesContent":["import type Anthropic from \"@anthropic-ai/sdk\";\nimport type { GitMorph } from \"../client.js\";\nimport {\n  resolveToolSet,\n  type CreateToolsOptions,\n  type NormalizedTool,\n} from \"../tools/core.js\";\nimport { toJsonSchema } from \"../tools/json-schema.js\";\nimport { clampOutput } from \"../tools/truncate.js\";\nimport type { GitmorphToolName } from \"../tools/registry.js\";\n\nexport { GITMORPH_SYSTEM_PROMPT } from \"../tools/instructions.js\";\nexport { DEFAULT_TOOL_NAMES } from \"../tools/registry.js\";\nexport type { CreateToolsOptions } from \"../tools/core.js\";\nexport type { GitmorphToolName, DefaultGitmorphToolName } from \"../tools/registry.js\";\n\n/** Extra options for the Anthropic adapter on top of the shared set. */\nexport interface AnthropicToolOptions<\n  Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[],\n> extends CreateToolsOptions<Only> {\n  /**\n   * Attach `cache_control: { type: \"ephemeral\" }` to the last tool so the\n   * tool definitions become a cached prefix of every request. Stable tool\n   * sets benefit from this for free — default off, flip on for production\n   * agent loops that send many messages.\n   *\n   * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching\n   */\n  cacheControl?: boolean;\n}\n\n/** One element of `msg.content` when `msg.stop_reason === \"tool_use\"`. */\nexport interface ToolUseBlock {\n  readonly id: string;\n  readonly name: string;\n  readonly input: unknown;\n}\n\n/**\n * Return value of {@link createGitmorphTools} for Anthropic. `tools` is a\n * drop-in for `messages.create({ tools })`; `handleToolUse` consumes one\n * `tool_use` block and returns a ready-to-send `tool_result`.\n */\nexport interface GitmorphAnthropicTools {\n  readonly tools: Anthropic.Messages.Tool[];\n  /**\n   * Execute a tool_use block and return a tool_result content block. Never\n   * throws — errors become `is_error: true` results the model can recover\n   * from in the next turn.\n   */\n  handleToolUse(\n    block: ToolUseBlock,\n  ): Promise<Anthropic.Messages.ToolResultBlockParam>;\n}\n\n/**\n * Create Anthropic SDK tools + dispatcher for a {@link GitMorph} client.\n *\n * @example\n * ```ts\n * import Anthropic from \"@anthropic-ai/sdk\";\n * import { GitMorph } from \"@morphllm/gitmorph-sdk\";\n * import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from \"@morphllm/gitmorph-sdk/anthropic\";\n *\n * const anthropic = new Anthropic();\n * const gm = new GitMorph();\n * const { tools, handleToolUse } = createGitmorphTools(gm, { cacheControl: true });\n *\n * const messages: Anthropic.Messages.MessageParam[] = [\n *   { role: \"user\", content: \"Find every useEffect in facebook/react\" },\n * ];\n *\n * let msg = await anthropic.messages.create({\n *   model: \"claude-sonnet-4-6\",\n *   max_tokens: 4096,\n *   system: GITMORPH_SYSTEM_PROMPT,\n *   tools,\n *   messages,\n * });\n *\n * while (msg.stop_reason === \"tool_use\") {\n *   const toolUses = msg.content.filter((b): b is Anthropic.Messages.ToolUseBlock => b.type === \"tool_use\");\n *   const results = await Promise.all(toolUses.map(handleToolUse));\n *   messages.push({ role: \"assistant\", content: msg.content });\n *   messages.push({ role: \"user\", content: results });\n *   msg = await anthropic.messages.create({ model: \"claude-sonnet-4-6\", max_tokens: 4096, system: GITMORPH_SYSTEM_PROMPT, tools, messages });\n * }\n * ```\n */\nexport function createGitmorphTools<\n  const Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[],\n>(\n  gm: GitMorph,\n  opts: AnthropicToolOptions<Only> = {},\n): GitmorphAnthropicTools {\n  return build(resolveToolSet(gm, opts), opts);\n}\n\n/**\n * Pinned variant — every tool operates on a single repository. Tools drop\n * the `repo` argument.\n *\n * @example\n * ```ts\n * const { tools, handleToolUse } = createGitmorphRepoTools(gm, \"facebook/react\");\n * ```\n */\nexport function createGitmorphRepoTools<\n  const Only extends readonly GitmorphToolName[] = readonly GitmorphToolName[],\n>(\n  gm: GitMorph,\n  slug: string,\n  opts: AnthropicToolOptions<Only> = {},\n): GitmorphAnthropicTools {\n  return build(resolveToolSet(gm, opts, slug), opts);\n}\n\n// ── Internals ────────────────────────────────────────────────────────────────\n\nfunction build(\n  normalized: NormalizedTool[],\n  opts: AnthropicToolOptions,\n): GitmorphAnthropicTools {\n  const byName = new Map(normalized.map((t) => [t.name, t]));\n  const maxBytes = opts.maxOutputBytes;\n\n  const tools: Anthropic.Messages.Tool[] = normalized.map((t) => ({\n    name: t.name,\n    description: t.description,\n    input_schema: toJsonSchema(t.schema) as Anthropic.Messages.Tool[\"input_schema\"],\n  }));\n\n  if (opts.cacheControl && tools.length > 0) {\n    // Anthropic caches up to and including the first tool marked with\n    // cache_control. Mark the last one so the entire tools array is cached.\n    (tools[tools.length - 1] as Anthropic.Messages.Tool & {\n      cache_control?: { type: \"ephemeral\" };\n    }).cache_control = { type: \"ephemeral\" };\n  }\n\n  const handleToolUse: GitmorphAnthropicTools[\"handleToolUse\"] = async (\n    block,\n  ) => {\n    const def = byName.get(block.name);\n    if (!def) return errorResult(block.id, `Unknown tool: ${block.name}`);\n\n    const parsed = def.schema.safeParse(block.input);\n    if (!parsed.success) {\n      return errorResult(\n        block.id,\n        `Invalid input for ${block.name}: ${parsed.error.message}`,\n      );\n    }\n\n    try {\n      const result = await def.execute(parsed.data);\n      return {\n        type: \"tool_result\",\n        tool_use_id: block.id,\n        content: clampOutput(result, maxBytes),\n      };\n    } catch (err) {\n      return errorResult(block.id, describeError(err));\n    }\n  };\n\n  return { tools, handleToolUse };\n}\n\nfunction errorResult(\n  tool_use_id: string,\n  message: string,\n): Anthropic.Messages.ToolResultBlockParam {\n  return {\n    type: \"tool_result\",\n    tool_use_id,\n    is_error: true,\n    content: message,\n  };\n}\n\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) {\n    const name = err.name && err.name !== \"Error\" ? `${err.name}: ` : \"\";\n    return `${name}${err.message}`;\n  }\n  return typeof err === \"string\" ? err : JSON.stringify(err);\n}\n"]}