@helloleo/plugins 0.2.27 → 0.2.29-beta.0

package/dist/templates/tanstack-start-2026-07-30/package.json

@@ -15,7 +15,7 @@
     "lint": "oxlint --fix"
   },
   "dependencies": {
-    "@helloleo/runtime": "^0.1.4",
+    "@helloleo/runtime": "0.2.0-beta.0",
     "@hookform/resolvers": "^5.4.0",
     "@radix-ui/react-accordion": "^1.2.15",
     "@radix-ui/react-alert-dialog": "^1.1.18",
@@ -44,9 +44,9 @@
     "@radix-ui/react-toggle-group": "^1.1.14",
     "@radix-ui/react-tooltip": "^1.2.11",
     "@tailwindcss/vite": "^4.3.2",
-    "@tanstack/react-query": "^5.101.2",
+    "@tanstack/react-query": "^5.102.8",
     "@tanstack/react-router": "^1.170.17",
-    "@tanstack/react-router-with-query": "^1.130.17",
+    "@tanstack/react-router-ssr-query": "^1.167.2",
     "@tanstack/react-start": "^1.168.27",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/dist/templates/tanstack-start-2026-07-30/src/lib/cache.ts

@@ -0,0 +1,60 @@
+/**
+ * Cached reads — declare them here, never call the upstream straight from a
+ * loader.
+ *
+ * A heavy read (a search over thousands of rows, a report the integration takes
+ * seconds to build) is slow AND spends the customer's quota on that system, so a
+ * dashboard that re-queries on every render burns both. `withCache` puts a TTL
+ * in front of one read and hands back a plain function: the loader calls
+ * `getOdooPartners()` and nothing about the cache leaks into the call site.
+ *
+ * The function also carries .refresh() and .purge(), which is how a page offers
+ * the user current data without knowing anything about KV.
+ *
+ * Declare at MODULE SCOPE, in a server-side file like this one. A withCache
+ * call at the top of a route component file would evaluate in the browser too,
+ * shipping the fetcher and the integration call it makes to the client.
+ *
+ * Nothing refreshes on a schedule. What keeps a value fresh is its TTL expiring
+ * and the next visitor paying for one live read, plus .refresh() when someone
+ * presses the button for it.
+ *
+ * Rules:
+ * - Server-side only (loaders, server routes), like every other binding.
+ * - TTL is in SECONDS and must be at least 60 (KV's own floor). Pick it from
+ *   how stale the data may be: a stock level is minutes, a price list is hours.
+ * - Cached data is NEVER the source of truth. Expiry is Cloudflare's own, and
+ *   purging a key is always safe — it costs one slow read, nothing more.
+ * - Never cache anything user-specific under a shared key; the cache is
+ *   per-project, not per-visitor.
+ *
+ * The example below is commented out on purpose: it names a model and fields
+ * that only exist if this project is connected to Odoo. Uncomment it, or write
+ * your own against whatever this project actually connects to.
+ *
+ *   import { withCache } from '@helloleo/runtime'
+ *   import { callIntegration } from '#/lib/proxy'
+ *
+ *   export const getOdooPartners = withCache('odoo:partners', 7200, async () => {
+ *     const res = await callIntegration({
+ *       integration: 'odoo',
+ *       endpoint: '/jsonrpc',
+ *       body: {
+ *         model: 'res.partner',
+ *         method: 'search_read',
+ *         args: [[['is_company', '=', true]]],
+ *         kwargs: { fields: ['name', 'email'], limit: 500 },
+ *       },
+ *     })
+ *     // Let a failed read throw: nothing is written on a rejection, so a bad
+ *     // response is never served for the whole TTL.
+ *     if (!res.success) throw new Error(`Odoo read failed (${res.status})`)
+ *     return res.data
+ *   })
+ *
+ * Then in a loader:
+ *
+ *   const partners = await getOdooPartners()
+ */
+
+export {}

package/dist/templates/tanstack-start-2026-07-30/src/lib/kv.ts

@@ -18,6 +18,9 @@ import { kv } from '@helloleo/runtime'
  * - KV is for small, hot values. Relational data belongs in the database
  *   (`#/db`); files belong in storage (`#/lib/storage`).
  * - Keys are flat strings — namespace with prefixes ('cache:', 'session:').
+ * - Caching a heavy read is NOT a raw kv.put: use `#/lib/cache`, which gives
+ *   the read a TTL and a row in Settings → Cache the user can see the age of
+ *   and purge. Hand-rolling it here hides the cache from them entirely.
  */
 
 /** JSON convenience wrappers — kv stores strings, most values are objects. */

package/dist/templates/tanstack-start-2026-07-30/src/router.tsx

@@ -1,31 +1,31 @@
 import { QueryClient } from '@tanstack/react-query'
 import { createRouter as createTanStackRouter } from '@tanstack/react-router'
-import { routerWithQueryClient } from '@tanstack/react-router-with-query'
+import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
 import { routeTree } from './routeTree.gen'
 import { DefaultErrorComponent } from '@/components/error-component'
 
-// TanStack Start calls getRouter() on both server and client. routerWithQueryClient
-// wires the QueryClient into the router context and handles SSR dehydration /
-// rehydration, so loaders can call context.queryClient.ensureQueryData() and the
-// client picks the cache up without refetching.
+// TanStack Start calls getRouter() on both server and client.
+// setupRouterSsrQueryIntegration wires the QueryClient into the router context
+// and handles SSR dehydration / rehydration, so loaders can call
+// context.queryClient.ensureQueryData() and the client picks the cache up
+// without refetching.
 export function getRouter() {
   const queryClient = new QueryClient()
 
-  const router = routerWithQueryClient(
-    createTanStackRouter({
-      routeTree,
-      context: { queryClient },
-      scrollRestoration: true,
-      // Catches uncaught render/loader errors on any route. Routes can still
-      // set their own `errorComponent` to override this.
-      defaultErrorComponent: DefaultErrorComponent,
-      defaultPreload: 'intent',
-      // With React Query we never want loader data to be stale -- the loader runs
-      // on every preload/visit and React Query owns caching from there.
-      defaultPreloadStaleTime: 0,
-    }),
-    queryClient,
-  )
+  const router = createTanStackRouter({
+    routeTree,
+    context: { queryClient },
+    scrollRestoration: true,
+    // Catches uncaught render/loader errors on any route. Routes can still
+    // set their own `errorComponent` to override this.
+    defaultErrorComponent: DefaultErrorComponent,
+    defaultPreload: 'intent',
+    // With React Query we never want loader data to be stale -- the loader runs
+    // on every preload/visit and React Query owns caching from there.
+    defaultPreloadStaleTime: 0,
+  })
+
+  setupRouterSsrQueryIntegration({ router, queryClient })
 
   return router
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helloleo/plugins",
-  "version": "0.2.27",
+  "version": "0.2.29-beta.0",
   "description": "OpenCode plugins for HelloLeo",
   "license": "UNLICENSED",
   "type": "module",