dsh-worktree-switch 0.2.1 → 0.3.1

package/lib/index.js

@@ -1,6 +1,108 @@
 import Schema from "@deepseek-ai/schemastery";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import { lstat, realpath, stat } from "node:fs/promises";
-import { basename, isAbsolute, relative, resolve } from "node:path";
+// src/host/paths.ts
+/**
+* Path predicates the host half shares between the verbs, the scope hint, and
+* the working-directory watcher.
+* @module dsh-worktree-switch/host/paths
+*/
+/**
+* Whether one absolute directory is the path itself or an ancestor of it.
+* @param directory - candidate ancestor.
+* @param path - absolute path to test.
+* @returns true when `path` is `directory` or lives below it.
+*/
+function contains(directory, path) {
+	const inside = relative(directory, path);
+	return inside === "" || !inside.startsWith("..") && !isAbsolute(inside);
+}
+// src/host/guard.ts
+/**
+* The source-checkout guard: while a session runs in a worktree copy, shell
+* commands that would run Git against the project checkout are refused before
+* dispatch.
+*
+* The prompt context (`worktree-switch:scope`) explains where the workspace
+* is, but it cannot stop a model that still reaches for the checkout it can
+* see — and the sandbox deliberately grants writes there. This guard is the
+* enforcement half that needs no harness change: `tools/pre-execute` can deny
+* one call, and the model reads the reason as that call's error result.
+*
+* The pattern is deliberately narrow. Only a shell call that mentions `git`
+* is considered, and only when it names the project checkout either as an
+* explicit `workdir` or as a literal absolute path in the command text.
+* `cd ..`-style relative escapes and shell variables are not resolved; the
+* guard is a net, not the sandbox boundary.
+* @module dsh-worktree-switch/host/guard
+*/
+/** Tool names whose `command` argument is executed by a shell. */
+const SHELL_TOOLS = /* @__PURE__ */ new Set(["bash"]);
+/**
+* Read a shell call's command and explicit directory, if this is one.
+* @param exec - the pending tool call.
+* @returns the fields the guard needs, or null for every other tool.
+*/
+function shellArguments(exec) {
+	if (!SHELL_TOOLS.has(exec.name)) return null;
+	if (exec.arguments === null || typeof exec.arguments !== "object") return null;
+	const args = exec.arguments;
+	const command = args["command"];
+	if (typeof command !== "string" || command.trim() === "") return null;
+	const workdir = args["workdir"];
+	const explicit = typeof workdir === "string" && workdir.trim() !== "" ? workdir : void 0;
+	return explicit === void 0 ? { command } : {
+		command,
+		workdir: explicit
+	};
+}
+/**
+* The model-facing denial for one shell command.
+* @param command - shell command text as the model wrote it.
+* @param workdir - explicit working directory, when the call carried one.
+* @param cwd - the session's committed working directory.
+* @param scope - the copy the session runs in.
+* @returns the denial reason, or null when the call may run.
+*/
+function sourceCheckoutDenial(command, workdir, cwd, scope) {
+	if (!/\bgit\b/.test(command)) return null;
+	const checkout = scope.worktree.path;
+	const project = scope.repositoryRoot;
+	if (workdir !== void 0) {
+		const target = isAbsolute(workdir) ? workdir : resolve(cwd, workdir);
+		if (contains(project, target) && !contains(checkout, target)) return denial(scope);
+	}
+	if (command.split(checkout).join("").includes(project)) return denial(scope);
+	return null;
+}
+/** The one explanation every denial carries, including the way to get main. */
+function denial(scope) {
+	return `Denied: this session runs in the worktree copy ${JSON.stringify(scope.worktree.path)}, so Git commands targeting the project checkout ${JSON.stringify(scope.repositoryRoot)} are blocked. Run Git in the current working directory instead; to bring main's latest into this copy, use \`git fetch origin main\` and then \`git merge origin/main\` (or \`git rebase origin/main\`).`;
+}
+/**
+* Refuse shell calls that run Git against the project checkout while the
+* session is inside a copy.
+*
+* The registry is the same one the prompt context reads, so the guard is
+* active exactly while the model has been told it is in a copy.
+* @param ctx - host context carrying `workingDirectory` and the tool runtime.
+* @param registry - sessions' confirmed copies.
+*/
+function installSourceCheckoutGuard(ctx, registry) {
+	ctx.on("tools/pre-execute", async (exec, next) => {
+		const agent = exec.agent;
+		if (agent === void 0) return next();
+		const scope = registry.get(String(agent.session.id));
+		if (scope === null) return next();
+		const args = shellArguments(exec);
+		if (args === null) return next();
+		const denial = sourceCheckoutDenial(args.command, args.workdir, ctx.workingDirectory.get(agent.session), scope);
+		return denial === null ? next() : {
+			kind: "deny",
+			reason: denial
+		};
+	});
+}
 /** Per-stream capture cap; worktree listings and status lines are small. */
 const MAX_OUTPUT_BYTES = 1048576;
 /**
@@ -275,7 +377,7 @@ function isWorktreeName(value) {
 }
 // src/host/handlers.ts
 /**
-* The plugin's host Remote face: the four verbs the browser half can call,
+* The plugin's host Remote face: the five verbs the browser half can call,
 * expressed against a live session and the checkouts on disk.
 *
 * This module is the seam the host tests drive directly. Everything below it —
@@ -339,14 +441,68 @@ async function worktreeAt(current, repositoryRoot) {
 	};
 }
 /**
+* Resolve the canonical root of the repository that contains a directory.
+* Git reports the spelling of the path it was given; the worktree service
+* publishes canonical paths, so both halves must agree on one spelling.
+* @param ctx - host context carrying `subprocess`.
+* @param directory - absolute directory inside the project.
+* @param signal - caller cancellation.
+* @returns the canonical repository root.
+*/
+async function repositoryOf(ctx, directory, signal) {
+	return canonicalPath(await repositoryRoot(ctx, directory, signal));
+}
+/**
+* Re-derive the copy one session runs in from its committed directory.
+*
+* A copy's root is the only linked checkout whose name matches the pool
+* convention, but a session may have changed into a directory *inside* the copy,
+* so ancestors are probed from the committed directory up to the project
+* anchor.
+* @param ctx - host context carrying `workingDirectory` and `subprocess`.
+* @param agent - live session owner.
+* @param signal - caller cancellation.
+* @returns the copy and project root, or null when the session is not in one.
+*/
+async function detectSessionScope(ctx, agent, signal) {
+	const current = ctx.workingDirectory.get(agent.session);
+	const anchor = agent.session.header.cwd ?? current;
+	if (current === anchor || !contains(anchor, current)) return null;
+	let root;
+	try {
+		root = await repositoryOf(ctx, anchor, signal);
+	} catch {
+		return null;
+	}
+	signal?.throwIfAborted();
+	let probe = current;
+	for (;;) {
+		const copy = await worktreeAt(probe, root);
+		if (copy !== null) return {
+			worktree: copy,
+			repositoryRoot: root
+		};
+		const parent = dirname(probe);
+		if (probe === root || probe === anchor || parent === probe) return null;
+		probe = parent;
+	}
+}
+/**
 * Build the host face.
 * @param ctx - Host context with `agents`, `worktrees`, `workingDirectory`, and `subprocess`.
 * @param options - resolved row config.
-* @returns the four verbs.
+* @returns the five verbs.
 */
 function createWorktreeToggle(ctx, options) {
 	/** One in-flight preparation per session, so a double mount cannot create twice. */
 	const pending = /* @__PURE__ */ new Map();
+	/**
+	* Copies this host instance created for a session, by session id. Turning the
+	* switch off may only delete what the switch itself just made: a copy that
+	* existed before this instance started is left for the panel's explicit
+	* discard, because it may carry work the switch never saw.
+	*/
+	const createdBySession = /* @__PURE__ */ new Map();
 	const sessionOf = async (sessionId, signal) => {
 		signal?.throwIfAborted();
 		if (sessionId === "") throw new WorktreeToggleError("bad-request", "a session id is required");
@@ -360,21 +516,12 @@ function createWorktreeToggle(ctx, options) {
 		if (agent === void 0) throw new WorktreeToggleError("session-not-found", `no live agent for session ${sessionId}`, { sessionId });
 		return agent;
 	};
-	/**
-	* Resolve the canonical root of the repository that contains a directory.
-	* Git reports the spelling of the path it was given; the worktree service
-	* publishes canonical paths, so both halves must agree on one spelling.
-	* @param directory - absolute directory inside the project.
-	* @param signal - caller cancellation.
-	* @returns the canonical repository root.
-	*/
-	const repositoryOf = async (directory, signal) => canonicalPath(await repositoryRoot(ctx, directory, signal));
 	const status = async (request, signal) => {
 		const agent = await sessionOf(request.sessionId, signal);
 		const startDirectory = agent.session.header.cwd ?? ctx.workingDirectory.get(agent.session);
 		let root;
 		try {
-			root = await repositoryOf(startDirectory, signal);
+			root = await repositoryOf(ctx, startDirectory, signal);
 		} catch (error) {
 			if (error instanceof GitFailure) return {
 				supported: false,
@@ -386,10 +533,15 @@ function createWorktreeToggle(ctx, options) {
 		const current = ctx.workingDirectory.get(agent.session);
 		signal?.throwIfAborted();
 		const sourceDirty = await changedFileCount(ctx, root, signal);
+		const copy = await worktreeAt(current, root);
+		options.onScope?.(request.sessionId, copy === null ? null : {
+			worktree: copy,
+			repositoryRoot: root
+		});
 		return {
 			supported: true,
 			repositoryRoot: root,
-			sessionWorktree: await worktreeAt(current, root),
+			sessionWorktree: copy,
 			sourceDirty,
 			defaultEnabled: options.defaultEnabled
 		};
@@ -398,14 +550,19 @@ function createWorktreeToggle(ctx, options) {
 		const agent = await sessionOf(request.sessionId, signal);
 		const current = await status(request, signal);
 		if (!current.supported) throw new WorktreeToggleError("not-a-git-repository", "the session project is not inside a Git working tree");
-		if (current.sessionWorktree !== null) return {
-			state: "existing",
-			worktree: current.sessionWorktree,
-			repositoryRoot: current.repositoryRoot,
-			sourceDirty: current.sourceDirty
-		};
-		const working = ctx.workingDirectory.get(agent.session);
-		const workingProject = await repositoryOf(working, signal);
+		if (current.sessionWorktree !== null) {
+			options.onScope?.(request.sessionId, {
+				worktree: current.sessionWorktree,
+				repositoryRoot: current.repositoryRoot
+			});
+			return {
+				state: "existing",
+				worktree: current.sessionWorktree,
+				repositoryRoot: current.repositoryRoot,
+				sourceDirty: current.sourceDirty
+			};
+		}
+		const workingProject = await repositoryOf(ctx, ctx.workingDirectory.get(agent.session), signal);
 		if (workingProject !== current.repositoryRoot) throw new WorktreeToggleError("session-moved", `this session now works in ${workingProject}, not in its project ${current.repositoryRoot}`, {
 			repositoryRoot: current.repositoryRoot,
 			workingProject
@@ -419,13 +576,19 @@ function createWorktreeToggle(ctx, options) {
 					name,
 					from: "HEAD"
 				}, signal);
+				const worktree = {
+					name: created.branch,
+					path: created.path,
+					branch: created.branch
+				};
+				createdBySession.set(request.sessionId, worktree);
+				options.onScope?.(request.sessionId, {
+					worktree,
+					repositoryRoot: created.repositoryRoot
+				});
 				return {
 					state: "created",
-					worktree: {
-						name: created.branch,
-						path: created.path,
-						branch: created.branch
-					},
+					worktree,
 					repositoryRoot: created.repositoryRoot,
 					sourceDirty: current.sourceDirty
 				};
@@ -452,7 +615,7 @@ function createWorktreeToggle(ctx, options) {
 		const directory = absolutePath(request.path);
 		let root;
 		try {
-			root = await repositoryOf(directory, signal);
+			root = await repositoryOf(ctx, directory, signal);
 		} catch (error) {
 			if (error instanceof GitFailure) return {
 				supported: false,
@@ -493,15 +656,20 @@ function createWorktreeToggle(ctx, options) {
 			items
 		};
 	};
-	const discard = async (request, signal) => {
-		const directory = absolutePath(request.path);
-		if (!isWorktreeName(request.name)) throw new WorktreeToggleError("worktree-name-invalid", `not a worktree name: ${request.name}`);
-		const root = await repositoryOf(directory, signal);
-		const listed = await list({ path: directory }, signal);
+	/**
+	* Delete one clean copy and its branch. Both the panel's discard and the
+	* switch's own undo go through here, so the dirty guard has one home.
+	* @param root - canonical repository root.
+	* @param name - copy name; already validated by the caller.
+	* @param signal - caller cancellation.
+	* @returns the removed copy's identity.
+	*/
+	const removeCopy = async (root, name, signal) => {
+		const listed = await list({ path: root }, signal);
 		if (!listed.supported) throw new WorktreeToggleError("not-a-git-repository", "the project is not inside a Git working tree");
-		const item = listed.items.find((entry) => entry.name === request.name);
-		if (item === void 0) throw new WorktreeToggleError("worktree-not-found", `no worktree named ${request.name} in ${root}`, {
-			name: request.name,
+		const item = listed.items.find((entry) => entry.name === name);
+		if (item === void 0) throw new WorktreeToggleError("worktree-not-found", `no worktree named ${name} in ${root}`, {
+			name,
 			repositoryRoot: root
 		});
 		if (item.changedFiles > 0) throw new WorktreeToggleError("worktree-dirty", `${item.name} has ${item.changedFiles} uncommitted change(s); commit or discard them first`, {
@@ -545,6 +713,7 @@ function createWorktreeToggle(ctx, options) {
 			name: item.name,
 			branch: item.branch
 		});
+		for (const [sessionId, copy] of createdBySession) if (copy.path === item.path) createdBySession.delete(sessionId);
 		return {
 			removed: true,
 			name: item.name,
@@ -552,9 +721,90 @@ function createWorktreeToggle(ctx, options) {
 			path: item.path
 		};
 	};
+	const discard = async (request, signal) => {
+		const directory = absolutePath(request.path);
+		if (!isWorktreeName(request.name)) throw new WorktreeToggleError("worktree-name-invalid", `not a worktree name: ${request.name}`);
+		const root = await repositoryOf(ctx, directory, signal);
+		return await removeCopy(root, request.name, signal);
+	};
+	const release = async (request, signal) => {
+		const running = pending.get(request.sessionId);
+		if (running !== void 0) try {
+			await running;
+		} catch {}
+		signal?.throwIfAborted();
+		const agent = await sessionOf(request.sessionId, signal);
+		const current = ctx.workingDirectory.get(agent.session);
+		const anchor = agent.session.header.cwd ?? current;
+		let root;
+		try {
+			root = await repositoryOf(ctx, anchor, signal);
+		} catch (error) {
+			if (error instanceof GitFailure) throw new WorktreeToggleError("not-a-git-repository", "the session project is not inside a Git working tree");
+			throw error;
+		}
+		const listed = await list({ path: anchor }, signal);
+		if (!listed.supported) return {
+			directory: current,
+			removed: null,
+			kept: null
+		};
+		const path = await canonicalPath(current);
+		const item = listed.items.find((entry) => contains(entry.path, path));
+		if (item === void 0) {
+			options.onScope?.(request.sessionId, null);
+			return {
+				directory: current,
+				removed: null,
+				kept: null
+			};
+		}
+		const copy = {
+			name: item.name,
+			path: item.path,
+			branch: item.branch
+		};
+		signal?.throwIfAborted();
+		let directory;
+		try {
+			directory = await ctx.workingDirectory.set(agent, anchor, signal);
+		} catch (error) {
+			throw new WorktreeToggleError("release-failed", `could not move the session back to ${anchor}: ${error instanceof Error ? error.message : String(error)}`, {
+				name: copy.name,
+				path: copy.path
+			});
+		}
+		options.onScope?.(request.sessionId, null);
+		const mine = createdBySession.get(request.sessionId);
+		if (mine === void 0 || mine.path !== copy.path) return {
+			directory,
+			removed: null,
+			kept: copy
+		};
+		try {
+			const removed = await removeCopy(root, copy.name, signal);
+			return {
+				directory,
+				removed: {
+					name: removed.name,
+					path: removed.path,
+					branch: removed.branch
+				},
+				kept: null
+			};
+		} catch (error) {
+			if (signal?.aborted === true) throw error;
+			return {
+				directory,
+				removed: null,
+				kept: copy
+			};
+		}
+	};
 	return {
 		status,
 		prepare,
+		release,
 		list,
 		discard
 	};
@@ -568,6 +818,7 @@ const PLUGIN_ID = "dsh-worktree-switch";
 const ENDPOINTS = [
 	"status",
 	"prepare",
+	"release",
 	"list",
 	"discard"
 ];
@@ -634,6 +885,11 @@ async function dispatch(toggle, endpoint, payload, signal) {
 			if ("failure" in sessionId) throw sessionId.failure;
 			return ok(await toggle.prepare({ sessionId: sessionId.value }, signal));
 		}
+		if (endpoint === "release") {
+			const sessionId = requiredString(payload, "sessionId");
+			if ("failure" in sessionId) throw sessionId.failure;
+			return ok(await toggle.release({ sessionId: sessionId.value }, signal));
+		}
 		if (endpoint === "list") {
 			const path = requiredString(payload, "path");
 			if ("failure" in path) throw path.failure;
@@ -686,6 +942,108 @@ function registerWorktreeRoutes(ctx, toggle) {
 		}
 	}), `${PLUGIN_ID} ${endpoint} route`);
 }
+// src/host/scope.ts
+/** Sessions whose confirmed copy the prompt context reads. */
+var SessionScopeRegistry = class {
+	scopes = /* @__PURE__ */ new Map();
+	/**
+	* Read one session's confirmed scope, without any filesystem work.
+	* @param sessionId - wire session identity.
+	* @returns the known copy, or null.
+	*/
+	get(sessionId) {
+		return this.scopes.get(sessionId) ?? null;
+	}
+	/**
+	* Record that a session now runs in a copy.
+	* @param sessionId - wire session identity.
+	* @param scope - the confirmed copy and its project root.
+	*/
+	remember(sessionId, scope) {
+		this.scopes.set(sessionId, scope);
+	}
+	/**
+	* Drop a session's scope; a session with no entry gets no hint.
+	* @param sessionId - wire session identity.
+	*/
+	forget(sessionId) {
+		this.scopes.delete(sessionId);
+	}
+	/** Drop every entry; the plugin dropping its context drops its hints with it. */
+	clear() {
+		this.scopes.clear();
+	}
+};
+/**
+* The model-facing line describing a worktree session's workspace.
+* @param scope - the session's confirmed copy.
+* @returns one sentence pair, JSON-quoted so paths survive the prompt.
+*/
+function scopeHint(scope) {
+	return `This session is a linked Git worktree checkout at ${JSON.stringify(scope.worktree.path)} of the project ${JSON.stringify(scope.repositoryRoot)}. Run Git commands and file edits from the current working directory; the project checkout is the source, not this session's workspace.`;
+}
+/**
+* Register the worktree scope as dynamic prompt context and keep it fresh.
+*
+* The context is `required`, so it survives compositions that suppress
+* optional runtime context, and it renders from the registry synchronously —
+* the expensive Git detection happens on session creation and directory
+* changes, never at request time.
+* @param ctx - host context carrying `systemPrompt`, `agents`, and `workingDirectory`.
+* @param wiring - registry plus the Git-backed detector.
+*/
+function installWorktreeScope(ctx, wiring) {
+	const { registry, detect } = wiring;
+	ctx.inject(["systemPrompt"], (scoped) => {
+		scoped.systemPrompt.context({
+			name: "worktree-switch:scope",
+			order: scoped.systemPrompt.getContextOrder("WORKING_DIRECTORY") + 5,
+			interpolate: false,
+			required: true,
+			text: (assembly) => {
+				const agent = assembly.agent;
+				if (agent === void 0) return "";
+				const sessionId = String(agent.session.id);
+				const current = ctx.workingDirectory.get(agent.session);
+				const scope = registry.get(sessionId);
+				if (scope !== null && contains(scope.worktree.path, current)) return scopeHint(scope);
+				if (scope !== null) registry.forget(sessionId);
+				const anchor = agent.session.header.cwd ?? current;
+				if (current === anchor || !contains(anchor, current)) return "";
+				if (lastChecked.get(sessionId) === current) return "";
+				refresh(agent, current);
+				return "";
+			}
+		});
+	});
+	const inFlight = /* @__PURE__ */ new Set();
+	/** The directory value each session was last inspected at, hit or miss. */
+	const lastChecked = /* @__PURE__ */ new Map();
+	/** Re-derive one live agent's scope, remembering or forgetting it. */
+	const refresh = async (agent, current = ctx.workingDirectory.get(agent.session)) => {
+		const sessionId = String(agent.session.id);
+		const anchor = agent.session.header.cwd ?? current;
+		if (current === anchor || !contains(anchor, current)) {
+			registry.forget(sessionId);
+			return;
+		}
+		if (inFlight.has(sessionId)) return;
+		inFlight.add(sessionId);
+		lastChecked.set(sessionId, current);
+		try {
+			const found = await detect(agent);
+			if (found === null) registry.forget(sessionId);
+			else registry.remember(sessionId, found);
+		} catch {
+			registry.forget(sessionId);
+		} finally {
+			inFlight.delete(sessionId);
+		}
+	};
+	ctx.on("agent/created", async ({ agent }) => {
+		await refresh(agent);
+	});
+}
 // src/index.ts
 /** Plugin id: package name, bundle row id, browser module id. */
 const name = "dsh-worktree-switch";
@@ -703,14 +1061,30 @@ const inject = [
 	"workingDirectory"
 ];
 /** Schemastery schema for {@link Config}. */
-const Config = Schema.object({ defaultEnabled: Schema.boolean().default(true).description("Start a new session in a worktree copy until the user turns the switch off for that project.") });
+const Config = Schema.object({
+	defaultEnabled: Schema.boolean().default(true).description("Start a new session in a worktree copy until the user turns the switch off for that project."),
+	guardSourceCheckout: Schema.boolean().default(true).description("While a session is in a copy, deny shell commands that run Git against the project checkout.")
+});
 /**
 * Mount the host half.
 * @param ctx - Host context.
 * @param config - validated row config.
 */
 function apply(ctx, config) {
-	registerWorktreeRoutes(ctx, createWorktreeToggle(ctx, { defaultEnabled: config.defaultEnabled }));
+	const scopes = new SessionScopeRegistry();
+	const toggle = createWorktreeToggle(ctx, {
+		defaultEnabled: config.defaultEnabled,
+		onScope: (sessionId, scope) => {
+			if (scope === null) scopes.forget(sessionId);
+			else scopes.remember(sessionId, scope);
+		}
+	});
+	installWorktreeScope(ctx, {
+		registry: scopes,
+		detect: (agent, signal) => detectSessionScope(ctx, agent, signal)
+	});
+	if (config.guardSourceCheckout) installSourceCheckoutGuard(ctx, scopes);
+	registerWorktreeRoutes(ctx, toggle);
 }
 export { Config, apply, inject, name };