feat(mobile): one cached native-client install command for agents and machines

.agents/skills/test-t3-mobile/SKILL.md

@@ -31,11 +31,15 @@ when inspecting or seeding SQLite. Stop the test server before fixture writes.
 From the checkout being tested on the selected device host, run:
 
 ```bash
-node scripts/mobile-native-client.ts ensure <ios|android> <device-id>
+vp run mobile:install <ios|android> <device-id>
 ```
 
-This reuses a matching native client or builds and installs one. Authorized
-mobile verification includes that build step unless the user prohibits it.
+This installs the dev client for the checkout's native fingerprint: from the
+device, the local cache, or the shared cache in seconds, building once only
+when no machine has that fingerprint yet (5-15 minutes, logged to the file it
+names). The device id may be omitted when exactly one device is booted. It
+prints one JSON line; on failure it names the next command. Authorized mobile
+verification includes that step unless the user prohibits it.
 
 Start `vp run dev:client` from `apps/mobile`, or reuse a healthy Metro belonging
 to this checkout. Open its printed development-client URL with AgentDevice

AGENTS.md

@@ -134,7 +134,7 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 
 - Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
 
-For authorized mobile verification, a missing or outdated native client is a build step, not a blocker. Run `node scripts/mobile-native-client.ts ensure <ios|android> <device-id>` on the simulator host before starting Metro. It checks the local Expo fingerprint and builds/installs when needed. See `test-t3-mobile` for the full workflow.
+For authorized mobile verification, a missing or outdated native client is an install step, not a blocker. Run `vp run mobile:install <ios|android> [device-id]` on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over `expo run:*`, `xcodebuild`, or `gradlew`, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See `test-t3-mobile` for the full workflow.
 
 ## Pull requests
 

apps/mobile/README.md

@@ -22,20 +22,28 @@ repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
 
 ## Development
 
-For simulator/emulator development, select and boot a device, then ensure its native client matches
-this checkout before starting Metro:
+For simulator, emulator, or Android phone development, boot or connect a device, then install the
+native client that matches this checkout before starting Metro:
 
 ```bash
-node ../../scripts/mobile-native-client.ts ensure ios <simulator-udid>
-# Or: node ../../scripts/mobile-native-client.ts ensure android <emulator-serial>
+vp run mobile:install ios [simulator-udid]
+# Or: vp run mobile:install android [emulator-or-phone-serial]
 vp run dev:client
 ```
 
-The helper compares a local Expo fingerprint and the installed binary with its last successful
-build record. It builds and installs missing, stale, or unverified clients and reuses matching ones.
-Use `check` instead of `ensure` for a read-only decision: exit 0 means compatible, 2 means a build is
-needed, and 1 means an operational error. Run it on the simulator host; no EAS login is required.
-An externally installed client is unverified until the helper builds it once.
+The device argument can be omitted when exactly one device is booted or connected. The helper
+compares this checkout's Expo fingerprint and the installed binary with its last install record,
+and reuses a matching client. Otherwise it installs the build for that fingerprint from
+`~/.cache/t3code/native-clients/artifacts`, then the shared task cache, and builds only when
+neither has it. One iOS simulator build serves every iPhone and iPad simulator, and one APK per
+ABI (x86_64 or arm64-v8a) serves every emulator and phone of that ABI. Build output goes to the
+log file it prints (`T3_NATIVE_CLIENT_VERBOSE=1` streams it instead). Builds are shared back when
+your task-cache login (`bash infra/task-cache/install.sh`) can write. `T3_NATIVE_CLIENT_CACHE=read`
+skips the upload and `off` skips the shared cache. Physical iPhones still use `vp run ios:dev`.
+
+For a read-only decision, run `node ../../scripts/mobile-native-client.ts check <ios|android>
+[device]`: exit 0 means compatible, 2 means an install is needed, and 1 means an operational error.
+An externally installed client is unverified until the helper installs it once.
 
 Start Metro for an already verified dev client:
 

infra/task-cache/README.md

@@ -51,6 +51,10 @@ vp run --filter @t3tools/task-cache typecheck
 
 The smoke check uploads a unique fixture, restores its output into a cold second directory, changes its input, and confirms recomputation. It also checks that anonymous reads and uploads are rejected. Cacheable commands must run through `vp run`; direct `vp test` or `vp check` invocations do not use this cache.
 
+## Native clients
+
+`/projects/t3code/native-clients/<platform>/<variant>/<expo-fingerprint>` stores simulator and emulator development clients for `scripts/mobile-native-client.ts` in a separate `-native-clients` R2 bucket with 30-day retention. Unlike Vite Task entries, the Expo fingerprint is portable, so a client built on any Mac or Linux machine serves every other one. Readers download; writers upload through R2 multipart in 64 MB parts, because Workers cap request bodies. The uploader's bundle digest is stored as object metadata and checked by the client before it installs anything.
+
 ## Current limits
 
 - Vite Task separates operating systems and CPU architectures. macOS results do not satisfy Linux CI; Linux developer machines can populate compatible CI results.

infra/task-cache/src/NativeClients.test.ts

@@ -0,0 +1,135 @@
+import { expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as NativeClients from "./NativeClients.ts";
+
+const tokenDigest = "210eb3d2c67a7207923e1999751300a87a2dd22839b258b80c3d805a6fe64984";
+const auth = (name: string) => ({
+  authorization: `Basic ${btoa(`${name}:fixture-token-012345678901234567890123456789`)}`,
+});
+const key = `ios/development/${"a".repeat(40)}`;
+const base = `https://cache.example${NativeClients.routePrefix}${key}`;
+
+function memoryBucket() {
+  const objects = new Map<string, { bytes: ArrayBuffer; customMetadata: Record<string, string> }>();
+  const uploads = new Map<
+    string,
+    { key: string; customMetadata: Record<string, string>; parts: Map<number, ArrayBuffer> }
+  >();
+  const resume = (objectKey: string, uploadId: string) => ({
+    uploadPart: async (partNumber: number, body: ReadableStream) => {
+      uploads.get(uploadId)!.parts.set(partNumber, await new Response(body).arrayBuffer());
+      return { partNumber, etag: `etag-${partNumber}` };
+    },
+    complete: async (parts: ReadonlyArray<{ partNumber: number }>) => {
+      const upload = uploads.get(uploadId)!;
+      const chunks = parts.map(({ partNumber }) => upload.parts.get(partNumber)!);
+      objects.set(objectKey, {
+        bytes: await new Blob(chunks).arrayBuffer(),
+        customMetadata: upload.customMetadata,
+      });
+      uploads.delete(uploadId);
+    },
+    abort: async () => void uploads.delete(uploadId),
+  });
+  return {
+    head: async (objectKey: string) => (objects.has(objectKey) ? {} : null),
+    get: async (objectKey: string) => {
+      const object = objects.get(objectKey);
+      return object
+        ? {
+            size: object.bytes.byteLength,
+            body: new Blob([object.bytes]).stream(),
+            customMetadata: object.customMetadata,
+          }
+        : null;
+    },
+    createMultipartUpload: async (
+      objectKey: string,
+      options: { customMetadata: Record<string, string> },
+    ) => {
+      const uploadId = `upload/${uploads.size}+`;
+      uploads.set(uploadId, {
+        key: objectKey,
+        customMetadata: options.customMetadata,
+        parts: new Map(),
+      });
+      return { uploadId };
+    },
+    resumeMultipartUpload: resume,
+    uploads,
+  };
+}
+
+const request = (path: string, init: RequestInit & { name: string }) =>
+  Effect.gen(function* () {
+    const native = yield* NativeClients.NativeClients;
+    return yield* native.handle(
+      new Request(`${base}${path}`, {
+        ...init,
+        headers: { ...auth(init.name), ...init.headers },
+      }),
+    );
+  });
+
+it.effect("serves a writer's multipart upload to readers with its digest", () => {
+  const bucket = memoryBucket();
+  const bindings = {
+    CLIENTS: bucket,
+    developerKeys: JSON.stringify({ julius: tokenDigest }),
+    readerKeys: JSON.stringify({ "ci-reader": tokenDigest }),
+    readLimit: { limit: async () => ({ success: true }) },
+    storeLimit: { limit: async () => ({ success: true }) },
+  } as unknown as NativeClients.Bindings["Service"];
+  const digest = "d".repeat(64);
+  return Effect.gen(function* () {
+    const denied = yield* request("/uploads", {
+      name: "ci-reader",
+      method: "POST",
+      headers: { "x-t3-digest": digest },
+    });
+    expect(denied.status).toBe(403);
+
+    const created = yield* request("/uploads", {
+      name: "julius",
+      method: "POST",
+      headers: { "x-t3-digest": digest, "x-t3-build-ms": "540000" },
+    });
+    const { uploadId } = (yield* Effect.promise(() => created.json())) as { uploadId: string };
+    const parts = [];
+    for (const [index, chunk] of ["native ", "client"].entries()) {
+      const response = yield* request(`/uploads/${encodeURIComponent(uploadId)}/${index + 1}`, {
+        name: "julius",
+        method: "PUT",
+        body: chunk,
+        headers: { "content-length": String(chunk.length) },
+      });
+      const { etag } = (yield* Effect.promise(() => response.json())) as { etag: string };
+      parts.push({ partNumber: index + 1, etag });
+    }
+    const completed = yield* request(`/uploads/${encodeURIComponent(uploadId)}/complete`, {
+      name: "julius",
+      method: "POST",
+      body: JSON.stringify({ parts }),
+    });
+    expect(completed.status).toBe(204);
+
+    const download = yield* request("", { name: "ci-reader", method: "GET" });
+    expect(download.status).toBe(200);
+    expect(download.headers.get("x-t3-digest")).toBe(digest);
+    expect(download.headers.get("x-t3-build-ms")).toBe("540000");
+    expect(yield* Effect.promise(() => download.text())).toBe("native client");
+
+    const again = yield* request("/uploads", {
+      name: "julius",
+      method: "POST",
+      headers: { "x-t3-digest": digest },
+    });
+    expect(yield* Effect.promise(() => again.json())).toEqual({ exists: true });
+    expect(bucket.uploads.size).toBe(0);
+  }).pipe(
+    Effect.provide(
+      NativeClients.layer.pipe(Layer.provide(Layer.succeed(NativeClients.Bindings, bindings))),
+    ),
+  );
+});

infra/task-cache/src/NativeClients.ts

@@ -0,0 +1,183 @@
+import type * as Cloudflare from "@cloudflare/workers-types";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { developerIdentity } from "./developerAuth.ts";
+
+export const routePrefix = "/projects/t3code/native-clients/";
+
+export class NativeClientsError extends Schema.TaggedError<NativeClientsError>()(
+  "NativeClientsError",
+  { status: Schema.Number, reason: Schema.String },
+) {}
+
+export class Bindings extends Context.Service<
+  Bindings,
+  {
+    readonly CLIENTS: Cloudflare.R2Bucket;
+    readonly developerKeys: string;
+    readonly readerKeys: string;
+    readonly readLimit: Cloudflare.RateLimit;
+    readonly storeLimit: Cloudflare.RateLimit;
+  }
+>()("@t3tools/task-cache/NativeClients/Bindings") {}
+
+export class NativeClients extends Context.Service<
+  NativeClients,
+  { readonly handle: (request: Request) => Effect.Effect<Response> }
+>()("@t3tools/task-cache/NativeClients") {}
+
+const CompleteBody = Schema.fromJsonString(
+  Schema.Struct({
+    parts: Schema.Array(Schema.Struct({ partNumber: Schema.Number, etag: Schema.String })).check(
+      Schema.isMinLength(1),
+      Schema.isMaxLength(64),
+    ),
+  }),
+);
+const decodeComplete = Schema.decodeUnknownEffect(CompleteBody);
+
+// <platform>/<variant>/<fingerprint>[/uploads[/<uploadId>[/<part>|/complete]]]
+const route =
+  /^((?:ios|android)\/[a-z0-9_-]{1,32}\/[a-f0-9]{40,64})(?:\/uploads(?:\/([^/]{1,1024})(?:\/(complete|[1-9][0-9]?))?)?)?$/;
+const digestPattern = /^[a-f0-9]{64}$/;
+
+const make = Effect.gen(function* () {
+  const bindings = yield* Bindings;
+
+  const r2 = <A>(run: () => Promise<A>) =>
+    Effect.tryPromise({
+      try: run,
+      catch: () => new NativeClientsError({ status: 503, reason: "storage_unavailable" }),
+    });
+
+  const limit = Effect.fn("NativeClients.limit")(function* (writing: boolean) {
+    const allowed = yield* r2(() =>
+      (writing ? bindings.storeLimit : bindings.readLimit).limit({
+        key: writing ? "t3code:native-store" : "t3code:native-read",
+      }),
+    );
+    if (!allowed.success)
+      return yield* new NativeClientsError({ status: 429, reason: "rate_limit" });
+  });
+
+  const handle = Effect.fn("NativeClients.handle")(
+    function* (request: Request) {
+      const url = new URL(request.url);
+      const match = route.exec(url.pathname.slice(routePrefix.length));
+      if (!match || url.search || !url.pathname.startsWith(routePrefix))
+        return yield* new NativeClientsError({ status: 404, reason: "unknown_route" });
+      const [, key, uploadId, part] = match as unknown as [
+        string,
+        string,
+        string | undefined,
+        string | undefined,
+      ];
+      const operation =
+        uploadId === undefined
+          ? url.pathname.endsWith("/uploads")
+            ? "create"
+            : "download"
+          : part === undefined
+            ? "abort"
+            : part === "complete"
+              ? "complete"
+              : "part";
+      const method = {
+        download: "GET",
+        create: "POST",
+        part: "PUT",
+        complete: "POST",
+        abort: "DELETE",
+      }[operation];
+      yield* Effect.annotateCurrentSpan({ "native.operation": operation, "native.key": key });
+      if (request.method !== method)
+        return yield* new NativeClientsError({ status: 405, reason: "method_not_allowed" });
+      if (!request.headers.has("authorization"))
+        return yield* new NativeClientsError({ status: 401, reason: "missing_identity" });
+
+      const developer = yield* developerIdentity(request, bindings.developerKeys);
+      const writing = operation !== "download";
+      if (writing) {
+        if (typeof developer !== "string")
+          return yield* new NativeClientsError({ status: 403, reason: "write_denied" });
+      } else if (
+        typeof developer !== "string" &&
+        typeof (yield* developerIdentity(request, bindings.readerKeys)) !== "string"
+      ) {
+        return yield* new NativeClientsError({ status: 403, reason: "read_denied" });
+      }
+      yield* limit(writing);
+
+      if (operation === "download") {
+        const object = yield* r2(() => bindings.CLIENTS.get(key));
+        yield* Effect.annotateCurrentSpan({ "native.result": object ? "hit" : "miss" });
+        if (!object) return yield* new NativeClientsError({ status: 404, reason: "missing" });
+        return new Response(object.body as unknown as ReadableStream, {
+          headers: {
+            "Content-Type": "application/octet-stream",
+            "Content-Length": String(object.size),
+            "Cache-Control": "no-store",
+            "X-T3-Digest": object.customMetadata?.digest ?? "",
+            "X-T3-Build-Ms": object.customMetadata?.buildMs ?? "0",
+          },
+        });
+      }
+      if (operation === "create") {
+        const digest = request.headers.get("x-t3-digest") ?? "";
+        if (!digestPattern.test(digest))
+          return yield* new NativeClientsError({ status: 400, reason: "invalid_digest" });
+        if (yield* r2(() => bindings.CLIENTS.head(key))) {
+          yield* Effect.annotateCurrentSpan({ "native.result": "exists" });
+          return Response.json({ exists: true });
+        }
+        const buildMs = request.headers.get("x-t3-build-ms") ?? "";
+        const upload = yield* r2(() =>
+          bindings.CLIENTS.createMultipartUpload(key, {
+            customMetadata: {
+              digest,
+              writer: developer!,
+              buildMs: /^\d{1,10}$/.test(buildMs) ? buildMs : "0",
+            },
+          }),
+        );
+        return Response.json({ uploadId: upload.uploadId });
+      }
+
+      const upload = bindings.CLIENTS.resumeMultipartUpload(key, decodeURIComponent(uploadId!));
+      if (operation === "abort") {
+        yield* r2(() => upload.abort());
+        return new Response(null, { status: 204 });
+      }
+      if (operation === "part") {
+        if (!request.body || !request.headers.has("content-length"))
+          return yield* new NativeClientsError({ status: 411, reason: "length_required" });
+        const uploaded = yield* r2(() =>
+          upload.uploadPart(Number(part), request.body as unknown as Cloudflare.ReadableStream),
+        );
+        return Response.json({ etag: uploaded.etag });
+      }
+      const body = yield* decodeComplete(
+        yield* r2(() => request.text().then((text) => text.slice(0, 64 * 1024))),
+      ).pipe(
+        Effect.mapError(() => new NativeClientsError({ status: 400, reason: "invalid_parts" })),
+      );
+      yield* r2(() => upload.complete([...body.parts]));
+      yield* Effect.annotateCurrentSpan({ "native.result": "stored" });
+      return new Response(null, { status: 204 });
+    },
+    Effect.catchTags({
+      NativeClientsError: (error) =>
+        Effect.gen(function* () {
+          if (error.status >= 500)
+            yield* Effect.logWarning("Native client request failed", { reason: error.reason });
+          return Response.json({ error: error.reason }, { status: error.status });
+        }),
+    }),
+  );
+
+  return NativeClients.of({ handle });
+});
+
+export const layer = Layer.effect(NativeClients, make);