@fonlan/dsh-quick-commands 0.1.0

package/lib/index.js

@@ -0,0 +1,904 @@
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+//#region src/server/remote.ts
+/**
+* Remote (SSH) execution support: detect that a workspace path is a dsh-ssh
+* placeholder directory, and stream a quick command over an acquired SSH
+* connection.
+*
+* Deliberately dependency-free: the @dsh-ssh/dsh-ssh host plugin is consumed
+* only through duck-typed services (`sshPool` service + the `dsh-ssh-hosts`
+* settings namespace). When that plugin is absent everything degrades to the
+* local path (the runner keeps its subprocess backend untouched).
+*
+* The placeholder-path contract mirrors dsh-ssh/src/router.js exactly (it is
+* that plugin's public wire format):
+*   root   = $DSH_SSH_REMOTE_ROOT | $DSH_HOME/remote | ~/.dsh/remote
+*   layout = <root>/<hostId>/<base64url(remote absolute path)>
+* The encoded segment must decode to an absolute POSIX path (starts with
+* '/'); anything else is never misdetected as remote.
+*/
+function remoteRoot(env = process.env) {
+	if (env.DSH_SSH_REMOTE_ROOT !== void 0 && env.DSH_SSH_REMOTE_ROOT !== "") return path.resolve(String(env.DSH_SSH_REMOTE_ROOT));
+	const dshHome = env.DSH_HOME !== void 0 && env.DSH_HOME !== "" ? String(env.DSH_HOME) : path.join(os.homedir(), ".dsh");
+	return path.join(dshHome, "remote");
+}
+function isValidHostId(hostId) {
+	if (hostId.length === 0) return false;
+	if (hostId === "." || hostId === "..") return false;
+	return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(hostId);
+}
+function encodeRemotePath(remotePath) {
+	return Buffer.from(String(remotePath), "utf8").toString("base64url");
+}
+function decodeRemotePath(encoded) {
+	if (typeof encoded !== "string" || encoded.length === 0) return null;
+	if (!/^[A-Za-z0-9_-]+$/.test(encoded)) return null;
+	let text;
+	try {
+		text = Buffer.from(encoded, "base64url").toString("utf8");
+	} catch {
+		return null;
+	}
+	if (encodeRemotePath(text) !== encoded) return null;
+	return text;
+}
+/**
+* Local absolute path → { hostId, remotePath } when it is a dsh-ssh
+* placeholder (`<root>/<hostId>/<encoded>`), otherwise null. A coincidentally
+* matching real directory is never misdetected: the encoded segment must
+* round-trip to an absolute POSIX path.
+*/
+function localPathToRemoteRef(localPath, env = process.env) {
+	if (typeof localPath !== "string" || localPath.length === 0) return null;
+	const root = remoteRoot(env);
+	const rel = path.relative(root, localPath);
+	if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+	const segments = rel.split(path.sep);
+	if (segments.length !== 2) return null;
+	const hostId = segments[0];
+	const encoded = segments[1];
+	if (!isValidHostId(hostId)) return null;
+	const remotePath = decodeRemotePath(encoded);
+	if (remotePath === null) return null;
+	if (!remotePath.startsWith("/")) return null;
+	return {
+		hostId,
+		remotePath
+	};
+}
+/**
+* Map a session cwd (which may be inside the placeholder workspace, e.g. a
+* subdirectory of the workspace root) onto the remote filesystem. Only paths
+* strictly inside the placeholder are re-anchored; anything else falls back to
+* the workspace's remote root.
+*/
+function resolveRemoteCwd(sessionCwd, workspaceLocalPath, remotePath) {
+	const rel = path.relative(workspaceLocalPath, sessionCwd);
+	if (rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel)) return path.posix.resolve(remotePath, rel.split(path.sep).join("/"));
+	return remotePath;
+}
+/**
+* Read one host's connection config from the `dsh-ssh-hosts` settings
+* namespace (id → HostConfig dict, as written by the @dsh-ssh/dsh-ssh
+* settings page). Returns `{ ...host, id }` for pool.acquire, or undefined
+* when the host is not configured. `get` is the settings.get(ns) reader.
+*/
+function readHostConfig(get, hostId) {
+	let doc;
+	try {
+		doc = get("dsh-ssh-hosts");
+	} catch {
+		return;
+	}
+	if (typeof doc !== "object" || doc === null) return void 0;
+	const hosts = doc.hosts;
+	if (typeof hosts !== "object" || hosts === null) return void 0;
+	const host = hosts[hostId];
+	if (typeof host !== "object" || host === null) return void 0;
+	return {
+		...host,
+		id: hostId
+	};
+}
+function isChunk(item) {
+	return typeof item === "object" && item !== null && "stream" in item;
+}
+/** Single-quote one string for a POSIX shell (' → '\''). */
+function shellQuoteSingle(s) {
+	return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+/** stderr marker line: the remote process-group leader's pid ($$ of the sshd shell). */
+const PID_MARKER = "__QC_PID__";
+/**
+* One remote execution stream. Consumes conn.execStream in the background,
+* appends decoded chunks into the caller-provided tail buffers, and records the
+* terminal outcome.
+*
+* The command runs on the remote shell that sshd spawns for the channel (that
+* shell is the session/process-group leader; `$$` is its pid AND its pgid). The
+* leader pid is probed by prefixing `echo <marker> $$ >&2` to the command, so
+* `kill` can terminate the WHOLE process group (`kill -TERM -- -<pid>`), which
+* `pkill -f` alone cannot do for a child like `sleep 30` whose cmdline does not
+* match the original command text. The probe line is filtered out of the stderr
+* stream the user sees (a short buffer handles chunk-cut lines).
+*/
+var RemoteStreamExecutor = class {
+	conn;
+	pool;
+	cmd = "";
+	cwd = "";
+	started = false;
+	/** Remote process-group leader pid (parse the marker line; null until seen). */
+	leaderPid = null;
+	/** Raw stderr head buffer for the (possibly chunk-cut) marker line. */
+	markerBuf = "";
+	constructor(conn, pool) {
+		this.conn = conn;
+		this.pool = pool;
+	}
+	/**
+	* Start consuming the remote stream, settling the returned promise when the
+	* stream ends. `onData` sees decoded text chunks, `onExit` the terminal
+	* outcome (called exactly once, also on connection failure).
+	*/
+	async start(cmd, cwd, onData, onExit) {
+		this.cmd = cmd;
+		this.cwd = cwd;
+		this.started = true;
+		const wrapped = `echo ${PID_MARKER} $$ >&2; cd ${shellQuoteSingle(cwd)} && ( ${cmd} )`;
+		let exitCode = null;
+		let signal = null;
+		try {
+			for await (const raw of this.conn.execStream(wrapped)) {
+				const item = raw;
+				if (isChunk(item)) {
+					if (item.stream === "stdout") onData("stdout", item.chunk.toString("utf8"));
+					else this.emitStderr(item.chunk.toString("utf8"), onData);
+				} else exitCode = item.exitCode;
+			}
+		} catch (error) {
+			const e = error;
+			onExit({
+				exitCode: null,
+				signal: null,
+				error: (e?.message ?? String(error)) + (e?.stage ? ` (stage: ${e.stage})` : "")
+			});
+			return;
+		}
+		onExit({
+			exitCode,
+			signal
+		});
+	}
+	/** Route stderr text, swallowing the (possibly split) marker line. */
+	emitStderr(text, onData) {
+		if (this.leaderPid !== null) {
+			onData("stderr", text);
+			return;
+		}
+		this.markerBuf += text;
+		const nl = this.markerBuf.indexOf("\n");
+		if (nl === -1) {
+			if (this.markerBuf.length > 4096) {
+				onData("stderr", this.markerBuf);
+				this.markerBuf = "";
+			}
+			return;
+		}
+		const head = this.markerBuf.slice(0, nl);
+		this.markerBuf = this.markerBuf.slice(nl + 1);
+		const m = /^__QC_PID__\s+(\d+)\s*$/.exec(head);
+		if (m !== null) this.leaderPid = Number(m[1]);
+		else onData("stderr", head + "\n");
+		if (this.markerBuf !== "") {
+			const rest = this.markerBuf;
+			this.markerBuf = "";
+			onData("stderr", rest);
+		}
+	}
+	/** The probed group-leader pid, if the marker line has been seen. */
+	get pid() {
+		return this.leaderPid;
+	}
+	/**
+	* Terminate the remote command's whole process group (best-effort). With the
+	* probed leader pid this is a true group kill (covers children like sleep);
+	* before the probe arrives (or when it never does) it falls back to a
+	* `pkill -f` on the exact `cd <cwd> && <cmd>` channel command line. The
+	* original stream then closes; the caller records signal 'TERM'.
+	*/
+	async kill() {
+		if (!this.started) return;
+		if (this.leaderPid !== null) try {
+			await this.conn.exec(`kill -TERM -- -${this.leaderPid} 2>/dev/null; pkill -TERM -P ${this.leaderPid} 2>/dev/null; true`, { timeoutMs: 1e4 });
+			return;
+		} catch {}
+		const escaped = ("cd " + (this.cwd ? this.cwd + " && " : "") + this.cmd).replace(/[.*+?^$[\]{}()|/\\]/g, "\\$&").replace(/'/g, "'\\''");
+		try {
+			await this.conn.exec(`pkill -TERM -f '${escaped}' 2>/dev/null; true`, { timeoutMs: 1e4 });
+		} catch {}
+	}
+};
+//#endregion
+//#region src/server/runner.ts
+/**
+* Quick-command execution engine.
+*
+* Owns one subprocess per run (serial per workspace id), keeps bounded
+* in-memory output tails with offset-based readers for incremental client
+* polls, resolves the {workspace}/{cwd}/{title} placeholders against the
+* session-bound execution context, and terminates the whole process tree on
+* kill / popup close.
+*
+* Two backends:
+*   - local: DSH's `subprocess` service (`bash -c`/`pwsh -c`, workspace cwd).
+*   - remote: when the workspace path is a dsh-ssh placeholder directory and
+*     the `sshPool` service is present, the command streams over SSH with the
+*     workspace's remote path as cwd. The client-visible behaviour (tail +
+*     offset polls) is identical for both backends.
+*/
+/** Bounded in-memory tail window per output stream (bytes). */
+const TAIL_MAX_BYTES = 262144;
+/** Substitute supported placeholders in the command string. */
+function resolvePlaceholders(command, vars) {
+	return command.replaceAll("{workspace}", vars.workspace).replaceAll("{cwd}", vars.cwd).replaceAll("{title}", vars.title);
+}
+/** Pick the shell executable for the current platform. */
+function shellCmd() {
+	return process.platform === "win32" ? "pwsh" : "bash";
+}
+/** Pick the `-c` inclusive switch for the current platform. */
+function shellFlag() {
+	return "-c";
+}
+var QuickCommandRunner = class {
+	subprocess;
+	resolveRemote;
+	runs = /* @__PURE__ */ new Map();
+	liveByWorkspace = /* @__PURE__ */ new Map();
+	constructor(subprocess, resolveRemote) {
+		this.subprocess = subprocess;
+		this.resolveRemote = resolveRemote;
+	}
+	/** Resolve the remote reference lazily so SSH availability is re-checked per run. */
+	resolveRemoteBackend() {
+		try {
+			return this.resolveRemote?.();
+		} catch {
+			return;
+		}
+	}
+	async start(input) {
+		const liveId = this.liveByWorkspace.get(input.workspaceId);
+		if (liveId !== void 0) {
+			const live = this.runs.get(liveId);
+			if (live !== void 0 && live.outcome === null) return {
+				ok: false,
+				error: `a command is already running for this workspace (${live.commandName})`
+			};
+			this.liveByWorkspace.delete(input.workspaceId);
+		}
+		const ref = localPathToRemoteRef(input.workspacePath);
+		if (ref !== null) {
+			const backend = this.resolveRemoteBackend();
+			if (backend === void 0) return {
+				ok: false,
+				error: `workspace ${input.workspaceId} is an SSH remote workspace (host ${ref.hostId}), but the @dsh-ssh/dsh-ssh plugin (sshPool service) is not loaded`
+			};
+			return this.startRemote(input, ref.hostId, ref.remotePath, backend);
+		}
+		return this.startLocal(input);
+	}
+	async startLocal(input) {
+		const resolved = resolvePlaceholders(input.command, {
+			workspace: input.workspacePath,
+			cwd: input.sessionCwd,
+			title: input.workspaceTitle
+		});
+		const runId = randomUUID();
+		const handle = this.subprocess.spawn({
+			argv: [
+				shellCmd(),
+				shellFlag(),
+				resolved
+			],
+			cwd: input.workspacePath,
+			graceMs: 3e3,
+			stdio: {
+				stdin: "ignore",
+				stdout: { maxBytes: TAIL_MAX_BYTES },
+				stderr: { maxBytes: TAIL_MAX_BYTES }
+			},
+			env: {
+				...process.env,
+				DSH_WORKSPACE: input.workspacePath,
+				DSH_WORKSPACE_ID: input.workspaceId,
+				DSH_WORKSPACE_TITLE: input.workspaceTitle
+			}
+		});
+		const live = {
+			runId,
+			workspaceId: input.workspaceId,
+			commandName: input.commandName,
+			resolvedCommand: resolved,
+			kind: "local",
+			handle,
+			stdoutBytes: 0,
+			stderrBytes: 0,
+			stdoutTail: "",
+			stderrTail: "",
+			stdoutClipped: false,
+			stderrClipped: false,
+			outcome: null,
+			killRequested: false,
+			startedAt: Date.now()
+		};
+		this.runs.set(runId, live);
+		this.liveByWorkspace.set(input.workspaceId, runId);
+		const stdoutReader = handle.collected?.stdout;
+		const stderrReader = handle.collected?.stderr;
+		const drain = () => {
+			if (stdoutReader !== void 0) {
+				const read = stdoutReader.readFrom(live.stdoutBytes);
+				live.stdoutBytes = read.nextOffset;
+				live.stdoutTail += read.text;
+				if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+					live.stdoutTail = live.stdoutTail.slice(-262144);
+					live.stdoutClipped = true;
+				}
+			}
+			if (stderrReader !== void 0) {
+				const read = stderrReader.readFrom(live.stderrBytes);
+				live.stderrBytes = read.nextOffset;
+				live.stderrTail += read.text;
+				if (live.stderrTail.length > TAIL_MAX_BYTES) {
+					live.stderrTail = live.stderrTail.slice(-262144);
+					live.stderrClipped = true;
+				}
+			}
+		};
+		const interval = setInterval(drain, 150);
+		handle.done.then((outcome) => {
+			clearInterval(interval);
+			drain();
+			live.outcome = {
+				exitCode: outcome.exitCode,
+				signal: outcome.signal
+			};
+		}).catch(() => {
+			clearInterval(interval);
+			live.outcome = {
+				exitCode: null,
+				signal: null
+			};
+		});
+		return {
+			ok: true,
+			runId,
+			resolvedCommand: resolved
+		};
+	}
+	async startRemote(input, hostId, remotePath, backend) {
+		const cfg = backend.resolveHost(hostId);
+		if (cfg === void 0) return {
+			ok: false,
+			error: `remote host ${hostId} is not configured in dsh-ssh-hosts — add it in Settings → SSH hosts`
+		};
+		let conn;
+		try {
+			conn = await backend.pool.acquire(cfg);
+		} catch (error) {
+			const e = error;
+			return {
+				ok: false,
+				error: `ssh connect to host ${hostId} failed: ${e?.message ?? String(error)}` + (e?.stage ? ` (stage: ${e.stage})` : "")
+			};
+		}
+		const remoteCwd = resolveRemoteCwd(input.sessionCwd, input.workspacePath, remotePath);
+		const resolved = resolvePlaceholders(input.command, {
+			workspace: remotePath,
+			cwd: remoteCwd,
+			title: input.workspaceTitle
+		});
+		const runId = randomUUID();
+		const executor = new RemoteStreamExecutor(conn, backend.pool);
+		const live = {
+			runId,
+			workspaceId: input.workspaceId,
+			commandName: input.commandName,
+			resolvedCommand: resolved,
+			kind: "remote",
+			handle: executor,
+			stdoutBytes: 0,
+			stderrBytes: 0,
+			stdoutTail: "",
+			stderrTail: "",
+			stdoutClipped: false,
+			stderrClipped: false,
+			outcome: null,
+			killRequested: false,
+			startedAt: Date.now()
+		};
+		this.runs.set(runId, live);
+		this.liveByWorkspace.set(input.workspaceId, runId);
+		const append = (stream, text) => {
+			if (stream === "stdout") {
+				live.stdoutBytes += Buffer.byteLength(text, "utf8");
+				live.stdoutTail += text;
+				if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+					live.stdoutTail = live.stdoutTail.slice(-262144);
+					live.stdoutClipped = true;
+				}
+			} else {
+				live.stderrBytes += Buffer.byteLength(text, "utf8");
+				live.stderrTail += text;
+				if (live.stderrTail.length > TAIL_MAX_BYTES) {
+					live.stderrTail = live.stderrTail.slice(-262144);
+					live.stderrClipped = true;
+				}
+			}
+		};
+		executor.start(resolved, remoteCwd, append, (exit) => {
+			if (exit.error !== void 0 && exit.error !== "") append("stderr", `\n[ssh] ${exit.error}\n`);
+			live.outcome = {
+				exitCode: exit.exitCode,
+				signal: live.killRequested ? "TERM" : exit.signal
+			};
+			backend.pool.release();
+		});
+		return {
+			ok: true,
+			runId,
+			remoteHost: hostId,
+			resolvedCommand: resolved
+		};
+	}
+	poll(runId, stdoutFrom, stderrFrom) {
+		const live = this.runs.get(runId);
+		if (live === void 0) return null;
+		if (live.kind === "local") {
+			const handle = live.handle;
+			const stdoutReader = handle.collected?.stdout;
+			const stderrReader = handle.collected?.stderr;
+			if (stdoutReader !== void 0) {
+				const read = stdoutReader.readFrom(live.stdoutBytes);
+				live.stdoutBytes = read.nextOffset;
+				live.stdoutTail += read.text;
+				if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+					live.stdoutTail = live.stdoutTail.slice(-262144);
+					live.stdoutClipped = true;
+				}
+			}
+			if (stderrReader !== void 0) {
+				const read = stderrReader.readFrom(live.stderrBytes);
+				live.stderrBytes = read.nextOffset;
+				live.stderrTail += read.text;
+				if (live.stderrTail.length > TAIL_MAX_BYTES) {
+					live.stderrTail = live.stderrTail.slice(-262144);
+					live.stderrClipped = true;
+				}
+			}
+		}
+		let stdoutDelta = live.stdoutTail;
+		let stdoutLossy = live.stdoutClipped;
+		if (stdoutFrom > 0 && stdoutFrom <= live.stdoutBytes) {
+			const tailStart = live.stdoutBytes - live.stdoutTail.length;
+			if (stdoutFrom < tailStart) stdoutLossy = true;
+			else stdoutDelta = live.stdoutTail.slice(stdoutFrom - tailStart);
+		}
+		let stderrDelta = live.stderrTail;
+		let stderrLossy = live.stderrClipped;
+		if (stderrFrom > 0 && stderrFrom <= live.stderrBytes) {
+			const tailStart = live.stderrBytes - live.stderrTail.length;
+			if (stderrFrom < tailStart) stderrLossy = true;
+			else stderrDelta = live.stderrTail.slice(stderrFrom - tailStart);
+		}
+		const exited = live.outcome !== null;
+		return {
+			kind: "poll",
+			status: exited ? "exited" : "running",
+			exitCode: exited ? live.outcome.exitCode : null,
+			signal: exited ? live.outcome.signal : null,
+			stdoutEnd: live.stdoutBytes,
+			stderrEnd: live.stderrBytes,
+			stdoutDelta,
+			stderrDelta,
+			stdoutLossy,
+			stderrLossy
+		};
+	}
+	kill(runId) {
+		const live = this.runs.get(runId);
+		if (live === void 0) return "not-found";
+		if (live.outcome !== null) return "already-exited";
+		if (live.kind === "local") live.handle.terminate();
+		else {
+			live.killRequested = true;
+			live.handle.kill();
+		}
+		return "ok";
+	}
+	forWorkspace(workspaceId) {
+		const ids = this.liveByWorkspace.get(workspaceId);
+		if (ids === void 0) return [];
+		const live = this.runs.get(ids);
+		if (live === void 0) return [];
+		return [{
+			runId: live.runId,
+			commandName: live.commandName,
+			startedAt: live.startedAt,
+			status: live.outcome === null ? "running" : "exited"
+		}];
+	}
+	/** Every live run id (terminal and running) for fiber cleanup. */
+	listAll() {
+		return [...this.runs.keys()];
+	}
+};
+//#endregion
+//#region src/server/settings.ts
+const QUICK_COMMANDS_NS = settingsNamespace("quick-commands");
+/**
+* One command entry schema. name/command may be EMPTY: the settings card edits
+* rows field-by-field (instant save per keystroke), so a partially-typed row
+* is a legitimate persisted state. Runnable validation happens at run.start.
+*/
+const CommandSchema = z.object({
+	name: z.string(),
+	command: z.string()
+});
+/** One workspace command set. */
+const WorkspaceCommandsSchema = z.object({
+	workspaceId: z.string().min(1),
+	commands: z.array(CommandSchema).max(200)
+});
+const QuickCommandsSettingsSchema = z.object({
+	workspaces: z.array(WorkspaceCommandsSchema).max(500),
+	popupAnchor: z.union([z.const("corner"), z.const("button")]).default("corner"),
+	popupSize: z.object({
+		width: z.number().min(320).max(8192),
+		height: z.number().min(200).max(8192)
+	})
+});
+const DEFAULT_SETTINGS = {
+	workspaces: [],
+	popupAnchor: "corner"
+};
+function registerSettings(ctx) {
+	let current = {
+		...DEFAULT_SETTINGS,
+		workspaces: []
+	};
+	let service;
+	ctx.inject(["settings"], (sctx) => {
+		service = sctx.settings;
+		const scope = service.register(QUICK_COMMANDS_NS, QuickCommandsSettingsSchema);
+		current = scope.get();
+		scope.watch((next) => {
+			current = next;
+		});
+	});
+	async function persist(patch) {
+		if (service === void 0) throw new Error("@fonlan/dsh-quick-commands: settings service is not available in this profile");
+		await service.update(QUICK_COMMANDS_NS, patch);
+	}
+	return {
+		get: () => current,
+		commandsOf: (workspaceId) => {
+			const set = current.workspaces.find((w) => w.workspaceId === workspaceId);
+			return set === void 0 ? [] : set.commands;
+		},
+		setCommands: async (workspaceId, commands) => {
+			const next = current.workspaces.filter((w) => w.workspaceId !== workspaceId);
+			if (commands.length > 0) next.push({
+				workspaceId,
+				commands
+			});
+			await persist({ workspaces: next });
+		},
+		setAnchor: async (anchor) => {
+			await persist({ popupAnchor: anchor });
+		},
+		setPopupSize: async (size) => {
+			await persist({ popupSize: size });
+		}
+	};
+}
+//#endregion
+//#region src/server/rpc.ts
+const API_PREFIX = "/plugins/@fonlan/dsh-quick-commands/api";
+function header(headers, name) {
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+function isTrustedApiRequest(req, trustedHosts) {
+	const host = header(req.headers, "host");
+	if (host === void 0) return false;
+	let hostUrl;
+	try {
+		hostUrl = new URL(`http://${host}`);
+	} catch {
+		return false;
+	}
+	if (!isLoopbackHostname(hostUrl.hostname) && !trustedHosts.includes(hostUrl.host) && !trustedHosts.includes(hostUrl.hostname)) {
+		if (!trustedHosts.some((entry) => entry === hostUrl.hostname || entry === hostUrl.host)) return false;
+	}
+	if (header(req.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = header(req.headers, "origin");
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+function trustedHostsOf(ctx) {
+	for (const entry of ctx.get("loader")?.entries?.() ?? []) if (entry.options?.name === "connection") return entry.options.config?.trustedHosts ?? [];
+	return [];
+}
+function writeJson(res, body) {
+	res.writeHead(200, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(JSON.stringify(body));
+}
+function writeError(res, code, message, status = 400) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(JSON.stringify({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	}));
+}
+function requireString(value, name) {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} 不能为空`);
+	return value;
+}
+async function readJsonBody(req) {
+	const chunks = [];
+	for await (const chunk of req) chunks.push(chunk);
+	const text = Buffer.concat(chunks).toString("utf8");
+	if (text.trim() === "") return {};
+	try {
+		const parsed = JSON.parse(text);
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function registerApiRoutes(ctx, runner, settings) {
+	const fence = (req) => isTrustedApiRequest(req, trustedHostsOf(ctx));
+	const workspaceService = () => ctx.get("workspaceRegistry") ?? ctx.get("workspace");
+	/** Roster: every DSH workspace joined with its command set (for the card). */
+	function roster() {
+		const svc = workspaceService();
+		const config = settings.get();
+		const entries = [];
+		if (svc !== void 0) for (const ws of svc.list()) {
+			const set = config.workspaces.find((w) => w.workspaceId === ws.id);
+			const ref = localPathToRemoteRef(ws.path);
+			entries.push({
+				workspaceId: ws.id,
+				path: ws.path,
+				title: ws.title,
+				...ref !== null ? { remoteHost: ref.hostId } : {},
+				commands: set === void 0 ? [] : set.commands
+			});
+		}
+		else for (const set of config.workspaces) entries.push({
+			workspaceId: set.workspaceId,
+			path: "",
+			title: set.workspaceId,
+			commands: set.commands
+		});
+		return entries;
+	}
+	async function dispatch(method, body) {
+		switch (method) {
+			case "settings.get": return settings.get();
+			case "settings.setCommands": {
+				const workspaceId = requireString(body.workspaceId, "workspaceId");
+				const commandsRaw = body.commands;
+				if (!Array.isArray(commandsRaw)) throw new Error("commands must be an array");
+				const commands = commandsRaw.map((entry) => {
+					if (typeof entry !== "object" || entry === null) throw new Error("invalid command entry");
+					const e = entry;
+					if (typeof e.name !== "string") throw new Error("command name must be a string");
+					if (typeof e.command !== "string") throw new Error("command body must be a string");
+					return {
+						name: e.name,
+						command: e.command
+					};
+				});
+				await settings.setCommands(workspaceId, commands);
+				return settings.get();
+			}
+			case "settings.setAnchor": {
+				const anchor = body.anchor;
+				if (anchor !== "corner" && anchor !== "button") throw new Error("anchor must be corner or button");
+				await settings.setAnchor(anchor);
+				return settings.get();
+			}
+			case "settings.setPopupSize": {
+				const width = body.width;
+				const height = body.height;
+				if (typeof width !== "number" || !Number.isFinite(width) || width < 320 || width > 8192) throw new Error("width must be a number between 320 and 8192");
+				if (typeof height !== "number" || !Number.isFinite(height) || height < 200 || height > 8192) throw new Error("height must be a number between 200 and 8192");
+				await settings.setPopupSize({
+					width: Math.round(width),
+					height: Math.round(height)
+				});
+				return settings.get();
+			}
+			case "workspaces.list": return roster();
+			case "run.start": {
+				const workspaceId = requireString(body.workspaceId, "workspaceId");
+				const commandName = requireString(body.commandName, "commandName");
+				const sessionCwd = requireString(body.sessionCwd, "sessionCwd");
+				const ws = workspaceService()?.get(workspaceId);
+				if (ws === void 0) throw {
+					code: "workspace-not-found",
+					message: `workspace ${workspaceId} is not registered`,
+					status: 404
+				};
+				const entry = settings.commandsOf(workspaceId).find((c) => c.name === commandName);
+				if (entry === void 0) throw {
+					code: "command-not-found",
+					message: `command ${commandName} is not configured for this workspace`,
+					status: 404
+				};
+				if (entry.name.trim() === "" || entry.command.trim() === "") throw {
+					code: "command-empty",
+					message: `command ${commandName} has an empty name or body`,
+					status: 400
+				};
+				const result = await runner.start({
+					workspaceId,
+					workspacePath: ws.path,
+					workspaceTitle: ws.title,
+					commandName: entry.name,
+					command: entry.command,
+					sessionCwd,
+					popupAnchor: settings.get().popupAnchor
+				});
+				if (!result.ok) throw {
+					code: "run-busy",
+					message: result.error,
+					status: 409
+				};
+				const view = runner.poll(result.runId, 0, 0);
+				if (view === null) throw {
+					code: "internal",
+					message: "run not found after start",
+					status: 500
+				};
+				return {
+					runId: result.runId,
+					workspaceId,
+					commandName: entry.name,
+					resolvedCommand: result.resolvedCommand,
+					...result.remoteHost !== void 0 ? { remoteHost: result.remoteHost } : {},
+					status: view.status,
+					exitCode: view.exitCode,
+					signal: view.signal,
+					startedAt: Date.now(),
+					stdoutEnd: view.stdoutEnd,
+					stderrEnd: view.stderrEnd,
+					stdoutDelta: view.stdoutDelta,
+					stderrDelta: view.stderrDelta,
+					stdoutLossy: view.stdoutLossy,
+					stderrLossy: view.stderrLossy
+				};
+			}
+			case "run.poll": {
+				const runId = requireString(body.runId, "runId");
+				const stdoutFrom = typeof body.stdoutFrom === "number" ? body.stdoutFrom : 0;
+				const stderrFrom = typeof body.stderrFrom === "number" ? body.stderrFrom : 0;
+				const view = runner.poll(runId, stdoutFrom, stderrFrom);
+				if (view === null) throw {
+					code: "run-not-found",
+					message: "run not found (expired or unknown)",
+					status: 404
+				};
+				return view;
+			}
+			case "run.kill": {
+				const runId = requireString(body.runId, "runId");
+				const result = runner.kill(runId);
+				if (result === "not-found") throw {
+					code: "run-not-found",
+					message: "run not found",
+					status: 404
+				};
+				return { killed: result === "ok" };
+			}
+			case "run.list": {
+				const workspaceId = requireString(body.workspaceId, "workspaceId");
+				return runner.forWorkspace(workspaceId);
+			}
+			default: throw {
+				code: "method-not-found",
+				message: `unknown method ${method}`,
+				status: 404
+			};
+		}
+	}
+	const webServer = ctx.get("webServer");
+	if (webServer === void 0) return () => void 0;
+	return ctx.effect(() => {
+		return webServer.register({
+			kind: "prefix",
+			path: API_PREFIX,
+			handler: async (req, res) => {
+				if (!fence(req)) {
+					writeError(res, "forbidden", "forbidden", 403);
+					return;
+				}
+				if (req.method !== "POST") {
+					writeError(res, "method", "method not allowed", 405);
+					return;
+				}
+				const method = new URL(req.url ?? "", "http://placeholder").pathname.slice(40);
+				const payload = await readJsonBody(req);
+				try {
+					writeJson(res, {
+						ok: true,
+						value: await dispatch(method, payload)
+					});
+				} catch (error) {
+					const e = error;
+					writeError(res, e.code ?? "error", e.message ?? String(error), e.status ?? 400);
+				}
+			}
+		});
+	}, "quick-commands: api routes");
+}
+//#endregion
+//#region src/index.ts
+const name = "@fonlan/dsh-quick-commands";
+const inject = ["settings"];
+/** No plugin-level config; all configuration lives in the settings namespace. */
+function apply(ctx) {
+	const settings = registerSettings(ctx);
+	const subprocess = ctx.get("subprocess");
+	if (subprocess === void 0) {
+		ctx.logger?.warn?.("@fonlan/dsh-quick-commands: subprocess service unavailable; commands cannot run");
+		return;
+	}
+	const resolveRemote = () => {
+		const sshPool = ctx.get("sshPool");
+		if (sshPool === void 0 || typeof sshPool.acquire !== "function" || typeof sshPool.release !== "function") return;
+		return {
+			pool: sshPool,
+			resolveHost: (hostId) => readHostConfig((ns) => {
+				try {
+					return ctx.get("settings")?.get(ns);
+				} catch {
+					return;
+				}
+			}, hostId)
+		};
+	};
+	const runner = new QuickCommandRunner(subprocess, () => resolveRemote());
+	ctx.effect(() => registerApiRoutes(ctx, runner, settings), "quick-commands: api routes");
+	ctx.effect(() => () => {
+		for (const id of runner.listAll()) runner.kill(id);
+	}, "quick-commands: process cleanup");
+}
+//#endregion
+export { apply, inject, name };