@devframes/plugin-terminals 0.0.1

package/dist/constants.d.mts

@@ -0,0 +1,30 @@
+//#region src/constants.d.ts
+/** Stable devframe id for the terminals plugin. */
+declare const PLUGIN_ID = "devframes-plugin-terminals";
+/**
+ * Streaming channel carrying terminal output. Each session is a stream
+ * keyed by the session id, so clients subscribe by id the moment they
+ * see a session in the shared-state list.
+ */
+declare const TERMINAL_STREAM_CHANNEL = "devframes-plugin-terminals:output";
+/**
+ * Streaming channel the hub's own terminals subsystem (`ctx.terminals`) uses
+ * for aggregated sessions contributed by *other* devframes (e.g. code-server).
+ * Mirrors `@devframes/hub`'s internal channel name; the plugin surfaces those
+ * sessions read-only and reads their output from here. Kept as a literal so the
+ * plugin needs no build dependency on the hub.
+ */
+declare const HUB_TERMINAL_STREAM_CHANNEL = "devframe:terminals";
+/** Shared-state key holding the serializable session list. */
+declare const SESSIONS_STATE_KEY = "devframes-plugin-terminals:sessions";
+/** Shared-state key holding the spawnable command presets. */
+declare const PRESETS_STATE_KEY = "devframes-plugin-terminals:presets";
+/** Default dev-server port for the standalone CLI. */
+declare const DEFAULT_PORT = 9011;
+/** Default number of output chunks retained for replay on reconnect. */
+declare const DEFAULT_SCROLLBACK = 5000;
+/** Default terminal geometry before the client reports its real size. */
+declare const DEFAULT_COLS = 80;
+declare const DEFAULT_ROWS = 24;
+//#endregion
+export { DEFAULT_COLS, DEFAULT_PORT, DEFAULT_ROWS, DEFAULT_SCROLLBACK, HUB_TERMINAL_STREAM_CHANNEL, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, TERMINAL_STREAM_CHANNEL };

package/dist/constants.mjs

@@ -0,0 +1,30 @@
+//#region src/constants.ts
+/** Stable devframe id for the terminals plugin. */
+const PLUGIN_ID = "devframes-plugin-terminals";
+/**
+* Streaming channel carrying terminal output. Each session is a stream
+* keyed by the session id, so clients subscribe by id the moment they
+* see a session in the shared-state list.
+*/
+const TERMINAL_STREAM_CHANNEL = "devframes-plugin-terminals:output";
+/**
+* Streaming channel the hub's own terminals subsystem (`ctx.terminals`) uses
+* for aggregated sessions contributed by *other* devframes (e.g. code-server).
+* Mirrors `@devframes/hub`'s internal channel name; the plugin surfaces those
+* sessions read-only and reads their output from here. Kept as a literal so the
+* plugin needs no build dependency on the hub.
+*/
+const HUB_TERMINAL_STREAM_CHANNEL = "devframe:terminals";
+/** Shared-state key holding the serializable session list. */
+const SESSIONS_STATE_KEY = "devframes-plugin-terminals:sessions";
+/** Shared-state key holding the spawnable command presets. */
+const PRESETS_STATE_KEY = "devframes-plugin-terminals:presets";
+/** Default dev-server port for the standalone CLI. */
+const DEFAULT_PORT = 9011;
+/** Default number of output chunks retained for replay on reconnect. */
+const DEFAULT_SCROLLBACK = 5e3;
+/** Default terminal geometry before the client reports its real size. */
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+//#endregion
+export { DEFAULT_COLS, DEFAULT_PORT, DEFAULT_ROWS, DEFAULT_SCROLLBACK, HUB_TERMINAL_STREAM_CHANNEL, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, TERMINAL_STREAM_CHANNEL };

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import { SpawnRequest, TerminalBackend, TerminalMode, TerminalPreset, TerminalSessionInfo, TerminalStatus, TerminalsOptions, TerminalsSharedState } from "./types.mjs";
+import { DEFAULT_PORT, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, TERMINAL_STREAM_CHANNEL } from "./constants.mjs";
+import { DevframeDefinition } from "devframe/types";
+
+//#region src/index.d.ts
+/**
+ * Build a {@link DevframeDefinition} for the terminals panel. The same
+ * definition runs standalone (`createCli`), mounts into a Vite host
+ * (`/vite`), or docks inside a hub — its `setup` only relies on the core
+ * devframe RPC surface.
+ *
+ * @experimental This plugin is experimental and may change without a major
+ * version bump until it stabilizes.
+ *
+ * @example
+ * ```ts
+ * import { createTerminalsDevframe } from '@devframes/plugin-terminals'
+ *
+ * export default createTerminalsDevframe({
+ *   presets: [{ id: 'dev', title: 'pnpm dev', command: 'pnpm', args: ['dev'] }],
+ * })
+ * ```
+ */
+declare function createTerminalsDevframe(options?: TerminalsOptions): DevframeDefinition;
+/** Default-configured terminals devframe (interactive shell, no presets). */
+declare const terminals: DevframeDefinition;
+//#endregion
+export { DEFAULT_PORT, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, SpawnRequest, TERMINAL_STREAM_CHANNEL, TerminalBackend, TerminalMode, TerminalPreset, TerminalSessionInfo, TerminalStatus, TerminalsOptions, TerminalsSharedState, createTerminalsDevframe, terminals as default };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { n as terminals, t as createTerminalsDevframe } from "./src-Cu5HYNrI.mjs";
+import { DEFAULT_PORT, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, TERMINAL_STREAM_CHANNEL } from "./constants.mjs";
+export { DEFAULT_PORT, PLUGIN_ID, PRESETS_STATE_KEY, SESSIONS_STATE_KEY, TERMINAL_STREAM_CHANNEL, createTerminalsDevframe, terminals as default };

package/dist/node/index.d.mts

@@ -0,0 +1,157 @@
+import { SpawnRequest, TerminalMode, TerminalPreset, TerminalSessionInfo, TerminalsOptions } from "../types.mjs";
+import { DevframeNodeContext } from "devframe/types";
+import * as _$nostics from "nostics";
+import { Diagnostic } from "nostics";
+
+//#region src/node/manager.d.ts
+/**
+ * Owns terminal session lifecycle: spawns PTY / piped backends, streams
+ * their output over the `devframes-plugin-terminals:output` channel (one
+ * stream per session, stable for the session's whole life so restarts reuse
+ * the same id), and mirrors a serializable session list into shared state.
+ */
+declare class TerminalManager {
+  private ctx;
+  private options;
+  readonly shell: string;
+  readonly shellArgs: string[];
+  readonly defaultCwd: string;
+  readonly defaultMode: TerminalMode;
+  readonly allowArbitraryCommands: boolean;
+  readonly presets: TerminalPreset[];
+  private channel;
+  private sessionsState?;
+  private sessions;
+  private ptyAvailable;
+  /** Session ids this manager has registered into the hub (when hubbed). */
+  private hubOwned;
+  constructor(ctx: DevframeNodeContext, options?: TerminalsOptions);
+  /** Resolve shared state, probe the PTY backend, publish the preset catalog. */
+  init(): Promise<void>;
+  /** The hub's terminals subsystem when mounted in a hub, else undefined. */
+  private hubTerminals;
+  list(): TerminalSessionInfo[];
+  getPresets(): TerminalPreset[];
+  private buildEnv;
+  private resolveSpawn;
+  /**
+   * Spawn a session and return its descriptor immediately. The OS process
+   * is launched in the background and streams into the session's stream as
+   * soon as it produces output; clients can subscribe by id right away.
+   */
+  spawn(req?: SpawnRequest): TerminalSessionInfo;
+  private launch;
+  /**
+   * Poll the PTY foreground process name and reflect changes (e.g. `bash`
+   * → `vim` → `bash`) into the session info. The interval is `unref`'d so
+   * it never keeps the process alive on its own.
+   */
+  private startProcessPoll;
+  private stopProcessPoll;
+  write(id: string, data: string): void;
+  resize(id: string, cols: number, rows: number): void;
+  /** Stop the process but keep the session (and its stream) around. */
+  terminate(id: string): void;
+  /** Set a custom display name. Pass an empty string to clear it. */
+  rename(id: string, title: string): void;
+  /** Restart the session's command in place, reusing the same stream id. */
+  restart(id: string): TerminalSessionInfo;
+  /** Kill the process, close the stream, and drop the session. */
+  remove(id: string): void;
+  /** Tear everything down — used on server shutdown and in tests. */
+  dispose(): void;
+  private publish;
+  /**
+   * Push the current session list (own + aggregated hub sessions) into shared
+   * state. Kept separate from {@link publish} so the hub-session listener can
+   * refresh without re-running {@link syncHub} (which would re-emit hub events
+   * and loop).
+   */
+  private refreshSessionsState;
+  /**
+   * Reflect the live session list into the hub's terminals subsystem when this
+   * devframe is mounted in a hub. `ctx.terminals` only exists on a
+   * `DevframeHubContext`, so it's accessed by duck-typing — standalone runtimes
+   * (CLI / Vite / build) have no such property and skip silently. This is what
+   * surfaces the plugin's sessions in the hub's own terminals panel.
+   */
+  private syncHub;
+}
+//#endregion
+//#region src/node/backend.d.ts
+/**
+ * Whether real pseudo-terminals are available in this runtime — i.e. zigpty's
+ * native bindings loaded. Without them interactive sessions still run through
+ * zigpty's pipe-based emulation, with degraded TUI fidelity.
+ */
+declare function isPtyAvailable(): Promise<boolean>;
+//#endregion
+//#region src/node/context.d.ts
+declare function setTerminalManager(ctx: DevframeNodeContext, manager: TerminalManager): void;
+declare function getTerminalManager(ctx: DevframeNodeContext): TerminalManager;
+//#endregion
+//#region src/node/diagnostics.d.ts
+interface ReporterOptions {
+  method?: 'log' | 'warn' | 'error';
+}
+declare function reporter(d: Diagnostic, {
+  method
+}?: ReporterOptions): void;
+/**
+ * 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`).
+ */
+declare const diagnostics: _$nostics.Diagnostics<{
+  readonly DP_TERMINALS_0001: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Spawn a session first, or refresh the session list.";
+  };
+  readonly DP_TERMINALS_0002: {
+    readonly why: (p: {
+      command: string;
+    }) => string;
+    readonly fix: "Add it to `presets`, or pass `allowArbitraryCommands: true` to createTerminalsDevframe().";
+  };
+  readonly DP_TERMINALS_0003: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Spawn the session with `mode: \"interactive\"` to accept input.";
+  };
+  readonly DP_TERMINALS_0004: {
+    readonly why: (p: {
+      command: string;
+      reason: string;
+    }) => string;
+  };
+  readonly DP_TERMINALS_0005: {
+    readonly why: "Native PTY bindings (zigpty) are unavailable; interactive sessions fall back to pipe-based terminal emulation. Full-screen TUIs may not render correctly.";
+    readonly fix: "Check that this platform is covered by zigpty's prebuilds (Linux/macOS/Windows, x64/arm64, glibc/musl) and that the dependency installed intact.";
+  };
+  readonly DP_TERMINALS_0006: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+  };
+  readonly DP_TERMINALS_0007: {
+    readonly why: "Terminals manager is not initialised on this context";
+    readonly fix: "Call setupTerminals(ctx) (or use createTerminalsDevframe) before invoking terminal RPCs.";
+  };
+}, readonly [typeof reporter]>;
+//#endregion
+//#region src/node/index.d.ts
+/**
+ * Wire the terminals subsystem onto a devframe node context: create the
+ * {@link TerminalManager}, publish presets + the session list into shared
+ * state, and register the control RPC functions. Returns the manager so
+ * callers can spawn sessions or dispose it on shutdown.
+ *
+ * Works in any devframe runtime (CLI, Vite, build) — it only depends on the
+ * core `ctx.rpc` streaming + shared-state surface, not on the hub.
+ */
+declare function setupTerminals(ctx: DevframeNodeContext, options?: TerminalsOptions): Promise<TerminalManager>;
+//#endregion
+export { TerminalManager, diagnostics, getTerminalManager, isPtyAvailable, setTerminalManager, setupTerminals };