@termfleet/terminal 0.1.0 → 0.1.2

package/README.md

@@ -29,3 +29,7 @@ Created sessions can carry an app-namespaced ownership mark; discovery does not
 claim or terminate unmarked sessions. Terminal attachment is intentionally
 separate from session termination: disposing a viewer only detaches its
 ephemeral PTY client and releases all handles.
+
+`createSession` accepts a structured `{ program, arguments }` command plus an
+environment map. Arguments are passed directly without constructing a shell
+command, and the credential bootstrap deletes itself before the command starts.

package/dist/tmux-stream.d.ts

@@ -13,6 +13,7 @@ export type TmuxTerminalSocketOptions<TAuthorization = void> = {
     cwd?: string;
     errorLabel?: string;
     onInput?: (data: string, authorization: TAuthorization | undefined) => Promise<void> | void;
+    readOnly?: boolean;
     rows?: number;
     socket: WebSocket;
     terminalId: string;

package/dist/tmux-stream.js

@@ -1,6 +1,6 @@
 import pty from "@homebridge/node-pty-prebuilt-multiarch";
 import fs from "node:fs";
-import { assertSession, getWindowSize } from "./tmux.js";
+import { assertSession, getStatusLineCount, getWindowSize } from "./tmux.js";
 export class TmuxTerminalAttachError extends Error {
     phase;
     constructor(phase, cause) {
@@ -25,8 +25,13 @@ export function attachTmuxTerminalSocket(options) {
     catch (error) {
         throw new TmuxTerminalAttachError("resolve", error);
     }
-    const cols = options.cols ?? tmuxSize.width;
-    const rows = options.rows ?? tmuxSize.height;
+    // Observers inherit the durable pane dimensions exactly. Even an ignore-size tmux client can
+    // become the size source when it is the only attached client, so accepting the browser viewport
+    // here would silently reflow someone else's terminal merely by opening a read-only mirror.
+    const cols = options.readOnly ? tmuxSize.width : options.cols ?? tmuxSize.width;
+    const rows = options.readOnly
+        ? tmuxSize.height + getStatusLineCount(options.terminalId, options.tmuxSocket)
+        : options.rows ?? tmuxSize.height;
     let reconciledPty;
     try {
         reconciledPty = spawnReconciledPty("tmux", [
@@ -34,6 +39,7 @@ export function attachTmuxTerminalSocket(options) {
             "-T",
             "RGB",
             "attach-session",
+            ...(options.readOnly ? ["-r"] : []),
             "-t",
             options.terminalId
         ], {

package/dist/tmux.d.ts

@@ -9,7 +9,12 @@ export type TmuxWindowSize = {
     width: number;
     height: number;
 };
+export type TmuxCommand = {
+    arguments?: string[];
+    program: string;
+};
 export type CreateSessionOptions = {
+    command?: TmuxCommand;
     cwd?: string;
     env?: Record<string, string>;
     name: string;
@@ -21,7 +26,7 @@ export type CreateSessionOptions = {
 export declare function assertTmux(): void;
 export declare function targetForSession(sessionName: string): string;
 export declare function assertSession(name: string, socket?: string): void;
-export declare function createSession({ cwd, env, name, owner, ownerOption: ownershipOption, panes, socket }: CreateSessionOptions): Promise<{
+export declare function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption, panes, socket }: CreateSessionOptions): Promise<{
     name: string;
     panes: number;
 }>;
@@ -92,6 +97,7 @@ export declare function getWindowSize({ name, socket, window }: {
     window?: number;
     socket?: string;
 }): TmuxWindowSize;
+export declare function getStatusLineCount(name: string, socket?: string): number;
 export declare function listWindowSizesAsync(socket?: string): Promise<Map<string, TmuxWindowSize>>;
 export declare function setPaneStyle(target: string, style: string, socket?: string): Promise<void>;
 export declare function clearPaneStyle(target: string, socket?: string): Promise<void>;

package/dist/tmux.js

@@ -40,7 +40,7 @@ export function assertSession(name, socket) {
 // createWindowSession), so every tmux invocation here uses runAsync (spawn, not
 // spawnSync) and the pane-ready poll below uses sleepAsync — see waitForPanesReady.
 // Nothing in this function may block the loop.
-export async function createSession({ cwd, env, name, owner, ownerOption: ownershipOption = ownerOption, panes, socket }) {
+export async function createSession({ command, cwd, env, name, owner, ownerOption: ownershipOption = ownerOption, panes, socket }) {
     assertTmux();
     if (!name) {
         throw new Error("--name is required.");
@@ -48,6 +48,9 @@ export async function createSession({ cwd, env, name, owner, ownerOption: owners
     if (!Number.isInteger(panes) || panes < 1) {
         throw new Error("--panes must be a positive integer.");
     }
+    if (command !== undefined && !command.program) {
+        throw new Error("A command program is required.");
+    }
     // Global server options must be in place before the first pane spawns —
     // history-limit is read at pane creation. On a fresh dedicated `-L` socket no
     // server exists yet and `set-option -g` will NOT start one (only commands like
@@ -58,11 +61,13 @@ export async function createSession({ cwd, env, name, owner, ownerOption: owners
     const sessionEnv = env ?? {};
     const bootstrapDirectories = [];
     const paneBootstrapArgs = (pane) => {
+        const commandArgs = command === undefined ? [] : [command.program, ...(command.arguments ?? [])];
         if (Object.keys(sessionEnv).length === 0)
-            return [];
+            return commandArgs;
         const directory = mkdtempSync(join(tmpdir(), "tmux-session-env-"));
         bootstrapDirectories.push(directory);
-        return writeSessionEnvironmentBootstrap(directory, pane, sessionEnv);
+        const shell = process.env.SHELL ?? "/bin/sh";
+        return writeSessionEnvironmentBootstrap(directory, pane, sessionEnv, commandArgs.length === 0 ? [shell, "-l"] : commandArgs);
     };
     try {
         const startArgs = [...sessionServerOptionArgs(), "new-session", "-d", "-s", name];
@@ -271,10 +276,9 @@ function tmuxClientEnvironment(source = process.env) {
     }
     return environment;
 }
-function writeSessionEnvironmentBootstrap(directory, pane, environment) {
+function writeSessionEnvironmentBootstrap(directory, pane, environment, command) {
     const environmentPath = join(directory, `pane-${pane}.env`);
     const wrapperPath = join(directory, `pane-${pane}.sh`);
-    const shell = process.env.SHELL ?? "/bin/sh";
     const lines = Object.entries(environment).map(([name, value]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
             throw new Error(`Invalid session environment variable name: ${JSON.stringify(name)}.`);
@@ -284,15 +288,17 @@ function writeSessionEnvironmentBootstrap(directory, pane, environment) {
     writeFileSync(environmentPath, `${lines.join("\n")}\n`, { flag: "wx", mode: 0o600 });
     writeFileSync(wrapperPath, [
         "#!/bin/sh",
+        'environment_path="$1"',
+        "shift",
         "set -a",
-        '. "$1"',
+        '. "$environment_path"',
         "set +a",
-        'rm -f -- "$1" "$0"',
+        'rm -f -- "$environment_path" "$0"',
         'rmdir -- "$(dirname -- "$0")" 2>/dev/null || true',
-        'exec "$2" -l',
+        'exec "$@"',
         ""
     ].join("\n"), { flag: "wx", mode: 0o700 });
-    return [wrapperPath, environmentPath, shell];
+    return [wrapperPath, environmentPath, ...command];
 }
 function shellQuote(value) {
     return `'${value.replaceAll("'", `'"'"'`)}'`;
@@ -508,6 +514,19 @@ export function getWindowSize({ name, socket, window = 0 }) {
     }
     return { height, width };
 }
+export function getStatusLineCount(name, socket) {
+    assertSession(name, socket);
+    const value = run("tmux", tmuxArgs(socket, ["show-options", "-Aqv", "-t", name, "status"])).trim();
+    if (value === "off")
+        return 0;
+    if (value === "on")
+        return 1;
+    const lines = Number(value);
+    if (!Number.isInteger(lines) || lines < 0 || lines > 5) {
+        throw new Error(`Could not determine tmux status height for ${name}.`);
+    }
+    return lines;
+}
 // Every window-0 size in ONE async exec, keyed by session. The observe loop uses
 // this to size windows off the event loop instead of a synchronous getWindowSize
 // per window — that per-window fan-out blocked the provider loop under a large fleet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termfleet/terminal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Framework-neutral terminal transport and durable tmux session substrate extracted from Termfleet.",
   "keywords": [
     "pty",