agent-dir 0.5.0 → 1.1.0

package/dist/src/tools/git.js

@@ -1,12 +1,5 @@
 import { spawn } from "node:child_process";
 import { appendBoundedOutput, commandEnvironment, processTreeSpawnOptions, terminateProcessTree, } from "./commands.js";
-function validatePaths(paths) {
-    if (!Array.isArray(paths) ||
-        paths.length === 0 ||
-        paths.some((path) => typeof path !== "string" || !path)) {
-        throw new Error("paths must contain at least one non-empty path.");
-    }
-}
 function runGit(root, args, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
         const child = spawn("git", args, {
@@ -47,63 +40,6 @@ function runGit(root, args, timeoutMs = 30000) {
         });
     });
 }
-export function gitStage(root, paths) {
-    validatePaths(paths);
-    return runGit(root, ["add", "--", ...paths]);
-}
-export function gitUnstage(root, paths) {
-    validatePaths(paths);
-    return runGit(root, ["restore", "--staged", "--", ...paths]);
-}
-export function gitCommit(root, message) {
-    if (!message.trim())
-        throw new Error("commit message must not be empty.");
-    return runGit(root, ["commit", "-m", message]);
-}
-export function gitPush(root, remote, branch) {
-    const args = ["push"];
-    if (remote) {
-        if (!/^[A-Za-z0-9._-]+$/.test(remote))
-            throw new Error("Invalid Git remote name.");
-        args.push(remote);
-        if (branch) {
-            if (!/^[A-Za-z0-9._/-]+$/.test(branch))
-                throw new Error("Invalid Git branch name.");
-            args.push(branch);
-        }
-    }
-    else if (branch) {
-        throw new Error("A Git remote is required when specifying a branch.");
-    }
-    return runGit(root, args);
-}
 export function gitStatus(root) {
     return runGit(root, ["status", "--short", "--branch"]);
 }
-export function gitDiff(root, staged = false, pathspec) {
-    const args = ["diff", "--no-ext-diff", "--no-color"];
-    if (staged)
-        args.push("--cached");
-    if (pathspec)
-        args.push("--", pathspec);
-    return runGit(root, args);
-}
-export function gitRestore(root, paths, staged = false) {
-    validatePaths(paths);
-    return runGit(root, ["restore", ...(staged ? ["--staged"] : []), "--", ...paths]);
-}
-export function gitLog(root, limit = 20, pathspec) {
-    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
-        throw new Error("limit must be an integer between 1 and 200.");
-    const args = [
-        "log",
-        "--no-color",
-        "--date=iso-strict",
-        "--format=%H%x09%ad%x09%an%x09%s",
-        "-n",
-        String(limit),
-    ];
-    if (pathspec)
-        args.push("--", pathspec);
-    return runGit(root, args);
-}

package/dist/src/tools/metadata.d.ts

@@ -15,5 +15,4 @@ export interface ProjectOverview {
     };
 }
 export declare function fileInfo(root: string, relativePath: string): Promise<Record<string, unknown>>;
-export declare function packageInfo(root: string): Promise<Record<string, unknown>>;
 export declare function projectOverview(root: string): Promise<ProjectOverview>;

package/dist/src/tools/metadata.js

@@ -23,28 +23,6 @@ export async function fileInfo(root, relativePath) {
         createdAt: stat.birthtime.toISOString(),
     };
 }
-export async function packageInfo(root) {
-    const packagePath = path.join(await fs.realpath(root), "package.json");
-    try {
-        const packageJson = JSON.parse(await fs.readFile(packagePath, "utf8"));
-        return {
-            path: "package.json",
-            name: packageJson.name ?? null,
-            version: packageJson.version ?? null,
-            description: packageJson.description ?? null,
-            packageManager: packageJson.packageManager ?? null,
-            engines: packageJson.engines ?? null,
-            scripts: packageJson.scripts ?? {},
-            dependencies: packageJson.dependencies ?? {},
-            devDependencies: packageJson.devDependencies ?? {},
-        };
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return { path: "package.json", exists: false };
-        throw new Error("package.json exists but is not valid JSON.");
-    }
-}
 export async function projectOverview(root) {
     const entries = await listFiles(root);
     const files = entries.filter((entry) => entry.type === "file");

package/dist/src/tools/skills.d.ts

@@ -1,3 +1,4 @@
+export declare function invalidateSkillDiscoveryCache(root: string): void;
 export interface SkillResource {
     uri: string;
     digest: string;

package/dist/src/tools/skills.js

@@ -5,9 +5,15 @@ import { listFiles } from "./files.js";
 const SKILL_ROOTS = ["skills", ".agents/skills", ".claude/skills", ".github/skills"];
 const MAX_RESOURCES = 512;
 const MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+const MAX_RESOURCE_RESPONSE_BYTES = 32_000;
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_DESCRIPTION_LENGTH = 1024;
+const DISCOVERY_CACHE_TTL_MS = 2_000;
+const discoveryCache = new Map();
+export function invalidateSkillDiscoveryCache(root) {
+    discoveryCache.delete(path.resolve(root));
+}
 export async function listSkills(root) {
     return (await discoverSkills(root)).map((skill) => skill.entry);
 }
@@ -22,8 +28,51 @@ export async function readSkillResource(root, uri) {
         const filePath = skill.resources.get(uri);
         if (!filePath)
             continue;
+        const stats = await fs.stat(filePath);
+        if (stats.size > MAX_RESOURCE_RESPONSE_BYTES) {
+            const handle = await fs.open(filePath, "r");
+            let previewBytes;
+            try {
+                previewBytes = Buffer.alloc(MAX_RESOURCE_RESPONSE_BYTES);
+                const { bytesRead } = await handle.read(previewBytes, 0, previewBytes.length, 0);
+                previewBytes = previewBytes.subarray(0, bytesRead);
+            }
+            finally {
+                await handle.close();
+            }
+            if (previewBytes.includes(0)) {
+                return {
+                    uri,
+                    mimeType: "text/plain",
+                    text: `Binary resource omitted: ${stats.size} bytes exceeds the ${MAX_RESOURCE_RESPONSE_BYTES}-byte response limit.`,
+                };
+            }
+            const marker = "\n…[resource truncated at 32000 bytes]";
+            let preview = previewBytes
+                .subarray(0, MAX_RESOURCE_RESPONSE_BYTES - Buffer.byteLength(marker, "utf8"))
+                .toString("utf8");
+            while (preview.endsWith("\uFFFD"))
+                preview = preview.slice(0, -1);
+            return { uri, mimeType: mimeTypeFor(filePath), text: `${preview}${marker}` };
+        }
         const bytes = await fs.readFile(filePath);
         const text = bytes.toString("utf8");
+        if (bytes.length > MAX_RESOURCE_RESPONSE_BYTES) {
+            if (Buffer.from(text, "utf8").equals(bytes)) {
+                const marker = "\n…[resource truncated at 32000 bytes]";
+                let preview = bytes
+                    .subarray(0, MAX_RESOURCE_RESPONSE_BYTES - Buffer.byteLength(marker, "utf8"))
+                    .toString("utf8");
+                while (preview.endsWith("\uFFFD"))
+                    preview = preview.slice(0, -1);
+                return { uri, mimeType: mimeTypeFor(filePath), text: `${preview}${marker}` };
+            }
+            return {
+                uri,
+                mimeType: "text/plain",
+                text: `Binary resource omitted: ${bytes.length} bytes exceeds the ${MAX_RESOURCE_RESPONSE_BYTES}-byte response limit.`,
+            };
+        }
         if (Buffer.from(text, "utf8").equals(bytes)) {
             return { uri, mimeType: mimeTypeFor(filePath), text };
         }
@@ -89,6 +138,22 @@ export async function skillResourceUrisForPath(root, relativePath) {
     return [...matches].sort();
 }
 async function discoverSkills(root) {
+    const resolvedRoot = await fs.realpath(root);
+    const cached = discoveryCache.get(resolvedRoot);
+    if (cached && cached.expiresAt > Date.now())
+        return cached.promise;
+    const promise = discoverSkillsUncached(resolvedRoot);
+    discoveryCache.set(resolvedRoot, { expiresAt: Date.now() + DISCOVERY_CACHE_TTL_MS, promise });
+    try {
+        return await promise;
+    }
+    catch (error) {
+        if (discoveryCache.get(resolvedRoot)?.promise === promise)
+            discoveryCache.delete(resolvedRoot);
+        throw error;
+    }
+}
+async function discoverSkillsUncached(root) {
     const resolvedRoot = await fs.realpath(root);
     const entries = await listFiles(root);
     const skills = [];

package/dist/src/types.d.ts

@@ -24,7 +24,6 @@ export interface Profile {
     npm?: NpmConfig;
     commands?: string[];
     blacklistedCommands?: string[];
-    git?: boolean;
 }
 export interface AgentConfig {
     version: 1;
@@ -35,7 +34,6 @@ export interface CommandConfig {
     npm?: NpmConfig;
     commands?: string[];
     blacklistedCommands?: string[];
-    git?: boolean;
 }
 export interface ServerOptions {
     root: string;
@@ -43,6 +41,7 @@ export interface ServerOptions {
     token: string;
     commandConfig?: CommandConfig;
     telemetry?: TelemetryConfig;
+    codeGraph?: import("./codegraph.js").CodeGraphIntegration;
 }
 export interface RequestLog {
     method: string;

package/docs/CONFIGURATION.md

@@ -0,0 +1,154 @@
+# Configuration and tunnel setup
+
+This guide covers first-run setup, saved profiles, authentication tokens, tunnels, and command permissions.
+
+## Requirements
+
+- Node.js 24 or newer
+- npm
+- Wormhole CLI or `cloudflared` CLI for remote access
+
+## First-run setup
+
+When run interactively for the first time without an existing config, Agent Dir offers a setup wizard. It collects a profile name, project directory, and port, then optionally configures Cloudflare Tunnel and Wormhole. Cloudflare connector tokens are entered without being echoed. You can enable either provider, both, or neither; Cloudflare is the default when both are configured.
+
+Run the wizard directly at any time:
+
+```bash
+agent-dir setup
+```
+
+The wizard saves the profile and exits without starting a tunnel. Non-interactive invocations and invocations with explicit launch options do not start the wizard.
+
+To skip profile setup and start a temporary random Wormhole tunnel:
+
+```bash
+agent-dir . --random --tunnel wormhole
+```
+
+## Profiles
+
+Profiles store the project directory, port, tunnel settings, allowed npm scripts, allowed non-npm commands, and blocked command prefixes.
+
+```bash
+agent-dir config add my-project \
+  --directory ~/src/my-project \
+  --tunnel wormhole \
+  --subdomain my-project-x7k4m2 \
+  --npm typecheck,lint,format,test,build \
+  --command grep,find,rg,git \
+  --blacklist "git commit,git push --force"
+```
+
+Start a saved profile by name:
+
+```bash
+agent-dir my-project
+```
+
+Manage profiles:
+
+```bash
+agent-dir config list
+agent-dir config show my-project
+agent-dir config delete my-project
+agent-dir config delete --all
+```
+
+Deletion asks for confirmation by default. Use `--yes` for automation. The older `config remove <name>` command is an alias for `config delete <name>`.
+
+Profile configuration is stored at `~/.config/agent-dir/config.json`, outside the project repository, with user-only permissions. CLI options can override saved values for a single run. `config show` redacts configured tunnel tokens.
+
+### Example profile
+
+```json
+{
+  "directory": "~/src/my-project",
+  "port": 3002,
+  "tunnel": "cloudflared",
+  "defaultTunnel": "cloudflared",
+  "tunnels": {
+    "wormhole": { "subdomain": "my-project-x7k4m2" },
+    "cloudflared": {
+      "hostname": "mcp.example.com",
+      "token": "CLOUDFLARE_TUNNEL_TOKEN"
+    }
+  }
+}
+```
+
+The Cloudflare connector token is separate from the Agent Dir MCP Bearer token. Avoid passing secrets as command-line arguments because they may appear in shell history or process listings; prefer the interactive prompt when possible.
+
+## Tunnel setup
+
+### Wormhole
+
+Temporary random URL:
+
+```bash
+agent-dir . --random --tunnel wormhole
+```
+
+Custom subdomain:
+
+```bash
+agent-dir . --tunnel wormhole --subdomain my-project-x7k4m2
+```
+
+Choose a distinctive subdomain to reduce collisions. Wormhole limits how many subdomains a user can have registered or active. If registration fails with a subdomain limit error, stop unused Wormhole processes, release an existing subdomain, or use `--random`.
+
+The tunnel is only transport; Agent Dir's local server still enforces its own authentication.
+
+### Cloudflare Tunnel
+
+Configure a Cloudflare Tunnel and DNS/ingress route for the hostname before launching Agent Dir:
+
+```bash
+agent-dir . --tunnel cloudflared --hostname mcp.example.com
+```
+
+For saved profiles, Cloudflare is selected by default when a `tunnels.cloudflared` entry exists. Use `-c` to explicitly select Cloudflare or `-w` to select Wormhole:
+
+```bash
+agent-dir my-project -c
+agent-dir my-project -w
+```
+
+The `--hostname` value is the public URL Agent Dir displays; the named tunnel's DNS and ingress configuration must already exist. Agent Dir monitors `cloudflared tunnel run` and restarts the process if it disconnects. See the [Cloudflare Tunnel setup guide](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/).
+
+## Authentication tokens
+
+Agent Dir generates a random Bearer token when the server starts unless a profile token or `--token` is configured. Authentication cannot be disabled.
+
+Retrieve or rotate a profile token:
+
+```bash
+agent-dir config token my-project
+agent-dir config token my-project --rotate
+```
+
+The token command intentionally prints the secret. Do not share or commit its output.
+
+Clients should send `Authorization: Bearer <token>`. Query-string tokens are supported for clients that cannot set headers, but are less secure because URLs may be recorded in logs or copied.
+
+## Command permissions
+
+npm scripts and general executables have separate allowlists.
+
+Allow npm scripts:
+
+```text
+--npm typecheck,lint,format,test,build
+```
+
+Allow executables:
+
+```text
+--command grep,find,rg,git
+```
+
+Commands are launched with `shell: false`; executable and arguments are passed separately. Git uses the same allowlisted command interface as other executables; there are no dedicated Git MCP tools.
+
+A configured `blacklistedCommands` entry overrides the allowlist and blocks matching command/argument prefixes. For example, allowing `git` while blacklisting `git commit` and `git push --force` still permits `git status`. Prefix entries are separated by commas.
+
+Avoid allowing `sh`, `bash`, `zsh`, `cmd`, `node`, or `python` unless you intentionally want to grant much broader execution capability.

package/docs/MCP.md

@@ -0,0 +1,106 @@
+# MCP interface and security model
+
+Agent Dir exposes a local project through an authenticated, stateless Model Context Protocol endpoint.
+
+## Endpoint and authentication
+
+- `POST /mcp` is the application MCP endpoint and requires authentication.
+- `HEAD /__health` is reserved for local tunnel health checks and does not expose project contents.
+- Legacy direct filesystem REST routes such as `/__tree` and direct `GET`/`PUT`/`DELETE` file paths are not supported.
+
+Use the Bearer token in the standard header:
+
+```http
+Authorization: Bearer <token>
+```
+
+The server also accepts a query-string token for clients that cannot set an Authorization header. Prefer the header because query-string tokens can be exposed in URLs and logs.
+
+## Stateless protocol behavior
+
+The implementation supports MCP protocol version `2026-07-28`. Requests carry protocol version and client capabilities in `params._meta`; this path does not require an initialize handshake or `Mcp-Session-Id`.
+
+Standard Streamable HTTP requests do not need implementation-specific `MCP-Protocol-Version`, `Mcp-Method`, or `Mcp-Name` headers. If supplied, these headers are validated against the JSON-RPC request and metadata.
+
+Supported features include:
+
+- `server/discover`
+- cursor pagination for list-style methods
+- `subscriptions/listen` for tool, prompt, and resource change events
+- resource subscriptions and filesystem change notifications
+- cache metadata
+- structured tool results with `resultType` and `outputSchema`
+- the stable `io.modelcontextprotocol/skills` extension
+
+Modern `subscriptions/listen` replaces the legacy GET/SSE notification model. List-style methods use opaque cursors when more than 50 entries are available.
+
+## Public tool set
+
+The core public tool set is intentionally small:
+
+| Tool | Purpose |
+| --- | --- |
+| `project_context` | Compact project overview and active execution policy |
+| `find_files` | Find paths by glob |
+| `search_code` | Search source-like files with bounded output |
+| `find_symbol` | Locate likely symbol definitions |
+| `find_references` | Locate symbol references |
+| `read_range` | Read a bounded line range from a UTF-8 file |
+| `apply_changes` | Create, patch, or delete files |
+| `file_info` | Inspect filesystem metadata |
+| `validate` | Run lightweight diagnostics and explicitly requested allowed npm scripts |
+| `run_npm_batch` | Run explicitly allowlisted npm scripts sequentially |
+| `run_command_batch` | Run explicitly allowlisted executables sequentially without a shell |
+| `codegraph_explore` | Optional structural code intelligence when CodeGraph is available |
+
+`codegraph_explore` is only advertised when CodeGraph is installed and the current project has a readable `.codegraph/codegraph.db` index. Other CodeGraph tools are not forwarded.
+
+Batch command operations execute sequentially and stop at the first failed command. Tool results include structured content and a serialized text representation; tools returning structured data advertise an output schema.
+
+## Command execution policy
+
+npm scripts and other executables use separate allowlists. An executable not in the configured allowlist is rejected, and configured `blacklistedCommands` prefixes override the allowlist. Commands are launched without a shell.
+
+Git is run through `run_command_batch` when `git` is allowlisted. There are no dedicated Git MCP tools. This keeps the advertised tool set small while preserving explicit executable and argument restrictions. Avoid allowing shells or interpreters unless broader command execution is intentional.
+
+## CodeGraph integration
+
+CodeGraph is optional and installed separately:
+
+```bash
+npm install -g @colbymchenry/codegraph
+codegraph init
+```
+
+Agent Dir exposes `codegraph_explore` only when the executable is on `PATH` and the current project has a readable index. It starts CodeGraph on first use and reuses the child process for subsequent calls. The project root is fixed as the CodeGraph path; callers cannot forward arbitrary `projectPath` values. Agent Dir passes a limited environment to the child process and terminates it during shutdown.
+
+Discovery distinguishes these states:
+
+- `not_installed` — CodeGraph is unavailable on `PATH`.
+- `not_indexed` — installed, but this project has no readable index.
+- `available` — installed and indexed.
+- `startup_failed` / `runtime_failed` — CodeGraph failed to start or later terminated; Agent Dir remains available.
+
+When indexed, agents are instructed to use CodeGraph for non-trivial structural questions such as call/data flow, symbol relationships, and change impact. Exact-text searches and focused file edits use Agent Dir's native tools.
+
+## Agent instructions and Skills
+
+`server/discover` returns dynamically generated instructions. The Resources primitive exposes:
+
+```text
+agent-dir://instructions
+agent-dir://capabilities
+```
+
+The capabilities resource reports the Agent Dir version, registered tool names, execution policy, and preferred/avoid tool-selection patterns.
+
+Agent Dir implements the stable MCP Skills extension (`io.modelcontextprotocol/skills`) and discovers project-local `SKILL.md` files under:
+
+```text
+skills/
+.agents/skills/
+.claude/skills/
+.github/skills/
+```
+
+Skills are exposed through `skills/list`, `skills/get`, `resources/list`, and `resources/read`. Skill manifests are bounded to 512 resources and 16 MiB. Binary supporting files are returned as MCP blobs; `resources/directory/read` lists direct children of a skill resource directory.