handzon-core 0.6.0

package/src/pages/TutorialLanding.astro

@@ -0,0 +1,324 @@
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+import { getStepsForTutorial, parseStepId, sumDurations } from "../lib/content.ts";
+import type { TutorialEntry } from "../lib/content.ts";
+
+interface Props {
+  tutorial: TutorialEntry;
+  siteName?: string;
+  tagline?: string;
+  logoUrl?: string;
+  faviconUrl?: string;
+  repoUrl?: string;
+}
+
+const { tutorial, siteName, tagline, logoUrl, faviconUrl, repoUrl } = Astro.props;
+const steps = await getStepsForTutorial(tutorial.id);
+const duration = tutorial.data.estimatedDuration ?? sumDurations(steps) ?? "";
+const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
+---
+<BaseLayout
+  title={tutorial.data.title}
+  description={tutorial.data.description}
+  siteName={siteName}
+  tagline={tagline}
+  logoUrl={logoUrl}
+  faviconUrl={faviconUrl}
+  repoUrl={repoUrl}
+>
+  <div class="landing">
+    <a class="back" href="/">← All tutorials</a>
+
+    <header class="hero">
+      <div class="hero-meta">
+        <span class={`pill pill-${tutorial.data.difficulty}`}>{tutorial.data.difficulty}</span>
+        {duration && <span class="pill pill-neutral">⏱ {duration}</span>}
+        <span class="pill pill-neutral">{steps.length} {steps.length === 1 ? "step" : "steps"}</span>
+      </div>
+
+      <h1>{tutorial.data.title}</h1>
+      <p class="desc">{tutorial.data.description}</p>
+
+      <div class="hero-actions">
+        {firstStepSlug && (
+          <a class="cta" href={`/${tutorial.id}/${firstStepSlug}`} data-tutorial-slug={tutorial.id}>
+            <span class="cta-label">Start tutorial</span>
+            <span class="cta-arrow" aria-hidden="true">→</span>
+          </a>
+        )}
+        {tutorial.data.author && (
+          <div class="author">
+            By <strong>{tutorial.data.author.name}</strong>
+            {tutorial.data.publishedAt && (
+              <> · {new Date(tutorial.data.publishedAt).toLocaleDateString()}</>
+            )}
+          </div>
+        )}
+      </div>
+
+      {tutorial.data.tags.length > 0 && (
+        <div class="hero-tags" aria-label="Topics">
+          {tutorial.data.tags.map((tag) => (
+            <a class="hero-tag" href={`/?tag=${encodeURIComponent(tag)}`}>#{tag}</a>
+          ))}
+        </div>
+      )}
+    </header>
+
+    {tutorial.data.prerequisites.length > 0 && (
+      <section class="block">
+        <h2>Prerequisites</h2>
+        <ul class="prereqs">{tutorial.data.prerequisites.map((p) => <li>{p}</li>)}</ul>
+      </section>
+    )}
+
+    <section class="block">
+      <h2>Steps</h2>
+      <ol class="step-list">
+        {steps.map((s, i) => {
+          const { stepSlug } = parseStepId(s.id);
+          return (
+            <li>
+              <a href={`/${tutorial.id}/${stepSlug}`}>
+                <span class="step-num">{String(i + 1).padStart(2, "0")}</span>
+                <span class="step-body">
+                  <strong>{s.data.title}</strong>
+                  {s.data.summary && <span class="step-summary">{s.data.summary}</span>}
+                </span>
+                {s.data.duration && <span class="step-dur">{s.data.duration}</span>}
+                <span class="step-chevron" aria-hidden="true">→</span>
+              </a>
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  </div>
+
+  <script>
+    // Resume from last visited if we have one.
+    import { getStore } from "../lib/progress/local.ts";
+    const cta = document.querySelector<HTMLAnchorElement>("[data-tutorial-slug]");
+    if (cta) {
+      const slug = cta.dataset.tutorialSlug!;
+      const last = getStore().get().lastVisited[slug];
+      const step = typeof last === "string" ? last : last?.step;
+      if (step) {
+        cta.textContent = `Continue from "${step}" →`;
+        cta.setAttribute("href", `/${slug}/${step}`);
+      }
+    }
+  </script>
+</BaseLayout>
+
+<style>
+  .landing {
+    max-width: 56rem;
+    margin: 0 auto;
+    padding: 2rem clamp(1rem, 4vw, 3rem) 5rem;
+  }
+  .back {
+    display: inline-block;
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-muted);
+    text-decoration: none;
+    margin-bottom: 1.5rem;
+  }
+  .back:hover { color: var(--color-accent); }
+  .hero {
+    position: relative;
+    padding: 2rem 2rem 2.25rem;
+    background: linear-gradient(
+      180deg,
+      color-mix(in oklab, var(--color-accent) 8%, var(--color-bg)),
+      var(--color-bg) 80%
+    );
+    border: var(--border-default, 2px) solid var(--color-border);
+    border-left-width: var(--border-thick, 4px);
+    border-left-color: var(--color-accent);
+    margin-bottom: 3rem;
+  }
+  .hero-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+    margin-bottom: 1.1rem;
+  }
+  .pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.22rem 0.55rem;
+    font-family: var(--font-mono);
+    font-size: 0.7em;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    border: var(--border-default, 2px) solid var(--color-border);
+    color: var(--color-muted);
+    background: var(--color-bg);
+  }
+  .pill-soft {
+    border-color: transparent;
+    background: var(--color-surface);
+  }
+  .pill-beginner { color: var(--color-success); border-color: var(--color-success); }
+  .pill-intermediate { color: var(--color-warn); border-color: var(--color-warn); }
+  .pill-advanced { color: var(--color-danger); border-color: var(--color-danger); }
+
+  /* Topics — quiet, hash-prefixed, sitting below the CTA. No pill
+   * boxes (which fought with the difficulty/duration row); just
+   * monospace muted text, clickable to filter the homepage. */
+  .hero-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.65rem 1rem;
+    margin-top: 1.75rem;
+    padding-top: 1.25rem;
+    border-top: 1px solid var(--color-border);
+  }
+  .hero-tag {
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    color: var(--color-muted);
+    text-decoration: none;
+    transition: color 0.12s ease;
+  }
+  .hero-tag:hover { color: var(--color-accent); }
+  h1 {
+    font-size: clamp(2.1rem, 4.5vw, 3rem);
+    font-weight: 800;
+    margin: 0 0 0.75rem;
+    letter-spacing: -0.025em;
+    line-height: 1.05;
+  }
+  .desc {
+    font-size: clamp(1rem, 1.5vw, 1.15rem);
+    line-height: 1.55;
+    color: var(--color-muted);
+    margin: 0 0 1.75rem;
+    max-width: 50ch;
+  }
+  .hero-actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 1.25rem;
+  }
+  .author { color: var(--color-muted); font-size: 0.85em; }
+  .cta {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.65rem;
+    padding: 0.85rem 1.4rem;
+    background: color-mix(in oklab, var(--color-accent) 10%, transparent);
+    color: var(--color-accent);
+    border: 1px solid var(--color-accent);
+    font-weight: 700;
+    font-size: 0.95em;
+    text-decoration: none;
+    cursor: pointer;
+    transition: background 0.12s ease, color 0.12s ease;
+  }
+  .cta:hover {
+    background: var(--color-accent);
+    color: var(--color-accent-fg);
+  }
+  .cta:hover .cta-arrow { transform: translateX(3px); }
+  .cta-arrow {
+    display: inline-block;
+    transition: transform 0.12s ease;
+    font-family: var(--font-mono);
+  }
+  .block { margin-top: 3rem; }
+  .block h2 {
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    color: var(--color-accent);
+    margin: 0 0 1rem;
+    font-weight: 700;
+  }
+  .prereqs {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: grid;
+    gap: 0.4rem;
+  }
+  .prereqs li {
+    display: flex;
+    align-items: center;
+    gap: 0.7rem;
+    padding: 0.55rem 0.85rem;
+    background: var(--color-surface);
+    border: 1px solid var(--color-border);
+    color: var(--color-fg);
+    font-size: 0.95em;
+    line-height: 1.4;
+  }
+  .prereqs li::before {
+    content: "✓";
+    display: inline-grid;
+    place-items: center;
+    width: 1.1rem;
+    height: 1.1rem;
+    border: 1px solid color-mix(in oklab, var(--color-accent) 40%, var(--color-border));
+    background: color-mix(in oklab, var(--color-accent) 12%, var(--color-bg));
+    color: var(--color-accent);
+    font-family: var(--font-mono);
+    font-size: 0.7em;
+    font-weight: 700;
+    flex-shrink: 0;
+  }
+  .step-list { list-style: none; padding: 0; margin: 0; display: grid; gap: 0.5rem; }
+  .step-list li { border: 1px solid var(--color-border); background: var(--color-bg); }
+  .step-list a {
+    display: grid;
+    grid-template-columns: auto 1fr auto auto;
+    gap: 1rem;
+    align-items: center;
+    padding: 0.9rem 1rem;
+    text-decoration: none;
+    color: var(--color-fg);
+    transition: background 0.12s ease, border-color 0.12s ease;
+  }
+  .step-list li:hover { border-color: var(--color-accent); }
+  .step-list a:hover { background: var(--color-surface); }
+  .step-list a:hover .step-chevron { color: var(--color-accent); transform: translateX(3px); }
+  .step-num {
+    display: inline-grid;
+    place-items: center;
+    min-width: 2.25rem;
+    height: 2.25rem;
+    padding: 0 0.5rem;
+    font-family: var(--font-mono);
+    font-size: 0.8em;
+    font-weight: 700;
+    color: var(--color-accent);
+    background: color-mix(in oklab, var(--color-accent) 10%, var(--color-bg));
+    border: 1px solid color-mix(in oklab, var(--color-accent) 35%, var(--color-border));
+  }
+  .step-body { display: grid; gap: 0.15rem; min-width: 0; }
+  .step-body strong { font-weight: 600; font-size: 1em; letter-spacing: -0.005em; }
+  .step-summary { color: var(--color-muted); font-size: 0.88em; }
+  .step-dur {
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    color: var(--color-muted);
+    padding: 0.2rem 0.5rem;
+    border: 1px solid var(--color-border);
+  }
+  .step-chevron {
+    font-family: var(--font-mono);
+    color: var(--color-muted);
+    transition: transform 0.12s ease, color 0.12s ease;
+  }
+  @media (max-width: 640px) {
+    .hero { padding: 1.5rem 1.25rem 1.75rem; }
+    .step-list a { grid-template-columns: auto 1fr auto; padding: 0.75rem; }
+    .step-chevron { display: none; }
+  }
+</style>

package/src/pages/TutorialStep.astro

@@ -0,0 +1,67 @@
+---
+import { render } from "astro:content";
+import TutorialLayout from "../layouts/TutorialLayout.astro";
+import ChatButton from "../components/ai/ChatButton.tsx";
+import { parseStepId } from "../lib/content.ts";
+import type { StepEntry, TutorialEntry } from "../lib/content.ts";
+import { mdxComponents } from "../lib/mdx-components.ts";
+import { buildContext } from "../lib/ai/context.ts";
+import { emptyState } from "../lib/progress/types.ts";
+import type { AiConfig } from "../types/ai.ts";
+
+interface Props {
+  tutorial: TutorialEntry;
+  steps: StepEntry[];
+  currentStep: StepEntry;
+  aiDefaults: AiConfig;
+  siteName?: string;
+  tagline?: string;
+  logoUrl?: string;
+  faviconUrl?: string;
+  repoUrl?: string;
+}
+
+const {
+  tutorial,
+  steps,
+  currentStep,
+  aiDefaults,
+  siteName,
+  tagline,
+  logoUrl,
+  faviconUrl,
+  repoUrl,
+} = Astro.props;
+const { stepSlug } = parseStepId(currentStep.id);
+const { Content } = await render(currentStep);
+
+const components = mdxComponents();
+const hasCheckpoint = currentStep.body?.includes("<Checkpoint") ?? false;
+
+const aiConfig: AiConfig = { ...aiDefaults, ...(tutorial.data.ai ?? {}) };
+const initialContext = buildContext({
+  tutorial,
+  steps,
+  currentStep,
+  progress: emptyState(),
+  references: [],
+  includeFutureSteps: aiConfig.includeFutureSteps,
+});
+---
+<TutorialLayout
+  tutorial={tutorial}
+  steps={steps}
+  currentStep={currentStep}
+  currentStepSlug={stepSlug}
+  hasCheckpoint={hasCheckpoint}
+  siteName={siteName}
+  tagline={tagline}
+  logoUrl={logoUrl}
+  faviconUrl={faviconUrl}
+  repoUrl={repoUrl}
+>
+  <Content components={components} />
+  {aiConfig.enabled && (
+    <ChatButton client:idle config={aiConfig} context={initialContext} />
+  )}
+</TutorialLayout>

package/src/pages/paths.ts

@@ -0,0 +1,36 @@
+/**
+ * Static-path helpers for handzon scaffolds. Use these as the
+ * `getStaticPaths` export of a route file:
+ *
+ *   export const getStaticPaths = getTutorialLandingPaths;
+ *   export const getStaticPaths = getTutorialStepPaths;
+ */
+import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
+import type { StepEntry, TutorialEntry } from "../lib/content.ts";
+
+export async function getTutorialLandingPaths() {
+  const tutorials = await getTutorials();
+  return tutorials.map((tut) => ({
+    params: { tutorial: tut.id },
+    props: { tutorial: tut },
+  }));
+}
+
+export async function getTutorialStepPaths() {
+  const tutorials = await getTutorials();
+  const paths: Array<{
+    params: { tutorial: string; step: string };
+    props: { tutorial: TutorialEntry; steps: StepEntry[]; currentStep: StepEntry };
+  }> = [];
+  for (const tut of tutorials) {
+    const steps = await getStepsForTutorial(tut.id);
+    for (const step of steps) {
+      const { stepSlug } = parseStepId(step.id);
+      paths.push({
+        params: { tutorial: tut.id, step: stepSlug },
+        props: { tutorial: tut, steps, currentStep: step },
+      });
+    }
+  }
+  return paths;
+}

package/src/server/auth/config.ts

@@ -0,0 +1,102 @@
+/**
+ * Auth.js config factory consumed by the scaffold's `auth.config.ts`.
+ *
+ * Usage (scaffold side):
+ *
+ *   import { createAuthConfig } from "handzon-core/server/auth/config";
+ *   import { getDb } from "handzon-core/server/db/client";
+ *   export default createAuthConfig({ db: getDb() });
+ *
+ * GitHub is the only provider in 0.2; email/password and others are
+ * out of scope (see plan: github-auth_d52529d5).
+ */
+import { DrizzleAdapter } from "@auth/drizzle-adapter";
+import GitHub from "@auth/core/providers/github";
+import { defineConfig } from "auth-astro";
+import { accounts, sessions, users, verificationTokens } from "./schema.ts";
+
+interface AuthConfigOptions {
+  /**
+   * Postgres drizzle client, or `null` when DATABASE_URL isn't
+   * available at build time. When `null`, we return a stub config so
+   * auth-astro's integration loads but does nothing — useful for Tier 1
+   * builds and for `pnpm build` on a fresh checkout without a database.
+   */
+  db: Parameters<typeof DrizzleAdapter>[0] | null;
+}
+
+/**
+ * Normalises whatever the operator gave us into a full URL that
+ * Auth.js + GitHub OAuth callbacks can use. Priority:
+ *
+ *   1. `AUTH_URL`              — operator override; supports either a
+ *                                full URL or a bare hostname (in which
+ *                                case we append `.onrender.com`, the
+ *                                same shape used by ALLOWED_ORIGIN and
+ *                                PUBLIC_AI_SERVICE_URL).
+ *   2. `RENDER_EXTERNAL_URL`   — Render auto-injects this on every web
+ *                                service (e.g. `https://foo.onrender.com`).
+ *   3. `RENDER_EXTERNAL_HOSTNAME` — bare hostname, also auto-injected;
+ *                                we prefix with `https://`.
+ *
+ * Returns `undefined` when none are set (local dev with no override —
+ * Auth.js falls back to the request's Origin header).
+ */
+function resolveAuthUrl(): string | undefined {
+  const explicit = process.env.AUTH_URL?.trim();
+  if (explicit) {
+    const trimmed = explicit.replace(/\/$/, "");
+    return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}.onrender.com`;
+  }
+  const renderUrl = process.env.RENDER_EXTERNAL_URL?.trim();
+  if (renderUrl) return renderUrl.replace(/\/$/, "");
+  const renderHost = process.env.RENDER_EXTERNAL_HOSTNAME?.trim();
+  if (renderHost) return `https://${renderHost}`;
+  return undefined;
+}
+
+export function createAuthConfig({ db }: AuthConfigOptions) {
+  // Auth.js v5 reads `AUTH_URL` from process.env on each request, so
+  // we resolve once and write it back. Idempotent: if AUTH_URL was
+  // already a full URL, this is a no-op aside from the trailing-slash
+  // trim.
+  const resolvedUrl = resolveAuthUrl();
+  if (resolvedUrl && resolvedUrl !== process.env.AUTH_URL) {
+    process.env.AUTH_URL = resolvedUrl;
+  }
+
+  if (!db) {
+    // No database → no adapter → no providers. auth-astro logs a warning
+    // and any sign-in attempt fails gracefully instead of crashing the
+    // build.
+    return defineConfig({ providers: [] });
+  }
+  return defineConfig({
+    adapter: DrizzleAdapter(db, {
+      usersTable: users,
+      accountsTable: accounts,
+      sessionsTable: sessions,
+      verificationTokensTable: verificationTokens,
+    }),
+    providers: [
+      GitHub({
+        clientId: process.env.GITHUB_CLIENT_ID,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      }),
+    ],
+    // JWT session strategy keeps the cookie self-describing — no extra
+    // DB hit on every request. The `users` table still holds the
+    // canonical record; we just don't store the live session there.
+    session: { strategy: "jwt" },
+    callbacks: {
+      // Surface the `users.id` UUID on `session.user.id` so server
+      // code (getOrCreateLearner) can match it without re-resolving.
+      async session({ session, token }) {
+        if (session.user && token.sub) {
+          (session.user as { id?: string }).id = token.sub;
+        }
+        return session;
+      },
+    },
+  });
+}

package/src/server/auth/schema.ts

@@ -0,0 +1,66 @@
+/**
+ * Auth.js (NextAuth) drizzle schema for Postgres. Tables shape matches
+ * the canonical reference in `@auth/drizzle-adapter` docs. Drizzle
+ * passes these to `DrizzleAdapter(db)` via the adapter's auto-detection.
+ *
+ * The `learners` row that maps a signed-in user to local progress lives
+ * in `../db/schema.ts` — it adds a nullable `user_id` FK to `users` here.
+ */
+import {
+  integer,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core";
+
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: text("name"),
+  email: text("email").notNull().unique(),
+  emailVerified: timestamp("email_verified", { withTimezone: true }),
+  image: text("image"),
+});
+
+export const accounts = pgTable(
+  "accounts",
+  {
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("provider_account_id").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    pk: primaryKey({ columns: [account.provider, account.providerAccountId] }),
+  }),
+);
+
+export const sessions = pgTable("sessions", {
+  sessionToken: text("session_token").primaryKey(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: timestamp("expires", { withTimezone: true }).notNull(),
+});
+
+export const verificationTokens = pgTable(
+  "verification_tokens",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: timestamp("expires", { withTimezone: true }).notNull(),
+  },
+  (vt) => ({
+    pk: primaryKey({ columns: [vt.identifier, vt.token] }),
+  }),
+);

package/src/server/auth/session.ts

@@ -0,0 +1,27 @@
+/**
+ * Thin wrapper around `auth-astro/server`'s `getSession` that flattens
+ * the shape into something boring and stable. Callers don't need to
+ * know about Auth.js's JWT vs database session details.
+ */
+import { getSession } from "auth-astro/server";
+
+export interface AuthedUser {
+  userId: string;
+  email: string | null;
+  name: string | null;
+  image: string | null;
+}
+
+export async function getAuthedUser(request: Request): Promise<AuthedUser | null> {
+  const session = await getSession(request);
+  const user = session?.user as
+    | { id?: string; email?: string | null; name?: string | null; image?: string | null }
+    | undefined;
+  if (!user?.id) return null;
+  return {
+    userId: user.id,
+    email: user.email ?? null,
+    name: user.name ?? null,
+    image: user.image ?? null,
+  };
+}