handzon-core 0.6.0

package/src/server/auth.ts

@@ -0,0 +1,127 @@
+import type { AstroCookieSetOptions, AstroCookies } from "astro";
+import { and, eq, isNull } from "drizzle-orm";
+import { getAuthedUser } from "./auth/session.ts";
+import { getDb } from "./db/client.ts";
+import { learners, progressEntries } from "./db/schema.ts";
+
+const COOKIE = "tt-device";
+const ONE_YEAR = 60 * 60 * 24 * 365;
+
+const COOKIE_OPTS: AstroCookieSetOptions = {
+  httpOnly: true,
+  // Only flip on `secure` in production — Astro's dev server is plain
+  // HTTP and `secure: true` silently drops the cookie there.
+  secure: import.meta.env.PROD,
+  sameSite: "lax",
+  path: "/",
+  maxAge: ONE_YEAR,
+};
+
+function randomDeviceId(): string {
+  // 32-char hex (128 bits) — plenty for an unpredictable, opaque id.
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Resolve the current learner row.
+ *
+ * - No session + no cookie → mint a device learner + cookie (anonymous).
+ * - No session + cookie    → return the existing device learner.
+ * - Session present        → return the user-linked learner. If a device
+ *                            cookie also exists and points to an orphan
+ *                            (user_id NULL), re-key its progress to the
+ *                            user learner in a single transaction and
+ *                            drop the device cookie. One-time claim.
+ *
+ * `request` is required so we can read the Auth.js session. Endpoints
+ * that don't currently have it (older internal callers) can pass `null`
+ * to keep the anonymous-only path.
+ */
+export async function getOrCreateLearner(
+  cookies: AstroCookies,
+  request: Request | null,
+): Promise<{ id: string; deviceId: string | null }> {
+  const db = getDb();
+  const authed = request ? await getAuthedUser(request) : null;
+
+  if (authed) {
+    const userLearner = await findOrCreateUserLearner(db, authed.userId);
+    const deviceId = cookies.get(COOKIE)?.value;
+    if (deviceId) {
+      await maybeClaimDeviceProgress(db, deviceId, userLearner.id);
+      cookies.delete(COOKIE, { path: "/" });
+    }
+    return { id: userLearner.id, deviceId: null };
+  }
+
+  // Anonymous path — unchanged from pre-auth behaviour.
+  let deviceId = cookies.get(COOKIE)?.value;
+  if (deviceId) {
+    const found = await db
+      .select()
+      .from(learners)
+      .where(eq(learners.deviceId, deviceId))
+      .limit(1);
+    if (found[0]) return { id: found[0].id, deviceId };
+  }
+  deviceId = randomDeviceId();
+  const [created] = await db.insert(learners).values({ deviceId }).returning();
+  cookies.set(COOKIE, deviceId, COOKIE_OPTS);
+  return { id: created!.id, deviceId };
+}
+
+async function findOrCreateUserLearner(
+  db: ReturnType<typeof getDb>,
+  userId: string,
+): Promise<{ id: string }> {
+  const existing = await db
+    .select({ id: learners.id })
+    .from(learners)
+    .where(eq(learners.userId, userId))
+    .limit(1);
+  if (existing[0]) return { id: existing[0].id };
+  const [created] = await db.insert(learners).values({ userId }).returning({ id: learners.id });
+  return { id: created!.id };
+}
+
+/**
+ * If `deviceId` points at an orphan (user_id NULL) learner with progress,
+ * re-parent its progress rows to `userLearnerId` and delete the orphan.
+ * Idempotent: subsequent sign-ins with the same device cookie no-op.
+ */
+async function maybeClaimDeviceProgress(
+  db: ReturnType<typeof getDb>,
+  deviceId: string,
+  userLearnerId: string,
+): Promise<void> {
+  const orphans = await db
+    .select({ id: learners.id })
+    .from(learners)
+    .where(and(eq(learners.deviceId, deviceId), isNull(learners.userId)))
+    .limit(1);
+  const orphan = orphans[0];
+  if (!orphan || orphan.id === userLearnerId) return;
+
+  await db.transaction(async (tx) => {
+    // Move progress rows. ON CONFLICT: keep the row with the most
+    // recent updated_at — if the user already has progress on this
+    // (kind, scope, key), prefer whichever was touched last.
+    await tx.execute(/* sql */ `
+      INSERT INTO "progress_entries" ("learner_id","kind","scope","key","value","updated_at")
+      SELECT '${userLearnerId}'::uuid, "kind","scope","key","value","updated_at"
+      FROM "progress_entries"
+      WHERE "learner_id" = '${orphan.id}'::uuid
+      ON CONFLICT ("learner_id","kind","scope","key")
+      DO UPDATE SET
+        "value" = CASE WHEN EXCLUDED."updated_at" > "progress_entries"."updated_at"
+                       THEN EXCLUDED."value" ELSE "progress_entries"."value" END,
+        "updated_at" = GREATEST(EXCLUDED."updated_at", "progress_entries"."updated_at");
+    `);
+    await tx.delete(progressEntries).where(eq(progressEntries.learnerId, orphan.id));
+    await tx.delete(learners).where(eq(learners.id, orphan.id));
+  });
+}

package/src/server/db/client.ts

@@ -0,0 +1,14 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import * as schema from "./schema";
+
+let _client: ReturnType<typeof drizzle> | null = null;
+
+export function getDb() {
+  if (_client) return _client;
+  const url = process.env.DATABASE_URL;
+  if (!url) throw new Error("DATABASE_URL is not set.");
+  const sql = postgres(url, { max: 5, idle_timeout: 20 });
+  _client = drizzle(sql, { schema });
+  return _client;
+}

package/src/server/db/migrate.ts

@@ -0,0 +1,29 @@
+/**
+ * Drizzle migration runner used by the scaffold's `db:migrate` script
+ * (and the Tier 2 Blueprint's `preDeployCommand`). Keeping it inside
+ * the framework lets the scaffold's `package.json` stay free of a
+ * direct `drizzle-orm` dependency — the previous setup imported
+ * `drizzle-orm/postgres-js/migrator` from the scaffold itself, which
+ * only resolved when pnpm's `shamefully-hoist=true` was on the
+ * workspace `.npmrc`. Render's strict install rejected it.
+ *
+ * Usage (scaffold side):
+ *
+ *   import { runMigrations } from "handzon-core/server/db/migrate";
+ *   runMigrations("./drizzle")
+ *     .then(() => process.exit(0))
+ *     .catch((e) => { console.error(e); process.exit(1); });
+ */
+import { migrate } from "drizzle-orm/postgres-js/migrator";
+import { getDb } from "./client.ts";
+
+export async function runMigrations(migrationsFolder: string): Promise<void> {
+  if (!process.env.DATABASE_URL) {
+    console.log("DATABASE_URL not set — skipping migrations (Tier 1 build).");
+    return;
+  }
+  const db = getDb();
+  console.log("Running migrations…");
+  await migrate(db, { migrationsFolder });
+  console.log("Migrations complete.");
+}

package/src/server/db/schema.ts

@@ -0,0 +1,65 @@
+import { sql } from "drizzle-orm";
+import {
+  index,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { users } from "../auth/schema.ts";
+
+// Re-export the Auth.js tables so consumers (and drizzle-kit) see one
+// schema barrel.
+export { users, accounts, sessions, verificationTokens } from "../auth/schema.ts";
+
+export const learners = pgTable(
+  "learners",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    // Nullable now — signed-in learners don't need a device cookie.
+    deviceId: text("device_id"),
+    // Optional FK to the Auth.js user. Set on first sign-in via the
+    // claim transaction; null for anonymous learners.
+    userId: uuid("user_id").references(() => users.id, { onDelete: "set null" }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    // Partial uniques: only enforced when the column is non-null. Lets
+    // multiple signed-in learners coexist without device ids and avoids
+    // the historical `device_id NOT NULL UNIQUE` constraint blocking
+    // user-only rows.
+    deviceIdUnique: uniqueIndex("learners_device_id_unique")
+      .on(table.deviceId)
+      .where(sql`${table.deviceId} IS NOT NULL`),
+    userIdUnique: uniqueIndex("learners_user_id_unique")
+      .on(table.userId)
+      .where(sql`${table.userId} IS NOT NULL`),
+  }),
+);
+
+export const progressEntries = pgTable(
+  "progress_entries",
+  {
+    learnerId: uuid("learner_id")
+      .notNull()
+      .references(() => learners.id, { onDelete: "cascade" }),
+    // 'step' | 'checkpoint' | 'quiz' | 'pref' | 'lastVisited' | 'tutorial'
+    // The 'tutorial' kind keys aggregate popularity events. Two keys
+    // matter for cross-learner counts: 'started' (first step view per
+    // learner) and 'completed' (all steps in the tutorial complete).
+    // The composite PK guarantees each learner is counted at most once
+    // per (slug, key), so a plain COUNT(*) gives unique-learner totals.
+    kind: text("kind").notNull(),
+    scope: text("scope").notNull(), // tutorial slug or 'global'
+    key: text("key").notNull(),
+    value: jsonb("value").notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    pk: primaryKey({ columns: [table.learnerId, table.kind, table.scope, table.key] }),
+    byLearner: index("progress_by_learner").on(table.learnerId, table.scope),
+  }),
+);

package/src/server/handlers/healthz.ts

@@ -0,0 +1,6 @@
+import type { APIRoute } from "astro";
+import { json } from "../http.ts";
+
+// Hit by Render's healthCheckPath on both tiers. Both tiers are SSR
+// node services in this template, so the response is computed at runtime.
+export const GET: APIRoute = () => json({ status: "ok" });

package/src/server/handlers/progress.ts

@@ -0,0 +1,90 @@
+import type { APIRoute } from "astro";
+import { eq, sql } from "drizzle-orm";
+import { z } from "zod";
+import { getOrCreateLearner } from "../auth.ts";
+import { getDb } from "../db/client.ts";
+import { progressEntries } from "../db/schema.ts";
+import { isSameOrigin, json } from "../http.ts";
+
+const MAX_BODY_BYTES = 32 * 1024;
+const MAX_ENTRIES = 200;
+
+const ProgressEntrySchema = z.object({
+  kind: z.enum(["step", "checkpoint", "quiz", "pref", "lastVisited", "tutorial"]),
+  scope: z.string().min(1).max(128),
+  key: z.string().min(1).max(128),
+  value: z.unknown(),
+});
+
+const ProgressBodySchema = z.array(ProgressEntrySchema).max(MAX_ENTRIES);
+
+// Tier 1: no Postgres — returns an empty list (the frontend uses the
+// local store and never reads this in that mode). Tier 2: hits Postgres.
+export const GET: APIRoute = async ({ cookies, request }) => {
+  if (!process.env.DATABASE_URL) {
+    return json({ entries: [] });
+  }
+  const learner = await getOrCreateLearner(cookies, request);
+  const db = getDb();
+  const rows = await db
+    .select()
+    .from(progressEntries)
+    .where(eq(progressEntries.learnerId, learner.id));
+  return json({ entries: rows });
+};
+
+export const POST: APIRoute = async ({ cookies, request }) => {
+  if (!isSameOrigin(request)) {
+    return json({ error: "Cross-origin write rejected." }, { status: 403 });
+  }
+  if (!process.env.DATABASE_URL) {
+    return json({ written: 0 });
+  }
+
+  const lengthHeader = request.headers.get("content-length");
+  if (lengthHeader && Number(lengthHeader) > MAX_BODY_BYTES) {
+    return json({ error: "Payload too large." }, { status: 413 });
+  }
+  const raw = await request.text();
+  if (raw.length > MAX_BODY_BYTES) {
+    return json({ error: "Payload too large." }, { status: 413 });
+  }
+
+  let parsed: z.infer<typeof ProgressBodySchema>;
+  try {
+    parsed = ProgressBodySchema.parse(JSON.parse(raw));
+  } catch (e) {
+    return json({ error: e instanceof Error ? e.message : "Invalid JSON." }, { status: 400 });
+  }
+  if (parsed.length === 0) return json({ written: 0 });
+
+  const learner = await getOrCreateLearner(cookies, request);
+  const db = getDb();
+  const now = new Date();
+  const rows = parsed.map((b) => ({
+    learnerId: learner.id,
+    kind: b.kind,
+    scope: b.scope,
+    key: b.key,
+    value: b.value,
+    updatedAt: now,
+  }));
+  await db
+    .insert(progressEntries)
+    .values(rows)
+    .onConflictDoUpdate({
+      target: [
+        progressEntries.learnerId,
+        progressEntries.kind,
+        progressEntries.scope,
+        progressEntries.key,
+      ],
+      set: {
+        // `excluded` is the row Postgres would have inserted — without
+        // this the SET was a no-op (`value = progress_entries.value`).
+        value: sql`excluded.value`,
+        updatedAt: sql`excluded.updated_at`,
+      },
+    });
+  return json({ written: rows.length });
+};

package/src/server/handlers/tutorialStats.ts

@@ -0,0 +1,67 @@
+import type { APIRoute } from "astro";
+import { eq, sql } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import { progressEntries } from "../db/schema.ts";
+import { json } from "../http.ts";
+
+export interface TutorialStat {
+  slug: string;
+  started: number;
+  completed: number;
+}
+
+interface CacheEntry {
+  expiresAt: number;
+  payload: { stats: TutorialStat[] };
+}
+
+const CACHE_TTL_MS = 60_000;
+let cache: CacheEntry | null = null;
+
+/**
+ * Returns one row per tutorial slug with cross-learner started /
+ * completed counts. Tier 1 (no DATABASE_URL) returns an empty array so
+ * card hydration is a no-op and the build stays static.
+ *
+ * Each (learner, slug, key) is a single row thanks to the composite PK
+ * on `progress_entries`, so `COUNT(*)` is a unique-learner count — no
+ * extra `DISTINCT` needed.
+ */
+export const GET: APIRoute = async () => {
+  if (!process.env.DATABASE_URL) {
+    return json({ stats: [] satisfies TutorialStat[] }, {
+      headers: { "Cache-Control": "public, max-age=60" },
+    });
+  }
+  const now = Date.now();
+  if (cache && cache.expiresAt > now) {
+    return json(cache.payload, {
+      headers: { "Cache-Control": "public, max-age=60" },
+    });
+  }
+
+  const db = getDb();
+  const rows = await db
+    .select({
+      scope: progressEntries.scope,
+      key: progressEntries.key,
+      count: sql<number>`count(*)::int`.as("count"),
+    })
+    .from(progressEntries)
+    .where(eq(progressEntries.kind, "tutorial"))
+    .groupBy(progressEntries.scope, progressEntries.key);
+
+  const bySlug = new Map<string, TutorialStat>();
+  for (const r of rows) {
+    const entry = bySlug.get(r.scope) ?? { slug: r.scope, started: 0, completed: 0 };
+    if (r.key === "started") entry.started = Number(r.count);
+    else if (r.key === "completed") entry.completed = Number(r.count);
+    bySlug.set(r.scope, entry);
+  }
+
+  const payload = { stats: Array.from(bySlug.values()) };
+  cache = { expiresAt: now + CACHE_TTL_MS, payload };
+  return json(payload, {
+    headers: { "Cache-Control": "public, max-age=60" },
+  });
+};

package/src/server/http.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared HTTP helpers for API routes. Centralises the JSON response shape
+ * and the same-origin guard so routes don't reinvent either.
+ */
+
+export function json(body: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  headers.set("Content-Type", "application/json");
+  return new Response(JSON.stringify(body), { ...init, headers });
+}
+
+/**
+ * Reject cross-origin writes. SameSite=Lax on the device cookie already
+ * blocks most CSRF, but `Sec-Fetch-Site` is the modern, browser-supplied
+ * check — pair them for defense in depth. Same-origin and direct
+ * navigations are allowed; `none` (typed URL, bookmark) is allowed for GET
+ * only, which API mutating routes don't expose.
+ */
+export function isSameOrigin(request: Request): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  if (site === "same-origin") return true;
+  if (site === "none") return true;
+  if (site) return false;
+  // Older browsers without Sec-Fetch-Site: fall back to Origin/Referer.
+  const origin = request.headers.get("origin");
+  if (!origin) return true;
+  const host = request.headers.get("host");
+  try {
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}

package/src/types/ai.ts

@@ -0,0 +1,17 @@
+export interface AiConfig {
+  enabled: boolean;
+  name: string;
+  tagline?: string;
+  greeting?: string;
+  avatar?: string;
+  persona?: string;
+  provider: "anthropic" | "openai" | "google" | "openai-compatible";
+  model: string;
+  byok: "required" | "optional" | "disabled";
+  tone: "socratic" | "direct" | "encouraging";
+  contextBudgetTokens: number;
+  includeFutureSteps: boolean;
+  tools: { suggestPlaygroundEdit: boolean };
+  disabledSkills?: string[];
+  allowedDomains?: string[];
+}

package/styles/base.css

@@ -0,0 +1,127 @@
+@import "@fontsource-variable/geist";
+@import "@fontsource-variable/geist-mono";
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  background: var(--color-bg);
+  color: var(--color-fg);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+body {
+  margin: 0;
+  min-height: 100dvh;
+}
+
+a {
+  color: var(--color-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+a:hover {
+  color: var(--color-fg);
+}
+
+:focus-visible {
+  outline: var(--border-default, 2px) solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+/* Tutorial prose — consistent type scale, single weight family.
+ * Same weight (700) across every heading; size + tracking handles the
+ * hierarchy so it doesn't look "h1 thin / h2 super heavy".
+ */
+.prose {
+  font-family: var(--font-sans);
+  line-height: 1.65;
+  font-size: 1rem;
+  max-width: 72ch;
+}
+
+.prose h1,
+.prose h2,
+.prose h3,
+.prose h4,
+.prose h5,
+.prose h6 {
+  font-weight: 700;
+  letter-spacing: -0.015em;
+  line-height: 1.2;
+  margin-top: 2rem;
+  margin-bottom: 0.6rem;
+  color: var(--color-fg);
+}
+
+.prose h1 { font-size: 1.875rem; letter-spacing: -0.02em; }
+.prose h2 {
+  font-size: 1.4rem;
+  padding-top: 1.25rem;
+  border-top: var(--border-default) solid var(--color-border);
+}
+.prose h3 { font-size: 1.15rem; }
+.prose h4 { font-size: 1rem; }
+
+.prose p { margin: 0.75em 0; }
+
+.prose ul,
+.prose ol {
+  padding-left: 1.5rem;
+  margin: 0.75em 0;
+}
+
+.prose li { margin: 0.25em 0; }
+
+.prose code:not(pre code),
+.tut-tab-panel code:not(pre code) {
+  font-family: var(--font-mono);
+  background: var(--color-surface-2);
+  padding: 0.15em 0.45em;
+  font-size: 0.875em;
+  color: var(--color-accent);
+  border-radius: 0;
+}
+
+.prose blockquote {
+  border-left: var(--border-thick, 3px) solid var(--color-accent);
+  padding-left: 1rem;
+  margin: 1em 0;
+  color: var(--color-muted);
+}
+
+.prose hr {
+  border: none;
+  border-top: var(--border-default, 2px) solid var(--color-border);
+  margin: 2em 0;
+}
+
+.prose img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0;
+}
+
+.prose table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1em 0;
+}
+
+.prose th,
+.prose td {
+  border: var(--border-default, 2px) solid var(--color-border);
+  padding: 0.5em 0.75em;
+  text-align: left;
+}
+
+.prose th {
+  background: var(--color-surface);
+  font-weight: 700;
+}

package/styles/components/a11y.css

@@ -0,0 +1,12 @@
+/* sr-only utility for accessibility-only text */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/styles/components/byok.css

@@ -0,0 +1,50 @@
+/* BYOK setup */
+.byok-panel {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: min(440px, 92vw);
+  background: var(--color-surface);
+  border: var(--border-default) solid var(--color-border);
+  padding: 1.5rem;
+  z-index: 70;
+  border-radius: 0;
+}
+.byok-panel h2 { margin: 0 0 0.5rem; font-size: 1.25rem; }
+.byok-desc { color: var(--color-muted); font-size: 0.9em; margin: 0.25rem 0 1rem; }
+.byok-link { font-size: 0.85em; margin: 0 0 1rem; }
+.byok-field { display: grid; gap: 0.35rem; margin-bottom: 1rem; }
+.byok-field span {
+  font-family: var(--font-mono);
+  font-size: 0.72em;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--color-muted);
+}
+.byok-field input {
+  background: var(--color-bg);
+  border: var(--border-default) solid var(--color-border);
+  color: var(--color-fg);
+  padding: 0.55rem 0.75rem;
+  font: inherit;
+  border-radius: 0;
+}
+.byok-actions { display: flex; justify-content: flex-end; }
+.byok-actions button {
+  background: var(--color-accent);
+  color: var(--color-accent-fg);
+  border: 0;
+  padding: 0.55rem 1rem;
+  font-weight: 600;
+  cursor: pointer;
+  border-radius: 0;
+}
+.byok-actions button:disabled { opacity: 0.4; cursor: not-allowed; }
+.byok-disclaimer {
+  margin: 0;
+  padding-top: 1rem;
+  border-top: var(--border-default) solid var(--color-border);
+  color: var(--color-muted);
+  font-size: 0.8em;
+}