expose preview automation APIs

.changeset/fuzzy-browsers-connect.md

@@ -0,0 +1,5 @@
+---
+"t3code-cli": minor
+---
+
+add public preview automation, pairing metadata, shell snapshot, and mirrored T3 package APIs

README.md

@@ -63,6 +63,92 @@ t3cli --environment <name> ...                                      # Use a spec
 - Set `T3CLI_ENV=<name>` to select an environment when `--environment` is omitted
 - `T3CODE_URL` and `T3CODE_TOKEN` override the selected environment only when both are set
 
+## Programmatic API
+
+Pairing accepts T3 client presentation metadata. Automation clients should identify themselves as
+bots and provide a label that users can recognize in T3 Code:
+
+```ts
+import * as Effect from "effect/Effect";
+import { T3AuthPairing } from "t3code-cli/auth";
+import { T3AuthPairingLayer } from "t3code-cli/runtime";
+
+const pair = Effect.gen(function* () {
+  const auth = yield* T3AuthPairing;
+  return yield* auth.pair({
+    pairingUrl,
+    clientMetadata: {
+      label: "aperture bridge",
+      deviceType: "bot",
+      os: "linux",
+    },
+  });
+}).pipe(Effect.provide(T3AuthPairingLayer));
+```
+
+`T3PreviewAutomation` registers a preview host and exposes T3's request stream, response RPC, and
+focus RPC. Compose its live layer with the existing connection layers when supplying credentials
+directly:
+
+```ts
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { T3CodeConnectionProviderLive } from "t3code-cli/connection";
+import { T3CodeNodeRpcLayer } from "t3code-cli/node";
+import { T3PreviewAutomation, T3PreviewAutomationLive } from "t3code-cli/preview";
+import { T3RpcOperationsLive } from "t3code-cli/rpc";
+
+const connectionLayer = T3CodeConnectionProviderLive({
+  origin: { url },
+  auth: { token },
+});
+const rpcLayer = T3CodeNodeRpcLayer.pipe(Layer.provide(connectionLayer));
+const previewLayer = T3PreviewAutomationLive.pipe(
+  Layer.provide(T3RpcOperationsLive.pipe(Layer.provide(rpcLayer))),
+);
+
+const runHost = Effect.gen(function* () {
+  const preview = yield* T3PreviewAutomation;
+  yield* preview
+    .connect({ clientId, environmentId, supportedOperations })
+    .pipe(Stream.runForEach(handlePreviewEvent));
+}).pipe(Effect.scoped, Effect.provide(previewLayer));
+```
+
+`T3PreviewAutomationLayer` is the shorter CLI-config-backed layer for callers that use a selected
+`t3cli` environment.
+
+`T3Orchestration.watchShellSnapshots()` emits the initial shell snapshot and a reduced snapshot for
+each later project or thread event. A new full snapshot resets the reducer after reconnects.
+
+T3 Code's shared and client-runtime export maps are mirrored under `t3code-cli/shared/*` and
+`t3code-cli/client-runtime/*`. For example, the viewport catalog and resolver are available through
+the matching shared subpath:
+
+```ts
+import {
+  PREVIEW_VIEWPORT_PRESETS,
+  resolvePreviewViewport,
+} from "t3code-cli/shared/previewViewport";
+import { PreviewViewportSetting } from "t3code-cli/contracts";
+```
+
+## Upstream Maintenance
+
+Synchronize dependency versions and patches with the current `upstream-t3code` revision:
+
+```sh
+pnpm sync-upstream
+```
+
+Pass `--target` to update the submodule first. It accepts `stable`, `nightly`, `main`, a version such
+as `0.0.31` or `v0.0.31`, or a Git ref or commit:
+
+```sh
+pnpm sync-upstream --target stable
+```
+
 ## Project Management
 
 ```sh

package.json

@@ -26,72 +26,87 @@
     "src"
   ],
   "type": "module",
-  "types": "./dist/src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./application": {
-      "types": "./dist/src/application/index.d.ts",
+      "types": "./dist/application.d.ts",
       "import": "./dist/application.js",
       "default": "./dist/application.js"
     },
     "./auth": {
-      "types": "./dist/src/auth/index.d.ts",
+      "types": "./dist/auth.d.ts",
       "import": "./dist/auth.js",
       "default": "./dist/auth.js"
     },
     "./cli": {
-      "types": "./dist/src/cli/index.d.ts",
+      "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js",
       "default": "./dist/cli.js"
     },
+    "./client-runtime/*": {
+      "types": "./dist/client-runtime/*.d.ts",
+      "import": "./dist/client-runtime/*.js",
+      "default": "./dist/client-runtime/*.js"
+    },
     "./config": {
-      "types": "./dist/src/config/index.d.ts",
+      "types": "./dist/config.d.ts",
       "import": "./dist/config.js",
       "default": "./dist/config.js"
     },
     "./connection": {
-      "types": "./dist/src/connection/index.d.ts",
+      "types": "./dist/connection.d.ts",
       "import": "./dist/connection.js",
       "default": "./dist/connection.js"
     },
     "./contracts": {
-      "types": "./dist/src/contracts/index.d.ts",
+      "types": "./dist/contracts.d.ts",
       "import": "./dist/contracts.js",
       "default": "./dist/contracts.js"
     },
     "./node": {
-      "types": "./dist/src/node/index.d.ts",
+      "types": "./dist/node.d.ts",
       "import": "./dist/node.js",
       "default": "./dist/node.js"
     },
     "./orchestration": {
-      "types": "./dist/src/orchestration/index.d.ts",
+      "types": "./dist/orchestration.d.ts",
       "import": "./dist/orchestration.js",
       "default": "./dist/orchestration.js"
     },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js",
+      "default": "./dist/preview.js"
+    },
     "./rpc": {
-      "types": "./dist/src/rpc/index.d.ts",
+      "types": "./dist/rpc.d.ts",
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
     },
     "./runtime": {
-      "types": "./dist/src/runtime/index.d.ts",
+      "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
       "default": "./dist/runtime.js"
     },
+    "./shared/*": {
+      "types": "./dist/shared/*.d.ts",
+      "import": "./dist/shared/*.js",
+      "default": "./dist/shared/*.js"
+    },
     "./t3tools": {
-      "types": "./dist/src/t3tools/index.d.ts",
+      "types": "./dist/t3tools.d.ts",
       "import": "./dist/t3tools.js",
       "default": "./dist/t3tools.js"
     },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "vp pack && tsc -p tsconfig.dts.json",
+    "build": "vp pack",
     "check": "vp check",
     "format": "vp fmt",
     "format:check": "vp fmt --check",
@@ -103,12 +118,13 @@
     "release:version": "changeset version && pnpm format",
     "release:check": "pnpm check && pnpm typecheck && pnpm pack --dry-run",
     "release:publish": "changeset publish",
+    "sync-upstream": "node scripts/sync-upstream.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.78",
+    "@effect/platform-node": "4.0.0-beta.102",
     "@napi-rs/keyring": "^1.3.0",
-    "effect": "4.0.0-beta.78",
+    "effect": "4.0.0-beta.102",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
     "string-width": "^8.2.2",
@@ -119,10 +135,12 @@
     "@effect/vitest": "catalog:",
     "@t3tools/client-runtime": "link:upstream-t3code/packages/client-runtime",
     "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "link:upstream-t3code/packages/shared",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/node": "^26.1.2",
     "typescript": "^7.0.2",
-    "vite-plus": "^0.2.6"
+    "vite-plus": "^0.2.6",
+    "yaml": "catalog:"
   },
   "engines": {
     "node": ">=24.0.0"