@camstack/addon-terminal 0.1.1 → 0.1.2

package/dist/addon.js

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
+let node_fs = require("node:fs");
+let node_path = require("node:path");
 //#region ../types/dist/event-category-BLcNejAE.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -26081,6 +26083,40 @@ Object.freeze({
 });
 //#endregion
 //#region src/pty.ts
+/**
+* Minimal pty abstraction. The manager depends on this interface, never on
+* `node-pty` directly, so its tests spawn no real process and the native
+* module is imported lazily (only when a real session opens on the host).
+*
+* `child_process.spawn` is deliberately NOT used: a plain pipe is NOT-A-TTY, so
+* a full-screen program (`btm`) gets no terminal and no runtime resize channel.
+* See docs/design/2026-07-26-terminal-session-design.md ("The pty").
+*/
+/**
+* Resolve `file` to an executable path the way a shell would: a path-qualified
+* name is checked directly, a bare name is searched on `PATH`. Returns the
+* resolved absolute path, or `null` when nothing executable matches — the
+* caller turns that into a clear "binary not found" error BEFORE spawning,
+* instead of a pty that dies at 127 and vanishes with no visible cause.
+*/
+function resolveExecutable(file) {
+	if (file.includes("/")) return isExecutableFile(file) ? file : null;
+	const dirs = (process.env.PATH ?? "").split(node_path.delimiter).filter((d) => d.length > 0);
+	for (const dir of dirs) {
+		const candidate = (0, node_path.join)(dir, file);
+		if (isExecutableFile(candidate)) return candidate;
+	}
+	return null;
+}
+function isExecutableFile(p) {
+	try {
+		if (!(0, node_fs.statSync)(p).isFile()) return false;
+		(0, node_fs.accessSync)(p, node_fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
 var cachedModule = null;
 async function loadNodePty() {
 	if (cachedModule) return cachedModule;
@@ -26142,7 +26178,7 @@ function parsePath(url) {
 	};
 }
 function handleOut(manager, sessionId, req, res) {
-	if (!manager.hasSession(sessionId)) {
+	if (!manager.hasEntry(sessionId)) {
 		res.writeHead(404, { "content-type": "text/plain" });
 		res.end("no such session");
 		return;
@@ -26264,6 +26300,13 @@ function findProfile(profiles, profileId) {
 var MIN_GRID = 1;
 var MAX_COLS = 1e3;
 var MAX_ROWS = 500;
+/**
+* How long an exited session is kept addressable so a GET /out that arrives
+* AFTER the pty died still delivers the `exit` event (with its code) to the UI,
+* instead of a bare 404 that renders as a blank terminal. A process that fails
+* to start (missing binary → exit 127) is the common case this makes visible.
+*/
+var EXITED_RETENTION_MS = 1e4;
 function clampDimension(value, max) {
 	if (!Number.isFinite(value)) return MIN_GRID;
 	const int = Math.floor(value);
@@ -26277,6 +26320,7 @@ var TerminalSessionManager = class {
 	profiles;
 	mintId;
 	now;
+	resolveBinary;
 	constructor(opts) {
 		this.opts = opts;
 		this.profiles = buildProfiles({
@@ -26286,6 +26330,7 @@ var TerminalSessionManager = class {
 		});
 		this.mintId = opts.mintId ?? (() => crypto.randomUUID());
 		this.now = opts.now ?? (() => Date.now());
+		this.resolveBinary = opts.resolveBinary ?? ((file) => file);
 	}
 	/** Re-derive the allowlist after a settings change. */
 	reconfigureProfiles(config) {
@@ -26308,8 +26353,10 @@ var TerminalSessionManager = class {
 		const cols = clampDimension(input.cols, MAX_COLS);
 		const rows = clampDimension(input.rows, MAX_ROWS);
 		const sessionId = this.mintId();
+		const resolvedFile = this.resolveBinary(profile.file);
+		if (resolvedFile === null) throw new Error(`Terminal profile '${profile.profileId}' cannot start: executable '${profile.file}' was not found on PATH. Install it in the server image or set its path in Terminal settings.`);
 		const pty = this.opts.spawn({
-			file: profile.file,
+			file: resolvedFile,
 			args: profile.args,
 			cols,
 			rows,
@@ -26354,7 +26401,11 @@ var TerminalSessionManager = class {
 			} catch {}
 			session.sinks.clear();
 			session.screen.dispose();
-			this.sessions.delete(sessionId);
+			const retire = setTimeout(() => {
+				this.sessions.delete(sessionId);
+			}, EXITED_RETENTION_MS);
+			retire.unref?.();
+			session.retireTimer = retire;
 		});
 		this.opts.logger.info("terminal: session opened", { meta: {
 			sessionId,
@@ -26395,6 +26446,15 @@ var TerminalSessionManager = class {
 		return s !== void 0 && !s.exited;
 	}
 	/**
+	* True when the session is still addressable — including an EXITED one inside
+	* its retention window. `handleOut` gates on this (not `hasSession`) so the
+	* exit event reaches the UI; live-only paths (`writeInput`) gate on
+	* `hasSession`.
+	*/
+	hasEntry(sessionId) {
+		return this.sessions.has(sessionId);
+	}
+	/**
 	* Attach an output sink. Immediately pushes a full-screen repaint (the current
 	* authoritative buffer) so a fresh xterm.js is in sync, then streams live
 	* output. Returns a detach function.
@@ -26428,6 +26488,7 @@ var TerminalSessionManager = class {
 	/** Kill every live session — called on addon shutdown. */
 	disposeAll() {
 		for (const session of this.sessions.values()) {
+			if (session.retireTimer !== void 0) clearTimeout(session.retireTimer);
 			try {
 				session.pty.kill();
 			} catch {}
@@ -31290,6 +31351,7 @@ var TerminalAddon = class extends BaseAddon {
 		const manager = new TerminalSessionManager({
 			spawn: createNodePtySpawner(),
 			screenFactory: createXtermScreen,
+			resolveBinary: resolveExecutable,
 			logger: this.ctx.logger,
 			btmPath: this.config.btmPath,
 			allowShell: this.config.allowShell,

package/dist/addon.mjs

@@ -1,3 +1,5 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
@@ -26080,6 +26082,40 @@ Object.freeze({
 });
 //#endregion
 //#region src/pty.ts
+/**
+* Minimal pty abstraction. The manager depends on this interface, never on
+* `node-pty` directly, so its tests spawn no real process and the native
+* module is imported lazily (only when a real session opens on the host).
+*
+* `child_process.spawn` is deliberately NOT used: a plain pipe is NOT-A-TTY, so
+* a full-screen program (`btm`) gets no terminal and no runtime resize channel.
+* See docs/design/2026-07-26-terminal-session-design.md ("The pty").
+*/
+/**
+* Resolve `file` to an executable path the way a shell would: a path-qualified
+* name is checked directly, a bare name is searched on `PATH`. Returns the
+* resolved absolute path, or `null` when nothing executable matches — the
+* caller turns that into a clear "binary not found" error BEFORE spawning,
+* instead of a pty that dies at 127 and vanishes with no visible cause.
+*/
+function resolveExecutable(file) {
+	if (file.includes("/")) return isExecutableFile(file) ? file : null;
+	const dirs = (process.env.PATH ?? "").split(delimiter).filter((d) => d.length > 0);
+	for (const dir of dirs) {
+		const candidate = join(dir, file);
+		if (isExecutableFile(candidate)) return candidate;
+	}
+	return null;
+}
+function isExecutableFile(p) {
+	try {
+		if (!statSync(p).isFile()) return false;
+		accessSync(p, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
 var cachedModule = null;
 async function loadNodePty() {
 	if (cachedModule) return cachedModule;
@@ -26141,7 +26177,7 @@ function parsePath(url) {
 	};
 }
 function handleOut(manager, sessionId, req, res) {
-	if (!manager.hasSession(sessionId)) {
+	if (!manager.hasEntry(sessionId)) {
 		res.writeHead(404, { "content-type": "text/plain" });
 		res.end("no such session");
 		return;
@@ -26263,6 +26299,13 @@ function findProfile(profiles, profileId) {
 var MIN_GRID = 1;
 var MAX_COLS = 1e3;
 var MAX_ROWS = 500;
+/**
+* How long an exited session is kept addressable so a GET /out that arrives
+* AFTER the pty died still delivers the `exit` event (with its code) to the UI,
+* instead of a bare 404 that renders as a blank terminal. A process that fails
+* to start (missing binary → exit 127) is the common case this makes visible.
+*/
+var EXITED_RETENTION_MS = 1e4;
 function clampDimension(value, max) {
 	if (!Number.isFinite(value)) return MIN_GRID;
 	const int = Math.floor(value);
@@ -26276,6 +26319,7 @@ var TerminalSessionManager = class {
 	profiles;
 	mintId;
 	now;
+	resolveBinary;
 	constructor(opts) {
 		this.opts = opts;
 		this.profiles = buildProfiles({
@@ -26285,6 +26329,7 @@ var TerminalSessionManager = class {
 		});
 		this.mintId = opts.mintId ?? (() => crypto.randomUUID());
 		this.now = opts.now ?? (() => Date.now());
+		this.resolveBinary = opts.resolveBinary ?? ((file) => file);
 	}
 	/** Re-derive the allowlist after a settings change. */
 	reconfigureProfiles(config) {
@@ -26307,8 +26352,10 @@ var TerminalSessionManager = class {
 		const cols = clampDimension(input.cols, MAX_COLS);
 		const rows = clampDimension(input.rows, MAX_ROWS);
 		const sessionId = this.mintId();
+		const resolvedFile = this.resolveBinary(profile.file);
+		if (resolvedFile === null) throw new Error(`Terminal profile '${profile.profileId}' cannot start: executable '${profile.file}' was not found on PATH. Install it in the server image or set its path in Terminal settings.`);
 		const pty = this.opts.spawn({
-			file: profile.file,
+			file: resolvedFile,
 			args: profile.args,
 			cols,
 			rows,
@@ -26353,7 +26400,11 @@ var TerminalSessionManager = class {
 			} catch {}
 			session.sinks.clear();
 			session.screen.dispose();
-			this.sessions.delete(sessionId);
+			const retire = setTimeout(() => {
+				this.sessions.delete(sessionId);
+			}, EXITED_RETENTION_MS);
+			retire.unref?.();
+			session.retireTimer = retire;
 		});
 		this.opts.logger.info("terminal: session opened", { meta: {
 			sessionId,
@@ -26394,6 +26445,15 @@ var TerminalSessionManager = class {
 		return s !== void 0 && !s.exited;
 	}
 	/**
+	* True when the session is still addressable — including an EXITED one inside
+	* its retention window. `handleOut` gates on this (not `hasSession`) so the
+	* exit event reaches the UI; live-only paths (`writeInput`) gate on
+	* `hasSession`.
+	*/
+	hasEntry(sessionId) {
+		return this.sessions.has(sessionId);
+	}
+	/**
 	* Attach an output sink. Immediately pushes a full-screen repaint (the current
 	* authoritative buffer) so a fresh xterm.js is in sync, then streams live
 	* output. Returns a detach function.
@@ -26427,6 +26487,7 @@ var TerminalSessionManager = class {
 	/** Kill every live session — called on addon shutdown. */
 	disposeAll() {
 		for (const session of this.sessions.values()) {
+			if (session.retireTimer !== void 0) clearTimeout(session.retireTimer);
 			try {
 				session.pty.kill();
 			} catch {}
@@ -31289,6 +31350,7 @@ var TerminalAddon = class extends BaseAddon {
 		const manager = new TerminalSessionManager({
 			spawn: createNodePtySpawner(),
 			screenFactory: createXtermScreen,
+			resolveBinary: resolveExecutable,
 			logger: this.ctx.logger,
 			btmPath: this.config.btmPath,
 			allowShell: this.config.allowShell,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-terminal",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Interactive terminal sessions (pty + xterm) as a CamStack addon",
   "keywords": [
     "camstack",