@helloleo/plugins 0.2.13 → 0.2.14

package/dist/index.js

@@ -24955,7 +24955,8 @@ var scaffold = tool({
     const typeNotes = isStart ? [
       "- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
       "- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
-      "- The database schema lives in src/db/schema.ts and is the single source of truth. Migration files under drizzle/ are generated and applied automatically. Never create, edit or delete them. Prefer adding new columns/tables over renaming existing ones."
+      "- The database schema lives in src/db/schema.ts and is the single source of truth. Migration files under drizzle/ are generated and applied automatically. Never create, edit or delete them. Prefer adding new columns/tables over renaming existing ones.",
+      "- Persistence goes through @helloleo/runtime exclusively: database via #/db (see src/db/index.ts), key-value store via #/lib/kv (see src/lib/kv.ts), file storage + presigned browser uploads via #/lib/storage (see src/lib/storage.ts), env/secrets via env from @helloleo/runtime. Read those files before server-side data work. Never install another DB/storage client, never import from cloudflare:workers, all of it is server-side only."
     ] : [
       "- This is a TanStack Router SPA. The client entry is index.html -> src/main.tsx. There is no server: no API routes, no server functions, no database.",
       "- Fetch data from external APIs only. If the app needs its own persistence or server-side code, it should have been scaffolded as tanstack-start."

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

@@ -0,0 +1,37 @@
+import { kv } from '@helloleo/runtime'
+
+/**
+ * Key-value store — @helloleo/runtime `kv`. Use this file as the base for
+ * caches, sessions, counters and flags. Same import in dev and production;
+ * never install redis/ioredis or branch on environment.
+ *
+ * The raw contract (values are ALWAYS strings):
+ *
+ *   await kv.put('session:abc', value, { expirationTtl: 3600 })  // ttl in seconds, optional
+ *   await kv.get('session:abc')                                  // string | null
+ *   await kv.delete('session:abc')
+ *   await kv.list({ prefix: 'session:', limit: 100 })            // { keys, cursor, listComplete }
+ *
+ * Rules:
+ * - Server-side only (route handlers, loaders, server functions) — the
+ *   binding does not exist in the browser or at app module scope.
+ * - 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:').
+ */
+
+/** JSON convenience wrappers — kv stores strings, most values are objects. */
+export async function kvGetJson<T>(key: string): Promise<T | null> {
+  const raw = await kv.get(key)
+  return raw === null ? null : (JSON.parse(raw) as T)
+}
+
+export async function kvPutJson(
+  key: string,
+  value: unknown,
+  opts?: { expirationTtl?: number },
+): Promise<void> {
+  await kv.put(key, JSON.stringify(value), opts)
+}
+
+export { kv }

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

@@ -0,0 +1,44 @@
+import { storage } from '@helloleo/runtime'
+
+/**
+ * File/object storage — @helloleo/runtime `storage`. Use this file as the
+ * base for uploads, images, exports and any binary data. Same import in dev
+ * and production; never install @aws-sdk/*, multer, or use node:fs.
+ *
+ * The raw contract:
+ *
+ *   await storage.put('avatars/u1.png', bytes, { contentType: 'image/png' })
+ *   await storage.get('avatars/u1.png')   // { body: ReadableStream, size, contentType } | null
+ *   await storage.head('avatars/u1.png')  // { size, contentType } | null
+ *   await storage.delete('avatars/u1.png')
+ *   await storage.list({ prefix: 'avatars/', limit: 100 })  // { keys: [{ key, size }], cursor }
+ *
+ * Rules:
+ * - Server-side only (route handlers, loaders, server functions).
+ * - Browser uploads/downloads go through PRESIGNED URLS (below) — never
+ *   stream file bytes through your own API route when a presigned URL works:
+ *   the browser talks to storage directly.
+ * - Key layout is up to the app — namespace with prefixes ('avatars/',
+ *   'exports/').
+ */
+
+/**
+ * Presign an upload: the server hands the browser a short-lived URL it can
+ * `fetch(url, { method: 'PUT', body: file })` to directly. Pair with a DB row
+ * that records the key.
+ */
+export function getUploadUrl(
+  key: string,
+  opts?: { ttlSeconds?: number; contentType?: string },
+): Promise<string> {
+  return storage.presignPut(key, opts?.ttlSeconds ?? 600, {
+    contentType: opts?.contentType,
+  })
+}
+
+/** Presign a download — short-lived direct GET URL for the browser. */
+export function getDownloadUrl(key: string, ttlSeconds = 600): Promise<string> {
+  return storage.presignGet(key, ttlSeconds)
+}
+
+export { storage }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helloleo/plugins",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "OpenCode plugins for HelloLeo",
   "license": "UNLICENSED",
   "type": "module",

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

@@ -0,0 +1,37 @@
+import { kv } from '@helloleo/runtime'
+
+/**
+ * Key-value store — @helloleo/runtime `kv`. Use this file as the base for
+ * caches, sessions, counters and flags. Same import in dev and production;
+ * never install redis/ioredis or branch on environment.
+ *
+ * The raw contract (values are ALWAYS strings):
+ *
+ *   await kv.put('session:abc', value, { expirationTtl: 3600 })  // ttl in seconds, optional
+ *   await kv.get('session:abc')                                  // string | null
+ *   await kv.delete('session:abc')
+ *   await kv.list({ prefix: 'session:', limit: 100 })            // { keys, cursor, listComplete }
+ *
+ * Rules:
+ * - Server-side only (route handlers, loaders, server functions) — the
+ *   binding does not exist in the browser or at app module scope.
+ * - 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:').
+ */
+
+/** JSON convenience wrappers — kv stores strings, most values are objects. */
+export async function kvGetJson<T>(key: string): Promise<T | null> {
+  const raw = await kv.get(key)
+  return raw === null ? null : (JSON.parse(raw) as T)
+}
+
+export async function kvPutJson(
+  key: string,
+  value: unknown,
+  opts?: { expirationTtl?: number },
+): Promise<void> {
+  await kv.put(key, JSON.stringify(value), opts)
+}
+
+export { kv }

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

@@ -0,0 +1,44 @@
+import { storage } from '@helloleo/runtime'
+
+/**
+ * File/object storage — @helloleo/runtime `storage`. Use this file as the
+ * base for uploads, images, exports and any binary data. Same import in dev
+ * and production; never install @aws-sdk/*, multer, or use node:fs.
+ *
+ * The raw contract:
+ *
+ *   await storage.put('avatars/u1.png', bytes, { contentType: 'image/png' })
+ *   await storage.get('avatars/u1.png')   // { body: ReadableStream, size, contentType } | null
+ *   await storage.head('avatars/u1.png')  // { size, contentType } | null
+ *   await storage.delete('avatars/u1.png')
+ *   await storage.list({ prefix: 'avatars/', limit: 100 })  // { keys: [{ key, size }], cursor }
+ *
+ * Rules:
+ * - Server-side only (route handlers, loaders, server functions).
+ * - Browser uploads/downloads go through PRESIGNED URLS (below) — never
+ *   stream file bytes through your own API route when a presigned URL works:
+ *   the browser talks to storage directly.
+ * - Key layout is up to the app — namespace with prefixes ('avatars/',
+ *   'exports/').
+ */
+
+/**
+ * Presign an upload: the server hands the browser a short-lived URL it can
+ * `fetch(url, { method: 'PUT', body: file })` to directly. Pair with a DB row
+ * that records the key.
+ */
+export function getUploadUrl(
+  key: string,
+  opts?: { ttlSeconds?: number; contentType?: string },
+): Promise<string> {
+  return storage.presignPut(key, opts?.ttlSeconds ?? 600, {
+    contentType: opts?.contentType,
+  })
+}
+
+/** Presign a download — short-lived direct GET URL for the browser. */
+export function getDownloadUrl(key: string, ttlSeconds = 600): Promise<string> {
+  return storage.presignGet(key, ttlSeconds)
+}
+
+export { storage }

package/src/tools/scaffold.ts

@@ -153,6 +153,7 @@ export const scaffold = tool({
 					"- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
 					"- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
 					"- The database schema lives in src/db/schema.ts and is the single source of truth. Migration files under drizzle/ are generated and applied automatically. Never create, edit or delete them. Prefer adding new columns/tables over renaming existing ones.",
+					"- Persistence goes through @helloleo/runtime exclusively: database via #/db (see src/db/index.ts), key-value store via #/lib/kv (see src/lib/kv.ts), file storage + presigned browser uploads via #/lib/storage (see src/lib/storage.ts), env/secrets via env from @helloleo/runtime. Read those files before server-side data work. Never install another DB/storage client, never import from cloudflare:workers, all of it is server-side only.",
 				]
 			: [
 					"- This is a TanStack Router SPA. The client entry is index.html -> src/main.tsx. There is no server: no API routes, no server functions, no database.",