@termfleet/terminal 0.1.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termfleet/terminal",
-  "version": "0.1.2",
+  "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"