@helloleo/runtime 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@helloleo/runtime",
+  "version": "0.1.0",
+  "authors": [
+    "Herbie Vine <herbie@terros>"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/contracts.ts",
+    "./cf-shim": "./src/cf-shim.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "aws4fetch": "^1.0.20",
+    "drizzle-orm": "^0.36.4"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250906.0",
+    "@libsql/client": "^0.14.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "@libsql/client": "*"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/kv-binding.ts

@@ -0,0 +1,23 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { KvLike } from "../contracts.ts";
+
+// Adapt a Cloudflare KV binding (or the dev shim's KVNamespace-compatible
+// object) to the neutral KvLike contract. The CF binding already matches this
+// shape closely; this thin wrapper pins it to the contract so a non-CF adapter
+// (Redis, Upstash, DynamoDB) can implement the same interface later.
+export function kvFromBinding(ns: KVNamespace): KvLike {
+  return {
+    get: (key) => ns.get(key),
+    put: (key, value, opts) =>
+      ns.put(key, value, opts?.expirationTtl ? { expirationTtl: opts.expirationTtl } : undefined),
+    delete: (key) => ns.delete(key),
+    async list(opts) {
+      const res = await ns.list({ prefix: opts?.prefix, cursor: opts?.cursor, limit: opts?.limit });
+      return {
+        keys: res.keys.map((k) => ({ name: k.name, expiration: k.expiration })),
+        cursor: res.list_complete ? undefined : res.cursor,
+        listComplete: res.list_complete,
+      };
+    },
+  };
+}

package/src/adapters/storage-binding.ts

@@ -0,0 +1,91 @@
+/// <reference types="@cloudflare/workers-types" />
+import { AwsClient } from "aws4fetch";
+import type { PutBody, StorageLike, StoredObject } from "../contracts.ts";
+
+export interface R2PresignConfig {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  endpoint?: string; // https://<account>.r2.cloudflarestorage.com
+  bucket?: string;
+}
+
+// Adapt a Cloudflare R2 binding to the neutral StorageLike contract.
+//
+// get/put/delete/head/list use the binding directly (fast, no signing, no
+// creds). presign* can't use the binding (R2 bindings have no presign), so they
+// sign against R2's S3-compatible endpoint with aws4fetch — which means
+// presigned URLs need R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY / R2_S3_ENDPOINT
+// set as Worker secrets. Same code path works for any S3-compatible store.
+export function storageFromBinding(bucket: R2Bucket, cfg: R2PresignConfig): StorageLike {
+  let signer: AwsClient | undefined;
+  const presignBase = (): { client: AwsClient; base: string } => {
+    if (!cfg.accessKeyId || !cfg.secretAccessKey || !cfg.endpoint || !cfg.bucket) {
+      throw new Error(
+        "Presigned URLs require R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_S3_ENDPOINT and R2_BUCKET_NAME. " +
+          "The R2 binding alone cannot presign.",
+      );
+    }
+    signer ??= new AwsClient({
+      accessKeyId: cfg.accessKeyId,
+      secretAccessKey: cfg.secretAccessKey,
+      service: "s3",
+      region: "auto",
+    });
+    return { client: signer, base: `${cfg.endpoint.replace(/\/$/, "")}/${cfg.bucket}` };
+  };
+
+  return {
+    async get(key) {
+      const obj = await bucket.get(key);
+      if (!obj) return null;
+      return {
+        body: obj.body,
+        size: obj.size,
+        contentType: obj.httpMetadata?.contentType,
+      } satisfies StoredObject;
+    },
+    async put(key, body: PutBody, opts) {
+      await bucket.put(key, body, {
+        httpMetadata: opts?.contentType ? { contentType: opts.contentType } : undefined,
+      });
+    },
+    delete: (key) => bucket.delete(key),
+    async head(key) {
+      const obj = await bucket.head(key);
+      if (!obj) return null;
+      return { size: obj.size, contentType: obj.httpMetadata?.contentType };
+    },
+    async list(opts) {
+      const res = await bucket.list({
+        prefix: opts?.prefix,
+        cursor: opts?.cursor,
+        limit: opts?.limit,
+      });
+      return {
+        keys: res.objects.map((o) => ({ key: o.key, size: o.size })),
+        cursor: res.truncated ? res.cursor : undefined,
+      };
+    },
+    async presignGet(key, ttlSeconds) {
+      const { client, base } = presignBase();
+      const signed = await client.sign(
+        `${base}/${encodeURIComponent(key)}?X-Amz-Expires=${ttlSeconds}`,
+        {
+          method: "GET",
+          aws: { signQuery: true },
+        },
+      );
+      return signed.url;
+    },
+    async presignPut(key, ttlSeconds, opts) {
+      const { client, base } = presignBase();
+      const url = `${base}/${encodeURIComponent(key)}?X-Amz-Expires=${ttlSeconds}`;
+      const signed = await client.sign(url, {
+        method: "PUT",
+        headers: opts?.contentType ? { "content-type": opts.contentType } : undefined,
+        aws: { signQuery: true },
+      });
+      return signed.url;
+    },
+  };
+}

package/src/cf-shim.ts

@@ -0,0 +1,230 @@
+// DEV-ONLY shim for "cloudflare:workers".
+//
+// @helloleo/vite-config aliases "cloudflare:workers" → this module when running
+// in a sandbox (CodeSandbox) where workerd can't run nested. It exports an
+// `env` whose bindings are backed by local, Miniflare-equivalent adapters:
+//   - DB:     libsql (.dev.db), presented with D1's async surface
+//   - KV:     libsql _kv table in the same file (persists + shares like D1)
+//   - BUCKET: filesystem (./dev-storage), R2Bucket-compatible subset
+//
+// The runtime (env.ts → index.ts) reads these exactly as it reads real
+// bindings, so SSR + server functions behave like prod. Only the I/O backend
+// differs. This module imports @libsql/client and node:fs, so it must NEVER be
+// imported in the workerd build — the alias only fires in dev (command==="serve"
+// && sandbox), so it isn't.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createClient } from "@libsql/client";
+
+// ---- D1 (libsql) ------------------------------------------------------
+//
+// libsql (not better-sqlite3) because it runs under BOTH node and bun — the
+// sandbox dev runtime; better-sqlite3 is a native addon Bun can't dlopen. Same
+// sqlite dialect as D1, file-backed locally, and the same client speaks to Turso
+// later by swapping the url. Wrapped into D1's async surface so the runtime
+// stays on a single drizzle-orm/d1 driver in both dev and prod.
+const dbFile = process.env.DEV_DB_PATH ?? ".dev.db";
+const client = createClient({ url: `file:${dbFile}` });
+
+// Apply schema.sql on boot if present, so a query in a route loader never hits
+// "no such table" on a fresh sandbox.
+if (existsSync("schema.sql")) {
+  try {
+    await client.executeMultiple(readFileSync("schema.sql", "utf-8"));
+  } catch (e) {
+    console.error("[cf-shim] failed to apply schema.sql:", e);
+  }
+}
+
+// Minimal D1Database surface over libsql. Covers what drizzle-orm/d1 calls:
+// prepare().bind().all()/first()/run()/raw() and batch().
+function makeD1() {
+  const prepare = (sql: string) => {
+    const make = (params: unknown[]) => {
+      const args = params as Array<string | number | bigint | boolean | null | Uint8Array>;
+      return {
+        async all<T = unknown>() {
+          const r = await client.execute({ sql, args });
+          return { results: r.rows as unknown as T[], success: true, meta: {} };
+        },
+        async first<T = unknown>(col?: string) {
+          const r = await client.execute({ sql, args });
+          const row = r.rows[0] as Record<string, unknown> | undefined;
+          if (!row) return null;
+          return (col ? row[col] : row) as T;
+        },
+        async run() {
+          const r = await client.execute({ sql, args });
+          return {
+            success: true,
+            meta: {
+              changes: r.rowsAffected,
+              last_row_id: Number(r.lastInsertRowid ?? 0),
+              duration: 0,
+            },
+          };
+        },
+        async raw<T = unknown[]>() {
+          const r = await client.execute({ sql, args });
+          return r.rows.map((row) =>
+            r.columns.map((c) => (row as Record<string, unknown>)[c]),
+          ) as T[];
+        },
+      };
+    };
+    return { bind: (...params: unknown[]) => make(params), ...make([]) };
+  };
+  return {
+    prepare,
+    async batch(stmts: Array<{ all: () => Promise<unknown> }>) {
+      const out = [];
+      for (const s of stmts) out.push(await s.all());
+      return out;
+    },
+    async exec(sql: string) {
+      await client.executeMultiple(sql);
+      return { count: 0, duration: 0 };
+    },
+  };
+}
+
+// ---- KV (libsql table + TTL) ------------------------------------------
+//
+// Backed by the SAME libsql file as D1 (a _kv table) so dev KV persists across
+// restarts and is shared across processes, exactly like D1/R2. In-memory was a
+// footgun: each `vite dev` had its own KV, and it reset on restart.
+await client.executeMultiple(
+  "CREATE TABLE IF NOT EXISTS _kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER);",
+);
+
+function makeKv() {
+  const liveRow = async (key: string) => {
+    const r = await client.execute({
+      sql: "SELECT value, expires_at FROM _kv WHERE key = ?",
+      args: [key],
+    });
+    const row = r.rows[0] as { value: string; expires_at: number | null } | undefined;
+    if (!row) return null;
+    if (row.expires_at && Date.now() > row.expires_at) {
+      await client.execute({ sql: "DELETE FROM _kv WHERE key = ?", args: [key] });
+      return null;
+    }
+    return row;
+  };
+  return {
+    async get(key: string) {
+      return (await liveRow(key))?.value ?? null;
+    },
+    async put(key: string, value: string, opts?: { expirationTtl?: number }) {
+      const expiresAt = opts?.expirationTtl ? Date.now() + opts.expirationTtl * 1000 : null;
+      await client.execute({
+        sql: "INSERT INTO _kv (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at",
+        args: [key, value, expiresAt],
+      });
+    },
+    async delete(key: string) {
+      await client.execute({ sql: "DELETE FROM _kv WHERE key = ?", args: [key] });
+    },
+    async list(opts?: { prefix?: string; limit?: number }) {
+      const prefix = `${opts?.prefix ?? ""}%`;
+      const r = await client.execute({
+        sql: "SELECT key FROM _kv WHERE key LIKE ? AND (expires_at IS NULL OR expires_at > ?) ORDER BY key",
+        args: [prefix, Date.now()],
+      });
+      const names = r.rows.map((row) => (row as unknown as { key: string }).key);
+      const limited = opts?.limit ? names.slice(0, opts.limit) : names;
+      return {
+        keys: limited.map((name) => ({ name })),
+        list_complete: limited.length === names.length,
+        cursor: "",
+      };
+    },
+  };
+}
+
+// ---- R2 (filesystem) --------------------------------------------------
+
+function makeR2() {
+  const root = process.env.DEV_STORAGE_DIR ?? "dev-storage";
+  const pathFor = (key: string) => join(root, key.replace(/\.\./g, "_"));
+  mkdirSync(root, { recursive: true });
+
+  const toBuffer = async (body: unknown): Promise<Buffer> => {
+    if (typeof body === "string") return Buffer.from(body);
+    if (body instanceof ArrayBuffer) return Buffer.from(body);
+    if (ArrayBuffer.isView(body)) return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    if (body instanceof ReadableStream) {
+      const chunks: Uint8Array[] = [];
+      const reader = body.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) chunks.push(value);
+      }
+      return Buffer.concat(chunks);
+    }
+    throw new Error("[cf-shim] unsupported R2 put body");
+  };
+
+  const meta = new Map<string, string | undefined>(); // key -> contentType
+
+  return {
+    async get(key: string) {
+      const p = pathFor(key);
+      if (!existsSync(p)) return null;
+      const buf = readFileSync(p);
+      return {
+        size: buf.byteLength,
+        httpMetadata: { contentType: meta.get(key) },
+        body: new ReadableStream({
+          start(c) {
+            c.enqueue(new Uint8Array(buf));
+            c.close();
+          },
+        }),
+      };
+    },
+    async put(key: string, body: unknown, opts?: { httpMetadata?: { contentType?: string } }) {
+      const p = pathFor(key);
+      mkdirSync(join(p, ".."), { recursive: true });
+      writeFileSync(p, await toBuffer(body));
+      meta.set(key, opts?.httpMetadata?.contentType);
+    },
+    async delete(key: string) {
+      const p = pathFor(key);
+      if (existsSync(p)) rmSync(p);
+      meta.delete(key);
+    },
+    async head(key: string) {
+      const p = pathFor(key);
+      if (!existsSync(p)) return null;
+      return { size: statSync(p).size, httpMetadata: { contentType: meta.get(key) } };
+    },
+    async list(opts?: { prefix?: string; limit?: number }) {
+      const all = existsSync(root) ? await readdir(root, { recursive: true }) : [];
+      const prefix = opts?.prefix ?? "";
+      const keys = all.filter(
+        (k) => k.startsWith(prefix) && existsSync(pathFor(k)) && statSync(pathFor(k)).isFile(),
+      );
+      const limited = opts?.limit ? keys.slice(0, opts.limit) : keys;
+      return {
+        objects: limited.map((key) => ({ key, size: statSync(pathFor(key)).size })),
+        truncated: false,
+        cursor: undefined,
+      };
+    },
+  };
+}
+
+export const env = {
+  DB: makeD1(),
+  KV: makeKv(),
+  BUCKET: makeR2(),
+  R2_ACCESS_KEY_ID: process.env.R2_ACCESS_KEY_ID,
+  R2_SECRET_ACCESS_KEY: process.env.R2_SECRET_ACCESS_KEY,
+  R2_S3_ENDPOINT: process.env.R2_S3_ENDPOINT,
+  R2_BUCKET_NAME: process.env.R2_BUCKET_NAME,
+  // biome-ignore lint/suspicious/noExplicitAny: dev shim presents the CF env shape
+} as any;

package/src/contracts.ts

@@ -0,0 +1,60 @@
+// Provider-neutral storage contracts.
+//
+// The interfaces are the lowest common denominator across providers so app
+// code never imports a vendor SDK directly. Today's adapters: CF bindings
+// (prod) and local shims (dev). Tomorrow's (Redis/Upstash for KV, S3/MinIO for
+// storage, Turso for db) implement the SAME interface — swapping a provider is
+// then an adapter change, not a call-site rewrite.
+//
+// Anything ABOVE the intersection (KV metadata, R2 multipart, D1 interactive
+// transactions) is deliberately left off these contracts. Adapters that can't
+// honor a method must throw `NotSupported` — fail loud, never silently degrade.
+
+export class NotSupported extends Error {
+  constructor(feature: string, adapter: string) {
+    super(`${feature} is not supported by the ${adapter} adapter`);
+    this.name = "NotSupported";
+  }
+}
+
+// ---- KV ----------------------------------------------------------------
+
+export interface KvListResult {
+  keys: { name: string; expiration?: number }[];
+  cursor?: string;
+  listComplete: boolean;
+}
+
+export interface KvLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, opts?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(opts?: { prefix?: string; cursor?: string; limit?: number }): Promise<KvListResult>;
+}
+
+// ---- Object storage ----------------------------------------------------
+
+export interface StoredObject {
+  body: ReadableStream;
+  size: number;
+  contentType?: string;
+}
+
+export interface StorageListResult {
+  keys: { key: string; size: number }[];
+  cursor?: string;
+}
+
+export type PutBody = ArrayBuffer | ArrayBufferView | ReadableStream | string;
+
+export interface StorageLike {
+  get(key: string): Promise<StoredObject | null>;
+  put(key: string, body: PutBody, opts?: { contentType?: string }): Promise<void>;
+  delete(key: string): Promise<void>;
+  head(key: string): Promise<{ size: number; contentType?: string } | null>;
+  list(opts?: { prefix?: string; cursor?: string; limit?: number }): Promise<StorageListResult>;
+  // Presigned URLs let the browser GET/PUT directly, bypassing the Worker.
+  // R2 bindings can't presign — these always go through the S3 API + creds.
+  presignGet(key: string, ttlSeconds: number): Promise<string>;
+  presignPut(key: string, ttlSeconds: number, opts?: { contentType?: string }): Promise<string>;
+}

package/src/env.ts

@@ -0,0 +1,35 @@
+/// <reference types="@cloudflare/workers-types" />
+
+// Single entry point to the per-request Cloudflare environment.
+//
+// PROD (workerd / Workers for Platforms): "cloudflare:workers" is the real
+// module; `env` holds the live bindings. @helloleo/vite-config externalizes
+// this specifier in the workerd build.
+//
+// DEV (CodeSandbox / sandbox): @helloleo/vite-config aliases
+// "cloudflare:workers" → "@helloleo/runtime/cf-shim", which provides an `env`
+// whose bindings are backed by local Miniflare-equivalent adapters
+// (better-sqlite3 D1, in-memory KV, filesystem R2). Same import, same shape —
+// the env-switch lives entirely in that one alias.
+import { env as cfEnv } from "cloudflare:workers";
+
+// Bindings + secrets this runtime expects. Apps extend their own Env in
+// worker-configuration.d.ts; this is the subset the runtime reads.
+export interface RuntimeEnv {
+  // HelloLeo Cloud database (D1, or the dev shim's sqlite-backed equivalent).
+  DB: D1Database;
+  // Optional KV namespace. Throw at access time if a feature needs it but it's
+  // unbound, rather than failing silently.
+  KV?: KVNamespace;
+  // Optional R2 bucket for object storage.
+  BUCKET?: R2Bucket;
+
+  // R2 S3-API credentials. Required ONLY for presigned URLs — the R2 binding
+  // itself cannot presign, so storage.presign*() signs against the S3 endpoint.
+  R2_ACCESS_KEY_ID?: string;
+  R2_SECRET_ACCESS_KEY?: string;
+  R2_S3_ENDPOINT?: string;
+  R2_BUCKET_NAME?: string;
+}
+
+export const env = cfEnv as unknown as RuntimeEnv;

package/src/index.ts

@@ -0,0 +1,65 @@
+// @helloleo/runtime — env-agnostic data access for HelloLeo apps.
+//
+//   import { db, kv, storage } from "@helloleo/runtime";
+//
+// Same import in dev (CodeSandbox) and prod (Workers for Platforms). The
+// dev/prod fork lives in ONE place: @helloleo/vite-config aliases
+// "cloudflare:workers" to the local shim in dev, so `env` carries
+// local-backed bindings; in prod it's the real CF env. This module never
+// branches on the target.
+//
+// All three are lazy singletons (see lazy.ts) so the top-level import is safe
+// on workerd, where bindings only exist per-request. Use them INSIDE a server
+// function / route loader / handler — never at module scope of app code.
+import { drizzle } from "drizzle-orm/d1";
+import { kvFromBinding } from "./adapters/kv-binding.ts";
+import { storageFromBinding } from "./adapters/storage-binding.ts";
+import type { KvLike, StorageLike } from "./contracts.ts";
+import { env } from "./env.ts";
+import { lazy } from "./lazy.ts";
+
+// Schema-less Drizzle client. Good for `db.select().from(table)` style queries
+// where the app imports its own table objects. Sqlite dialect → portable across
+// D1 (prod), the dev shim, and Turso/libsql by swapping the driver here only.
+export const db = lazy(() => drizzle(env.DB));
+
+// Typed Drizzle client bound to an app schema (enables `db.query.*` relational
+// queries + full inference). Still lazy, so safe to call at app module scope.
+//
+//   export const db = createDb(schema);
+export function createDb<TSchema extends Record<string, unknown>>(schema: TSchema) {
+  return lazy(() => drizzle(env.DB, { schema }));
+}
+
+export const kv: KvLike = lazy<KvLike>(() => {
+  if (!env.KV) {
+    throw new Error("KV is not bound. Add a kv_namespaces entry named 'KV' to wrangler.jsonc.");
+  }
+  return kvFromBinding(env.KV);
+});
+
+export const storage: StorageLike = lazy<StorageLike>(() => {
+  if (!env.BUCKET) {
+    throw new Error(
+      "Storage is not bound. Add an r2_buckets entry named 'BUCKET' to wrangler.jsonc.",
+    );
+  }
+  return storageFromBinding(env.BUCKET, {
+    accessKeyId: env.R2_ACCESS_KEY_ID,
+    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+    endpoint: env.R2_S3_ENDPOINT,
+    bucket: env.R2_BUCKET_NAME,
+  });
+});
+
+export type {
+  KvLike,
+  KvListResult,
+  PutBody,
+  StorageLike,
+  StorageListResult,
+  StoredObject,
+} from "./contracts.ts";
+export { NotSupported } from "./contracts.ts";
+export type { RuntimeEnv } from "./env.ts";
+export { env } from "./env.ts";

package/src/lazy.ts

@@ -0,0 +1,31 @@
+// Lazy singleton via Proxy.
+//
+// On workerd, Cloudflare bindings (env.DB / env.KV / env.BUCKET) only exist at
+// REQUEST time — reading them at module scope yields undefined. A plain
+// `export const db = drizzle(env.DB)` therefore crashes at isolate boot.
+//
+// `lazy()` exports a value (importable at the top of any file) but defers
+// construction to the first property access, which is always inside a request.
+// `import { db }` looks eager; the real client is built — and cached — on first
+// use. The build() callback is the single place the dev/prod fork lives (it
+// reads `env`, whose bindings are swapped by the cf-shim alias in dev).
+//
+// RULE: only use this for the CONNECTION (stateless, isolate-shared). Anything
+// carrying identity (a per-user, token-scoped client) must be built per-request
+// inside middleware, never cached in a module singleton — it would leak across
+// requests.
+export function lazy<T extends object>(build: () => T): T {
+  let instance: T | undefined;
+  const resolve = (): T => {
+    if (!instance) instance = build();
+    return instance;
+  };
+  return new Proxy({} as T, {
+    get(_target, prop, receiver) {
+      return Reflect.get(resolve(), prop, receiver);
+    },
+    has(_target, prop) {
+      return Reflect.has(resolve(), prop);
+    },
+  });
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types", "bun"]
+  },
+  "include": ["src/**/*.ts"]
+}