Merge latest t3-code/main into h-code

README.md

@@ -1,23 +1,26 @@
 # T3 Code
 
-T3 Code is a minimal web GUI for coding agents (currently Codex, Claude, and OpenCode, more coming soon).
+T3 Code is a minimal web GUI for coding agents (currently Codex, Claude, Cursor, and OpenCode, more coming soon).
 
 ## Installation
 
 > [!WARNING]
-> T3 Code currently supports Codex, Claude, and OpenCode.
+> T3 Code currently supports Codex, Claude, Cursor, and OpenCode.
 > Install and authenticate at least one provider before use:
 >
 > - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
 > - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
+> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `cursor-agent login`
 > - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
 
 ### Run without installing
 
 ```bash
-npx t3
+npx t3@latest
 ```
 
+Tip: Use `npx t3@latest --help` for the full CLI reference.
+
 ### Desktop app
 
 Install the latest version of the desktop app from [GitHub Releases](https://github.com/pingdotgg/t3code/releases), or from your favorite package registry:
@@ -46,11 +49,7 @@ We are very very early in this project. Expect bugs.
 
 We are not accepting contributions yet.
 
-Observability guide: [docs/operations/observability.md](./docs/operations/observability.md)
-
-Relay observability: [docs/operations/relay-observability.md](./docs/operations/relay-observability.md)
-
-T3 Cloud Clerk setup: [docs/cloud/t3-cloud-clerk.md](./docs/cloud/t3-cloud-clerk.md)
+There's no public docs site yet, checkout the miscellaneous markdown files in [docs](./docs).
 
 ## Documentation
 
@@ -62,12 +61,28 @@ T3 Cloud Clerk setup: [docs/cloud/t3-cloud-clerk.md](./docs/cloud/t3-cloud-clerk
 
 ## If you REALLY want to contribute still.... read this first
 
-Before local development, prepare the environment and install dependencies:
+### Install `vp`
+
+T3 Code uses Vite+ so you'll need to install the global `vp` command-line tool.
+
+#### macOS / Linux
+
+```bash
+curl -fsSL https://vite.plus | bash
+```
+
+#### Windows
+
+```bash
+irm https://vite.plus/ps1 | iex
+```
+
+Checkout their getting started guide for more information: https://viteplus.dev/guide/
+
+### Install dependencies
 
 ```bash
-# Optional: only needed if you use mise for dev tool management.
-mise install
-vp install
+vp i
 ```
 
 T3 Cloud is optional and disabled in a fresh clone. To enable it for web, desktop, and mobile source

apps/desktop/src/app/DesktopAppIdentity.ts

@@ -52,7 +52,7 @@ const make = Effect.gen(function* () {
           Effect.map((parsed) =>
             Option.fromNullishOr(parsed.t3codeCommitHash).pipe(Option.flatMap(normalizeCommitHash)),
           ),
-          Effect.catch(() => Effect.succeed(Option.none<string>())),
+          Effect.orElseSucceed(() => Option.none<string>()),
         ),
     });
   });

apps/desktop/src/backend/DesktopServerExposure.test.ts

@@ -64,6 +64,13 @@ function mockSpawnerLayer(statusJson = "{}") {
   );
 }
 
+function dieOnSpawnLayer() {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make(() => Effect.die("unexpected tailscale spawn")),
+  );
+}
+
 function makeEnvironmentLayer(baseDir: string, env: Record<string, string | undefined> = {}) {
   return makeDesktopEnvironmentLayer({
     dirname: "/repo/apps/desktop/src",
@@ -86,6 +93,7 @@ function makeLayer(input: {
   readonly baseDir: string;
   readonly networkInterfaces?: DesktopNetworkInterfaces;
   readonly env?: Record<string, string | undefined>;
+  readonly spawnerLayer?: Layer.Layer<ChildProcessSpawner.ChildProcessSpawner>;
 }) {
   const env = { T3CODE_HOME: input.baseDir, ...input.env };
   const environmentLayer = makeEnvironmentLayer(input.baseDir, env);
@@ -97,7 +105,7 @@ function makeLayer(input: {
     Layer.provideMerge(DesktopAppSettings.layer),
     Layer.provideMerge(NodeFileSystem.layer),
     Layer.provideMerge(NodeHttpClient.layerUndici),
-    Layer.provideMerge(mockSpawnerLayer()),
+    Layer.provideMerge(input.spawnerLayer ?? mockSpawnerLayer()),
     Layer.provideMerge(networkLayer),
     Layer.provideMerge(DesktopConfig.layerTest(env)),
     Layer.provideMerge(environmentLayer),
@@ -116,13 +124,23 @@ const withHarness = <A, E, R>(
     | DesktopAppSettings.DesktopAppSettings
   >,
   env: Record<string, string | undefined> = {},
+  spawnerLayer?: Layer.Layer<ChildProcessSpawner.ChildProcessSpawner>,
 ) =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const baseDir = yield* fileSystem.makeTempDirectoryScoped({
       prefix: "t3-desktop-server-exposure-test-",
     });
-    return yield* effect.pipe(Effect.provide(makeLayer({ baseDir, networkInterfaces, env })));
+    return yield* effect.pipe(
+      Effect.provide(
+        makeLayer({
+          baseDir,
+          networkInterfaces,
+          env,
+          ...(spawnerLayer ? { spawnerLayer } : {}),
+        }),
+      ),
+    );
   }).pipe(Effect.provide(NodeServices.layer), Effect.scoped);
 
 describe("DesktopServerExposure", () => {
@@ -239,6 +257,27 @@ describe("DesktopServerExposure", () => {
     ),
   );
 
+  it.effect("does not spawn the tailscale CLI while server exposure is local-only", () =>
+    withHarness(
+      lanNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+        // mode stays at default "local-only", tailscaleServeEnabled stays false.
+
+        const endpoints = yield* serverExposure.getAdvertisedEndpoints;
+        // Only the loopback endpoint; no tailscale spawn means the dieOnSpawnLayer
+        // would have crashed the test if the gate was missing.
+        assert.deepEqual(
+          endpoints.map((endpoint) => endpoint.httpBaseUrl),
+          ["http://127.0.0.1:4173/"],
+        );
+      }),
+      {},
+      dieOnSpawnLayer(),
+    ),
+  );
+
   it.effect("uses ConfigProvider desktop exposure overrides", () =>
     withHarness(
       lanNetworkInterfaces,

apps/desktop/src/backend/DesktopServerExposure.ts

@@ -12,6 +12,7 @@ import type {
 } from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
@@ -22,8 +23,11 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 import { DEFAULT_DESKTOP_SETTINGS, type DesktopSettings } from "../settings/DesktopAppSettings.ts";
 import * as DesktopConfig from "../app/DesktopConfig.ts";
 import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
+import { readTailscaleStatus } from "@t3tools/tailscale";
 import * as DesktopAppSettingsService from "../settings/DesktopAppSettings.ts";
 
+const TAILSCALE_STATUS_CACHE_TTL = Duration.seconds(60);
+
 export const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
 const DESKTOP_LAN_BIND_HOST = "0.0.0.0";
 
@@ -412,6 +416,18 @@ const make = Effect.gen(function* () {
   const desktopSettings = yield* DesktopAppSettingsService.DesktopAppSettings;
   const stateRef = yield* Ref.make(initialRuntimeState());
 
+  // Cache the `tailscale status` spawn for the TTL. On macOS, the Mac App
+  // Store Tailscale CLI lives inside Tailscale's sandbox container, so each
+  // spawn re-triggers the "Other apps" TCC prompt.
+  const cachedReadMagicDnsName = yield* Effect.cachedWithTTL(
+    readTailscaleStatus.pipe(
+      Effect.map((status) => status.magicDnsName),
+      Effect.orElseSucceed(() => null),
+      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner),
+    ),
+    TAILSCALE_STATUS_CACHE_TTL,
+  );
+
   const readNetworkInterfaces = networkInterfaces.read;
 
   const getState = Ref.get(stateRef).pipe(Effect.map(toContractState));
@@ -516,11 +532,20 @@ const make = Effect.gen(function* () {
       exposure: toResolvedExposure(state),
       customHttpsEndpointUrls: config.desktopHttpsEndpointUrls,
     });
+
+    // Don't spawn the Tailscale CLI when the user hasn't opted into any
+    // network exposure. The spawn itself triggers a macOS "Other apps"
+    // TCC prompt on Mac App Store Tailscale builds.
+    if (state.mode !== "network-accessible" && !state.tailscaleServeEnabled) {
+      return coreEndpoints;
+    }
+
     const tailscaleEndpoints = yield* resolveTailscaleAdvertisedEndpoints({
       port: state.port,
       serveEnabled: state.tailscaleServeEnabled,
       servePort: state.tailscaleServePort,
       networkInterfaces: currentNetworkInterfaces,
+      readMagicDnsName: cachedReadMagicDnsName,
     }).pipe(
       Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner),
       Effect.provideService(HttpClient.HttpClient, httpClient),

apps/desktop/src/backend/tailscaleEndpointProvider.test.ts

@@ -104,6 +104,25 @@ describe("tailscale endpoint provider", () => {
     }).pipe(Effect.provide(unusedTailscaleExternalServicesLayer)),
   );
 
+  it.effect("uses an injected magic DNS name reader instead of spawning tailscale", () =>
+    Effect.gen(function* () {
+      let readerCalls = 0;
+      const endpoints = yield* resolveTailscaleAdvertisedEndpoints({
+        port: 3773,
+        networkInterfaces: {},
+        readMagicDnsName: Effect.sync(() => {
+          readerCalls += 1;
+          return "desktop.tail.ts.net";
+        }),
+      });
+      assert.equal(readerCalls, 1);
+      assert.deepEqual(
+        endpoints.map((endpoint) => endpoint.httpBaseUrl),
+        ["https://desktop.tail.ts.net/"],
+      );
+    }).pipe(Effect.provide(unusedTailscaleExternalServicesLayer)),
+  );
+
   it.effect(
     "marks the Tailscale HTTPS endpoint available after Serve is enabled and reachable",
     () =>

apps/desktop/src/backend/tailscaleEndpointProvider.ts

@@ -105,22 +105,30 @@ export const resolveTailscaleAdvertisedEndpoints = Effect.fn("resolveTailscaleAd
     readonly servePort?: number;
     readonly networkInterfaces: DesktopNetworkInterfaces;
     readonly statusJson?: string | null;
+    readonly readMagicDnsName?: Effect.Effect<
+      string | null,
+      never,
+      ChildProcessSpawner.ChildProcessSpawner
+    >;
     readonly probe?: (baseUrl: string) => Effect.Effect<boolean, never, HttpClient.HttpClient>;
   }): Effect.fn.Return<
     readonly AdvertisedEndpoint[],
     never,
     ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient
   > {
     const ipEndpoints = resolveTailscaleIpAdvertisedEndpoints(input);
+    const readDnsName =
+      input.readMagicDnsName ??
+      readTailscaleStatus.pipe(
+        Effect.map((status) => status.magicDnsName),
+        Effect.catch(() => Effect.succeed<string | null>(null)),
+      );
     const dnsName =
       input.statusJson === undefined
-        ? yield* readTailscaleStatus.pipe(
-            Effect.map((status) => status.magicDnsName),
-            Effect.catch(() => Effect.succeed(null)),
-          )
+        ? yield* readDnsName
         : input.statusJson
           ? yield* parseTailscaleMagicDnsName(input.statusJson).pipe(
-              Effect.catch(() => Effect.succeed(null)),
+              Effect.orElseSucceed(() => null),
             )
           : null;
     const magicDnsEndpoint = yield* resolveTailscaleMagicDnsAdvertisedEndpoint({