handzon-core 0.12.1 → 0.13.0

package/src/server/auth/config.ts

@@ -24,6 +24,12 @@ interface AuthConfigOptions {
    * builds and for `pnpm build` on a fresh checkout without a database.
    */
   db: Parameters<typeof DrizzleAdapter>[0] | null;
+  /**
+   * Override auth-astro's route prefix when a fronting proxy rewrites
+   * paths before the request reaches the Handzon app. Defaults to
+   * Astro's configured `base` plus `/api/auth`.
+   */
+  authPrefix?: string;
 }
 
 /**
@@ -56,13 +62,14 @@ function resolveAuthUrl(): string | undefined {
   return undefined;
 }
 
-function resolveAuthPrefix(): string {
+function resolveAuthPrefix(authPrefix?: string): string {
+  if (authPrefix) return authPrefix;
   const base = import.meta.env.BASE_URL;
   const normalizedBase = base === "/" ? "" : base.replace(/\/$/, "");
   return `${normalizedBase}/api/auth`;
 }
 
-export function createAuthConfig({ db }: AuthConfigOptions) {
+export function createAuthConfig({ db, authPrefix }: 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
@@ -72,18 +79,20 @@ export function createAuthConfig({ db }: AuthConfigOptions) {
     process.env.AUTH_URL = resolvedUrl;
   }
 
+  const prefix = resolveAuthPrefix(authPrefix);
+
   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({ prefix, providers: [] });
   }
   return defineConfig({
     // auth-astro defaults to /api/auth, but Astro apps mounted with
     // `base` receive requests at /<base>/api/auth. Use the same base
     // that powers app links and API calls so the catch-all auth route
     // returns a Response instead of falling through with undefined.
-    prefix: resolveAuthPrefix(),
+    prefix,
     adapter: DrizzleAdapter(db, {
       usersTable: users,
       accountsTable: accounts,

package/src/server/mcp/startTutorial.ts

@@ -1,5 +1,13 @@
 import type { StarterSpec, VerifySpec } from "../../collections.ts";
-import { type McpTool, text } from "./protocol.ts";
+import {
+  isStarterSpec,
+  isVerifySpec,
+  resolveForTrack,
+  type TrackScoped,
+} from "../../lib/track-scoped.ts";
+import type { TrackOption } from "../../lib/tracks.ts";
+import { type McpContext, type McpTool, text } from "./protocol.ts";
+import { resolveMcpTrack } from "./tracks.ts";
 
 interface StartTutorialStep {
   slug: string;
@@ -7,7 +15,7 @@ interface StartTutorialStep {
   title: string;
   summary?: string;
   duration?: string;
-  verify?: VerifySpec | null;
+  verify?: TrackScoped<VerifySpec> | null;
 }
 
 interface StartTutorialInput {
@@ -17,14 +25,18 @@ interface StartTutorialInput {
     description: string;
     difficulty: string;
     tags: string[];
-    starter?: StarterSpec;
+    tracks?: TrackOption[];
+    defaultTrack?: string;
+    starter?: TrackScoped<StarterSpec>;
   };
   steps: StartTutorialStep[];
   workspaceName?: string;
+  resolvedTrack?: string;
 }
 
 export type LoadStartTutorial = (
   slug: string,
+  ctx: McpContext,
 ) => Promise<Omit<StartTutorialInput, "workspaceName"> | null>;
 
 export interface StartTutorialPayload {
@@ -34,6 +46,8 @@ export interface StartTutorialPayload {
     description: string;
     difficulty: string;
     tags: string[];
+    tracks: TrackOption[];
+    track?: string | null;
   };
   starter: StarterSpec | null;
   workspace: {
@@ -80,19 +94,39 @@ function buildCommands(starter: StarterSpec | undefined, targetDir: string, open
   return commands;
 }
 
+function resolveStarterForTrack(
+  starter: TrackScoped<StarterSpec> | undefined,
+  trackId: string | undefined,
+) {
+  return resolveForTrack(starter, trackId, isStarterSpec as (v: unknown) => v is StarterSpec);
+}
+
+function resolveVerifyForTrack(
+  verify: TrackScoped<VerifySpec> | undefined,
+  trackId: string | undefined,
+) {
+  return resolveForTrack(verify, trackId, isVerifySpec as (v: unknown) => v is VerifySpec);
+}
+
 export function buildStartTutorialPayload({
   tutorial,
   steps,
   workspaceName,
+  resolvedTrack,
 }: StartTutorialInput): StartTutorialPayload {
-  const [firstStep] = [...steps].sort((a, b) => a.order - b.order);
+  const resolvedSteps = steps.map((step) => ({
+    ...step,
+    verify: resolveVerifyForTrack(step.verify ?? undefined, resolvedTrack) ?? null,
+  }));
+  const [firstStep] = [...resolvedSteps].sort((a, b) => a.order - b.order);
   if (!firstStep) {
     throw new Error(`Tutorial ${tutorial.slug} has no steps.`);
   }
 
-  const targetDir = resolveTargetDir(tutorial.slug, tutorial.starter, workspaceName);
-  const openPath = resolveOpenPath(targetDir, tutorial.starter);
-  const commands = buildCommands(tutorial.starter, targetDir, openPath);
+  const starter = resolveStarterForTrack(tutorial.starter, resolvedTrack);
+  const targetDir = resolveTargetDir(tutorial.slug, starter, workspaceName);
+  const openPath = resolveOpenPath(targetDir, starter);
+  const commands = buildCommands(starter, targetDir, openPath);
 
   return {
     tutorial: {
@@ -101,8 +135,10 @@ export function buildStartTutorialPayload({
       description: tutorial.description,
       difficulty: tutorial.difficulty,
       tags: tutorial.tags,
+      tracks: tutorial.tracks ?? [],
+      track: resolvedTrack ?? null,
     },
-    starter: tutorial.starter ?? null,
+    starter: starter ?? null,
     workspace: { targetDir, openPath },
     commands,
     firstStep,
@@ -131,20 +167,42 @@ export function createStartTutorialTool(load: LoadStartTutorial): McpTool {
           description:
             "Optional local directory name to use instead of the tutorial's default targetDir.",
         },
+        track: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Optional tutorial track id. Overrides the learner's persisted prefs.track for this call.",
+        },
       },
       required: ["slug"],
       additionalProperties: false,
     },
-    handler: async (args) => {
-      const { slug, workspaceName } = args as { slug: string; workspaceName?: string };
-      const loaded = await load(slug);
+    handler: async (args, ctx) => {
+      const { slug, workspaceName, track } = args as {
+        slug: string;
+        workspaceName?: string;
+        track?: string;
+      };
+      const loaded = await load(slug, ctx);
       if (!loaded) {
         return {
           content: [{ type: "text", text: `No tutorial with slug "${slug}".` }],
           isError: true,
         };
       }
-      return text(JSON.stringify(buildStartTutorialPayload({ ...loaded, workspaceName }), null, 2));
+      const resolvedTrack = await resolveMcpTrack({
+        tracks: loaded.tutorial.tracks,
+        defaultTrack: loaded.tutorial.defaultTrack,
+        explicitTrack: track,
+        learnerId: ctx.learnerId,
+      });
+      return text(
+        JSON.stringify(
+          buildStartTutorialPayload({ ...loaded, workspaceName, resolvedTrack }),
+          null,
+          2,
+        ),
+      );
     },
   };
 }

package/src/server/mcp/tools.ts

@@ -1,4 +1,5 @@
 import { eq } from "drizzle-orm";
+import type { VerifySpec } from "../../collections.ts";
 import {
   getStep,
   getStepsForTutorial,
@@ -6,10 +7,13 @@ import {
   getTutorials,
   parseStepId,
 } from "../../lib/content.ts";
+import { isVerifySpec, resolveForTrack, type TrackScoped } from "../../lib/track-scoped.ts";
+import { stripInactiveTrackBlocks } from "../../lib/track-source.ts";
 import { getDb } from "../db/client.ts";
 import { progressEntries } from "../db/schema.ts";
 import { type McpTool, text } from "./protocol.ts";
 import { createStartTutorialTool } from "./startTutorial.ts";
+import { resolveMcpTrack } from "./tracks.ts";
 import { progressWriteTools, verificationTools } from "./writeTools.ts";
 
 /**
@@ -24,6 +28,13 @@ function extractCheckpointLabel(body: string): string | undefined {
   return m[1] ?? m[2] ?? m[3];
 }
 
+function resolveVerifyForTrack(
+  verify: TrackScoped<VerifySpec> | undefined,
+  trackId: string | undefined,
+) {
+  return resolveForTrack(verify, trackId, isVerifySpec as (v: unknown) => v is VerifySpec);
+}
+
 /**
  * Catalog read tools. No auth required beyond a valid bearer token —
  * agents browsing what's available before deciding which tutorial to
@@ -42,6 +53,8 @@ export const catalogReadTools: McpTool[] = [
         description: t.data.description,
         difficulty: t.data.difficulty,
         tags: t.data.tags,
+        tracks: t.data.tracks,
+        defaultTrack: t.data.defaultTrack,
       }));
       return text(JSON.stringify({ tutorials: rows }, null, 2));
     },
@@ -73,6 +86,8 @@ export const catalogReadTools: McpTool[] = [
         difficulty: tutorial.data.difficulty,
         tags: tutorial.data.tags,
         gated: tutorial.data.gated,
+        tracks: tutorial.data.tracks,
+        defaultTrack: tutorial.data.defaultTrack,
         starter: tutorial.data.starter ?? null,
         steps: steps.map((s) => {
           const { stepSlug, order } = parseStepId(s.id);
@@ -99,6 +114,8 @@ export const catalogReadTools: McpTool[] = [
         description: tutorial.data.description,
         difficulty: tutorial.data.difficulty,
         tags: tutorial.data.tags,
+        tracks: tutorial.data.tracks,
+        defaultTrack: tutorial.data.defaultTrack,
         starter: tutorial.data.starter,
       },
       steps: steps.map((s) => {
@@ -122,12 +139,18 @@ export const catalogReadTools: McpTool[] = [
       properties: {
         tutorial: { type: "string", minLength: 1 },
         step: { type: "string", minLength: 1 },
+        track: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Optional tutorial track id. Overrides the learner's persisted prefs.track for this call.",
+        },
       },
       required: ["tutorial", "step"],
       additionalProperties: false,
     },
     handler: async (args) => {
-      const { tutorial, step } = args as { tutorial: string; step: string };
+      const { tutorial, step, track } = args as { tutorial: string; step: string; track?: string };
       const tut = await getTutorialBySlug(tutorial);
       if (!tut) {
         return {
@@ -143,12 +166,22 @@ export const catalogReadTools: McpTool[] = [
         };
       }
       const { stepSlug, order } = parseStepId(stepEntry.id);
-      const body = stepEntry.body ?? "";
-      const verifySpec = (stepEntry.data as { verify?: unknown }).verify;
+      const activeTrack = await resolveMcpTrack({
+        tracks: tut.data.tracks,
+        defaultTrack: tut.data.defaultTrack,
+        explicitTrack: track,
+        learnerId: ctx.learnerId,
+      });
+      const body = stripInactiveTrackBlocks(stepEntry.body ?? "", activeTrack);
+      const verifySpec = resolveVerifyForTrack(
+        (stepEntry.data as { verify?: TrackScoped<VerifySpec> }).verify,
+        activeTrack,
+      );
       const payload = {
         tutorial,
         slug: stepSlug,
         order,
+        track: activeTrack ?? null,
         title: stepEntry.data.title,
         summary: stepEntry.data.summary,
         duration: stepEntry.data.duration,

package/src/server/mcp/tracks.ts

@@ -0,0 +1,43 @@
+import { and, eq } from "drizzle-orm";
+import { resolveActiveTrack, type TrackOption } from "../../lib/tracks.ts";
+import { getDb } from "../db/client.ts";
+import { progressEntries } from "../db/schema.ts";
+
+export async function readPersistedTrack(
+  learnerId: string | undefined,
+): Promise<string | undefined> {
+  if (!learnerId) return undefined;
+  const db = getDb();
+  const [row] = await db
+    .select({ value: progressEntries.value })
+    .from(progressEntries)
+    .where(
+      and(
+        eq(progressEntries.learnerId, learnerId),
+        eq(progressEntries.kind, "pref"),
+        eq(progressEntries.scope, "global"),
+        eq(progressEntries.key, "track"),
+      ),
+    )
+    .limit(1);
+  return typeof row?.value === "string" ? row.value : undefined;
+}
+
+export async function resolveMcpTrack({
+  tracks,
+  defaultTrack,
+  explicitTrack,
+  learnerId,
+}: {
+  tracks?: TrackOption[];
+  defaultTrack?: string;
+  explicitTrack?: string;
+  learnerId?: string;
+}): Promise<string | undefined> {
+  return resolveActiveTrack({
+    tracks,
+    explicitTrack,
+    preferredTrack: await readPersistedTrack(learnerId),
+    defaultTrack,
+  });
+}

package/src/server/mcp/writeTools.ts

@@ -1,12 +1,22 @@
-import { getStep } from "../../lib/content.ts";
+import type { VerifySpec } from "../../collections.ts";
+import { getStep, getTutorialBySlug } from "../../lib/content.ts";
+import { isVerifySpec, resolveForTrack, type TrackScoped } from "../../lib/track-scoped.ts";
 import { getDb } from "../db/client.ts";
 import { helpRequests } from "../db/schema.ts";
 import { writeProgressEntries } from "../progress.ts";
 import { type CheckObservation, evaluate } from "../verify/evaluator.ts";
 import { errorResult, type McpTool, text } from "./protocol.ts";
+import { resolveMcpTrack } from "./tracks.ts";
 
 const SCOPE = "progress:write";
 
+function resolveVerifyForTrack(
+  verify: TrackScoped<VerifySpec> | undefined,
+  trackId: string | undefined,
+) {
+  return resolveForTrack(verify, trackId, isVerifySpec as (v: unknown) => v is VerifySpec);
+}
+
 function requireLearner(learnerId: string | undefined) {
   if (!learnerId) {
     throw new Error("No resolved learner — bearer token required.");
@@ -312,6 +322,12 @@ export const verificationTools: McpTool[] = [
       properties: {
         tutorial: { type: "string", minLength: 1 },
         step: { type: "string", minLength: 1 },
+        track: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Optional tutorial track id. Overrides the learner's persisted prefs.track for this verification.",
+        },
         observations: {
           type: "array",
           description:
@@ -326,16 +342,28 @@ export const verificationTools: McpTool[] = [
       const a = args as {
         tutorial: string;
         step: string;
+        track?: string;
         observations: CheckObservation[];
       };
       const learnerId = requireLearner(ctx.learnerId);
+      const tutorialEntry = await getTutorialBySlug(a.tutorial);
+      if (!tutorialEntry) {
+        return errorResult(`No tutorial "${a.tutorial}".`);
+      }
       const stepEntry = await getStep(a.tutorial, a.step);
       if (!stepEntry) {
         return errorResult(`No step "${a.step}" in "${a.tutorial}".`);
       }
-      const spec = (stepEntry.data as { verify?: unknown }).verify as
-        | import("../../collections.ts").VerifySpec
-        | undefined;
+      const activeTrack = await resolveMcpTrack({
+        tracks: tutorialEntry.data.tracks,
+        defaultTrack: tutorialEntry.data.defaultTrack,
+        explicitTrack: a.track,
+        learnerId,
+      });
+      const spec = resolveVerifyForTrack(
+        (stepEntry.data as { verify?: TrackScoped<VerifySpec> }).verify,
+        activeTrack,
+      );
       if (!spec) {
         return errorResult(
           `Step ${a.tutorial}/${a.step} has no verify block. Use complete_checkpoint for prose-fallback verification.`,
@@ -356,6 +384,7 @@ export const verificationTools: McpTool[] = [
               source: "verify",
               tutorial: a.tutorial,
               step: a.step,
+              track: activeTrack ?? null,
               results: a.observations,
               ts,
             },
@@ -383,6 +412,7 @@ export const verificationTools: McpTool[] = [
           key: spec.id,
           value: {
             pass: false,
+            track: activeTrack ?? null,
             failingCheckIndex: verdict.failingCheckIndex,
             reason: verdict.reason,
             hint: verdict.hint,

package/styles/components/track-selector.css

@@ -0,0 +1,44 @@
+.track-selector {
+  display: grid;
+  gap: 0.5rem;
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: var(--border-default, 2px) solid var(--color-border);
+}
+
+.track-selector-label {
+  font-family: var(--font-mono);
+  font-size: 0.72em;
+  color: var(--color-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.track-selector-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+}
+
+.track-selector-option {
+  appearance: none;
+  border: var(--border-default, 2px) solid var(--color-border);
+  background: var(--color-bg);
+  color: var(--color-fg);
+  cursor: pointer;
+  font: inherit;
+  font-family: var(--font-mono);
+  font-size: 0.75em;
+  line-height: 1;
+  padding: 0.45rem 0.6rem;
+}
+
+.track-selector-option:hover {
+  border-color: var(--color-accent);
+}
+
+.track-selector-option[data-active="true"] {
+  background: var(--color-accent);
+  border-color: var(--color-accent);
+  color: var(--color-accent-fg);
+}

package/styles/components.css

@@ -15,6 +15,7 @@
 
 /* Site chrome */
 @import "./components/progress.css";
+@import "./components/track-selector.css";
 
 /* AI assistant */
 @import "./components/chat.css";