@helloleo/plugins 0.2.13 → 0.2.15

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/drizzle/meta/_journal.json

@@ -1,13 +1 @@
-{
-  "version": "7",
-  "dialect": "sqlite",
-  "entries": [
-    {
-      "idx": 0,
-      "version": "6",
-      "when": 1785420910012,
-      "tag": "0000_tidy_kang",
-      "breakpoints": true
-    }
-  ]
-}
+{"version":"7","dialect":"sqlite","entries":[]}

package/dist/templates/tanstack-start-2026-07-30/src/db/schema.ts

@@ -1,18 +1,20 @@
-import { sql } from 'drizzle-orm'
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
-
-// Single source of truth for the D1 / libsql schema. Sqlite dialect → the same
-// definition runs on the dev cf-shim (libsql .dev.db, synced via `drizzle-kit
-// push`) and prod D1 (migrations via `wrangler d1 migrations apply`).
+// Single source of truth for the database schema. Define tables here — the
+// SQL migration files under drizzle/ are generated and applied automatically
+// (dev on server start, production on publish). Never hand-write SQL or touch
+// drizzle/. Prefer ADDING columns/tables over renaming or deleting existing
+// ones: renames cannot be migrated automatically.
 //
-// Add your own tables here, then `bun run db:push` (dev) or `bun run
-// db:generate` + deploy (prod). Do NOT hand-write SQL — this file is the schema.
-export const entries = sqliteTable('entries', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  label: text('label').notNull(),
-  createdAt: integer('created_at')
-    .notNull()
-    .default(sql`(unixepoch())`),
-})
-
-export type Entry = typeof entries.$inferSelect
+// Example:
+//
+//   import { sql } from 'drizzle-orm'
+//   import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+//
+//   export const notes = sqliteTable('notes', {
+//     id: integer('id').primaryKey({ autoIncrement: true }),
+//     title: text('title').notNull(),
+//     createdAt: integer('created_at')
+//       .notNull()
+//       .default(sql`(unixepoch())`),
+//   })
+//
+//   export type Note = typeof notes.$inferSelect

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/dist/templates/tanstack-start-2026-07-30/src/routes/api/health.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router'
+import { sql } from 'drizzle-orm'
 import { db } from '#/db'
-import { entries } from '#/db/schema'
 
 /**
  * Server route example: GET /api/health. Use this file as the base for
@@ -39,7 +39,9 @@ export const Route = createFileRoute('/api/health')({
           runtime: 'cloudflare-workers',
         }
 
-        // Database health: lightweight query against a known table
+        // Database health: schema-agnostic connectivity ping. Deliberately
+        // NOT a query against an app table — the health probe must keep
+        // working no matter how src/db/schema.ts evolves.
         let database: {
           status: 'ok' | 'error'
           latencyMs: number
@@ -47,7 +49,7 @@ export const Route = createFileRoute('/api/health')({
         }
         const dbStart = Date.now()
         try {
-          await db.select({ id: entries.id }).from(entries).limit(1)
+          await db.run(sql`SELECT 1`)
           database = {
             status: 'ok',
             latencyMs: Date.now() - dbStart,

package/package.json

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

package/src/templates/tanstack-start-2026-07-30/drizzle/meta/_journal.json

@@ -1,13 +1 @@
-{
-  "version": "7",
-  "dialect": "sqlite",
-  "entries": [
-    {
-      "idx": 0,
-      "version": "6",
-      "when": 1785420910012,
-      "tag": "0000_tidy_kang",
-      "breakpoints": true
-    }
-  ]
-}
+{"version":"7","dialect":"sqlite","entries":[]}

package/src/templates/tanstack-start-2026-07-30/src/db/schema.ts

@@ -1,18 +1,20 @@
-import { sql } from 'drizzle-orm'
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
-
-// Single source of truth for the D1 / libsql schema. Sqlite dialect → the same
-// definition runs on the dev cf-shim (libsql .dev.db, synced via `drizzle-kit
-// push`) and prod D1 (migrations via `wrangler d1 migrations apply`).
+// Single source of truth for the database schema. Define tables here — the
+// SQL migration files under drizzle/ are generated and applied automatically
+// (dev on server start, production on publish). Never hand-write SQL or touch
+// drizzle/. Prefer ADDING columns/tables over renaming or deleting existing
+// ones: renames cannot be migrated automatically.
 //
-// Add your own tables here, then `bun run db:push` (dev) or `bun run
-// db:generate` + deploy (prod). Do NOT hand-write SQL — this file is the schema.
-export const entries = sqliteTable('entries', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  label: text('label').notNull(),
-  createdAt: integer('created_at')
-    .notNull()
-    .default(sql`(unixepoch())`),
-})
-
-export type Entry = typeof entries.$inferSelect
+// Example:
+//
+//   import { sql } from 'drizzle-orm'
+//   import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+//
+//   export const notes = sqliteTable('notes', {
+//     id: integer('id').primaryKey({ autoIncrement: true }),
+//     title: text('title').notNull(),
+//     createdAt: integer('created_at')
+//       .notNull()
+//       .default(sql`(unixepoch())`),
+//   })
+//
+//   export type Note = typeof notes.$inferSelect

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/templates/tanstack-start-2026-07-30/src/routes/api/health.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router'
+import { sql } from 'drizzle-orm'
 import { db } from '#/db'
-import { entries } from '#/db/schema'
 
 /**
  * Server route example: GET /api/health. Use this file as the base for
@@ -39,7 +39,9 @@ export const Route = createFileRoute('/api/health')({
           runtime: 'cloudflare-workers',
         }
 
-        // Database health: lightweight query against a known table
+        // Database health: schema-agnostic connectivity ping. Deliberately
+        // NOT a query against an app table — the health probe must keep
+        // working no matter how src/db/schema.ts evolves.
         let database: {
           status: 'ok' | 'error'
           latencyMs: number
@@ -47,7 +49,7 @@ export const Route = createFileRoute('/api/health')({
         }
         const dbStart = Date.now()
         try {
-          await db.select({ id: entries.id }).from(entries).limit(1)
+          await db.run(sql`SELECT 1`)
           database = {
             status: 'ok',
             latencyMs: Date.now() - dbStart,

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.",

package/dist/templates/tanstack-start-2026-07-30/drizzle/0000_tidy_kang.sql

@@ -1,5 +0,0 @@
-CREATE TABLE `entries` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`label` text NOT NULL,
-	`created_at` integer DEFAULT (unixepoch()) NOT NULL
-);

package/dist/templates/tanstack-start-2026-07-30/drizzle/meta/0000_snapshot.json

@@ -1,50 +0,0 @@
-{
-  "version": "6",
-  "dialect": "sqlite",
-  "id": "ec5ce3c5-da3c-496c-942e-72a9a9579093",
-  "prevId": "00000000-0000-0000-0000-000000000000",
-  "tables": {
-    "entries": {
-      "name": "entries",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "integer",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": true
-        },
-        "label": {
-          "name": "label",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false,
-          "default": "(unixepoch())"
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    }
-  },
-  "views": {},
-  "enums": {},
-  "_meta": {
-    "schemas": {},
-    "tables": {},
-    "columns": {}
-  },
-  "internal": {
-    "indexes": {}
-  }
-}

package/src/templates/tanstack-start-2026-07-30/drizzle/0000_tidy_kang.sql

@@ -1,5 +0,0 @@
-CREATE TABLE `entries` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`label` text NOT NULL,
-	`created_at` integer DEFAULT (unixepoch()) NOT NULL
-);

package/src/templates/tanstack-start-2026-07-30/drizzle/meta/0000_snapshot.json

@@ -1,50 +0,0 @@
-{
-  "version": "6",
-  "dialect": "sqlite",
-  "id": "ec5ce3c5-da3c-496c-942e-72a9a9579093",
-  "prevId": "00000000-0000-0000-0000-000000000000",
-  "tables": {
-    "entries": {
-      "name": "entries",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "integer",
-          "primaryKey": true,
-          "notNull": true,
-          "autoincrement": true
-        },
-        "label": {
-          "name": "label",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true,
-          "autoincrement": false,
-          "default": "(unixepoch())"
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "checkConstraints": {}
-    }
-  },
-  "views": {},
-  "enums": {},
-  "_meta": {
-    "schemas": {},
-    "tables": {},
-    "columns": {}
-  },
-  "internal": {
-    "indexes": {}
-  }
-}