@akira-tl/forgerelay 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-09
+
+### Added
+
+- First-class `rename` and `delete` MCP tools for files and directories in workspace or OS-temp file roots, including direct availability in minimal, full, and Codex tool modes.
+
+### Security
+
+- `rename` validates both source and destination canonical roots and refuses existing destinations; `delete` refuses allowed roots themselves and requires explicit `recursive: true` for non-empty directory trees.
+
 ## [0.2.1] - 2026-08-09
 
 ### Changed

package/dist/file-mutations.js

@@ -0,0 +1,50 @@
+import { lstat, realpath, rename, rm, rmdir, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { expandHomePath, resolveCanonicalAllowedPath } from "./roots.js";
+export async function renamePath(input, context) {
+    const source = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
+    await assertNotAllowedRootItself(source, context.allowedRoots, input.path);
+    const destination = await resolveCanonicalAllowedPath(input.newPath, context.cwd, context.allowedRoots);
+    await assertDestinationMissing(destination, input.newPath);
+    await lstat(source);
+    await rename(source, destination);
+    return { path: input.path, newPath: input.newPath };
+}
+export async function deletePath(input, context) {
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
+    await assertNotAllowedRootItself(path, context.allowedRoots, input.path);
+    const entry = await lstat(path);
+    const recursive = input.recursive ?? false;
+    if (entry.isDirectory()) {
+        if (recursive) {
+            await rm(path, { recursive: true, force: false });
+        }
+        else {
+            await rmdir(path);
+        }
+    }
+    else {
+        await unlink(path);
+    }
+    return { path: input.path, recursive };
+}
+async function assertDestinationMissing(path, inputPath) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw new Error(`Rename destination already exists: ${inputPath}`);
+}
+async function assertNotAllowedRootItself(path, allowedRoots, inputPath) {
+    const canonicalPath = await realpath(path);
+    for (const root of allowedRoots) {
+        const canonicalRoot = await realpath(resolve(expandHomePath(root)));
+        if (canonicalPath === canonicalRoot) {
+            throw new Error(`Cannot rename or delete an allowed root itself: ${inputPath}`);
+        }
+    }
+}

package/dist/mcp/server-instructions.js

@@ -4,6 +4,8 @@ export const toolNames = {
     read: "read",
     write: "write",
     edit: "edit",
+    rename: "rename",
+    delete: "delete",
     grep: "grep",
     glob: "glob",
     ls: "ls",
@@ -23,15 +25,17 @@ export function buildToolDescriptions(config) {
         read: `Read a file inside an open workspace or the OS temp directory. Instruction files returned by ${toolNames.openWorkspace} and advertised skill files are also readable when applicable.${skillCapability} Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         edit: `Edit one file inside an open workspace or the OS temp directory by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. Do not use ${toolNames.shell} to create or modify project files; use ${toolNames.edit} or ${toolNames.write} for file changes. Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
+        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. Do not use ${toolNames.shell} to create, move, rename, or delete project files; use ${toolNames.edit}, ${toolNames.write}, ${toolNames.rename}, or ${toolNames.delete} for file changes. Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
 function capabilityContractInstructions(config, context) {
     const workspaceLifecycle = config.toolMode === "codex"
         ? `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`
-        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId for later file, search, edit, write, show-changes, and shell tools. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
+        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId for later file, search, edit, write, rename, delete, show-changes, and shell tools. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in availableAgentsFiles, use ${toolNames.read} to inspect that instruction file and follow it.`;
     const skills = config.skillsEnabled
         ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, but ${toolNames.read} only permits advertised SKILL.md files and files under already-loaded skill directories.`
@@ -48,7 +52,7 @@ function capabilityContractInstructions(config, context) {
 }
 function toolSurfaceInstructions(config) {
     if (config.toolMode === "codex") {
-        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, apply_patch, exec_command, and write_stdin.`;
+        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, ${toolNames.rename}, ${toolNames.delete}, apply_patch, exec_command, and write_stdin.`;
     }
     if (config.toolMode === "full") {
         return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools.`;
@@ -64,12 +68,12 @@ function selectedWorkflowInstructions(config) {
 }
 function defaultWorkflowInstructions(config) {
     if (config.toolMode === "codex") {
-        return `Use ${toolNames.read} for direct file reads, apply_patch for all file modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes.`;
+        return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes.`;
     }
     const inspection = config.toolMode === "full"
         ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
         : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
-    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted modifications, ${toolNames.write} only for new files or complete rewrites, and ${toolNames.shell} for tests, builds, git inspection, package scripts, and commands that are better executed by the shell.`, `Do not create or modify files with ${toolNames.shell}; avoid shell redirection, heredocs, tee, sed -i, perl -i, node/python/ruby scripts, or any command whose purpose is to write project files.`);
+    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, and commands that are better executed by the shell.`, `Do not create or modify files with ${toolNames.shell}; avoid shell redirection, heredocs, tee, sed -i, perl -i, node/python/ruby scripts, or any command whose purpose is to write project files.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/server.js

@@ -14,6 +14,7 @@ import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@mode
 import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
+import { deletePath, renamePath } from "./file-mutations.js";
 import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
 import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
@@ -1069,6 +1070,148 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             });
         });
     }
+    registerAppTool(server, toolNames.rename, {
+        title: "Rename path",
+        description: toolDescriptions.rename,
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+            path: z.string().describe("Source file or directory path relative to the workspace root, or absolute inside the OS temp directory."),
+            newPath: z.string().describe("Destination path relative to the workspace root, or absolute inside the OS temp directory. The destination must not already exist."),
+        },
+        outputSchema: resultOutputSchema({
+            status: z.literal("renamed"),
+            path: z.string(),
+            newPath: z.string(),
+        }),
+        ...toolWidgetDescriptorMeta(config, "edit"),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, path, newPath }, extra) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.rename,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { path, newPath, paths: [path, newPath] },
+            changedPaths: () => [path, newPath],
+            operation: async () => {
+                const startedAt = performance.now();
+                try {
+                    await renamePath({ path, newPath }, {
+                        cwd: workspace.root,
+                        allowedRoots: workspaces.fileToolRoots(workspace),
+                    });
+                    const result = `Renamed ${path} to ${newPath}.`;
+                    const content = [textBlock(result)];
+                    logToolCall(config, {
+                        tool: toolNames.rename,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: `${path} -> ${newPath}`,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return {
+                        content,
+                        _meta: {
+                            tool: toolNames.rename,
+                            card: {
+                                workspaceId,
+                                path: newPath,
+                                summary: { previousPath: path },
+                                payload: { content },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            status: "renamed",
+                            path,
+                            newPath,
+                        },
+                    };
+                }
+                catch (error) {
+                    logToolCall(config, {
+                        tool: toolNames.rename,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: `${path} -> ${newPath}`,
+                        success: false,
+                        durationMs: Math.round(performance.now() - startedAt),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+            },
+        });
+    });
+    registerAppTool(server, toolNames.delete, {
+        title: "Delete path",
+        description: toolDescriptions.delete,
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+            path: z.string().describe("File or directory path relative to the workspace root, or absolute inside the OS temp directory."),
+            recursive: z.boolean().optional().describe("Delete a non-empty directory tree. Defaults to false."),
+        },
+        outputSchema: resultOutputSchema({
+            status: z.literal("deleted"),
+            path: z.string(),
+            recursive: z.boolean(),
+        }),
+        ...toolWidgetDescriptorMeta(config, "edit"),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, path, recursive }, extra) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.delete,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { path, recursive: recursive ?? false },
+            changedPaths: () => [path],
+            operation: async () => {
+                const startedAt = performance.now();
+                try {
+                    const deleted = await deletePath({ path, recursive }, {
+                        cwd: workspace.root,
+                        allowedRoots: workspaces.fileToolRoots(workspace),
+                    });
+                    const result = `Deleted ${path}${deleted.recursive ? " recursively" : ""}.`;
+                    const content = [textBlock(result)];
+                    logToolCall(config, {
+                        tool: toolNames.delete,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return {
+                        content,
+                        _meta: {
+                            tool: toolNames.delete,
+                            card: {
+                                workspaceId,
+                                path,
+                                summary: { recursive: deleted.recursive },
+                                payload: { content },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            status: "deleted",
+                            path,
+                            recursive: deleted.recursive,
+                        },
+                    };
+                }
+                catch (error) {
+                    logToolCall(config, {
+                        tool: toolNames.delete,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path,
+                        success: false,
+                        durationMs: Math.round(performance.now() - startedAt),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+            },
+        });
+    });
     if (config.toolMode === "codex") {
         registerAppTool(server, "apply_patch", {
             title: "Apply patch",