@devframes/plugin-terminals 0.0.1

package/dist/rpc-F1ncx7tt.mjs

@@ -0,0 +1,247 @@
+import { defineRpcFunction } from "devframe";
+import * as v from "valibot";
+import { colors } from "devframe/utils/colors";
+import { defineDiagnostics } from "nostics";
+import { ansiFormatter } from "nostics/formatters/ansi";
+//#region src/node/diagnostics.ts
+const formatAnsi = ansiFormatter(colors);
+function reporter(d, { method = "warn" } = {}) {
+	console[method](formatAnsi(d));
+}
+/**
+* Structured diagnostics for the terminals plugin. Uses the plugin's own
+* `DP_TERMINALS_` prefix per the built-in plugin convention, keeping it
+* collision-free with devframe core (`DF`) and the hub (`DF8xxx`).
+*/
+const diagnostics = defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	reporters: [reporter],
+	codes: {
+		DP_TERMINALS_0001: {
+			why: (p) => `Terminal session "${p.id}" does not exist`,
+			fix: "Spawn a session first, or refresh the session list."
+		},
+		DP_TERMINALS_0002: {
+			why: (p) => `Spawning the arbitrary command "${p.command}" is not allowed`,
+			fix: "Add it to `presets`, or pass `allowArbitraryCommands: true` to createTerminalsDevframe()."
+		},
+		DP_TERMINALS_0003: {
+			why: (p) => `Cannot write to read-only terminal session "${p.id}"`,
+			fix: "Spawn the session with `mode: \"interactive\"` to accept input."
+		},
+		DP_TERMINALS_0004: { why: (p) => `Failed to spawn "${p.command}": ${p.reason}` },
+		DP_TERMINALS_0005: {
+			why: "Native PTY bindings (zigpty) are unavailable; interactive sessions fall back to pipe-based terminal emulation. Full-screen TUIs may not render correctly.",
+			fix: "Check that this platform is covered by zigpty's prebuilds (Linux/macOS/Windows, x64/arm64, glibc/musl) and that the dependency installed intact."
+		},
+		DP_TERMINALS_0006: { why: (p) => `Unknown terminal preset "${p.id}"` },
+		DP_TERMINALS_0007: {
+			why: "Terminals manager is not initialised on this context",
+			fix: "Call setupTerminals(ctx) (or use createTerminalsDevframe) before invoking terminal RPCs."
+		}
+	}
+});
+//#endregion
+//#region src/node/context.ts
+const managers = /* @__PURE__ */ new WeakMap();
+function setTerminalManager(ctx, manager) {
+	managers.set(ctx, manager);
+}
+function getTerminalManager(ctx) {
+	const manager = managers.get(ctx);
+	if (!manager) throw diagnostics.DP_TERMINALS_0007({});
+	return manager;
+}
+//#endregion
+//#region src/rpc/schemas.ts
+const terminalModeSchema = v.picklist(["interactive", "readonly"]);
+const spawnRequestSchema = v.object({
+	presetId: v.optional(v.string()),
+	command: v.optional(v.string()),
+	args: v.optional(v.array(v.string())),
+	cwd: v.optional(v.string()),
+	mode: v.optional(terminalModeSchema),
+	title: v.optional(v.string()),
+	cols: v.optional(v.number()),
+	rows: v.optional(v.number()),
+	env: v.optional(v.record(v.string(), v.string()))
+});
+const sessionInfoSchema = v.object({
+	id: v.string(),
+	title: v.string(),
+	processName: v.optional(v.string()),
+	customTitle: v.optional(v.string()),
+	mode: terminalModeSchema,
+	status: v.picklist([
+		"running",
+		"exited",
+		"error"
+	]),
+	backend: v.picklist(["pty", "pipe"]),
+	command: v.string(),
+	args: v.array(v.string()),
+	cwd: v.string(),
+	cols: v.number(),
+	rows: v.number(),
+	pid: v.optional(v.number()),
+	exitCode: v.optional(v.number()),
+	icon: v.optional(v.string()),
+	channel: v.optional(v.string()),
+	presetId: v.optional(v.string()),
+	createdAt: v.number()
+});
+const presetSchema = v.object({
+	id: v.string(),
+	title: v.string(),
+	command: v.string(),
+	args: v.array(v.string()),
+	mode: terminalModeSchema,
+	icon: v.optional(v.string())
+});
+//#endregion
+//#region src/rpc/functions/list.ts
+const list = defineRpcFunction({
+	name: "devframes-plugin-terminals:list",
+	type: "query",
+	jsonSerializable: true,
+	snapshot: true,
+	args: [],
+	returns: v.array(sessionInfoSchema),
+	agent: {
+		description: "List the current terminal sessions with their status, mode, and command.",
+		safety: "read"
+	},
+	setup: (ctx) => ({ handler: () => getTerminalManager(ctx).list() })
+});
+//#endregion
+//#region src/rpc/functions/presets.ts
+const presets = defineRpcFunction({
+	name: "devframes-plugin-terminals:presets",
+	type: "query",
+	jsonSerializable: true,
+	snapshot: true,
+	args: [],
+	returns: v.array(presetSchema),
+	setup: (ctx) => ({ handler: () => getTerminalManager(ctx).getPresets().map((p) => ({
+		id: p.id,
+		title: p.title,
+		command: p.command,
+		args: p.args ?? [],
+		mode: p.mode ?? "readonly",
+		icon: p.icon
+	})) })
+});
+//#endregion
+//#region src/rpc/functions/remove.ts
+const remove = defineRpcFunction({
+	name: "devframes-plugin-terminals:remove",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ id: v.string() })],
+	returns: v.void(),
+	agent: {
+		description: "Kill a terminal session and discard it (process, stream, and scrollback).",
+		safety: "destructive"
+	},
+	setup: (ctx) => ({ handler: ({ id }) => {
+		getTerminalManager(ctx).remove(id);
+	} })
+});
+//#endregion
+//#region src/rpc/functions/rename.ts
+const rename = defineRpcFunction({
+	name: "devframes-plugin-terminals:rename",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({
+		id: v.string(),
+		title: v.string()
+	})],
+	returns: v.void(),
+	setup: (ctx) => ({ handler: ({ id, title }) => {
+		getTerminalManager(ctx).rename(id, title);
+	} })
+});
+//#endregion
+//#region src/rpc/functions/resize.ts
+const resize = defineRpcFunction({
+	name: "devframes-plugin-terminals:resize",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({
+		id: v.string(),
+		cols: v.pipe(v.number(), v.integer(), v.minValue(1)),
+		rows: v.pipe(v.number(), v.integer(), v.minValue(1))
+	})],
+	returns: v.void(),
+	setup: (ctx) => ({ handler: ({ id, cols, rows }) => {
+		getTerminalManager(ctx).resize(id, cols, rows);
+	} })
+});
+//#endregion
+//#region src/rpc/functions/restart.ts
+const restart = defineRpcFunction({
+	name: "devframes-plugin-terminals:restart",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ id: v.string() })],
+	returns: sessionInfoSchema,
+	setup: (ctx) => ({ handler: ({ id }) => getTerminalManager(ctx).restart(id) })
+});
+//#endregion
+//#region src/rpc/functions/spawn.ts
+const spawn = defineRpcFunction({
+	name: "devframes-plugin-terminals:spawn",
+	type: "action",
+	jsonSerializable: true,
+	args: [spawnRequestSchema],
+	returns: sessionInfoSchema,
+	agent: {
+		description: "Spawn a new terminal session. Pass a preset id, or a command + mode. Interactive sessions accept input; readonly sessions only stream output.",
+		safety: "action"
+	},
+	setup: (ctx) => ({ handler: (req) => getTerminalManager(ctx).spawn(req ?? {}) })
+});
+//#endregion
+//#region src/rpc/functions/terminate.ts
+const terminate = defineRpcFunction({
+	name: "devframes-plugin-terminals:terminate",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ id: v.string() })],
+	returns: v.void(),
+	agent: {
+		description: "Terminate a terminal session's running process. The session and its scrollback are kept; use restart to run it again.",
+		safety: "destructive"
+	},
+	setup: (ctx) => ({ handler: ({ id }) => {
+		getTerminalManager(ctx).terminate(id);
+	} })
+});
+//#endregion
+//#region src/rpc/index.ts
+const serverFunctions = [
+	list,
+	presets,
+	spawn,
+	defineRpcFunction({
+		name: "devframes-plugin-terminals:write",
+		type: "action",
+		jsonSerializable: true,
+		args: [v.object({
+			id: v.string(),
+			data: v.string()
+		})],
+		returns: v.void(),
+		setup: (ctx) => ({ handler: ({ id, data }) => {
+			getTerminalManager(ctx).write(id, data);
+		} })
+	}),
+	resize,
+	terminate,
+	restart,
+	rename,
+	remove
+];
+//#endregion
+export { diagnostics as i, getTerminalManager as n, setTerminalManager as r, serverFunctions as t };