@tilt-launcher/sdk 1.2.0 → 1.2.1

package/README.md

@@ -12,6 +12,58 @@ npm install @tilt-launcher/sdk
 
 ## Quick Start
 
+### One-Shot Query (CLI tools, CI, health checks)
+
+```ts
+import { queryTilt } from '@tilt-launcher/sdk';
+
+const status = await queryTilt(10350);
+if (!status.allHealthy) {
+  for (const err of status.errors) {
+    console.error(`${err.name}: ${err.lastBuildError ?? err.runtimeStatus}`);
+  }
+  process.exit(1);
+}
+console.log(`All ${status.healthy.length} resources healthy`);
+```
+
+### Streaming (dashboards, monitoring)
+
+```ts
+import { watchTilt } from '@tilt-launcher/sdk';
+
+const stop = await watchTilt(10350, (event) => {
+  for (const r of event.resources) {
+    if (r.runtimeStatus === 'error') console.error(`${r.name} failed!`);
+  }
+  for (const log of event.logs) {
+    console.log(`[${log.resourceName ?? 'system'}] ${log.text}`);
+  }
+});
+
+// Stop watching when done
+setTimeout(stop, 60_000);
+```
+
+### Full Client (multiple operations)
+
+```ts
+import { TiltClient } from '@tilt-launcher/sdk';
+
+const tilt = new TiltClient(10350);
+
+if (await tilt.isReachable()) {
+  const resources = await tilt.getResources();
+  const status = await tilt.getStatus();
+  const myService = await tilt.getResource('my-service');
+  await tilt.triggerResource('my-service');
+}
+
+tilt.close();
+```
+
+### Full Manager (multi-env orchestration)
+
 ```ts
 import { TiltManagerSDK } from '@tilt-launcher/sdk';
 import type { Config, StatusUpdate, LogDelta } from '@tilt-launcher/sdk';
@@ -31,34 +83,35 @@ const config: Config = {
 };
 
 const sdk = new TiltManagerSDK(config, {
-  onStatusUpdate: (update: StatusUpdate) => {
-    console.log('Status:', update.envs);
-  },
-  onLogDelta: (delta: LogDelta) => {
-    console.log('Logs:', delta);
-  },
+  onStatusUpdate: (update: StatusUpdate) => console.log('Status:', update.envs),
+  onLogDelta: (delta: LogDelta) => console.log('Logs:', delta),
 });
 
-// Start polling the Tilt API
 sdk.startPolling(5000);
-
-// Start an environment
 await sdk.startEnv('my-app');
+```
+
+## API
 
-// Get current status
-const status = sdk.currentStatusUpdate();
+### `queryTilt(port, options?)` → `Promise<TiltStatus>`
 
-// Control resources
-await sdk.triggerResource('my-app', 'web-server');
-await sdk.disableResource('my-app', 'slow-service');
-await sdk.enableResource('my-app', 'slow-service');
+One-shot: fetch all resources and return a structured status summary. No cleanup needed.
 
-// Stop
-await sdk.stopEnv('my-app');
-sdk.stopPolling();
-```
+### `watchTilt(port, callback, options?)` → `Promise<() => void>`
 
-## API
+Stream resource + log updates via WebSocket. Returns an unsubscribe function.
+
+### `TiltClient`
+
+| Method                  | Description                               |
+| ----------------------- | ----------------------------------------- |
+| `isReachable()`         | Check if Tilt is running at this port     |
+| `getResources()`        | Fetch all resource statuses               |
+| `getStatus()`           | Fetch resources as a `TiltStatus` summary |
+| `getResource(name)`     | Get a single resource by name             |
+| `triggerResource(name)` | Trigger a resource update                 |
+| `watch(callback)`       | Subscribe to WebSocket updates            |
+| `close()`               | Close all connections                     |
 
 ### `TiltManagerSDK`
 
@@ -77,28 +130,24 @@ sdk.stopPolling();
 | `startPolling(intervalMs)`     | Start polling Tilt APIs            |
 | `stopPolling()`                | Stop polling                       |
 
-### Types
-
-- `Config` — app configuration with environment list
-- `Environment` — a single Tilt environment definition
-- `StatusUpdate` — full status snapshot (all envs + resources)
-- `ResourceRow` — individual resource status (health, pid, labels, etc.)
-- `LogDelta` — incremental log update
-- `DiscoverResult` — result of resource discovery
-- `LauncherBridge` — abstract UI bridge interface
-
-### Callbacks
+### Key Types
 
-| Callback          | Fires when                                               |
-| ----------------- | -------------------------------------------------------- |
-| `onStatusUpdate`  | Tilt API poll returns new data                           |
-| `onLogDelta`      | New log lines arrive via WebSocket                       |
-| `onConfigMutated` | SDK internally modifies config (e.g., caching resources) |
+| Type             | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `TiltResource`   | Single resource from `TiltClient` (name, status, etc) |
+| `TiltStatus`     | Status summary: resources, errors, healthy, pending   |
+| `TiltWatchEvent` | WebSocket event: resources + logs                     |
+| `ResourceRow`    | Resource from `TiltManagerSDK` (includes health)      |
+| `StatusUpdate`   | Full status snapshot from `TiltManagerSDK`            |
+| `LogDelta`       | Incremental log update                                |
+| `Config`         | App configuration with environment list               |
+| `Environment`    | Single Tilt environment definition                    |
+| `LauncherBridge` | Abstract UI bridge interface                          |
 
 ## Requirements
 
-- `tilt` must be on `$PATH`
 - Node.js ≥ 18 or Bun
+- `tilt` on `$PATH` (only required for `TiltManagerSDK`; `TiltClient` uses HTTP)
 
 ## License
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types.ts';
 export { type LauncherBridge } from './bridge.ts';
 export { TiltManagerSDK } from './tiltManagerSDK.ts';
+export { TiltClient, queryTilt, watchTilt, type TiltResource, type TiltStatus, type TiltWatchEvent, type TiltWatchCallback, type TiltClientOptions, } from './tiltClient.ts';

package/dist/index.js

@@ -766,6 +766,269 @@ ${err.message}` }));
     this.emitStatus();
   }
 }
+
+// src/tiltClient.ts
+function parseEndpoint(endpoint) {
+  if (!endpoint)
+    return {};
+  try {
+    const url = new URL(endpoint);
+    return {
+      port: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
+      path: url.pathname || "/"
+    };
+  } catch {
+    return {};
+  }
+}
+function parseUIResource(item, tiltPort) {
+  const endpointUrl = item.status?.endpointLinks?.[0]?.url;
+  let endpoint;
+  if (endpointUrl) {
+    try {
+      endpoint = new URL(endpointUrl).toString();
+    } catch {
+      try {
+        endpoint = new URL(endpointUrl, `http://localhost:${tiltPort}`).toString();
+      } catch {
+        endpoint = undefined;
+      }
+    }
+  }
+  const parsed = parseEndpoint(endpoint);
+  const labels = item.metadata?.labels ? Object.keys(item.metadata.labels) : [];
+  const disableState = (item.status?.disableStatus?.state ?? "").toLowerCase();
+  const isDisabled = disableState === "disabled" || disableState === "pending";
+  const runtimeStatus = isDisabled ? "disabled" : item.status?.runtimeStatus ?? "unknown";
+  const resourceKind = runtimeStatus === "not_applicable" || runtimeStatus === "disabled" ? "cmd" : runtimeStatus === "ok" || runtimeStatus === "pending" || runtimeStatus === "error" ? "serve" : "unknown";
+  const buildHistory = item.status?.buildHistory;
+  const lastBuild = buildHistory?.[0];
+  const lastBuildDuration = lastBuild?.startTime && lastBuild?.finishTime ? (new Date(lastBuild.finishTime).getTime() - new Date(lastBuild.startTime).getTime()) / 1000 : undefined;
+  const waiting = item.status?.waiting;
+  const rawConditions = item.status?.conditions;
+  const conditions = rawConditions?.map((c) => ({
+    type: c.type ?? "",
+    status: c.status ?? "",
+    ...c.lastTransitionTime != null ? { lastTransitionTime: c.lastTransitionTime } : {}
+  }));
+  const rawPid = item.status?.localResourceInfo?.pid;
+  return {
+    name: item.metadata?.name ?? "unknown",
+    label: item.metadata?.name ?? "unknown",
+    category: labels[0] ?? "services",
+    type: item.status?.specs?.[0]?.type ?? "unknown",
+    endpoint,
+    port: parsed.port,
+    resourceKind,
+    runtimeStatus,
+    isDisabled,
+    updateStatus: item.status?.updateStatus,
+    waitingReason: waiting?.reason,
+    waitingOn: waiting?.on?.map((ref) => ref.name ?? "").filter(Boolean),
+    lastDeployTime: item.status?.lastDeployTime,
+    lastBuildDuration,
+    lastBuildError: lastBuild?.error,
+    hasPendingChanges: item.status?.hasPendingChanges,
+    triggerMode: item.status?.triggerMode,
+    queued: item.status?.queued,
+    pid: rawPid ? Number(rawPid) : undefined,
+    conditions
+  };
+}
+function buildStatus(resources) {
+  const errors = resources.filter((r) => r.runtimeStatus === "error");
+  const healthy = resources.filter((r) => r.runtimeStatus === "ok");
+  const pending = resources.filter((r) => r.runtimeStatus === "pending");
+  const active = resources.filter((r) => !r.isDisabled && r.runtimeStatus !== "not_applicable");
+  return {
+    resources,
+    errors,
+    healthy,
+    pending,
+    allHealthy: active.length > 0 && errors.length === 0 && pending.length === 0
+  };
+}
+
+class TiltClient {
+  baseUrl;
+  port;
+  timeoutMs;
+  ws = null;
+  watchCallback = null;
+  reconnectTimer = null;
+  closed = false;
+  constructor(port, options) {
+    const host = options?.host ?? "127.0.0.1";
+    this.port = port;
+    this.baseUrl = `http://${host}:${port}`;
+    this.timeoutMs = options?.timeoutMs ?? 5000;
+  }
+  async isReachable() {
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+  async getResources() {
+    const resp = await fetch(`${this.baseUrl}/api/v1alpha1/uiresources`, {
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt API error: ${resp.status} ${resp.statusText}`);
+    }
+    const data = await resp.json();
+    return (data.items ?? []).filter((item) => item.metadata?.name && item.metadata.name !== "(Tiltfile)").map((item) => parseUIResource(item, this.port));
+  }
+  async getStatus() {
+    const resources = await this.getResources();
+    return buildStatus(resources);
+  }
+  async getResource(name) {
+    const resources = await this.getResources();
+    return resources.find((r) => r.name === name) ?? null;
+  }
+  async triggerResource(name) {
+    const resp = await fetch(`${this.baseUrl}/api/trigger`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ manifest_names: [name], build_reason: 16 }),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt trigger error: ${resp.status} ${resp.statusText}`);
+    }
+  }
+  async watch(callback) {
+    this.watchCallback = callback;
+    await this.connectWS();
+    return () => {
+      this.watchCallback = null;
+      this.disconnectWS();
+    };
+  }
+  close() {
+    this.closed = true;
+    this.watchCallback = null;
+    this.disconnectWS();
+  }
+  async connectWS() {
+    if (this.ws)
+      return;
+    const tokenResp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!tokenResp.ok)
+      throw new Error("Could not get WebSocket token from Tilt");
+    const token = (await tokenResp.text()).trim();
+    const wsUrl = `ws://127.0.0.1:${this.port}/ws/view?token=${token}`;
+    const ws = new WebSocket(wsUrl);
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(typeof event.data === "string" ? event.data : event.data.toString());
+        this.handleWSMessage(data);
+      } catch {}
+    };
+    ws.onerror = () => {};
+    ws.onclose = () => {
+      this.ws = null;
+      if (this.watchCallback && !this.closed) {
+        this.reconnectTimer = setTimeout(() => {
+          this.reconnectTimer = null;
+          this.connectWS();
+        }, 3000);
+      }
+    };
+    this.ws = ws;
+  }
+  disconnectWS() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+    }
+  }
+  handleWSMessage(data) {
+    if (!this.watchCallback)
+      return;
+    const resources = [];
+    const logs = [];
+    if (data.uiResources && Array.isArray(data.uiResources)) {
+      for (const item of data.uiResources) {
+        if (item.metadata?.name && item.metadata.name !== "(Tiltfile)") {
+          resources.push(parseUIResource(item, this.port));
+        }
+      }
+    }
+    if (data.logList?.segments && Array.isArray(data.logList.segments)) {
+      const spans = data.logList.spans;
+      for (const seg of data.logList.segments) {
+        const text = seg.text?.trimEnd();
+        if (!text)
+          continue;
+        const resourceName = seg.spanId && spans?.[seg.spanId]?.manifestName;
+        logs.push({
+          resourceName: resourceName && resourceName !== "(Tiltfile)" ? resourceName : undefined,
+          text
+        });
+      }
+    }
+    if (resources.length > 0 || logs.length > 0) {
+      this.watchCallback({ resources, logs });
+    }
+  }
+}
+async function queryTilt(port, options) {
+  const client = new TiltClient(port, options);
+  try {
+    return await client.getStatus();
+  } finally {
+    client.close();
+  }
+}
+async function watchTilt(port, callback, options) {
+  const client = new TiltClient(port, options);
+  const unsub = await client.watch(callback);
+  return () => {
+    unsub();
+    client.close();
+  };
+}
+function tiltResourceToCached(r) {
+  return {
+    name: r.name,
+    label: r.label,
+    category: r.category,
+    type: r.type,
+    endpoint: r.endpoint,
+    port: r.port,
+    runtimeStatus: r.runtimeStatus,
+    isDisabled: r.isDisabled,
+    resourceKind: r.resourceKind,
+    updateStatus: r.updateStatus,
+    waitingReason: r.waitingReason,
+    waitingOn: r.waitingOn,
+    lastDeployTime: r.lastDeployTime,
+    lastBuildDuration: r.lastBuildDuration,
+    lastBuildError: r.lastBuildError,
+    hasPendingChanges: r.hasPendingChanges,
+    triggerMode: r.triggerMode,
+    queued: r.queued,
+    pid: r.pid,
+    conditions: r.conditions
+  };
+}
 export {
-  TiltManagerSDK
+  watchTilt,
+  queryTilt,
+  TiltManagerSDK,
+  TiltClient
 };

package/dist/tiltClient.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Standalone Tilt API client.
+ *
+ * Connects directly to a running Tilt instance via its HTTP/WebSocket API.
+ * No config file, no process management — just point at a port and query.
+ *
+ * @example
+ * ```ts
+ * import { TiltClient } from '@tilt-launcher/sdk';
+ *
+ * const tilt = new TiltClient(10350);
+ * const resources = await tilt.getResources();
+ * const failing = resources.filter(r => r.runtimeStatus === 'error');
+ * tilt.close();
+ * ```
+ */
+import type { CachedResource } from './types.ts';
+export interface TiltResource {
+    /** Resource name as defined in Tiltfile */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Tilt category grouping */
+    category: string;
+    /** Resource type from spec (e.g. "local", "docker_compose") */
+    type: string;
+    /** Public endpoint URL if exposed */
+    endpoint?: string | undefined;
+    /** Port number extracted from endpoint */
+    port?: number | undefined;
+    /** Kind of resource: long-running service, one-shot command, or unknown */
+    resourceKind: 'serve' | 'cmd' | 'unknown';
+    /** Tilt runtime status: ok, pending, error, not_applicable, disabled */
+    runtimeStatus: string;
+    /** Whether the resource is disabled */
+    isDisabled: boolean;
+    /** Update status: ok, pending, error, not_applicable */
+    updateStatus?: string | undefined;
+    /** If waiting, why */
+    waitingReason?: string | undefined;
+    /** Resources this one is waiting on */
+    waitingOn?: string[] | undefined;
+    /** ISO timestamp of last deploy */
+    lastDeployTime?: string | undefined;
+    /** Duration of last build in seconds */
+    lastBuildDuration?: number | undefined;
+    /** Error message from last build, if any */
+    lastBuildError?: string | undefined;
+    /** Whether there are pending file changes */
+    hasPendingChanges?: boolean | undefined;
+    /** Trigger mode (0 = auto, 1 = manual) */
+    triggerMode?: number | undefined;
+    /** Whether a trigger is queued */
+    queued?: boolean | undefined;
+    /** PID of local resource process */
+    pid?: number | undefined;
+    /** Tilt conditions array */
+    conditions?: Array<{
+        type: string;
+        status: string;
+        lastTransitionTime?: string;
+    }> | undefined;
+}
+export interface TiltStatus {
+    /** All resources discovered in this Tilt instance */
+    resources: TiltResource[];
+    /** Resources currently in error state */
+    errors: TiltResource[];
+    /** Resources currently running OK */
+    healthy: TiltResource[];
+    /** Resources pending/building */
+    pending: TiltResource[];
+    /** Whether all non-disabled resources are healthy */
+    allHealthy: boolean;
+}
+export interface TiltWatchEvent {
+    /** Updated resource statuses */
+    resources: TiltResource[];
+    /** Log lines from this update (spanId-tagged) */
+    logs: Array<{
+        resourceName?: string | undefined;
+        text: string;
+    }>;
+}
+export type TiltWatchCallback = (event: TiltWatchEvent) => void;
+export interface TiltClientOptions {
+    /** Hostname of the Tilt instance. Default: '127.0.0.1' */
+    host?: string;
+    /** Timeout for HTTP requests in ms. Default: 5000 */
+    timeoutMs?: number;
+}
+export declare class TiltClient {
+    private readonly baseUrl;
+    private readonly port;
+    private readonly timeoutMs;
+    private ws;
+    private watchCallback;
+    private reconnectTimer;
+    private closed;
+    constructor(port: number, options?: TiltClientOptions);
+    /** Check if Tilt is reachable at this port. */
+    isReachable(): Promise<boolean>;
+    /** Fetch all resources from this Tilt instance. */
+    getResources(): Promise<TiltResource[]>;
+    /** Fetch resources and return a structured status summary. */
+    getStatus(): Promise<TiltStatus>;
+    /** Get a single resource by name. */
+    getResource(name: string): Promise<TiltResource | null>;
+    /** Trigger a resource update (equivalent to pressing the trigger button in Tilt UI). */
+    triggerResource(name: string): Promise<void>;
+    /**
+     * Watch for resource updates via WebSocket.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const stop = await tilt.watch((event) => {
+     *   for (const r of event.resources) {
+     *     if (r.runtimeStatus === 'error') console.error(`${r.name} failed!`);
+     *   }
+     * });
+     * // Later:
+     * stop();
+     * ```
+     */
+    watch(callback: TiltWatchCallback): Promise<() => void>;
+    /** Close all connections. */
+    close(): void;
+    private connectWS;
+    private disconnectWS;
+    private handleWSMessage;
+}
+/**
+ * One-shot query: get the current status of all resources from a Tilt instance.
+ *
+ * @example
+ * ```ts
+ * import { queryTilt } from '@tilt-launcher/sdk';
+ *
+ * const status = await queryTilt(10350);
+ * if (!status.allHealthy) {
+ *   for (const err of status.errors) {
+ *     console.error(`${err.name}: ${err.lastBuildError ?? err.runtimeStatus}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function queryTilt(port: number, options?: TiltClientOptions): Promise<TiltStatus>;
+/**
+ * Stream resource updates from a Tilt instance.
+ * Returns an unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * import { watchTilt } from '@tilt-launcher/sdk';
+ *
+ * const stop = await watchTilt(10350, (event) => {
+ *   console.log(`${event.resources.length} resources updated`);
+ * });
+ *
+ * // Stop watching after 30s
+ * setTimeout(stop, 30_000);
+ * ```
+ */
+export declare function watchTilt(port: number, callback: TiltWatchCallback, options?: TiltClientOptions): Promise<() => void>;
+/** @internal Convert TiltResource to CachedResource for backward compatibility */
+export declare function tiltResourceToCached(r: TiltResource): CachedResource;

package/dist/tiltClient.js

@@ -0,0 +1,265 @@
+// src/tiltClient.ts
+function parseEndpoint(endpoint) {
+  if (!endpoint)
+    return {};
+  try {
+    const url = new URL(endpoint);
+    return {
+      port: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
+      path: url.pathname || "/"
+    };
+  } catch {
+    return {};
+  }
+}
+function parseUIResource(item, tiltPort) {
+  const endpointUrl = item.status?.endpointLinks?.[0]?.url;
+  let endpoint;
+  if (endpointUrl) {
+    try {
+      endpoint = new URL(endpointUrl).toString();
+    } catch {
+      try {
+        endpoint = new URL(endpointUrl, `http://localhost:${tiltPort}`).toString();
+      } catch {
+        endpoint = undefined;
+      }
+    }
+  }
+  const parsed = parseEndpoint(endpoint);
+  const labels = item.metadata?.labels ? Object.keys(item.metadata.labels) : [];
+  const disableState = (item.status?.disableStatus?.state ?? "").toLowerCase();
+  const isDisabled = disableState === "disabled" || disableState === "pending";
+  const runtimeStatus = isDisabled ? "disabled" : item.status?.runtimeStatus ?? "unknown";
+  const resourceKind = runtimeStatus === "not_applicable" || runtimeStatus === "disabled" ? "cmd" : runtimeStatus === "ok" || runtimeStatus === "pending" || runtimeStatus === "error" ? "serve" : "unknown";
+  const buildHistory = item.status?.buildHistory;
+  const lastBuild = buildHistory?.[0];
+  const lastBuildDuration = lastBuild?.startTime && lastBuild?.finishTime ? (new Date(lastBuild.finishTime).getTime() - new Date(lastBuild.startTime).getTime()) / 1000 : undefined;
+  const waiting = item.status?.waiting;
+  const rawConditions = item.status?.conditions;
+  const conditions = rawConditions?.map((c) => ({
+    type: c.type ?? "",
+    status: c.status ?? "",
+    ...c.lastTransitionTime != null ? { lastTransitionTime: c.lastTransitionTime } : {}
+  }));
+  const rawPid = item.status?.localResourceInfo?.pid;
+  return {
+    name: item.metadata?.name ?? "unknown",
+    label: item.metadata?.name ?? "unknown",
+    category: labels[0] ?? "services",
+    type: item.status?.specs?.[0]?.type ?? "unknown",
+    endpoint,
+    port: parsed.port,
+    resourceKind,
+    runtimeStatus,
+    isDisabled,
+    updateStatus: item.status?.updateStatus,
+    waitingReason: waiting?.reason,
+    waitingOn: waiting?.on?.map((ref) => ref.name ?? "").filter(Boolean),
+    lastDeployTime: item.status?.lastDeployTime,
+    lastBuildDuration,
+    lastBuildError: lastBuild?.error,
+    hasPendingChanges: item.status?.hasPendingChanges,
+    triggerMode: item.status?.triggerMode,
+    queued: item.status?.queued,
+    pid: rawPid ? Number(rawPid) : undefined,
+    conditions
+  };
+}
+function buildStatus(resources) {
+  const errors = resources.filter((r) => r.runtimeStatus === "error");
+  const healthy = resources.filter((r) => r.runtimeStatus === "ok");
+  const pending = resources.filter((r) => r.runtimeStatus === "pending");
+  const active = resources.filter((r) => !r.isDisabled && r.runtimeStatus !== "not_applicable");
+  return {
+    resources,
+    errors,
+    healthy,
+    pending,
+    allHealthy: active.length > 0 && errors.length === 0 && pending.length === 0
+  };
+}
+
+class TiltClient {
+  baseUrl;
+  port;
+  timeoutMs;
+  ws = null;
+  watchCallback = null;
+  reconnectTimer = null;
+  closed = false;
+  constructor(port, options) {
+    const host = options?.host ?? "127.0.0.1";
+    this.port = port;
+    this.baseUrl = `http://${host}:${port}`;
+    this.timeoutMs = options?.timeoutMs ?? 5000;
+  }
+  async isReachable() {
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+  async getResources() {
+    const resp = await fetch(`${this.baseUrl}/api/v1alpha1/uiresources`, {
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt API error: ${resp.status} ${resp.statusText}`);
+    }
+    const data = await resp.json();
+    return (data.items ?? []).filter((item) => item.metadata?.name && item.metadata.name !== "(Tiltfile)").map((item) => parseUIResource(item, this.port));
+  }
+  async getStatus() {
+    const resources = await this.getResources();
+    return buildStatus(resources);
+  }
+  async getResource(name) {
+    const resources = await this.getResources();
+    return resources.find((r) => r.name === name) ?? null;
+  }
+  async triggerResource(name) {
+    const resp = await fetch(`${this.baseUrl}/api/trigger`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ manifest_names: [name], build_reason: 16 }),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt trigger error: ${resp.status} ${resp.statusText}`);
+    }
+  }
+  async watch(callback) {
+    this.watchCallback = callback;
+    await this.connectWS();
+    return () => {
+      this.watchCallback = null;
+      this.disconnectWS();
+    };
+  }
+  close() {
+    this.closed = true;
+    this.watchCallback = null;
+    this.disconnectWS();
+  }
+  async connectWS() {
+    if (this.ws)
+      return;
+    const tokenResp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!tokenResp.ok)
+      throw new Error("Could not get WebSocket token from Tilt");
+    const token = (await tokenResp.text()).trim();
+    const wsUrl = `ws://127.0.0.1:${this.port}/ws/view?token=${token}`;
+    const ws = new WebSocket(wsUrl);
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(typeof event.data === "string" ? event.data : event.data.toString());
+        this.handleWSMessage(data);
+      } catch {}
+    };
+    ws.onerror = () => {};
+    ws.onclose = () => {
+      this.ws = null;
+      if (this.watchCallback && !this.closed) {
+        this.reconnectTimer = setTimeout(() => {
+          this.reconnectTimer = null;
+          this.connectWS();
+        }, 3000);
+      }
+    };
+    this.ws = ws;
+  }
+  disconnectWS() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+    }
+  }
+  handleWSMessage(data) {
+    if (!this.watchCallback)
+      return;
+    const resources = [];
+    const logs = [];
+    if (data.uiResources && Array.isArray(data.uiResources)) {
+      for (const item of data.uiResources) {
+        if (item.metadata?.name && item.metadata.name !== "(Tiltfile)") {
+          resources.push(parseUIResource(item, this.port));
+        }
+      }
+    }
+    if (data.logList?.segments && Array.isArray(data.logList.segments)) {
+      const spans = data.logList.spans;
+      for (const seg of data.logList.segments) {
+        const text = seg.text?.trimEnd();
+        if (!text)
+          continue;
+        const resourceName = seg.spanId && spans?.[seg.spanId]?.manifestName;
+        logs.push({
+          resourceName: resourceName && resourceName !== "(Tiltfile)" ? resourceName : undefined,
+          text
+        });
+      }
+    }
+    if (resources.length > 0 || logs.length > 0) {
+      this.watchCallback({ resources, logs });
+    }
+  }
+}
+async function queryTilt(port, options) {
+  const client = new TiltClient(port, options);
+  try {
+    return await client.getStatus();
+  } finally {
+    client.close();
+  }
+}
+async function watchTilt(port, callback, options) {
+  const client = new TiltClient(port, options);
+  const unsub = await client.watch(callback);
+  return () => {
+    unsub();
+    client.close();
+  };
+}
+function tiltResourceToCached(r) {
+  return {
+    name: r.name,
+    label: r.label,
+    category: r.category,
+    type: r.type,
+    endpoint: r.endpoint,
+    port: r.port,
+    runtimeStatus: r.runtimeStatus,
+    isDisabled: r.isDisabled,
+    resourceKind: r.resourceKind,
+    updateStatus: r.updateStatus,
+    waitingReason: r.waitingReason,
+    waitingOn: r.waitingOn,
+    lastDeployTime: r.lastDeployTime,
+    lastBuildDuration: r.lastBuildDuration,
+    lastBuildError: r.lastBuildError,
+    hasPendingChanges: r.hasPendingChanges,
+    triggerMode: r.triggerMode,
+    queued: r.queued,
+    pid: r.pid,
+    conditions: r.conditions
+  };
+}
+export {
+  watchTilt,
+  tiltResourceToCached,
+  queryTilt,
+  TiltClient
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilt-launcher/sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "SDK for managing Tilt dev environments — start, stop, monitor, and control resources",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/index.ts src/types.ts src/bridge.ts src/tiltManagerSDK.ts --outdir dist --target node && tsc -p tsconfig.build.json",
+    "build": "bun build src/index.ts src/types.ts src/bridge.ts src/tiltManagerSDK.ts src/tiltClient.ts --outdir dist --target node && tsc -p tsconfig.build.json",
     "check": "tsc --noEmit -p tsconfig.json",
     "prepublishOnly": "bun run check && bun run build"
   },

package/src/index.ts

@@ -1,3 +1,13 @@
 export * from './types.ts';
 export { type LauncherBridge } from './bridge.ts';
 export { TiltManagerSDK } from './tiltManagerSDK.ts';
+export {
+  TiltClient,
+  queryTilt,
+  watchTilt,
+  type TiltResource,
+  type TiltStatus,
+  type TiltWatchEvent,
+  type TiltWatchCallback,
+  type TiltClientOptions,
+} from './tiltClient.ts';

package/src/tiltClient.ts

@@ -0,0 +1,474 @@
+/**
+ * Standalone Tilt API client.
+ *
+ * Connects directly to a running Tilt instance via its HTTP/WebSocket API.
+ * No config file, no process management — just point at a port and query.
+ *
+ * @example
+ * ```ts
+ * import { TiltClient } from '@tilt-launcher/sdk';
+ *
+ * const tilt = new TiltClient(10350);
+ * const resources = await tilt.getResources();
+ * const failing = resources.filter(r => r.runtimeStatus === 'error');
+ * tilt.close();
+ * ```
+ */
+
+import type { CachedResource } from './types.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface TiltResource {
+  /** Resource name as defined in Tiltfile */
+  name: string;
+  /** Display label */
+  label: string;
+  /** Tilt category grouping */
+  category: string;
+  /** Resource type from spec (e.g. "local", "docker_compose") */
+  type: string;
+  /** Public endpoint URL if exposed */
+  endpoint?: string | undefined;
+  /** Port number extracted from endpoint */
+  port?: number | undefined;
+  /** Kind of resource: long-running service, one-shot command, or unknown */
+  resourceKind: 'serve' | 'cmd' | 'unknown';
+  /** Tilt runtime status: ok, pending, error, not_applicable, disabled */
+  runtimeStatus: string;
+  /** Whether the resource is disabled */
+  isDisabled: boolean;
+  /** Update status: ok, pending, error, not_applicable */
+  updateStatus?: string | undefined;
+  /** If waiting, why */
+  waitingReason?: string | undefined;
+  /** Resources this one is waiting on */
+  waitingOn?: string[] | undefined;
+  /** ISO timestamp of last deploy */
+  lastDeployTime?: string | undefined;
+  /** Duration of last build in seconds */
+  lastBuildDuration?: number | undefined;
+  /** Error message from last build, if any */
+  lastBuildError?: string | undefined;
+  /** Whether there are pending file changes */
+  hasPendingChanges?: boolean | undefined;
+  /** Trigger mode (0 = auto, 1 = manual) */
+  triggerMode?: number | undefined;
+  /** Whether a trigger is queued */
+  queued?: boolean | undefined;
+  /** PID of local resource process */
+  pid?: number | undefined;
+  /** Tilt conditions array */
+  conditions?: Array<{ type: string; status: string; lastTransitionTime?: string }> | undefined;
+}
+
+export interface TiltStatus {
+  /** All resources discovered in this Tilt instance */
+  resources: TiltResource[];
+  /** Resources currently in error state */
+  errors: TiltResource[];
+  /** Resources currently running OK */
+  healthy: TiltResource[];
+  /** Resources pending/building */
+  pending: TiltResource[];
+  /** Whether all non-disabled resources are healthy */
+  allHealthy: boolean;
+}
+
+export interface TiltWatchEvent {
+  /** Updated resource statuses */
+  resources: TiltResource[];
+  /** Log lines from this update (spanId-tagged) */
+  logs: Array<{ resourceName?: string | undefined; text: string }>;
+}
+
+export type TiltWatchCallback = (event: TiltWatchEvent) => void;
+
+// ── Internal helpers ─────────────────────────────────────────────────────
+
+function parseEndpoint(endpoint?: string): { port?: number; path?: string } {
+  if (!endpoint) return {};
+  try {
+    const url = new URL(endpoint);
+    return {
+      port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)),
+      path: url.pathname || '/',
+    };
+  } catch {
+    return {};
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseUIResource(item: any, tiltPort: number): TiltResource {
+  const endpointUrl = item.status?.endpointLinks?.[0]?.url as string | undefined;
+  let endpoint: string | undefined;
+  if (endpointUrl) {
+    try {
+      endpoint = new URL(endpointUrl).toString();
+    } catch {
+      try {
+        endpoint = new URL(endpointUrl, `http://localhost:${tiltPort}`).toString();
+      } catch {
+        endpoint = undefined;
+      }
+    }
+  }
+
+  const parsed = parseEndpoint(endpoint);
+  const labels = item.metadata?.labels ? Object.keys(item.metadata.labels) : [];
+  const disableState = (item.status?.disableStatus?.state ?? '').toLowerCase();
+  const isDisabled = disableState === 'disabled' || disableState === 'pending';
+  const runtimeStatus = isDisabled ? 'disabled' : (item.status?.runtimeStatus ?? 'unknown');
+  const resourceKind =
+    runtimeStatus === 'not_applicable' || runtimeStatus === 'disabled'
+      ? ('cmd' as const)
+      : runtimeStatus === 'ok' || runtimeStatus === 'pending' || runtimeStatus === 'error'
+        ? ('serve' as const)
+        : ('unknown' as const);
+
+  // Build history
+  const buildHistory = item.status?.buildHistory as
+    | Array<{ startTime?: string; finishTime?: string; error?: string }>
+    | undefined;
+  const lastBuild = buildHistory?.[0];
+  const lastBuildDuration =
+    lastBuild?.startTime && lastBuild?.finishTime
+      ? (new Date(lastBuild.finishTime).getTime() - new Date(lastBuild.startTime).getTime()) / 1000
+      : undefined;
+
+  // Waiting
+  const waiting = item.status?.waiting as { reason?: string; on?: Array<{ name?: string }> } | undefined;
+
+  // Conditions
+  const rawConditions = item.status?.conditions as
+    | Array<{ type?: string; status?: string; lastTransitionTime?: string }>
+    | undefined;
+  const conditions = rawConditions?.map((c) => ({
+    type: c.type ?? '',
+    status: c.status ?? '',
+    ...(c.lastTransitionTime != null ? { lastTransitionTime: c.lastTransitionTime } : {}),
+  }));
+
+  const rawPid = item.status?.localResourceInfo?.pid;
+
+  return {
+    name: item.metadata?.name ?? 'unknown',
+    label: item.metadata?.name ?? 'unknown',
+    category: labels[0] ?? 'services',
+    type: item.status?.specs?.[0]?.type ?? 'unknown',
+    endpoint,
+    port: parsed.port,
+    resourceKind,
+    runtimeStatus,
+    isDisabled,
+    updateStatus: item.status?.updateStatus,
+    waitingReason: waiting?.reason,
+    waitingOn: waiting?.on?.map((ref: { name?: string }) => ref.name ?? '').filter(Boolean),
+    lastDeployTime: item.status?.lastDeployTime,
+    lastBuildDuration,
+    lastBuildError: lastBuild?.error,
+    hasPendingChanges: item.status?.hasPendingChanges,
+    triggerMode: item.status?.triggerMode,
+    queued: item.status?.queued,
+    pid: rawPid ? Number(rawPid) : undefined,
+    conditions,
+  };
+}
+
+function buildStatus(resources: TiltResource[]): TiltStatus {
+  const errors = resources.filter((r) => r.runtimeStatus === 'error');
+  const healthy = resources.filter((r) => r.runtimeStatus === 'ok');
+  const pending = resources.filter((r) => r.runtimeStatus === 'pending');
+  const active = resources.filter((r) => !r.isDisabled && r.runtimeStatus !== 'not_applicable');
+  return {
+    resources,
+    errors,
+    healthy,
+    pending,
+    allHealthy: active.length > 0 && errors.length === 0 && pending.length === 0,
+  };
+}
+
+// ── TiltClient ───────────────────────────────────────────────────────────
+
+export interface TiltClientOptions {
+  /** Hostname of the Tilt instance. Default: '127.0.0.1' */
+  host?: string;
+  /** Timeout for HTTP requests in ms. Default: 5000 */
+  timeoutMs?: number;
+}
+
+export class TiltClient {
+  private readonly baseUrl: string;
+  private readonly port: number;
+  private readonly timeoutMs: number;
+  private ws: WebSocket | null = null;
+  private watchCallback: TiltWatchCallback | null = null;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private closed = false;
+
+  constructor(port: number, options?: TiltClientOptions) {
+    const host = options?.host ?? '127.0.0.1';
+    this.port = port;
+    this.baseUrl = `http://${host}:${port}`;
+    this.timeoutMs = options?.timeoutMs ?? 5000;
+  }
+
+  /** Check if Tilt is reachable at this port. */
+  async isReachable(): Promise<boolean> {
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Fetch all resources from this Tilt instance. */
+  async getResources(): Promise<TiltResource[]> {
+    const resp = await fetch(`${this.baseUrl}/api/v1alpha1/uiresources`, {
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt API error: ${resp.status} ${resp.statusText}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = (await resp.json()) as { items?: any[] };
+    return (data.items ?? [])
+      .filter((item: { metadata?: { name?: string } }) => item.metadata?.name && item.metadata.name !== '(Tiltfile)')
+      .map((item: unknown) => parseUIResource(item, this.port));
+  }
+
+  /** Fetch resources and return a structured status summary. */
+  async getStatus(): Promise<TiltStatus> {
+    const resources = await this.getResources();
+    return buildStatus(resources);
+  }
+
+  /** Get a single resource by name. */
+  async getResource(name: string): Promise<TiltResource | null> {
+    const resources = await this.getResources();
+    return resources.find((r) => r.name === name) ?? null;
+  }
+
+  /** Trigger a resource update (equivalent to pressing the trigger button in Tilt UI). */
+  async triggerResource(name: string): Promise<void> {
+    const resp = await fetch(`${this.baseUrl}/api/trigger`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ manifest_names: [name], build_reason: 16 /* manual */ }),
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!resp.ok) {
+      throw new Error(`Tilt trigger error: ${resp.status} ${resp.statusText}`);
+    }
+  }
+
+  /**
+   * Watch for resource updates via WebSocket.
+   * Returns an unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const stop = await tilt.watch((event) => {
+   *   for (const r of event.resources) {
+   *     if (r.runtimeStatus === 'error') console.error(`${r.name} failed!`);
+   *   }
+   * });
+   * // Later:
+   * stop();
+   * ```
+   */
+  async watch(callback: TiltWatchCallback): Promise<() => void> {
+    this.watchCallback = callback;
+    await this.connectWS();
+    return () => {
+      this.watchCallback = null;
+      this.disconnectWS();
+    };
+  }
+
+  /** Close all connections. */
+  close(): void {
+    this.closed = true;
+    this.watchCallback = null;
+    this.disconnectWS();
+  }
+
+  // ── WebSocket internals ──────────────────────────────────────────────
+
+  private async connectWS(): Promise<void> {
+    if (this.ws) return;
+
+    const tokenResp = await fetch(`${this.baseUrl}/api/websocket_token`, {
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!tokenResp.ok) throw new Error('Could not get WebSocket token from Tilt');
+    const token = (await tokenResp.text()).trim();
+
+    const wsUrl = `ws://127.0.0.1:${this.port}/ws/view?token=${token}`;
+    const ws = new WebSocket(wsUrl);
+
+    ws.onmessage = (event: MessageEvent) => {
+      try {
+        const data = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());
+        this.handleWSMessage(data);
+      } catch {
+        /* ignore malformed */
+      }
+    };
+
+    ws.onerror = () => {
+      /* triggers onclose */
+    };
+
+    ws.onclose = () => {
+      this.ws = null;
+      if (this.watchCallback && !this.closed) {
+        this.reconnectTimer = setTimeout(() => {
+          this.reconnectTimer = null;
+          void this.connectWS();
+        }, 3000);
+      }
+    };
+
+    this.ws = ws;
+  }
+
+  private disconnectWS(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+        /* already closed */
+      }
+      this.ws = null;
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private handleWSMessage(data: any): void {
+    if (!this.watchCallback) return;
+
+    const resources: TiltResource[] = [];
+    const logs: Array<{ resourceName?: string | undefined; text: string }> = [];
+
+    // Parse resources
+    if (data.uiResources && Array.isArray(data.uiResources)) {
+      for (const item of data.uiResources) {
+        if (item.metadata?.name && item.metadata.name !== '(Tiltfile)') {
+          resources.push(parseUIResource(item, this.port));
+        }
+      }
+    }
+
+    // Parse logs
+    if (data.logList?.segments && Array.isArray(data.logList.segments)) {
+      const spans = data.logList.spans as Record<string, { manifestName?: string }> | undefined;
+      for (const seg of data.logList.segments as Array<{ spanId?: string; text?: string }>) {
+        const text = seg.text?.trimEnd();
+        if (!text) continue;
+        const resourceName = seg.spanId && spans?.[seg.spanId]?.manifestName;
+        logs.push({
+          resourceName: resourceName && resourceName !== '(Tiltfile)' ? resourceName : undefined,
+          text,
+        });
+      }
+    }
+
+    if (resources.length > 0 || logs.length > 0) {
+      this.watchCallback({ resources, logs });
+    }
+  }
+}
+
+// ── Convenience functions ────────────────────────────────────────────────
+
+/**
+ * One-shot query: get the current status of all resources from a Tilt instance.
+ *
+ * @example
+ * ```ts
+ * import { queryTilt } from '@tilt-launcher/sdk';
+ *
+ * const status = await queryTilt(10350);
+ * if (!status.allHealthy) {
+ *   for (const err of status.errors) {
+ *     console.error(`${err.name}: ${err.lastBuildError ?? err.runtimeStatus}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export async function queryTilt(port: number, options?: TiltClientOptions): Promise<TiltStatus> {
+  const client = new TiltClient(port, options);
+  try {
+    return await client.getStatus();
+  } finally {
+    client.close();
+  }
+}
+
+/**
+ * Stream resource updates from a Tilt instance.
+ * Returns an unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * import { watchTilt } from '@tilt-launcher/sdk';
+ *
+ * const stop = await watchTilt(10350, (event) => {
+ *   console.log(`${event.resources.length} resources updated`);
+ * });
+ *
+ * // Stop watching after 30s
+ * setTimeout(stop, 30_000);
+ * ```
+ */
+export async function watchTilt(
+  port: number,
+  callback: TiltWatchCallback,
+  options?: TiltClientOptions,
+): Promise<() => void> {
+  const client = new TiltClient(port, options);
+  const unsub = await client.watch(callback);
+  return () => {
+    unsub();
+    client.close();
+  };
+}
+
+// ── Adapter: TiltResource → CachedResource (for TiltManagerSDK compat) ──
+
+/** @internal Convert TiltResource to CachedResource for backward compatibility */
+export function tiltResourceToCached(r: TiltResource): CachedResource {
+  return {
+    name: r.name,
+    label: r.label,
+    category: r.category,
+    type: r.type,
+    endpoint: r.endpoint,
+    port: r.port,
+    runtimeStatus: r.runtimeStatus,
+    isDisabled: r.isDisabled,
+    resourceKind: r.resourceKind,
+    updateStatus: r.updateStatus,
+    waitingReason: r.waitingReason,
+    waitingOn: r.waitingOn,
+    lastDeployTime: r.lastDeployTime,
+    lastBuildDuration: r.lastBuildDuration,
+    lastBuildError: r.lastBuildError,
+    hasPendingChanges: r.hasPendingChanges,
+    triggerMode: r.triggerMode,
+    queued: r.queued,
+    pid: r.pid,
+    conditions: r.conditions,
+  };
+}