@camstack/addon-terminal 0.1.1 → 0.1.3

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";
@@ -7505,16 +7507,23 @@ var StorageLocationDeclarationSchema = object({
 	* Which node root the seeded `<id>:default` instance is placed under on a
 	* FRESH install:
 	* - `'data'` (default) — the node's data dir (`CAMSTACK_DATA` / boot dir),
-	*   the appData volume. Right for small/durable data (backups, logs, models).
+	*   the appData volume. Right for small/durable data (logs, models).
 	* - `'media'` — the dedicated media volume (`CAMSTACK_MEDIA_ROOT`) when that
 	*   env is set, else falls back to the data root. Right for bulky, hot media
 	*   (recordings, event media) that should stay off the appData disk.
+	* - `'backup'` — the dedicated backup volume (`CAMSTACK_BACKUP_ROOT`, default
+	*   `/backups` in the image) so archives live on their own mount rather than
+	*   filling the appData disk. Falls back to the data root when unset.
 	*
 	* Only affects the seeded default's `basePath`; operators can repoint any
 	* location afterwards, and a `defaultsTo` slot inherits its parent's root
 	* regardless of this field. Absent (the common case) is treated as `'data'`.
 	*/
-	defaultRoot: _enum(["data", "media"]).optional()
+	defaultRoot: _enum([
+		"data",
+		"media",
+		"backup"
+	]).optional()
 });
 var DecoderStatsSchema = object({
 	inputFps: number(),
@@ -14526,11 +14535,53 @@ var LocationStatSchema = object({
 	fileCount: number(),
 	present: boolean()
 });
+/**
+* A backup schedule — the N:M "entry" that binds one cron cadence to a
+* SET of destination locations. Supersedes the per-location cron on
+* `BackupDestinationPolicy`: an operator creates a schedule, picks the
+* `backups` locations it should write to, and the orchestrator fans a
+* single archive out to all of them when the cron fires.
+*
+* `retentionCount` is per-schedule (D-decision 2026-07-28): every
+* location targeted by this schedule keeps this many archives from
+* this schedule's runs.
+*
+* `dataSources` optionally narrows which top-level state locations
+* (db, addons, tls, …) are archived; omitted = the orchestrator's
+* default full set.
+*/
+var BackupScheduleSchema = object({
+	/** Stable id. Generated by the orchestrator on first upsert if absent. */
+	id: string(),
+	/** Operator-facing display name. */
+	label: string(),
+	/** 5-field POSIX cron. Empty = disabled cadence (kept for editing). */
+	cron: string(),
+	/** Master on/off toggle for the whole schedule. */
+	enabled: boolean(),
+	/** `backups`-location ids this schedule writes to (fan-out set). */
+	locationIds: array(string()).readonly(),
+	/** Archives kept per targeted location for this schedule. */
+	retentionCount: number().int().min(1).max(1e3),
+	/** Optional subset of source locations to include; omitted = all. */
+	dataSources: array(string()).readonly().optional(),
+	/** ms-epoch of last successful run. */
+	lastRunAt: number().optional(),
+	/** ms-epoch of next computed firing (read-only, filled on list). */
+	nextRunAt: number().optional()
+});
 method(_void(), array(BackupDestinationInfoSchema).readonly(), { auth: "admin" }), method(object({
 	/** Subset of registered `backup-destination` addon ids to write to. */
 	destinations: array(string()).optional(),
 	locations: array(string()).optional(),
-	label: string().optional()
+	label: string().optional(),
+	/**
+	* Per-run retention override applied to every targeted
+	* destination. Used by schedule-driven runs (per-entry
+	* retention). Omitted = each destination's own policy
+	* retention (manual runs).
+	*/
+	retentionCount: number().int().min(1).max(1e3).optional()
 }).optional(), array(BackupEntrySchema).readonly(), {
 	kind: "mutation",
 	auth: "admin"
@@ -14579,7 +14630,21 @@ method(_void(), array(BackupDestinationInfoSchema).readonly(), { auth: "admin" }
 	ok: boolean(),
 	error: string().optional(),
 	nextRuns: array(number()).readonly()
-}));
+})), method(_void(), array(BackupScheduleSchema).readonly(), { auth: "admin" }), method(object({
+	id: string().optional(),
+	label: string(),
+	cron: string(),
+	enabled: boolean(),
+	locationIds: array(string()).readonly(),
+	retentionCount: number().int().min(1).max(1e3),
+	dataSources: array(string()).readonly().optional()
+}), BackupScheduleSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ id: string() }), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
 /**
 * `broker` — unified pub/sub broker registry, system-scoped collection.
 *
@@ -21701,6 +21766,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"backup.deleteSchedule": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"backup.getEntries": {
 		capName: "backup",
 		capScope: "system",
@@ -21731,6 +21802,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"backup.listSchedules": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"backup.previewSchedule": {
 		capName: "backup",
 		capScope: "system",
@@ -21755,6 +21832,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"backup.upsertSchedule": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"battery.wakeForStream": {
 		capName: "battery",
 		capScope: "device",
@@ -26081,6 +26164,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 +26259,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 +26381,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 +26401,7 @@ var TerminalSessionManager = class {
 	profiles;
 	mintId;
 	now;
+	resolveBinary;
 	constructor(opts) {
 		this.opts = opts;
 		this.profiles = buildProfiles({
@@ -26286,6 +26411,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 +26434,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 +26482,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 +26527,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 +26569,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 +31432,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
@@ -7504,16 +7506,23 @@ var StorageLocationDeclarationSchema = object({
 	* Which node root the seeded `<id>:default` instance is placed under on a
 	* FRESH install:
 	* - `'data'` (default) — the node's data dir (`CAMSTACK_DATA` / boot dir),
-	*   the appData volume. Right for small/durable data (backups, logs, models).
+	*   the appData volume. Right for small/durable data (logs, models).
 	* - `'media'` — the dedicated media volume (`CAMSTACK_MEDIA_ROOT`) when that
 	*   env is set, else falls back to the data root. Right for bulky, hot media
 	*   (recordings, event media) that should stay off the appData disk.
+	* - `'backup'` — the dedicated backup volume (`CAMSTACK_BACKUP_ROOT`, default
+	*   `/backups` in the image) so archives live on their own mount rather than
+	*   filling the appData disk. Falls back to the data root when unset.
 	*
 	* Only affects the seeded default's `basePath`; operators can repoint any
 	* location afterwards, and a `defaultsTo` slot inherits its parent's root
 	* regardless of this field. Absent (the common case) is treated as `'data'`.
 	*/
-	defaultRoot: _enum(["data", "media"]).optional()
+	defaultRoot: _enum([
+		"data",
+		"media",
+		"backup"
+	]).optional()
 });
 var DecoderStatsSchema = object({
 	inputFps: number(),
@@ -14525,11 +14534,53 @@ var LocationStatSchema = object({
 	fileCount: number(),
 	present: boolean()
 });
+/**
+* A backup schedule — the N:M "entry" that binds one cron cadence to a
+* SET of destination locations. Supersedes the per-location cron on
+* `BackupDestinationPolicy`: an operator creates a schedule, picks the
+* `backups` locations it should write to, and the orchestrator fans a
+* single archive out to all of them when the cron fires.
+*
+* `retentionCount` is per-schedule (D-decision 2026-07-28): every
+* location targeted by this schedule keeps this many archives from
+* this schedule's runs.
+*
+* `dataSources` optionally narrows which top-level state locations
+* (db, addons, tls, …) are archived; omitted = the orchestrator's
+* default full set.
+*/
+var BackupScheduleSchema = object({
+	/** Stable id. Generated by the orchestrator on first upsert if absent. */
+	id: string(),
+	/** Operator-facing display name. */
+	label: string(),
+	/** 5-field POSIX cron. Empty = disabled cadence (kept for editing). */
+	cron: string(),
+	/** Master on/off toggle for the whole schedule. */
+	enabled: boolean(),
+	/** `backups`-location ids this schedule writes to (fan-out set). */
+	locationIds: array(string()).readonly(),
+	/** Archives kept per targeted location for this schedule. */
+	retentionCount: number().int().min(1).max(1e3),
+	/** Optional subset of source locations to include; omitted = all. */
+	dataSources: array(string()).readonly().optional(),
+	/** ms-epoch of last successful run. */
+	lastRunAt: number().optional(),
+	/** ms-epoch of next computed firing (read-only, filled on list). */
+	nextRunAt: number().optional()
+});
 method(_void(), array(BackupDestinationInfoSchema).readonly(), { auth: "admin" }), method(object({
 	/** Subset of registered `backup-destination` addon ids to write to. */
 	destinations: array(string()).optional(),
 	locations: array(string()).optional(),
-	label: string().optional()
+	label: string().optional(),
+	/**
+	* Per-run retention override applied to every targeted
+	* destination. Used by schedule-driven runs (per-entry
+	* retention). Omitted = each destination's own policy
+	* retention (manual runs).
+	*/
+	retentionCount: number().int().min(1).max(1e3).optional()
 }).optional(), array(BackupEntrySchema).readonly(), {
 	kind: "mutation",
 	auth: "admin"
@@ -14578,7 +14629,21 @@ method(_void(), array(BackupDestinationInfoSchema).readonly(), { auth: "admin" }
 	ok: boolean(),
 	error: string().optional(),
 	nextRuns: array(number()).readonly()
-}));
+})), method(_void(), array(BackupScheduleSchema).readonly(), { auth: "admin" }), method(object({
+	id: string().optional(),
+	label: string(),
+	cron: string(),
+	enabled: boolean(),
+	locationIds: array(string()).readonly(),
+	retentionCount: number().int().min(1).max(1e3),
+	dataSources: array(string()).readonly().optional()
+}), BackupScheduleSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ id: string() }), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
 /**
 * `broker` — unified pub/sub broker registry, system-scoped collection.
 *
@@ -21700,6 +21765,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"backup.deleteSchedule": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"backup.getEntries": {
 		capName: "backup",
 		capScope: "system",
@@ -21730,6 +21801,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"backup.listSchedules": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"backup.previewSchedule": {
 		capName: "backup",
 		capScope: "system",
@@ -21754,6 +21831,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"backup.upsertSchedule": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"battery.wakeForStream": {
 		capName: "battery",
 		capScope: "device",
@@ -26080,6 +26163,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 +26258,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 +26380,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 +26400,7 @@ var TerminalSessionManager = class {
 	profiles;
 	mintId;
 	now;
+	resolveBinary;
 	constructor(opts) {
 		this.opts = opts;
 		this.profiles = buildProfiles({
@@ -26285,6 +26410,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 +26433,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 +26481,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 +26526,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 +26568,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 +31431,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.3",
   "description": "Interactive terminal sessions (pty + xterm) as a CamStack addon",
   "keywords": [
     "camstack",