@shadr/iterm2-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shad Reynolds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @shadr/iterm2-ts
+
+TypeScript client library for iTerm2's native WebSocket/Protobuf API. Control iTerm2 programmatically from Node.js — no Python dependency required.
+
+## Requirements
+
+- macOS
+- iTerm2 with "Enable Python API" enabled (Preferences > General > Magic)
+- Node.js 18+
+
+## Install
+
+```bash
+npm install @shadr/iterm2-ts
+```
+
+## Quick Start
+
+```typescript
+import { connect } from "@shadr/iterm2-ts";
+
+const iterm = await connect();
+
+try {
+  const app = await iterm.getApp();
+
+  // App → windows → tabs → sessions
+  const window = app.windows[0];       // { id, tabs, frame?, number? }
+  const tab = window.tabs[0];          // { id, sessions }
+  const session = tab.sessions[0];     // { id, name, frame?, gridSize? }
+
+  await iterm.sendText(session.id, "echo hello\n");
+} finally {
+  iterm.disconnect();
+}
+```
+
+## API Overview
+
+### Connection
+
+```typescript
+import { connect } from "@shadr/iterm2-ts";
+
+// Default connection
+const iterm = await connect();
+
+// With options — advisoryName identifies your script in iTerm2's API permissions dialog
+const iterm = await connect({ advisoryName: "my-script" });
+```
+
+### Sessions
+
+```typescript
+// Send keystrokes to a session
+await iterm.sendText(session.id, "ls -la\n");
+
+// Read visible screen contents as a string
+const screen = await iterm.getScreenContents(session.id);
+
+// Read scrollback buffer — returns an array of { text, hardNewline } per line
+const lines = await iterm.getBuffer(session.id, 50);
+
+// Split the session into two panes
+const newSession = await iterm.splitPane(session.id, { direction: "horizontal" });
+```
+
+### Windows & Tabs
+
+```typescript
+const { windowId, tabId, sessionId } = await iterm.createWindow();
+const tab = await iterm.createTab(windowId);
+await iterm.activate({ type: "session", id: sessionId });
+await iterm.close({ type: "window", ids: [windowId] });
+```
+
+### Profiles
+
+```typescript
+const profiles = await iterm.listProfiles();
+const bgColor = await iterm.getProfileProperty(session.id, "Background Color");
+await iterm.setProfileProperty(session.id, "Background Color", newColor);
+```
+
+### Events
+
+```typescript
+// Callback — returns an unsubscribe function
+const off = await iterm.on("sessionCreated", (event) => {
+  console.log("New session:", event.sessionId);
+});
+
+// Async iterator — blocks until the next event, good for loops
+for await (const event of iterm.notifications("focusChanged")) {
+  console.log("Focus changed:", event);
+}
+```
+
+### Cleanup
+
+```typescript
+iterm.disconnect();
+```
+
+## Use Cases
+
+- Automate dev environment setup (open windows, split panes, run commands)
+- Build MCP servers that control iTerm2
+- Script terminal layouts for presentations or demos
+- Monitor session output programmatically
+- React to terminal events (focus changes, keystrokes, new sessions)
+
+## Auth
+
+The library authenticates with iTerm2 using a cookie-based system:
+
+1. Checks the `ITERM2_COOKIE` environment variable
+2. Falls back to requesting a cookie via `osascript` (AppleScript)
+
+iTerm2 must be running with the Python API enabled.
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`list.ts`](examples/list.ts) — list all windows, tabs, sessions, and their buffer contents
+- [`activate.ts`](examples/activate.ts) — focus a window, tab, or session by ID
+- [`watch-events.ts`](examples/watch-events.ts) — subscribe to all events and log them
+
+Run any example with:
+
+```bash
+npx tsx examples/list.ts
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — layer overview and design decisions
+- [Protocol](docs/protocol.md) — wire protocol details and auth flow
+- [API Reference](docs/api-reference.md) — all public methods with examples
+
+## License
+
+MIT