@tilt-launcher/sidecar 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Eric
+
+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,127 @@
+# @tilt-launcher/sidecar
+
+Standalone sidecar process + typed client for the [Tilt Launcher SDK](../sdk). Communicates via JSON-RPC 2.0 over stdio — use it from any runtime or language.
+
+## Install
+
+```bash
+bun add @tilt-launcher/sidecar
+# or
+npm install @tilt-launcher/sidecar
+```
+
+This installs both the **`tilt-sidecar` binary** and the **typed TypeScript client**. The SDK (`@tilt-launcher/sdk`) is included as a dependency — no need to install it separately.
+
+## Quick Start
+
+```ts
+import { createSidecarClient } from '@tilt-launcher/sidecar';
+
+const sidecar = createSidecarClient();
+await sidecar.ready();
+
+// Everything is typed — same API as the SDK
+const config = await sidecar.getConfig();
+const status = await sidecar.getStatus();
+
+await sidecar.startEnv('my-app');
+
+sidecar.onStatusUpdate((update) => {
+  console.log('Status changed:', update);
+});
+
+sidecar.onLogDelta((delta) => {
+  console.log('New logs:', delta);
+});
+
+// Clean up
+sidecar.close();
+```
+
+## Why use the sidecar instead of the SDK directly?
+
+|                   | SDK                                              | Sidecar                       |
+| ----------------- | ------------------------------------------------ | ----------------------------- |
+| **Use when**      | Your app is Bun/Node and you want direct control | You want a managed subprocess |
+| **Process model** | In-process                                       | Separate binary               |
+| **Language**      | TypeScript only                                  | Any (JSON-RPC over stdio)     |
+| **Lifecycle**     | You manage polling and cleanup                   | Sidecar handles it            |
+| **Best for**      | Libraries, tight integration                     | Apps, CLIs, multi-language    |
+
+## API
+
+### `createSidecarClient(options?)`
+
+Spawns the sidecar and returns a typed client.
+
+```ts
+const sidecar = createSidecarClient({
+  binPath: '/path/to/tilt-sidecar', // optional, auto-detected
+  env: { TILT_LAUNCHER_CONFIG: '/custom/config.json' }, // optional
+  readyTimeoutMs: 15000, // optional, default 10s
+});
+```
+
+### Commands
+
+| Method                         | Returns                                                |
+| ------------------------------ | ------------------------------------------------------ |
+| `ready()`                      | `Promise<void>` — resolves when sidecar is initialized |
+| `getConfig()`                  | `Promise<Config>`                                      |
+| `saveConfig(config)`           | `Promise<Result>`                                      |
+| `getStatus()`                  | `Promise<StatusUpdate>`                                |
+| `getLogs(envId)`               | `Promise<{ envLogs, resourceLogs }>`                   |
+| `startEnv(envId)`              | `Promise<Result>`                                      |
+| `stopEnv(envId)`               | `Promise<Result>`                                      |
+| `restartEnv(envId)`            | `Promise<Result>`                                      |
+| `triggerResource(envId, name)` | `Promise<Result>`                                      |
+| `enableResource(envId, name)`  | `Promise<Result>`                                      |
+| `disableResource(envId, name)` | `Promise<Result>`                                      |
+| `discoverResources(input)`     | `Promise<DiscoverResult>`                              |
+| `getHomeDir()`                 | `Promise<string>`                                      |
+| `classifyTiltfilePath(path)`   | `Promise<PickedTiltfile>`                              |
+| `readDir(dirPath)`             | `Promise<ReadDirResult>`                               |
+| `close()`                      | Kills the sidecar process                              |
+
+### Events
+
+```ts
+sidecar.onStatusUpdate((update: StatusUpdate) => { ... });
+sidecar.onLogDelta((delta: LogDelta) => { ... });
+sidecar.onConfigUpdated((config: Config) => { ... });
+```
+
+### Types
+
+All types are re-exported from `@tilt-launcher/sdk`:
+
+```ts
+import type { Config, StatusUpdate, LogDelta, ResourceRow } from '@tilt-launcher/sidecar';
+```
+
+## Using the binary directly
+
+The sidecar binary can be used from any language via JSON-RPC 2.0 over stdin/stdout:
+
+```bash
+# Spawn it
+./node_modules/.bin/tilt-sidecar
+
+# Send a request (newline-delimited JSON)
+{"jsonrpc":"2.0","id":1,"method":"getStatus","params":{}}
+
+# Receive a response
+{"jsonrpc":"2.0","id":1,"result":{"envs":{}}}
+
+# Receive push notifications (no id)
+{"jsonrpc":"2.0","method":"statusUpdate","params":{...}}
+```
+
+## Requirements
+
+- `tilt` must be on `$PATH`
+- macOS or Linux (no Windows support yet)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Typed JSON-RPC client for the Tilt Launcher sidecar.
+ *
+ * Usage:
+ *   import { createSidecarClient } from '@tilt-launcher/sidecar/client';
+ *
+ *   const sidecar = createSidecarClient();
+ *   await sidecar.ready();
+ *
+ *   const config = await sidecar.getConfig();
+ *   const status = await sidecar.getStatus();
+ *   sidecar.onStatusUpdate((update) => console.log(update));
+ *
+ *   sidecar.close();
+ */
+import type { Config, DiscoverResult, LogDelta, PickedTiltfile, ReadDirResult, StatusUpdate } from '@tilt-launcher/sdk';
+export type { Config, DiscoverResult, LogDelta, PickedTiltfile, ReadDirResult, StatusUpdate };
+type Result = {
+    ok: boolean;
+    error?: string;
+};
+export interface SidecarClient {
+    /** Wait for the sidecar to emit its `ready` notification. */
+    ready(): Promise<void>;
+    getConfig(): Promise<Config>;
+    saveConfig(config: Config): Promise<Result>;
+    getStatus(): Promise<StatusUpdate>;
+    getLogs(envId: string): Promise<{
+        envLogs: string[];
+        resourceLogs: Record<string, string[]>;
+    }>;
+    startEnv(envId: string): Promise<Result>;
+    stopEnv(envId: string): Promise<Result>;
+    restartEnv(envId: string): Promise<Result>;
+    triggerResource(envId: string, resourceName: string): Promise<Result>;
+    enableResource(envId: string, resourceName: string): Promise<Result>;
+    disableResource(envId: string, resourceName: string): Promise<Result>;
+    discoverResources(input: {
+        tiltfilePath: string;
+        tiltPort: number;
+        timeoutMs?: number;
+    }): Promise<DiscoverResult>;
+    getHomeDir(): Promise<string>;
+    classifyTiltfilePath(filePath: string): Promise<PickedTiltfile>;
+    readDir(dirPath: string): Promise<ReadDirResult>;
+    onStatusUpdate(listener: (update: StatusUpdate) => void): void;
+    onLogDelta(listener: (delta: LogDelta) => void): void;
+    onConfigUpdated(listener: (config: Config) => void): void;
+    close(): void;
+}
+export interface CreateSidecarOptions {
+    /** Path to the tilt-sidecar binary. Auto-detected if not provided. */
+    binPath?: string;
+    /** Environment variables to pass to the sidecar process. */
+    env?: Record<string, string>;
+    /** Timeout for the ready() call in ms. Default: 10000 */
+    readyTimeoutMs?: number;
+}
+export declare function createSidecarClient(options?: CreateSidecarOptions): SidecarClient;

package/dist/client.js

@@ -0,0 +1,150 @@
+// src/client.ts
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+function findSidecarBin() {
+  const candidates = [
+    join(process.cwd(), "node_modules", ".bin", "tilt-sidecar"),
+    join(process.cwd(), "packages", "sidecar", "dist", "tilt-sidecar")
+  ];
+  for (const c of candidates) {
+    if (existsSync(c))
+      return c;
+  }
+  return "tilt-sidecar";
+}
+function createSidecarClient(options) {
+  const bin = options?.binPath ?? findSidecarBin();
+  const readyTimeoutMs = options?.readyTimeoutMs ?? 1e4;
+  const proc = spawn(bin, [], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, ...options?.env }
+  });
+  let nextId = 1;
+  const pending = new Map;
+  const handlers = {};
+  let readyResolve = null;
+  let readyReject = null;
+  const readyPromise = new Promise((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+  const readyTimer = setTimeout(() => {
+    if (readyReject) {
+      readyReject(new Error("Sidecar did not become ready within timeout"));
+      readyReject = null;
+    }
+  }, readyTimeoutMs);
+  let buffer = "";
+  const stdout = proc.stdout;
+  if (!stdout)
+    throw new Error("Sidecar stdout not available");
+  stdout.setEncoding("utf-8");
+  stdout.on("data", (chunk) => {
+    buffer += chunk;
+    const lines = buffer.split(`
+`);
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      try {
+        const msg = JSON.parse(line);
+        if ("id" in msg) {
+          const waiter = pending.get(msg.id);
+          if (waiter) {
+            pending.delete(msg.id);
+            if (msg.error) {
+              waiter.reject(new Error(msg.error.message));
+            } else {
+              waiter.resolve(msg.result);
+            }
+          }
+        } else if ("method" in msg) {
+          const params = msg.params;
+          switch (msg.method) {
+            case "ready":
+              clearTimeout(readyTimer);
+              if (readyResolve) {
+                readyResolve();
+                readyResolve = null;
+              }
+              break;
+            case "statusUpdate":
+              handlers.onStatusUpdate?.(params);
+              break;
+            case "logDelta":
+              handlers.onLogDelta?.(params);
+              break;
+            case "configUpdated":
+              handlers.onConfigUpdated?.(params);
+              break;
+          }
+        }
+      } catch {}
+    }
+  });
+  function rpc(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      const line = JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} });
+      const stdin = proc.stdin;
+      if (!stdin) {
+        pending.delete(id);
+        reject(new Error("Sidecar stdin not available"));
+        return;
+      }
+      stdin.write(line + `
+`);
+      setTimeout(() => {
+        if (pending.has(id)) {
+          pending.delete(id);
+          reject(new Error(`RPC timeout: ${method}`));
+        }
+      }, 60000);
+    });
+  }
+  return {
+    ready: () => readyPromise,
+    getConfig: () => rpc("getConfig"),
+    saveConfig: (config) => rpc("saveConfig", { config }),
+    getStatus: () => rpc("getStatus"),
+    getLogs: (envId) => rpc("getLogs", { envId }),
+    startEnv: (envId) => rpc("startEnv", { envId }),
+    stopEnv: (envId) => rpc("stopEnv", { envId }),
+    restartEnv: (envId) => rpc("restartEnv", { envId }),
+    triggerResource: (envId, resourceName) => rpc("triggerResource", { envId, resourceName }),
+    enableResource: (envId, resourceName) => rpc("enableResource", { envId, resourceName }),
+    disableResource: (envId, resourceName) => rpc("disableResource", { envId, resourceName }),
+    discoverResources: (input) => {
+      const params = {
+        tiltfilePath: input.tiltfilePath,
+        tiltPort: input.tiltPort
+      };
+      if (input.timeoutMs != null)
+        params.timeoutMs = input.timeoutMs;
+      return rpc("discoverResources", params);
+    },
+    getHomeDir: () => rpc("getHomeDir"),
+    classifyTiltfilePath: (filePath) => rpc("classifyTiltfilePath", { filePath }),
+    readDir: (dirPath) => rpc("readDir", { dirPath }),
+    onStatusUpdate: (listener) => {
+      handlers.onStatusUpdate = listener;
+    },
+    onLogDelta: (listener) => {
+      handlers.onLogDelta = listener;
+    },
+    onConfigUpdated: (listener) => {
+      handlers.onConfigUpdated = listener;
+    },
+    close: () => {
+      clearTimeout(readyTimer);
+      proc.stdin?.end();
+      proc.kill("SIGTERM");
+    }
+  };
+}
+export {
+  createSidecarClient
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@tilt-launcher/sidecar",
+  "version": "1.2.0",
+  "description": "Standalone sidecar binary + typed client for the Tilt Launcher SDK — JSON-RPC 2.0 over stdio",
+  "type": "module",
+  "main": "src/client.ts",
+  "types": "src/client.ts",
+  "bin": {
+    "tilt-sidecar": "dist/tilt-sidecar"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/client.ts",
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun build src/main.ts --compile --outfile dist/tilt-sidecar && bun build src/client.ts --outdir dist --target node && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "dependencies": {
+    "@tilt-launcher/sdk": "^1.2.0"
+  },
+  "keywords": [
+    "tilt",
+    "tiltfile",
+    "sidecar",
+    "json-rpc",
+    "launcher"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m4ttheweric/tilt-launcher",
+    "directory": "packages/sidecar"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.ts

@@ -0,0 +1,238 @@
+/**
+ * Typed JSON-RPC client for the Tilt Launcher sidecar.
+ *
+ * Usage:
+ *   import { createSidecarClient } from '@tilt-launcher/sidecar/client';
+ *
+ *   const sidecar = createSidecarClient();
+ *   await sidecar.ready();
+ *
+ *   const config = await sidecar.getConfig();
+ *   const status = await sidecar.getStatus();
+ *   sidecar.onStatusUpdate((update) => console.log(update));
+ *
+ *   sidecar.close();
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { Config, DiscoverResult, LogDelta, PickedTiltfile, ReadDirResult, StatusUpdate } from '@tilt-launcher/sdk';
+
+export type { Config, DiscoverResult, LogDelta, PickedTiltfile, ReadDirResult, StatusUpdate };
+
+type Result = { ok: boolean; error?: string };
+
+interface SidecarNotificationHandlers {
+  onStatusUpdate?: (update: StatusUpdate) => void;
+  onLogDelta?: (delta: LogDelta) => void;
+  onConfigUpdated?: (config: Config) => void;
+}
+
+export interface SidecarClient {
+  /** Wait for the sidecar to emit its `ready` notification. */
+  ready(): Promise<void>;
+
+  // ── Config ──
+  getConfig(): Promise<Config>;
+  saveConfig(config: Config): Promise<Result>;
+
+  // ── Status & Logs ──
+  getStatus(): Promise<StatusUpdate>;
+  getLogs(envId: string): Promise<{ envLogs: string[]; resourceLogs: Record<string, string[]> }>;
+
+  // ── Lifecycle ──
+  startEnv(envId: string): Promise<Result>;
+  stopEnv(envId: string): Promise<Result>;
+  restartEnv(envId: string): Promise<Result>;
+
+  // ── Resource control ──
+  triggerResource(envId: string, resourceName: string): Promise<Result>;
+  enableResource(envId: string, resourceName: string): Promise<Result>;
+  disableResource(envId: string, resourceName: string): Promise<Result>;
+
+  // ── Discovery ──
+  discoverResources(input: { tiltfilePath: string; tiltPort: number; timeoutMs?: number }): Promise<DiscoverResult>;
+
+  // ── Filesystem ──
+  getHomeDir(): Promise<string>;
+  classifyTiltfilePath(filePath: string): Promise<PickedTiltfile>;
+  readDir(dirPath: string): Promise<ReadDirResult>;
+
+  // ── Events ──
+  onStatusUpdate(listener: (update: StatusUpdate) => void): void;
+  onLogDelta(listener: (delta: LogDelta) => void): void;
+  onConfigUpdated(listener: (config: Config) => void): void;
+
+  // ── Lifecycle ──
+  close(): void;
+}
+
+export interface CreateSidecarOptions {
+  /** Path to the tilt-sidecar binary. Auto-detected if not provided. */
+  binPath?: string;
+  /** Environment variables to pass to the sidecar process. */
+  env?: Record<string, string>;
+  /** Timeout for the ready() call in ms. Default: 10000 */
+  readyTimeoutMs?: number;
+}
+
+function findSidecarBin(): string {
+  // Check if installed as npm dependency (bin is linked)
+  const candidates = [
+    // Installed via npm — bin is in node_modules/.bin/
+    join(process.cwd(), 'node_modules', '.bin', 'tilt-sidecar'),
+    // Monorepo — workspace build
+    join(process.cwd(), 'packages', 'sidecar', 'dist', 'tilt-sidecar'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  // Fallback: assume it's on PATH
+  return 'tilt-sidecar';
+}
+
+export function createSidecarClient(options?: CreateSidecarOptions): SidecarClient {
+  const bin = options?.binPath ?? findSidecarBin();
+  const readyTimeoutMs = options?.readyTimeoutMs ?? 10_000;
+
+  const proc: ChildProcess = spawn(bin, [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, ...options?.env },
+  });
+
+  let nextId = 1;
+  const pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  const handlers: SidecarNotificationHandlers = {};
+  let readyResolve: (() => void) | null = null;
+  let readyReject: ((e: Error) => void) | null = null;
+  const readyPromise = new Promise<void>((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+
+  const readyTimer = setTimeout(() => {
+    if (readyReject) {
+      readyReject(new Error('Sidecar did not become ready within timeout'));
+      readyReject = null;
+    }
+  }, readyTimeoutMs);
+
+  // Read stdout
+  let buffer = '';
+  const stdout = proc.stdout;
+  if (!stdout) throw new Error('Sidecar stdout not available');
+  stdout.setEncoding('utf-8');
+  stdout.on('data', (chunk: string) => {
+    buffer += chunk;
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line);
+        if ('id' in msg) {
+          const waiter = pending.get(msg.id);
+          if (waiter) {
+            pending.delete(msg.id);
+            if (msg.error) {
+              waiter.reject(new Error(msg.error.message));
+            } else {
+              waiter.resolve(msg.result);
+            }
+          }
+        } else if ('method' in msg) {
+          const params = msg.params;
+          switch (msg.method) {
+            case 'ready':
+              clearTimeout(readyTimer);
+              if (readyResolve) {
+                readyResolve();
+                readyResolve = null;
+              }
+              break;
+            case 'statusUpdate':
+              handlers.onStatusUpdate?.(params as StatusUpdate);
+              break;
+            case 'logDelta':
+              handlers.onLogDelta?.(params as LogDelta);
+              break;
+            case 'configUpdated':
+              handlers.onConfigUpdated?.(params as Config);
+              break;
+          }
+        }
+      } catch {
+        /* malformed */
+      }
+    }
+  });
+
+  function rpc<T>(method: string, params?: Record<string, unknown>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      const line = JSON.stringify({ jsonrpc: '2.0', id, method, params: params ?? {} });
+      const stdin = proc.stdin;
+      if (!stdin) {
+        pending.delete(id);
+        reject(new Error('Sidecar stdin not available'));
+        return;
+      }
+      stdin.write(line + '\n');
+      setTimeout(() => {
+        if (pending.has(id)) {
+          pending.delete(id);
+          reject(new Error(`RPC timeout: ${method}`));
+        }
+      }, 60_000);
+    });
+  }
+
+  return {
+    ready: () => readyPromise,
+
+    getConfig: () => rpc('getConfig'),
+    saveConfig: (config) => rpc('saveConfig', { config }),
+
+    getStatus: () => rpc('getStatus'),
+    getLogs: (envId) => rpc('getLogs', { envId }),
+
+    startEnv: (envId) => rpc('startEnv', { envId }),
+    stopEnv: (envId) => rpc('stopEnv', { envId }),
+    restartEnv: (envId) => rpc('restartEnv', { envId }),
+
+    triggerResource: (envId, resourceName) => rpc('triggerResource', { envId, resourceName }),
+    enableResource: (envId, resourceName) => rpc('enableResource', { envId, resourceName }),
+    disableResource: (envId, resourceName) => rpc('disableResource', { envId, resourceName }),
+
+    discoverResources: (input) => {
+      const params: Record<string, unknown> = {
+        tiltfilePath: input.tiltfilePath,
+        tiltPort: input.tiltPort,
+      };
+      if (input.timeoutMs != null) params.timeoutMs = input.timeoutMs;
+      return rpc('discoverResources', params);
+    },
+
+    getHomeDir: () => rpc('getHomeDir'),
+    classifyTiltfilePath: (filePath) => rpc('classifyTiltfilePath', { filePath }),
+    readDir: (dirPath) => rpc('readDir', { dirPath }),
+
+    onStatusUpdate: (listener) => {
+      handlers.onStatusUpdate = listener;
+    },
+    onLogDelta: (listener) => {
+      handlers.onLogDelta = listener;
+    },
+    onConfigUpdated: (listener) => {
+      handlers.onConfigUpdated = listener;
+    },
+
+    close: () => {
+      clearTimeout(readyTimer);
+      proc.stdin?.end();
+      proc.kill('SIGTERM');
+    },
+  };
+}

package/src/main.ts

@@ -0,0 +1,442 @@
+#!/usr/bin/env bun
+/**
+ * Tilt Launcher Sidecar — JSON-RPC server over stdin/stdout.
+ *
+ * Wraps TiltManagerSDK and exposes every SDK feature as a JSON-RPC method.
+ * Push notifications (statusUpdate, logDelta, configUpdated) are emitted
+ * as JSON-RPC notifications on stdout.
+ *
+ * Protocol: newline-delimited JSON-RPC 2.0.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { lstatSync, readdirSync, realpathSync, statSync, readlinkSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { homedir } from 'node:os';
+import { TiltManagerSDK } from '@tilt-launcher/sdk';
+import type { Config, StatusUpdate, LogDelta, PickedTiltfile, DirEntry } from '@tilt-launcher/sdk';
+import {
+  parseRequest,
+  successResponse,
+  errorResponse,
+  notification,
+  RPC_METHOD_NOT_FOUND,
+  RPC_INTERNAL_ERROR,
+} from './rpc.ts';
+
+// ── Path helpers ──────────────────────────────────────────────────────────
+
+/** Expand leading ~ to the user's home directory */
+function expandHome(p: string): string {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+// ── Config persistence ────────────────────────────────────────────────────
+
+const CONFIG_DIR = join(homedir(), '.config', 'tilt-launcher');
+const CONFIG_PATH = process.env.TILT_LAUNCHER_CONFIG || join(CONFIG_DIR, 'config.json');
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function normalizeConfig(raw: Config): Config {
+  const used = new Set<string>();
+  const environments = (raw.environments ?? []).map((env, idx) => {
+    const id = env.id && env.id.length > 0 ? env.id : slugify(env.name || `env-${idx + 1}`) || `env-${idx + 1}`;
+    let unique = id;
+    let suffix = 2;
+    while (used.has(unique)) {
+      unique = `${id}-${suffix++}`;
+    }
+    used.add(unique);
+    return {
+      ...env,
+      id: unique,
+      external: env.external ?? false,
+      description: env.description ?? '',
+      selectedResources: env.selectedResources ?? [],
+      cachedResources: env.cachedResources ?? [],
+      serviceMapping: env.serviceMapping,
+    };
+  });
+  return { themeMode: raw.themeMode ?? 'system', environments };
+}
+
+/** Validate that no two environments share the same tiltPort. */
+function ensureUniquePorts(cfg: Config): string | null {
+  const seen = new Map<number, string>();
+  for (const env of cfg.environments) {
+    const owner = seen.get(env.tiltPort);
+    if (owner) return `Port ${env.tiltPort} is used by both ${owner} and ${env.name}.`;
+    seen.set(env.tiltPort, env.name);
+  }
+  return null;
+}
+
+function loadConfig(): Config {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  if (!existsSync(CONFIG_PATH)) {
+    const fallback: Config = { environments: [] };
+    const normalized = normalizeConfig(fallback);
+    writeConfig(normalized);
+    return normalized;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')) as Config;
+    return normalizeConfig(parsed);
+  } catch (e) {
+    const backupPath = `${CONFIG_PATH}.bak`;
+    console.error(`Failed to parse config, backing up to ${backupPath}:`, e);
+    try {
+      renameSync(CONFIG_PATH, backupPath);
+    } catch {
+      /* backup failed */
+    }
+    const fallback: Config = { environments: [] };
+    const normalized = normalizeConfig(fallback);
+    writeConfig(normalized);
+    return normalized;
+  }
+}
+
+function writeConfig(config: Config): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+// ── SDK instance ──────────────────────────────────────────────────────────
+
+let config: Config = loadConfig();
+let configSaveTimer: ReturnType<typeof setTimeout> | null = null;
+
+const sdk = new TiltManagerSDK(config, {
+  onStatusUpdate: (update: StatusUpdate) => {
+    emit('statusUpdate', update);
+  },
+  onLogDelta: (delta: LogDelta) => {
+    emit('logDelta', delta);
+  },
+  onConfigMutated: (mutated: Config) => {
+    config = mutated;
+    if (configSaveTimer) clearTimeout(configSaveTimer);
+    configSaveTimer = setTimeout(() => {
+      writeConfig(config);
+      emit('configUpdated', config);
+    }, 5000);
+  },
+});
+
+sdk.startPolling(5000);
+
+// ── Output ────────────────────────────────────────────────────────────────
+
+function emit(method: string, params: unknown): void {
+  const line = notification(method, params);
+  process.stdout.write(line + '\n');
+}
+
+function respond(line: string): void {
+  process.stdout.write(line + '\n');
+}
+
+// ── Filesystem helpers ────────────────────────────────────────────────────
+
+/**
+ * macOS NSOpenPanel resolves POSIX symlinks before returning paths, so
+ * the file path is often the real file rather than the symlink the user
+ * navigated to. Given the real path, scan common workspace roots for a
+ * symlink whose realpath matches, then remap the path through it.
+ *
+ * Ported from Electron shell's findSymlinkFor().
+ */
+function findSymlinkFor(realFilePath: string): string | null {
+  const realDir = dirname(realFilePath);
+  const filename = basename(realFilePath);
+
+  const scanRoots = [
+    dirname(realDir), // siblings of the real directory
+    join(homedir(), 'Documents', 'GitHub'),
+    join(homedir(), 'Documents', 'Projects'),
+    join(homedir(), 'repos'),
+    join(homedir(), 'projects'),
+    join(homedir(), 'src'),
+    join(homedir(), 'dev'),
+    join(homedir(), 'code'),
+    join(homedir(), 'workspace'),
+  ];
+
+  for (const scanRoot of scanRoots) {
+    if (!existsSync(scanRoot)) continue;
+    try {
+      for (const entry of readdirSync(scanRoot)) {
+        const entryPath = join(scanRoot, entry);
+        try {
+          const entryStat = lstatSync(entryPath);
+          if (!entryStat.isSymbolicLink()) continue;
+          const entryReal = realpathSync(entryPath);
+          // Directory symlink whose target is realDir → remap file path through it
+          if (entryReal === realDir) return join(entryPath, filename);
+          // File symlink pointing directly to our file
+          if (entryReal === realFilePath) return entryPath;
+          // Symlink whose target is an ancestor of realDir → remap deeper path
+          const rel = relative(entryReal, realFilePath);
+          if (!rel.startsWith('..')) return join(entryPath, rel);
+        } catch {
+          continue;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify a Tiltfile path — detect symlinks with reverse-mapping support.
+ * Matches Electron shell's classifyTiltfilePath() behavior.
+ */
+function classifyTiltfilePath(filePath: string): PickedTiltfile {
+  const resolved = expandHome(filePath);
+
+  // Case 1: path is itself a symlink
+  try {
+    if (lstatSync(resolved).isSymbolicLink()) {
+      return { path: resolved, isSymlink: true, realPath: realpathSync(resolved) };
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // Case 2: macOS resolved the symlink — try to reverse-map back to the symlink
+  const symlinkPath = findSymlinkFor(resolved);
+  if (symlinkPath) {
+    return { path: symlinkPath, isSymlink: true, realPath: resolved };
+  }
+
+  return { path: resolved, isSymlink: false };
+}
+
+/**
+ * Read directory contents. Matches Electron shell behavior:
+ * - Filters out dotfiles (entries starting with '.')
+ * - Sorts directories before files, then alphabetical
+ * - Resolves symlink targets
+ */
+function readDir(dirPath: string): { ok: boolean; path: string; entries: DirEntry[]; error?: string } {
+  try {
+    const resolved = expandHome(dirPath);
+    const rawNames = readdirSync(resolved);
+    const entries: DirEntry[] = [];
+
+    for (const name of rawNames) {
+      if (name.startsWith('.')) continue; // Filter dotfiles
+
+      const fullPath = join(resolved, name);
+      try {
+        const lstats = lstatSync(fullPath);
+        const isSymlink = lstats.isSymbolicLink();
+        let isDirectory = lstats.isDirectory();
+        let isFile = lstats.isFile();
+        let symlinkTarget: string | undefined;
+        let realPath: string | undefined;
+
+        if (isSymlink) {
+          try {
+            symlinkTarget = readlinkSync(fullPath);
+          } catch {
+            /* ignore */
+          }
+          try {
+            realPath = realpathSync(fullPath);
+            const resolvedStat = statSync(fullPath); // follows the symlink
+            isDirectory = resolvedStat.isDirectory();
+            isFile = resolvedStat.isFile();
+          } catch {
+            isFile = true; /* broken symlink */
+          }
+        }
+
+        entries.push({ name, isDirectory, isFile, isSymlink, symlinkTarget, realPath });
+      } catch {
+        continue;
+      }
+    }
+
+    // Sort: directories first, then alphabetical
+    entries.sort((a, b) => {
+      if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+
+    return { ok: true, path: resolved, entries };
+  } catch (e) {
+    return { ok: false, path: dirPath, entries: [], error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// ── Method dispatch ───────────────────────────────────────────────────────
+
+type Handler = (params: Record<string, unknown>) => unknown | Promise<unknown>;
+
+const methods: Record<string, Handler> = {
+  // Config
+  getConfig: () => config,
+
+  saveConfig: (params) => {
+    const next = params.config as Config;
+    const normalized = normalizeConfig(next);
+
+    // Validate unique ports (matches Electron behavior)
+    const conflict = ensureUniquePorts(normalized);
+    if (conflict) return { ok: false, error: conflict };
+
+    config = normalized;
+    sdk.setConfig(config);
+    writeConfig(config);
+    emit('configUpdated', config);
+    return { ok: true };
+  },
+
+  // Status & Logs
+  getStatus: () => sdk.currentStatusUpdate(),
+
+  getLogs: (params) => {
+    const envId = params.envId as string;
+    return sdk.getEnvLogs(envId);
+  },
+
+  // Lifecycle
+  startEnv: (params) => {
+    const envId = params.envId as string;
+    return sdk.startEnv(envId);
+  },
+
+  stopEnv: (params) => {
+    const envId = params.envId as string;
+    return sdk.stopEnv(envId);
+  },
+
+  restartEnv: (params) => {
+    const envId = params.envId as string;
+    return sdk.restartEnv(envId);
+  },
+
+  // Resource control
+  triggerResource: async (params) => {
+    const envId = params.envId as string;
+    const resourceName = params.resourceName as string;
+    return sdk.triggerResource(envId, resourceName);
+  },
+
+  enableResource: async (params) => {
+    const envId = params.envId as string;
+    const resourceName = params.resourceName as string;
+    return sdk.enableResource(envId, resourceName);
+  },
+
+  disableResource: async (params) => {
+    const envId = params.envId as string;
+    const resourceName = params.resourceName as string;
+    return sdk.disableResource(envId, resourceName);
+  },
+
+  // Discovery
+  discoverResources: async (params) => {
+    const input: { tiltfilePath: string; tiltPort: number; timeoutMs?: number } = {
+      tiltfilePath: params.tiltfilePath as string,
+      tiltPort: params.tiltPort as number,
+    };
+    if (params.timeoutMs != null) input.timeoutMs = params.timeoutMs as number;
+    return sdk.discoverResources(input);
+  },
+
+  // Filesystem
+  classifyTiltfilePath: (params) => {
+    return classifyTiltfilePath(params.filePath as string);
+  },
+
+  getHomeDir: () => homedir(),
+
+  readDir: (params) => {
+    return readDir(params.dirPath as string);
+  },
+
+  // Login item (stub — platform-specific, handled by shells directly)
+  getLoginItem: () => ({ openAtLogin: false }),
+  setLoginItem: () => ({ ok: true }),
+};
+
+// ── Request handler ───────────────────────────────────────────────────────
+
+async function handleLine(line: string): Promise<void> {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  const parsed = parseRequest(trimmed);
+
+  // If parseRequest returned an error response, send it
+  if ('error' in parsed && parsed.error) {
+    respond(JSON.stringify(parsed));
+    return;
+  }
+
+  const request = parsed as { id: number | string; method: string; params: Record<string, unknown> };
+  const handler = methods[request.method];
+
+  if (!handler) {
+    respond(errorResponse(request.id, RPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`));
+    return;
+  }
+
+  try {
+    const result = await handler(request.params ?? {});
+    respond(successResponse(request.id, result));
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    respond(errorResponse(request.id, RPC_INTERNAL_ERROR, message));
+  }
+}
+
+// ── stdin reader ──────────────────────────────────────────────────────────
+
+let buffer = '';
+
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk: string) => {
+  buffer += chunk;
+  const lines = buffer.split('\n');
+  buffer = lines.pop() ?? '';
+  for (const line of lines) {
+    void handleLine(line);
+  }
+});
+
+process.stdin.on('end', () => {
+  // stdin closed — clean shutdown.
+  // Match Electron behavior: do NOT stop running Tilt environments.
+  // Quitting the launcher should leave Tilt processes running.
+  sdk.stopPolling();
+  process.exit(0);
+});
+
+// Handle signals gracefully — same policy: don't kill Tilt processes.
+process.on('SIGTERM', () => {
+  sdk.stopPolling();
+  process.exit(0);
+});
+
+process.on('SIGINT', () => {
+  sdk.stopPolling();
+  process.exit(0);
+});
+
+// Signal that sidecar is ready
+emit('ready', { version: '1.2.0' });

package/src/rpc.ts

@@ -0,0 +1,83 @@
+/**
+ * JSON-RPC 2.0 protocol handler for the sidecar.
+ *
+ * Handles: parsing requests from stdin, serializing responses to stdout,
+ * and emitting push notifications.
+ */
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: number | string;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number | string;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: unknown;
+}
+
+// Standard JSON-RPC error codes
+export const RPC_PARSE_ERROR = -32700;
+export const RPC_INVALID_REQUEST = -32600;
+export const RPC_METHOD_NOT_FOUND = -32601;
+export const RPC_INTERNAL_ERROR = -32603;
+
+// ── Parsing ───────────────────────────────────────────────────────────────
+
+export function parseRequest(line: string): JsonRpcRequest | JsonRpcResponse {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return {
+      jsonrpc: '2.0',
+      id: 0,
+      error: { code: RPC_PARSE_ERROR, message: 'Parse error: invalid JSON' },
+    };
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  if (obj.jsonrpc !== '2.0' || typeof obj.method !== 'string' || obj.id == null) {
+    return {
+      jsonrpc: '2.0',
+      id: (obj.id as number | string) ?? 0,
+      error: { code: RPC_INVALID_REQUEST, message: 'Invalid Request: missing jsonrpc, method, or id' },
+    };
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id: obj.id as number | string,
+    method: obj.method as string,
+    params: (obj.params as Record<string, unknown>) ?? {},
+  };
+}
+
+// ── Serialization ─────────────────────────────────────────────────────────
+
+export function successResponse(id: number | string, result: unknown): string {
+  const resp: JsonRpcResponse = { jsonrpc: '2.0', id, result };
+  return JSON.stringify(resp);
+}
+
+export function errorResponse(id: number | string, code: number, message: string, data?: unknown): string {
+  const resp: JsonRpcResponse = { jsonrpc: '2.0', id, error: { code, message, data } };
+  return JSON.stringify(resp);
+}
+
+export function notification(method: string, params: unknown): string {
+  const notif: JsonRpcNotification = { jsonrpc: '2.0', method, params };
+  return JSON.stringify(notif);
+}