handzon-core 0.7.0 → 0.8.1

package/src/server/handlers/progress.ts

@@ -1,10 +1,11 @@
 import type { APIRoute } from "astro";
-import { and, eq, sql } from "drizzle-orm";
+import { eq } 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";
+import { writeProgressEntries } from "../progress.ts";
 
 const MAX_BODY_BYTES = 32 * 1024;
 const MAX_ENTRIES = 200;
@@ -59,55 +60,10 @@ export const POST: APIRoute = async ({ cookies, request }) => {
   if (parsed.length === 0) return json({ written: 0 });
 
   const learner = await getOrCreateLearner(cookies, request);
-  const db = getDb();
-  const now = new Date();
-
   // `value: null` is the tombstone signal for "this entry was undone"
-  // (e.g. unchecking a checkpoint). The `value` column is NOT NULL, so
-  // we DELETE these rows instead of upserting them.
-  const deletes = parsed.filter((b) => b.value === null);
-  const upserts = parsed.filter((b) => b.value !== null);
-
-  for (const d of deletes) {
-    await db
-      .delete(progressEntries)
-      .where(
-        and(
-          eq(progressEntries.learnerId, learner.id),
-          eq(progressEntries.kind, d.kind),
-          eq(progressEntries.scope, d.scope),
-          eq(progressEntries.key, d.key),
-        ),
-      );
-  }
-
-  if (upserts.length > 0) {
-    const rows = upserts.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: parsed.length });
+  // (e.g. unchecking a checkpoint). writeProgressEntries handles the
+  // split into deletes + upserts; the same writer is used by the MCP
+  // write tools so behaviour stays consistent across surfaces.
+  const written = await writeProgressEntries(learner.id, parsed);
+  return json({ written });
 };

package/src/server/handlers/progressEvents.ts

@@ -0,0 +1,68 @@
+import type { APIRoute } from "astro";
+import { getOrCreateLearner } from "../auth.ts";
+import { isSameOrigin } from "../http.ts";
+import { subscribeLearner } from "../progressBus.ts";
+
+const HEARTBEAT_MS = 25_000;
+
+/**
+ * Server-Sent Events stream of progress writes for the current
+ * learner. One connection per open browser tab; the in-app store
+ * (`createRemoteStore`) opens an EventSource on first mount and
+ * merges incoming entries through the same reducer as the
+ * POST-response path.
+ *
+ * Each event has the shape:
+ *   data: { "kind": "...", "scope": "...", "key": "...", "value": ..., "ts": ... }
+ *
+ * Heartbeat comments keep proxies (CDN, Render's edge) from
+ * killing the connection on idle.
+ */
+export const GET: APIRoute = async ({ cookies, request }) => {
+  if (!process.env.DATABASE_URL) {
+    return new Response("SSE disabled — no DATABASE_URL.", { status: 503 });
+  }
+  if (!isSameOrigin(request)) {
+    return new Response("Cross-origin SSE rejected.", { status: 403 });
+  }
+  const learner = await getOrCreateLearner(cookies, request);
+  const encoder = new TextEncoder();
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Initial connect comment — clients show "open" only after a
+      // first bit of data, and some proxies need a flush.
+      controller.enqueue(encoder.encode(": connected\n\n"));
+      unsubscribe = subscribeLearner(learner.id, (msg) => {
+        try {
+          const payload = JSON.stringify(msg);
+          controller.enqueue(encoder.encode(`data: ${payload}\n\n`));
+        } catch (e) {
+          console.warn("[handzon] sse encode failed:", e);
+        }
+      });
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": keepalive\n\n"));
+        } catch {
+          /* controller closed — cancel will clean up */
+        }
+      }, HEARTBEAT_MS);
+    },
+    cancel() {
+      unsubscribe?.();
+      if (heartbeat) clearInterval(heartbeat);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+};

package/src/server/mcp/protocol.ts

@@ -0,0 +1,99 @@
+/**
+ * Minimal MCP-compatible JSON-RPC 2.0 dispatcher.
+ *
+ * We hand-roll the surface (rather than depending on
+ * @modelcontextprotocol/sdk) because the SDK targets Node http
+ * I/O, while Astro endpoints run on the Fetch Request/Response
+ * API. The Streamable HTTP transport supports immediate JSON
+ * responses, which is all v1 needs — SSE-streamed tool results
+ * are not on the v1 menu.
+ *
+ * Supported methods:
+ *   - initialize          → server capabilities + name/version
+ *   - tools/list          → ordered tool descriptors
+ *   - tools/call          → execute a tool with arguments
+ *
+ * Anything else returns -32601 Method not found.
+ */
+
+export const PROTOCOL_VERSION = "2025-03-26";
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResult {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result: unknown;
+}
+
+export interface JsonRpcError {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  error: { code: number; message: string; data?: unknown };
+}
+
+export type JsonRpcResponse = JsonRpcResult | JsonRpcError;
+
+export interface McpToolContent {
+  type: "text";
+  text: string;
+}
+
+export interface McpToolResult {
+  content: McpToolContent[];
+  isError?: boolean;
+}
+
+export interface McpTool<A = unknown> {
+  name: string;
+  description: string;
+  /** JSON Schema for the tool arguments. */
+  inputSchema: Record<string, unknown>;
+  handler: (args: A, ctx: McpContext) => Promise<McpToolResult>;
+  /** Set when the tool mutates state — used to gate by scope. */
+  requiredScope?: string;
+}
+
+export interface McpContext {
+  /** Resolved learner id when an authenticated tool is invoked. */
+  learnerId?: string;
+  /** Token scopes granted to the caller. */
+  scopes?: string[];
+  /** Original request — tools that need cookies, IP, etc. read from here. */
+  request: Request;
+}
+
+export interface ServerInfo {
+  name: string;
+  version: string;
+}
+
+export function ok(id: JsonRpcRequest["id"], result: unknown): JsonRpcResult {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+
+export function fail(
+  id: JsonRpcRequest["id"],
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcError {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: data === undefined ? { code, message } : { code, message, data },
+  };
+}
+
+export function text(value: string): McpToolResult {
+  return { content: [{ type: "text", text: value }] };
+}
+
+export function errorResult(message: string): McpToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}

package/src/server/mcp/server.ts

@@ -0,0 +1,94 @@
+import {
+  fail,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type McpContext,
+  type McpTool,
+  ok,
+  PROTOCOL_VERSION,
+  type ServerInfo,
+} from "./protocol.ts";
+
+const DEFAULT_INFO: ServerInfo = {
+  name: "handzon-mcp",
+  version: "0.1.0",
+};
+
+export interface DispatchOptions {
+  /** Tools registered with the server. */
+  tools: McpTool[];
+  /** Identity declared to MCP clients. Overridable per-site. */
+  serverInfo?: Partial<ServerInfo>;
+  /**
+   * Resolve the caller's learner id + scopes from the request, if any.
+   * Catalog reads don't need this; protected tools do. When null is
+   * returned for a tool with `requiredScope`, the call fails with
+   * -32001 Unauthorized.
+   */
+  resolveAuth?: (request: Request) => Promise<{ learnerId: string; scopes: string[] } | null>;
+}
+
+/**
+ * Dispatch one JSON-RPC request against the configured tool set.
+ * Pure of HTTP — the Astro endpoint owns request parsing, response
+ * serialization, and CORS. This function returns whatever the JSON-RPC
+ * spec wants in the response body.
+ */
+export async function dispatchMcp(
+  request: Request,
+  body: JsonRpcRequest,
+  opts: DispatchOptions,
+): Promise<JsonRpcResponse> {
+  const info = { ...DEFAULT_INFO, ...(opts.serverInfo ?? {}) };
+
+  if (body.method === "initialize") {
+    return ok(body.id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: info,
+    });
+  }
+
+  if (body.method === "tools/list") {
+    const tools = opts.tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }));
+    return ok(body.id, { tools });
+  }
+
+  if (body.method === "tools/call") {
+    const params = body.params as { name?: string; arguments?: unknown } | undefined;
+    const toolName = params?.name;
+    if (!toolName) return fail(body.id, -32602, "Missing tool name.");
+    const tool = opts.tools.find((t) => t.name === toolName);
+    if (!tool) return fail(body.id, -32601, `Unknown tool: ${toolName}`);
+
+    let learnerId: string | undefined;
+    let scopes: string[] | undefined;
+    if (opts.resolveAuth) {
+      const resolved = await opts.resolveAuth(request);
+      if (resolved) {
+        learnerId = resolved.learnerId;
+        scopes = resolved.scopes;
+      }
+    }
+    if (tool.requiredScope) {
+      if (!scopes?.includes(tool.requiredScope)) {
+        return fail(body.id, -32001, `Missing required scope: ${tool.requiredScope}`);
+      }
+    }
+
+    const ctx: McpContext = { request, learnerId, scopes };
+    try {
+      const result = await tool.handler(params?.arguments ?? {}, ctx);
+      return ok(body.id, result);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return fail(body.id, -32603, "Tool execution failed.", { message });
+    }
+  }
+
+  return fail(body.id, -32601, `Unknown method: ${body.method}`);
+}

package/src/server/mcp/tools.ts

@@ -0,0 +1,175 @@
+import { eq } from "drizzle-orm";
+import {
+  getStep,
+  getStepsForTutorial,
+  getTutorialBySlug,
+  getTutorials,
+  parseStepId,
+} from "../../lib/content.ts";
+import { getDb } from "../db/client.ts";
+import { progressEntries } from "../db/schema.ts";
+import { type McpTool, text } from "./protocol.ts";
+import { progressWriteTools, verificationTools } from "./writeTools.ts";
+
+/**
+ * Pull the first <Checkpoint label="…"> from a step body so the
+ * agent can surface the prose criterion when there's no machine-
+ * verifiable spec to run. Returns undefined when no Checkpoint or
+ * no label attribute is present.
+ */
+function extractCheckpointLabel(body: string): string | undefined {
+  const m = /<Checkpoint\b[^>]*\blabel\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})/.exec(body);
+  if (!m) return undefined;
+  return m[1] ?? m[2] ?? m[3];
+}
+
+/**
+ * Catalog read tools. No auth required beyond a valid bearer token —
+ * agents browsing what's available before deciding which tutorial to
+ * help with don't need progress:read.
+ */
+export const catalogReadTools: McpTool[] = [
+  {
+    name: "list_tutorials",
+    description: "List every tutorial published on this Handzon site.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => {
+      const tutorials = await getTutorials();
+      const rows = tutorials.map((t) => ({
+        slug: t.id,
+        title: t.data.title,
+        description: t.data.description,
+        difficulty: t.data.difficulty,
+        tags: t.data.tags,
+      }));
+      return text(JSON.stringify({ tutorials: rows }, null, 2));
+    },
+  },
+  {
+    name: "get_tutorial",
+    description:
+      "Return tutorial metadata + ordered step outline (slug, title, duration) for one tutorial.",
+    inputSchema: {
+      type: "object",
+      properties: { slug: { type: "string", minLength: 1 } },
+      required: ["slug"],
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const { slug } = args as { slug: string };
+      const tutorial = await getTutorialBySlug(slug);
+      if (!tutorial) {
+        return {
+          content: [{ type: "text", text: `No tutorial with slug "${slug}".` }],
+          isError: true,
+        };
+      }
+      const steps = await getStepsForTutorial(slug);
+      const payload = {
+        slug: tutorial.id,
+        title: tutorial.data.title,
+        description: tutorial.data.description,
+        difficulty: tutorial.data.difficulty,
+        tags: tutorial.data.tags,
+        gated: tutorial.data.gated,
+        steps: steps.map((s) => {
+          const { stepSlug, order } = parseStepId(s.id);
+          return {
+            slug: stepSlug,
+            order,
+            title: s.data.title,
+            summary: s.data.summary,
+            duration: s.data.duration,
+          };
+        }),
+      };
+      return text(JSON.stringify(payload, null, 2));
+    },
+  },
+  {
+    name: "get_step",
+    description: "Return one step's full Markdown source + metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step"],
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const { tutorial, step } = args as { tutorial: string; step: string };
+      const tut = await getTutorialBySlug(tutorial);
+      if (!tut) {
+        return {
+          content: [{ type: "text", text: `No tutorial with slug "${tutorial}".` }],
+          isError: true,
+        };
+      }
+      const stepEntry = await getStep(tutorial, step);
+      if (!stepEntry) {
+        return {
+          content: [{ type: "text", text: `No step "${step}" in "${tutorial}".` }],
+          isError: true,
+        };
+      }
+      const { stepSlug, order } = parseStepId(stepEntry.id);
+      const body = stepEntry.body ?? "";
+      const verifySpec = (stepEntry.data as { verify?: unknown }).verify;
+      const payload = {
+        tutorial,
+        slug: stepSlug,
+        order,
+        title: stepEntry.data.title,
+        summary: stepEntry.data.summary,
+        duration: stepEntry.data.duration,
+        source: body,
+        verify: verifySpec ?? null,
+        // Prose-fallback: when no verify block is declared, surface the
+        // <Checkpoint label="…"> text so the agent can self-attest the
+        // criterion before calling complete_checkpoint.
+        checkpointCriterion: verifySpec ? null : (extractCheckpointLabel(body) ?? null),
+      };
+      return text(JSON.stringify(payload, null, 2));
+    },
+  },
+];
+
+/**
+ * Authenticated read tools. Available to any valid bearer token (no
+ * `requiredScope` because reading your own progress is implicit in
+ * holding a PAT for the account).
+ */
+export const progressReadTools: McpTool[] = [
+  {
+    name: "get_progress",
+    description: "Return every progress entry for the authenticated learner.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async (_args, ctx) => {
+      if (!ctx.learnerId) {
+        return {
+          content: [{ type: "text", text: "No resolved learner — bearer token required." }],
+          isError: true,
+        };
+      }
+      const db = getDb();
+      const rows = await db
+        .select()
+        .from(progressEntries)
+        .where(eq(progressEntries.learnerId, ctx.learnerId));
+      return text(JSON.stringify({ entries: rows }, null, 2));
+    },
+  },
+];
+
+/**
+ * Default tool bundle the scaffold mounts. Order matters for the
+ * tools/list response — clients usually surface them in array order.
+ */
+export const defaultTools: McpTool[] = [
+  ...catalogReadTools,
+  ...progressReadTools,
+  ...progressWriteTools,
+  ...verificationTools,
+];