@voltro/cli 0.38.0 → 0.39.0

package/templates/apps/mobile-app/src/app/_layout.tsx

@@ -1,21 +1,35 @@
-// Root layout — wires the Voltro client provider, deep-link routing, and a
-// connection banner around the whole app.
+// Root layout — wires the Voltro client, deep-link routing, and a connection
+// banner around the whole app.
 //
-// NOTE: `buildApiHandles()` is the M0 seam (see ../client.ts). Until the RN boot
-// helper lands it returns an empty map, so the hooks render their loading state
-// rather than live data — deliberately honest, not a crash.
+// The boot ORDER here is load-bearing, and it is the one thing to preserve if
+// you rewrite this file:
+//
+//   1. hydrate persisted stores, THEN install them as the backing store;
+//   2. only then render the app.
+//
+// A store reads during render and a render cannot await, so rendering first
+// shows empty state and flickers into the saved state a frame later. The splash
+// screen stays up until step 1 finishes — that is what it is for.
+//
+// Connecting is deliberately NOT part of that gate. The app must open offline.
 import { useEffect, useState } from 'react'
 import { Stack, useRouter } from 'expo-router'
 import * as Linking from 'expo-linking'
+import * as SplashScreen from 'expo-splash-screen'
 import { StatusBar } from 'expo-status-bar'
-import { FrameworkRuntimesProvider, type ApiHandle } from '@voltro/client'
+import { FrameworkRuntimesProvider, type ApiHandle, type ResolvedClient } from '@voltro/client'
 import { useMobileConnectionStatus } from '@voltro/react-native'
 import { Text, View } from 'react-native'
-import { buildApiHandles } from '../client'
+import { connectApis, handlesFor, onlineSource, preparePersistence } from '../client'
 import { handleDeepLink, makeDeepLinks } from '../lib/deeplinks'
 
+void SplashScreen.preventAutoHideAsync()
+
 function ConnectionBanner() {
-  const { status } = useMobileConnectionStatus()
+  // Reachability comes from NetInfo. The default source reads `navigator.onLine`,
+  // which React Native does not have — so on a device it would answer "online"
+  // forever, including in airplane mode.
+  const { status } = useMobileConnectionStatus({ onlineSource })
   if (status === 'connected') return null
   return (
     <View style={{ backgroundColor: status === 'offline' ? '#b91c1c' : '#b45309', padding: 8 }}>
@@ -27,16 +41,31 @@ function ConnectionBanner() {
 }
 
 export default function RootLayout() {
-  // Build the api handle map once on mount (async — it opens the WebSocket via
-  // @voltro/client's buildApiRuntime). Empty until it resolves; the hooks render
-  // their loading state meanwhile.
+  const [ready, setReady] = useState(false)
   const [apis, setApis] = useState<ReadonlyMap<string, ApiHandle>>(() => new Map())
+  const router = useRouter()
+
+  // 1. Persisted state, before anything renders.
   useEffect(() => {
     let live = true
-    void buildApiHandles().then((map) => { if (live) setApis(map) })
+    void preparePersistence()
+      .catch(() => { /* a device with no readable storage still gets an app */ })
+      .finally(() => {
+        if (!live) return
+        setReady(true)
+        void SplashScreen.hideAsync()
+      })
     return () => { live = false }
   }, [])
-  const router = useRouter()
+
+  // 2. Connect, and keep connected. The supervisor re-dials with backoff; a
+  //    dropped socket needs no handling here.
+  useEffect(() => {
+    const supervisor = connectApis((clients: ReadonlyMap<string, ResolvedClient>) => {
+      setApis(handlesFor(clients))
+    })
+    return () => supervisor.dispose()
+  }, [])
 
   // Route inbound URLs (universal links, custom scheme, push taps) through the
   // ONE typed link table — the same `matchFirstDeepLink` path push will use.
@@ -51,6 +80,8 @@ export default function RootLayout() {
     return () => sub.remove()
   }, [router])
 
+  if (!ready) return null
+
   return (
     <FrameworkRuntimesProvider apis={apis}>
       <StatusBar style="auto" />

package/templates/apps/mobile-app/src/app/index.tsx

@@ -3,7 +3,7 @@
 // The SAME hooks as the web frontend: `useSubscription('notes.list')` streams
 // the server-side query; `useMutation('notes.create')` writes it. When the
 // mutation lands, the server pushes a delta and this list re-renders — no
-// refetch, no polling. (Requires the M0 client boot; see ../client.ts.)
+// refetch, no polling.
 //
 // Both come from `../lib/api`, which binds them ONCE to the api's generated
 // procedure map — so the tag autocompletes, a typo is a compile error, and the

package/templates/apps/mobile-app/src/app/settings.tsx

@@ -3,9 +3,12 @@ import { useState } from 'react'
 import { Pressable, Text, View } from 'react-native'
 import { useMobileConnectionStatus } from '@voltro/react-native'
 import { buildDeviceRegistration } from '../lib/notifications'
+import { onlineSource } from '../client'
 
 export default function Settings() {
-  const { status, reportSuccess, reportFailure } = useMobileConnectionStatus()
+  // Same injected source as the banner in _layout: the default reads
+  // `navigator.onLine`, which React Native does not have.
+  const { status, reportSuccess, reportFailure } = useMobileConnectionStatus({ onlineSource })
   const [registered, setRegistered] = useState<string | null>(null)
 
   return (

package/templates/apps/mobile-app/src/client.ts

@@ -1,74 +1,91 @@
 // The Voltro client for React Native.
 //
-// The transport keystone now EXISTS: `@voltro/client`'s `buildApiRuntime` builds
-// the runtime + subscription cache + rpc client over a WebSocket, and it takes
-// the WebSocket constructor as an INJECTED dependency — so React Native passes
-// its own `globalThis.WebSocket` (which RN provides) and gets the SAME client
-// stack the web app uses, without pulling in `@voltro/web`. See
-// plans/open/mobile/00-overview.md (M0).
+// Three pieces, all of them SHARED with the web client rather than
+// re-implemented for mobile:
 //
-// ┌─ THE ONE REMAINING SEAM ─────────────────────────────────────────────────┐
-// │ `buildApiHandle` below is functional. What it still needs is the api's rpc │
-// │ GROUP + descriptor map — on web these come from codegen's generated entry. │
-// │ A `voltro codegen` mobile target that emits them for this app is the next  │
-// │ M-step (plans/open/mobile/01). Until it lands, `buildApiHandles()` returns │
-// │ an empty map (the screens show their loading state) rather than faking it. │
-// └──────────────────────────────────────────────────────────────────────────┘
+//   · `mobileApis` — the generated binding (`.framework/mobileApis.generated.ts`,
+//     written by `voltro codegen` from `voltro.mobile.ts`). It carries the api's
+//     rpc group and descriptors, so the hooks are typed end to end from the
+//     api's own schema.
+//   · `startMobileApis` — connect + reconnect, over the SAME supervisor
+//     `@voltro/web` uses: exponential backoff, generation tracking, and the
+//     stale-seed gate that must not carry one subject's rows into the next.
+//   · `createAsyncStoragePersistence` — persisted stores over AsyncStorage,
+//     hydrated BEFORE the first render (a render cannot await).
+//
+// The ws URL is resolved at runtime, never baked in. `localhost` on a phone is
+// the PHONE — the single most common reason a mobile dev loop silently never
+// connects — so `resolveDevWsUrl` takes the LAN host Expo already knows.
 
-import { buildApiRuntime, type ApiHandle, type BuildApiRuntimeOptions } from '@voltro/client'
-import { offlineFirstDefaults } from '@voltro/react-native'
+import Constants from 'expo-constants'
+import NetInfo from '@react-native-community/netinfo'
+import { setStoreStorage, type ResolvedClient } from '@voltro/client'
+import {
+  createAsyncStoragePersistence,
+  netInfoOnlineSource,
+  offlineFirstDefaults,
+  resolveDevWsUrl,
+  startMobileApis,
+  toApiHandles,
+} from '@voltro/react-native'
+import { mobileApis } from '../.framework/mobileApis.generated'
+import { storeStorage } from './persistence'
 
-/** The api's rpc group type — sourced from @voltro/client so the template needs
- *  no direct @effect/rpc dependency. Codegen produces the concrete value. */
-type ApiRpcGroup = BuildApiRuntimeOptions['group']
+/** The api's port, as `voltro dev` allocates it. Override per environment. */
+const API_PORT = Number(process.env.EXPO_PUBLIC_API_PORT ?? 4000)
 
-/** The api's base URL. On a simulator/device this must be your machine's LAN
- *  address (not `localhost`), e.g. `http://192.168.1.20:4000`. */
-export const API_URL = process.env.EXPO_PUBLIC_API_URL ?? 'http://localhost:4000'
+/**
+ * The api's WebSocket URL.
+ *
+ * In development this is derived from the host running Metro, so a real device
+ * on the same wifi reaches your machine. In production set
+ * `EXPO_PUBLIC_API_WS_URL` to the deployed api.
+ */
+export const apiWsUrl = (): string =>
+  process.env.EXPO_PUBLIC_API_WS_URL
+  ?? resolveDevWsUrl(Constants.expoConfig?.hostUri, API_PORT)
 
-/** The offline-first posture spread into the app's client config. */
+/** The offline-first posture (local-first on, optimistic writes, sync status
+ *  surfaced). Spread into a client config, or read for UI decisions. */
 export const clientPosture = offlineFirstDefaults
 
-/** http(s)://host:port → ws(s)://host:port/ws (the api's WebSocket endpoint). */
-const toWsUrl = (httpUrl: string): string =>
-  `${httpUrl.replace(/^http/, 'ws').replace(/\/+$/, '')}/ws`
+/** Reachability, from NetInfo. Module scope on purpose: an inline
+ *  `netInfoOnlineSource(NetInfo)` is a new object every render, and the hook
+ *  would resubscribe on each one. */
+export const onlineSource = netInfoOnlineSource(NetInfo)
 
-/** React Native provides a global WebSocket; no tracking/reconnect wrapper here
- *  yet (the RN reconnect supervisor is a later M-step — plans/open/mobile/03). */
-const rnWebSocket = (url: string, protocols?: string | ReadonlyArray<string>): globalThis.WebSocket =>
-  new globalThis.WebSocket(url, protocols as string | string[] | undefined)
+/** Persisted stores, backed by AsyncStorage — NOT the Keychain. `persistence.ts`
+ *  says why, and where a secret goes instead. */
+export const persistence = createAsyncStoragePersistence({ storage: storeStorage })
 
 /**
- * Build one api's {@link ApiHandle} for the RN client provider. Fully functional
- * — hand it the codegen-produced `group` + `descriptors` for the api and it
- * returns a live handle. `descriptors` is `ClientDescriptor`-shaped
- * (see @voltro/client); pass the generated map.
+ * Load persisted state and install it as the backing store for every
+ * `defineStore({ persist })`.
+ *
+ * MUST be awaited before the first render. A store reads during render and a
+ * render cannot await, so an app that renders first shows empty state and then
+ * flickers into the saved one. The root layout holds the splash screen until
+ * this resolves.
  */
-export const buildApiHandle = async (
-  name: string,
-  group: ApiRpcGroup,
-  descriptors: ApiHandle['descriptors'],
-): Promise<ApiHandle> => {
-  const wsUrl = toWsUrl(API_URL)
-  const built = await buildApiRuntime({ name, wsUrl, group, webSocketConstructor: rnWebSocket })
-  return {
-    runtime: built.runtime,
-    cache: built.cache,
-    client: built.client as ApiHandle['client'],
-    descriptors,
-    inspectBaseUrl: API_URL.replace(/\/+$/, ''),
-    errorBus: built.errorBus,
-  }
+export const preparePersistence = async (): Promise<void> => {
+  await persistence.hydrate()
+  setStoreStorage(persistence.provider)
 }
 
+/** Every api this app talks to, bound to the resolved ws URL. */
+export const apis = mobileApis(() => apiWsUrl())
+
 /**
- * Build the `apis` map `FrameworkRuntimesProvider` needs. Returns an empty map
- * until codegen emits this app's rpc group (the seam above) — then map each
- * configured api through {@link buildApiHandle}.
+ * Connect the apis and keep them connected.
+ *
+ * `onChange` fires on the first connect, on every reconnect swap, and on
+ * teardown. Dispose the returned handle when the tree unmounts; call
+ * `reconnect()` after a sign-in so the connection re-resolves who it is.
  */
-export const buildApiHandles = async (): Promise<ReadonlyMap<string, ApiHandle>> => {
-  // Once codegen targets mobile:
-  //   const { rpcGroup, descriptors } = await import('./rpcGroup.generated')
-  //   return new Map([['app', await buildApiHandle('app', rpcGroup, descriptors)]])
-  return new Map<string, ApiHandle>()
-}
+export const connectApis = (
+  onChange: (clients: ReadonlyMap<string, ResolvedClient>, initialized: boolean) => void,
+) => startMobileApis({ apis, onChange })
+
+/** Map the live clients into the `apis` prop the client provider takes. */
+export const handlesFor = (clients: ReadonlyMap<string, ResolvedClient>) =>
+  toApiHandles(apis, clients)

package/templates/apps/mobile-app/src/lib/api.ts

@@ -21,10 +21,10 @@
 // that reason; scaffold the pair (`create-project --api=api-backend --mobile`),
 // which is what this template's README already assumes.
 //
-// RUNTIME NOTE: the hooks are typed today and live once the mobile codegen
-// target lands — `buildApiHandles()` in ../client.ts still returns an empty map
-// (see the seam documented there), so screens render their loading state until
-// then. The TYPES are real either way; they come from the api's own descriptors.
+// RUNTIME: live. `voltro codegen` writes this app's api binding into
+// `.framework/mobileApis.generated.ts` (from `voltro.mobile.ts`), and
+// `../client.ts` connects it through the same supervisor the web client uses.
+// The start scripts run codegen, so `pnpm ios` needs no separate step.
 import { createHooks } from '@voltro/client'
 import type { AppProcedures } from '@{{projectName}}/api/rpcGroup'
 

package/templates/apps/mobile-app/src/lib/deeplinks.ts

@@ -6,12 +6,12 @@
 // come from `@voltro/react-native`; this module is browser/RN-safe (no Metro, no
 // screens), which is exactly why it is unit-testable without a simulator.
 //
-// Declaration order wins in `matchFirstDeepLink`, so list more-specific patterns
+// Declaration order wins in `dispatchDeepLink`, so list more-specific patterns
 // FIRST. The `navigate` callback is injected (the screen layer passes
 // expo-router's `router.push`), keeping this table pure + testable.
 import {
   defineDeepLink,
-  matchFirstDeepLink,
+  dispatchDeepLink,
   type DeepLinkDescriptor,
 } from '@voltro/react-native'
 
@@ -32,8 +32,8 @@ export const handleDeepLink = (
   links: ReadonlyArray<DeepLinkDescriptor>,
   url: string,
 ): boolean => {
-  const hit = matchFirstDeepLink(links, url)
-  if (hit === null) return false
-  hit.descriptor.handler(hit.params)
-  return true
+  // `dispatchDeepLink` matches AND runs. Doing it in two steps here does not
+  // typecheck: the descriptors are a heterogeneous array, so the handler that
+  // comes back declares params the match that produced it cannot satisfy.
+  return dispatchDeepLink(links, url) !== null
 }

package/templates/apps/mobile-app/src/persistence.ts

@@ -8,9 +8,15 @@
 // Putting a session token in AsyncStorage is a security bug; secure-store is its
 // home.
 //
-// This is a generic async KV. M0 adapts it to whichever persistence CONTRACT it
-// wires (the client cache and/or `@voltro/local-first`'s `PersistenceAdapter`) —
-// it does not itself claim to satisfy a framework interface that would drift.
+// Two exports, and the split between them is the point:
+//   - `kv` is the APP's own store for things it manages itself, tokens included.
+//   - `storeStorage` backs `defineStore({ persist })` and is AsyncStorage ONLY.
+//
+// A persisted store is app STATE — a draft, a filter, a wizard step — and none of
+// that belongs in the Keychain, which cannot be enumerated and which the OS may
+// gate behind a biometric prompt. A secret does not belong in a persisted store
+// either; put it through `kv` with `secretKey()`. Routing store keys by prefix
+// would blur a rule worth keeping sharp.
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import * as SecureStore from 'expo-secure-store'
 
@@ -36,3 +42,18 @@ export const kv = {
 
 /** Prefix a key so it lands in secure storage. */
 export const secretKey = (name: string): string => `${SECRET_PREFIX}${name}`
+
+/**
+ * The backing store for `defineStore({ persist })`, handed to
+ * `createAsyncStoragePersistence()` in `src/client.ts`.
+ *
+ * Deliberately AsyncStorage alone — see the header. `getAllKeys` is what lets
+ * the adapter hydrate without being told which keys exist; SecureStore has no
+ * equivalent, which is the second reason secrets do not live here.
+ */
+export const storeStorage = {
+  getItem: (key: string): Promise<string | null> => AsyncStorage.getItem(key),
+  setItem: (key: string, value: string): Promise<void> => AsyncStorage.setItem(key, value),
+  removeItem: (key: string): Promise<void> => AsyncStorage.removeItem(key),
+  getAllKeys: async (): Promise<ReadonlyArray<string>> => AsyncStorage.getAllKeys(),
+}

package/templates/apps/mobile-app/tsconfig.json

@@ -3,8 +3,22 @@
   "compilerOptions": {
     "strict": true,
     "paths": {
-      "@/*": ["./src/*"]
-    }
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "types": [
+      "node",
+      "react"
+    ]
   },
-  "include": ["src", "app.config.ts", "tests", ".expo/types/**/*.ts", "expo-env.d.ts"]
+  "include": [
+    "src",
+    "app.config.ts",
+    "tests",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts"
+  ]
 }

package/dist/addCommand-aXSQveak.js

@@ -1,2 +0,0 @@
-import { r as e } from "./addCommand-BNeoeSxe.js";
-export { e as runAddCommand };

package/dist/agentsMd-BTchIZku.js

@@ -1,2 +0,0 @@
-import { a as e } from "./agentsMd-mhQMF1bx.js";
-export { e as runAgentsMd };

package/dist/apiBuild-ttSDDOGp.js

@@ -1,2 +0,0 @@
-import { c as e, l as t } from "./apiBuild-CvacV4zA.js";
-export { e as runApiBuild, t as runServeBundleBuild };

package/dist/baselineCommand-Cfw2Afwm.js

@@ -1,2 +0,0 @@
-import { o as e } from "./baselineCommand-C6NMt-oa.js";
-export { e as runBaselineCommand };

package/dist/codegen-uYrrDzQv.js

@@ -1,2 +0,0 @@
-import { t as e } from "./codegen-GYYcdpCg.js";
-export { e as checkRpcGroupFreshness };

package/dist/codegenCommand-C60m_LCp.js

@@ -1,30 +0,0 @@
-import { l as e, z as t } from "./dev-E7Eo5GHc.js";
-import { r as n } from "./codegen-GYYcdpCg.js";
-import { basename as r, relative as i, resolve as a } from "node:path";
-//#region src/codegenCommand.ts
-var o = async (i) => {
-	let { config: a, present: o, error: s } = await e(i);
-	if (o && a === null) return {
-		kind: "refused",
-		reason: "app.config.ts exists but could not be loaded" + (s === void 0 ? "" : ` — ${s instanceof Error ? s.message : String(s)}`)
-	};
-	let c = a?.plugins ?? [], { pluginContributions: l, pluginErrorImports: u, pluginRpcImports: d } = await t(c, a?.name ?? r(i), i), f = await n({
-		root: i,
-		...l.length > 0 ? { pluginContributions: l } : {},
-		...u.length > 0 ? { pluginErrorImports: u } : {},
-		...d.length > 0 ? { pluginRpcImports: d } : {},
-		...a?.name === void 0 ? {} : { apiName: a.name }
-	});
-	return f ? {
-		kind: "wrote",
-		file: f,
-		plugins: c.length,
-		errorSchemas: u.length,
-		routes: d.length
-	} : { kind: "nothing-to-write" };
-}, s = async (e) => {
-	let t = a(e.find((e) => !e.startsWith("-")) ?? process.cwd()), n = await o(t);
-	return n.kind === "refused" ? (console.error(`voltro codegen: ${n.reason} — refusing to write.`), console.error("  The generated file would omit every plugin's error union and client routes, and would typecheck, so the omission would only surface as a missing error tag at runtime."), 1) : n.kind === "nothing-to-write" ? (console.log("voltro codegen: no rpc primitives found — nothing to write."), 0) : (console.log(`voltro codegen: wrote ${i(t, n.file)} (plugins ${n.plugins}, error schemas ${n.errorSchemas}, plugin routes ${n.routes})`), n.plugins > 0 && n.errorSchemas === 0 && console.log("  note: no plugin contributed a cross-cutting error schema, so the wire error union carries only each procedure's own `error:`. Expected if none of your plugins declare `errorSchemas` — but `guards:` needs @voltro/plugin-rbac for its ScopeError to decode typed."), 0);
-};
-//#endregion
-export { o as regenerateRpcGroup, s as runCodegenCommand };

package/dist/dbCommand-CC-qNzpz.js

@@ -1,2 +0,0 @@
-import { s as e } from "./dbCommand-C4UW8cVN.js";
-export { e as runDbCommand };

package/dist/dev-CAOoXOkc.js

@@ -1,3 +0,0 @@
-import { c as e, d as t, f as n, i as r, u as i } from "./dev-E7Eo5GHc.js";
-import "./dialectDriver-CgXnDfec.js";
-export { r as buildStore, e as loadApiConfig, i as loadDiscovered, t as runDev, n as walk };

package/dist/doctorCommand-Cjl8Yii8.js

@@ -1,2 +0,0 @@
-import { v as e, y as t } from "./doctorCommand-gmDyALFL.js";
-export { e as runDoctorCommand, t as runServePreflight };