agent-dir 0.4.1 → 1.0.0

package/dist/src/tools/git.js

@@ -1,14 +1,13 @@
 import { spawn } from "node:child_process";
-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.");
-    }
-}
+import { appendBoundedOutput, commandEnvironment, processTreeSpawnOptions, terminateProcessTree, } from "./commands.js";
 function runGit(root, args, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
-        const child = spawn("git", args, { cwd: root, shell: false, env: process.env });
+        const child = spawn("git", args, {
+            cwd: root,
+            shell: false,
+            env: commandEnvironment(),
+            ...processTreeSpawnOptions(),
+        });
         let stdout = "";
         let stderr = "";
         let finished = false;
@@ -16,14 +15,14 @@ function runGit(root, args, timeoutMs = 30000) {
             if (finished)
                 return;
             finished = true;
-            child.kill("SIGTERM");
+            terminateProcessTree(child);
             reject(new Error(`git ${args.join(" ")} timed out after ${timeoutMs}ms.`));
         }, timeoutMs);
         child.stdout.on("data", (chunk) => {
-            stdout += chunk.toString();
+            stdout = appendBoundedOutput(stdout, chunk);
         });
         child.stderr.on("data", (chunk) => {
-            stderr += chunk.toString();
+            stderr = appendBoundedOutput(stderr, chunk);
         });
         child.on("error", (error) => {
             if (finished)
@@ -41,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/npm.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { appendBoundedOutput, commandEnvironment, processTreeSpawnOptions, terminateProcessTree, } from "./commands.js";
 export function runNpm(root, script, timeoutMs = 120000, allowedScripts = [], signal) {
     if (!/^[A-Za-z0-9:_-]+$/.test(script))
         throw new Error("Invalid npm script name.");
@@ -21,7 +22,8 @@ export function runNpm(root, script, timeoutMs = 120000, allowedScripts = [], si
             const child = spawn(executable, ["run", script], {
                 cwd: root,
                 shell: false,
-                env: process.env,
+                env: commandEnvironment(),
+                ...processTreeSpawnOptions(),
             });
             let stdout = "";
             let stderr = "";
@@ -32,14 +34,14 @@ export function runNpm(root, script, timeoutMs = 120000, allowedScripts = [], si
                     return;
                 finished = true;
                 clearTimeout(timer);
-                child.kill("SIGTERM");
+                terminateProcessTree(child);
                 reject(new Error(`npm run ${script} was aborted.`));
             };
             timer = setTimeout(() => {
                 if (finished)
                     return;
                 finished = true;
-                child.kill("SIGTERM");
+                terminateProcessTree(child);
                 signal?.removeEventListener("abort", abort);
                 reject(new Error(`npm run ${script} timed out after ${timeoutMs}ms.`));
             }, timeoutMs);
@@ -49,10 +51,10 @@ export function runNpm(root, script, timeoutMs = 120000, allowedScripts = [], si
             }
             signal?.addEventListener("abort", abort, { once: true });
             child.stdout.on("data", (chunk) => {
-                stdout += chunk.toString();
+                stdout = appendBoundedOutput(stdout, chunk);
             });
             child.stderr.on("data", (chunk) => {
-                stderr += chunk.toString();
+                stderr = appendBoundedOutput(stderr, chunk);
             });
             child.on("error", (error) => {
                 if (!finished) {

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/tunnel.js

@@ -14,8 +14,12 @@ function cleanOutput(value) {
 function writeLine(line = "") {
     process.stdout.write(`${line}\r\n`);
 }
-function publicUrl(subdomain) {
-    return `https://${subdomain}.wormhole.bar`;
+function publicUrl(options) {
+    if (options.provider === "cloudflared" && options.hostname)
+        return `https://${options.hostname}`;
+    if (options.subdomain)
+        return `https://${options.subdomain}.wormhole.bar`;
+    throw new Error("Tunnel URL cannot be determined from the configured options.");
 }
 function reasonCategory(reason) {
     if (/timeout/i.test(reason))
@@ -35,8 +39,8 @@ function failureFromLine(line) {
     return registration?.[1] ? `Wormhole registration failed: ${registration[1].trim()}` : undefined;
 }
 export function startTunnel(options) {
-    if (options.provider !== "wormhole")
-        return Promise.reject(new Error(`Unsupported tunnel provider: ${options.provider}`));
+    if (options.provider === "cloudflared" && !options.hostname)
+        return Promise.reject(new Error("Cloudflared requires a hostname routed to a named Cloudflare Tunnel."));
     return new Promise((resolve, reject) => {
         const telemetry = options.telemetry && options.telemetry.level !== "none"
             ? new TelemetryRecorder({
@@ -146,12 +150,13 @@ export function startTunnel(options) {
                 if (!url || stopped || reconnecting)
                     return;
                 try {
+                    // A 401 is expected: it proves the public tunnel reaches the authenticated server.
+                    // Never send the Agent Dir bearer token to the public hostname.
                     const response = await fetch(new URL(HEALTH_PATH, url), {
                         method: "HEAD",
-                        ...(options.token ? { headers: { authorization: `Bearer ${options.token}` } } : {}),
                         signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
                     });
-                    if (!response.ok)
+                    if (!response.ok && response.status !== 401)
                         throw new Error(`Health check returned HTTP ${response.status}.`);
                     healthFailures = 0;
                     if (healthState === "degraded") {
@@ -167,7 +172,7 @@ export function startTunnel(options) {
                     }
                     if (healthFailures >= HEALTH_FAILURE_THRESHOLD) {
                         healthFailures = 0;
-                        handleDisconnect("Public tunnel health check failed.");
+                        handleDisconnect("Tunnel health check failed.");
                     }
                 }
             }, HEALTH_INTERVAL_MS);
@@ -177,10 +182,16 @@ export function startTunnel(options) {
             if (stopped)
                 return;
             reconnecting = false;
-            const args = ["http", String(options.port)];
-            if (!options.random && options.subdomain)
+            const args = options.provider === "wormhole" ? ["http", String(options.port)] : ["tunnel", "run"];
+            if (options.provider === "wormhole" && !options.random && options.subdomain)
                 args.push("--subdomain", options.subdomain);
-            child = spawn("wormhole", args, { stdio: ["ignore", "pipe", "pipe"] });
+            const executable = options.provider === "wormhole" ? "wormhole" : "cloudflared";
+            child = spawn(executable, args, {
+                stdio: ["ignore", "pipe", "pipe"],
+                env: options.provider === "cloudflared" && options.cloudflaredToken
+                    ? { ...process.env, TUNNEL_TOKEN: options.cloudflaredToken }
+                    : process.env,
+            });
             let buffer = "";
             let connected = false;
             const cleanupAttempt = () => {
@@ -220,7 +231,7 @@ export function startTunnel(options) {
                     if (!resolved) {
                         if (!child) {
                             stop();
-                            reject(new Error("Wormhole connected without a child process."));
+                            reject(new Error(`${options.provider} connected without a child process.`));
                             return;
                         }
                         resolved = true;
@@ -245,10 +256,16 @@ export function startTunnel(options) {
                     return;
                 }
                 const explicit = line.match(/https:\/\/[^\s"'<>]+/)?.[0]?.replace(/[),.;]+$/, "");
-                if (explicit)
+                if (options.provider === "wormhole" && explicit)
                     connectedAt(explicit);
-                else if (/Status\s+.*connected/i.test(line) && options.subdomain)
-                    connectedAt(publicUrl(options.subdomain));
+                else if (options.provider === "wormhole" &&
+                    /Status\s+.*connected/i.test(line) &&
+                    options.subdomain)
+                    connectedAt(publicUrl(options));
+                else if (options.provider === "cloudflared" &&
+                    /registered tunnel connection|connection .* registered/i.test(line) &&
+                    options.hostname)
+                    connectedAt(publicUrl(options));
             };
             const onData = (chunk) => {
                 buffer += cleanOutput(chunk);
@@ -257,12 +274,12 @@ export function startTunnel(options) {
                 for (const line of lines)
                     processLine(line);
             };
-            const onError = (error) => disconnect(`Wormhole error: ${error.message}`);
+            const onError = (error) => disconnect(`${executable} error: ${error.message}`);
             const onExit = (code, signal) => {
                 const detail = signal ? `signal ${signal}` : `code ${code}`;
                 disconnect(startup
-                    ? `Wormhole exited before the tunnel was established (${detail}).`
-                    : `Wormhole process exited (${detail}).`);
+                    ? `${executable} exited before the tunnel was established (${detail}).`
+                    : `${executable} process exited (${detail}).`);
             };
             child.stdout?.on("data", onData);
             child.stderr?.on("data", onData);
@@ -270,7 +287,7 @@ export function startTunnel(options) {
             child.once("exit", onExit);
             timer = setTimeout(() => {
                 if (!connected)
-                    disconnect(`Timed out waiting for Wormhole to establish the tunnel after ${STARTUP_TIMEOUT_MS / 1000}s.`);
+                    disconnect(`Timed out waiting for ${executable} to establish the tunnel after ${STARTUP_TIMEOUT_MS / 1000}s.`);
             }, STARTUP_TIMEOUT_MS);
         };
         const handleDisconnect = (reason) => {

package/dist/src/types.d.ts

@@ -6,13 +6,24 @@ export interface NpmConfig {
 export interface Profile {
     directory: string;
     port: number;
-    tunnel: "none" | "wormhole";
+    tunnel: "none" | "wormhole" | "cloudflared";
+    defaultTunnel?: "none" | "wormhole" | "cloudflared";
+    tunnels?: {
+        wormhole?: {
+            subdomain?: string;
+            random?: boolean;
+        };
+        cloudflared?: {
+            hostname: string;
+            token?: string;
+        };
+    };
     subdomain?: string;
+    hostname?: string;
     token?: string;
     npm?: NpmConfig;
     commands?: string[];
     blacklistedCommands?: string[];
-    git?: boolean;
 }
 export interface AgentConfig {
     version: 1;
@@ -23,7 +34,6 @@ export interface CommandConfig {
     npm?: NpmConfig;
     commands?: string[];
     blacklistedCommands?: string[];
-    git?: boolean;
 }
 export interface ServerOptions {
     root: string;
@@ -40,9 +50,11 @@ export interface RequestLog {
     tool?: string;
 }
 export interface TunnelOptions {
-    provider: "wormhole";
+    provider: "wormhole" | "cloudflared";
     port: number;
+    cloudflaredToken?: string;
     subdomain?: string;
+    hostname?: string;
     random?: boolean;
     token?: string;
     telemetry?: TelemetryConfig;

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.