@termfleet/terminal 0.1.1 → 0.1.3

package/README.md

@@ -30,6 +30,12 @@ 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.
 
+`@termfleet/terminal/local-terminal.js` opens a structured command in the
+user's macOS Terminal without constructing AppleScript from caller data. Every
+program, argument, working directory, and environment value is POSIX-quoted
+before the fixed AppleScript receives it as a single argv value. Unsupported
+platforms fail honestly instead of guessing a terminal emulator.
+
 `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/local-terminal.d.ts

@@ -0,0 +1,13 @@
+export interface LocalTerminalCommand {
+    program: string;
+    arguments?: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+}
+export type LocalTerminalRunner = (program: string, arguments_: readonly string[]) => Promise<void>;
+export interface OpenLocalTerminalOptions {
+    platform?: NodeJS.Platform;
+    runner?: LocalTerminalRunner;
+}
+export declare function terminalShellCommand(command: LocalTerminalCommand): string;
+export declare function openLocalTerminal(command: LocalTerminalCommand, options?: OpenLocalTerminalOptions): Promise<void>;

package/dist/local-terminal.js

@@ -0,0 +1,39 @@
+import { runAsync } from "./internal/exec.js";
+const APPLE_SCRIPT = [
+    "on run argv",
+    'tell application "Terminal"',
+    "activate",
+    "do script (item 1 of argv)",
+    "end tell",
+    "end run",
+].join("\n");
+export function terminalShellCommand(command) {
+    if (!command.program)
+        throw new Error("A terminal command program is required.");
+    const environment = Object.entries(command.env ?? {}).map(([name, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new Error(`Invalid terminal environment variable name: ${JSON.stringify(name)}.`);
+        }
+        return `${name}=${value}`;
+    });
+    const launch = [
+        ...(environment.length ? ["env", ...environment] : []),
+        command.program,
+        ...(command.arguments ?? []),
+    ].map(shellQuote).join(" ");
+    return command.cwd ? `cd ${shellQuote(command.cwd)} && exec ${launch}` : `exec ${launch}`;
+}
+export async function openLocalTerminal(command, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin") {
+        throw new Error(`Opening a local terminal is not supported on ${platform}.`);
+    }
+    const runner = options.runner ?? defaultRunner;
+    await runner("osascript", ["-e", APPLE_SCRIPT, terminalShellCommand(command)]);
+}
+async function defaultRunner(program, arguments_) {
+    await runAsync(program, [...arguments_], { timeoutMs: 5_000 });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

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

@@ -97,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

@@ -514,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.1",
+  "version": "0.1.3",
   "description": "Framework-neutral terminal transport and durable tmux session substrate extracted from Termfleet.",
   "keywords": [
     "pty",
@@ -32,6 +32,11 @@
       "development": "./src/client.ts",
       "default": "./dist/client.js"
     },
+    "./local-terminal.js": {
+      "types": "./dist/local-terminal.d.ts",
+      "development": "./src/local-terminal.ts",
+      "default": "./dist/local-terminal.js"
+    },
     "./tmux-stream.js": {
       "types": "./dist/tmux-stream.d.ts",
       "development": "./src/tmux-stream.ts",
@@ -48,7 +53,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "tsc -p tsconfig.json"
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm test"
   },
   "engines": {
     "node": ">=20"