feat: resolve Phase 1 contract requests and compose every feature

Contracts and core:
- Feature gains auth and stop; FeatureFactory; core composeServer builds the
  context, runs the factories, then the job queue from the union of their jobs
  (R8/R14). startServer uses it; main.ts composes learner, import, studio, AI.
- AppConfig/loadConfig own the layout and settings: courseDirs include
  <dataDir>/courses and <dataDir>/worktrees, studioReposDir, cacheDir,
  importRoots, uploadMaxMb, aiAllowedBaseUrls, transcribeUrl, python.
  resolveConfig derives the same for tests; cachePaths shares the importer's
  cache layout.
- canView: the global author role views every course (R14); the learner,
  studio and AI packages all call it.
- migrate(db, packages): core first, then packages in name order.
- Media: nosniff on every response, a sandbox CSP on svg/html/js; a Range on
  an empty file is 416.
- courseUrl/lessonUrl and the lesson route patterns live in @stc/contracts.

Packages:
- import, studio and AI read AppConfig instead of process.env; the importer
  refuses ids used by studio/repos.
- learner migrations run through core migrate; library covers fall back to
  the importer's cached candidate behind a canView-checked route.
- studio preview renders through the learner LessonView (anchors honoured,
  draft URLs); AI drafts go to the studio draft branch for studio courses (as
  the requesting user) and to <dataDir>/drafts otherwise, and the generator
  page says which.

Web: tsconfig paths for @stc/<feature>/web browser entries; features.ts
imports them by package name; nav.roles hides links by role.

Tests: compose, config, canView, media headers, migrations order, covers,
preview, nav, SPA bundle without server code, and an end-to-end flow on
SQLite and Postgres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apps/server/src/features.ts

@@ -0,0 +1,44 @@
+import type { FeatureFactory, ServerContext } from "@stc/contracts";
+import type { PackageMigrations } from "@stc/db";
+import { aiFeature, createFsDraftSink, migrationsDirs as aiMigrations, type DraftSink } from "@stc/feature-ai";
+import { importFeature, migrationsDirs as importMigrations } from "@stc/feature-import";
+import { learnerFeature, migrationsDirs as learnerMigrations, userIdentity } from "@stc/feature-learner";
+import { createDraftWriter, migrationsDirs as studioMigrations, studioFeature, type StudioFeature } from "@stc/feature-studio";
+
+/** Every package's migration folders, keyed by package name (core runs first, then these in name order). */
+export const packageMigrations: PackageMigrations = {
+  "feature-ai": aiMigrations,
+  "feature-import": importMigrations,
+  "feature-learner": learnerMigrations,
+  "feature-studio": studioMigrations,
+};
+
+/**
+ * Where the AI generator writes drafts: studio-managed courses get a commit on the requesting author's
+ * `draft/<userId>` branch, authored as that user's name and email; overlay and imported courses (which the studio
+ * does not manage) fall back to files under `<dataDir>/drafts/<courseId>/<run>/`. The generator page says which.
+ */
+export function aiDraftSink(ctx: ServerContext, studio: Pick<StudioFeature, "store">): DraftSink {
+  const writer = createDraftWriter(ctx, { identity: (userId) => userIdentity(ctx.db, userId) });
+  const files = createFsDraftSink(ctx.config.dataDir);
+  return {
+    writeDraftFiles: (courseId, authorId, list, message) =>
+      (studio.store.isManaged(courseId) ? writer : files).writeDraftFiles(courseId, authorId, list, message),
+  };
+}
+
+export interface FeatureSetOptions {
+  /** Studio published-worktree polling (default on). */
+  studioWatch?: boolean;
+}
+
+/** The product: learner (auth, library, reader), importer, studio and AI, in that order. */
+export function productFeatures(opts: FeatureSetOptions = {}): FeatureFactory[] {
+  let studio: StudioFeature | null = null;
+  return [
+    learnerFeature,
+    (ctx) => importFeature(ctx),
+    (ctx) => (studio = studioFeature(ctx, { watch: opts.studioWatch ?? true })),
+    (ctx) => aiFeature(ctx, { draftSink: aiDraftSink(ctx, studio!) }),
+  ];
+}

apps/server/src/main.ts

@@ -1,62 +1,42 @@
-import type { AppConfig, AuthService, Feature, JobHandler, JobQueue, ServerContext } from "@stc/contracts";
-import { createApp, createJobQueue, loadConfig } from "@stc/core";
-import { createCourseRepository } from "@stc/course-format";
-import { connect, migrate } from "@stc/db";
-import { importFeature } from "@stc/feature-import";
-import { learnerFeature } from "@stc/feature-learner";
-import { resolve } from "node:path";
+import type { AppConfig, Feature, FeatureFactory } from "@stc/contracts";
+import { composeServer, loadConfig, type ComposeOptions } from "@stc/core";
 import indexHtml from "../../web/index.html";
+import { packageMigrations, productFeatures } from "./features";
 
-// Used until a feature supplies an `auth` service (the learner package does).
-const anonymousAuth: AuthService = { userFromRequest: async () => null };
+export interface StartOptions extends ComposeOptions {}
 
-/** A feature, or a factory that needs the server context. A feature may carry the `AuthService`. */
-export type FeatureEntry = (Feature & { auth?: AuthService }) | ((ctx: ServerContext) => Feature & { auth?: AuthService });
-
-export async function startServer(
-  config: AppConfig,
-  features: FeatureEntry[],
-  _webFeatures?: unknown,
-): Promise<{ server: Bun.Server<undefined>; stop(): Promise<void> }> {
-  const db = await connect(config.databaseUrl);
-  await migrate(db);
-  const courses = await createCourseRepository(config.courseDirs);
-  const handlers: Record<string, JobHandler> = {};
-  // Factories get the context before the job queue exists; ctx.jobs is set right after they run.
-  const ctx: ServerContext = { config, db, courses, jobs: null as unknown as JobQueue, auth: anonymousAuth };
-  const built = features.map((f) => (typeof f === "function" ? f(ctx) : f));
-  for (const f of built) {
-    Object.assign(handlers, f.jobs);
-    if (f.auth) ctx.auth = f.auth;
+/**
+ * Composes the features (core `composeServer`) and serves them with the SPA. Bun routes win over `fetch`;
+ * "/api/*" falls through to the composed app, so unknown API paths are 404 rather than the SPA.
+ */
+export async function startServer(config: AppConfig, features: (Feature | FeatureFactory)[], opts: StartOptions = {}) {
+  const composed = await composeServer(config, features, opts);
+  const { app } = composed;
+  let server: Bun.Server<undefined>;
+  try {
+    server = Bun.serve({
+      port: config.port,
+      routes: { ...app.routes, "/api/*": (req) => app.fetch(req), "/*": indexHtml },
+      fetch: (req) => app.fetch(req),
+      // Production (NODE_ENV=production, as in the Docker image) bundles the SPA once, minified, without HMR.
+      development: process.env.NODE_ENV !== "production",
+    });
+  } catch (e) {
+    await composed.stop();
+    throw e;
   }
-  const jobs = createJobQueue(db, handlers);
-  ctx.jobs = jobs;
-  const app = createApp(ctx, built);
-  jobs.start();
-  const server = Bun.serve({
-    port: config.port,
-    // Bun routes win over fetch; "/api/*" falls through to the composed app (404 for unknown API paths).
-    routes: { ...app.routes, "/api/*": (req) => app.fetch(req), "/*": indexHtml },
-    fetch: (req) => app.fetch(req),
-  });
   return {
     server,
+    ctx: composed.ctx,
     async stop() {
       await server.stop(true);
-      await jobs.stop();
-      await db.close();
+      await composed.stop();
     },
   };
 }
 
 if (import.meta.main) {
   const config = loadConfig();
-  // Contract request (import.md): core config should include <dataDir>/courses itself.
-  const generated = resolve(config.dataDir, "courses");
-  if (!config.courseDirs.some((c) => resolve(c) === generated)) config.courseDirs.push(generated);
-  const { server } = await startServer(config, [
-    learnerFeature,
-    (ctx) => importFeature(ctx),
-  ]);
+  const { server } = await startServer(config, productFeatures(), { migrations: packageMigrations });
   console.log(`STCourses listening on ${server.url}`);
 }

apps/server/test/e2e.test.ts

@@ -0,0 +1,117 @@
+// End-to-end (plan Task I3): the real server with every feature, against the fixtures, on SQLite and Postgres.
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { loadConfig } from "@stc/core";
+import { studioFeature } from "@stc/feature-studio";
+import { createBrowserRunner } from "../../../packages/feature-learner/src/web/runner/runner";
+import { aiDraftSink, packageMigrations, productFeatures } from "../src/features";
+import { startServer } from "../src/main";
+import { PG, pgSchema } from "./pg";
+
+const FIXTURES = resolve(import.meta.dir, "../../../fixtures/courses");
+const ORIGIN = "http://localhost:3000";
+
+const cookieFrom = (r: Response) => r.headers.getSetCookie().map((c) => c.split(";")[0]).filter((c) => !c.endsWith("=")).join("; ");
+
+async function run(databaseUrl: string) {
+  const dataDir = mkdtempSync(join(tmpdir(), "stc-e2e-"));
+  const config = loadConfig({
+    STC_PORT: "0", STC_DATABASE_URL: databaseUrl, STC_SECRET: "e2e-secret-0123456789abcdef0123456789",
+    STC_DATA_DIR: dataDir, STC_COURSE_DIRS: FIXTURES, STC_PUBLIC_URL: ORIGIN,
+  });
+  const s = await startServer(config, productFeatures({ studioWatch: false }), { migrations: packageMigrations });
+  const base = s.server.url.toString().replace(/\/$/, "");
+  const call = async (method: string, path: string, opts: { cookie?: string; body?: unknown } = {}) => {
+    const headers: Record<string, string> = { origin: ORIGIN };
+    if (opts.cookie) headers.cookie = opts.cookie;
+    if (opts.body !== undefined) headers["content-type"] = "application/json";
+    return fetch(base + path, { method, headers, body: opts.body === undefined ? undefined : JSON.stringify(opts.body) });
+  };
+  const signUp = async (email: string, name: string) => {
+    const r = await call("POST", "/api/auth/sign-up/email", { body: { email, name, password: "correct horse battery" } });
+    expect(r.status).toBe(200);
+    return cookieFrom(r);
+  };
+  try {
+    // 1. the server is up with every feature and the fixture course
+    expect(await (await call("GET", "/api/health")).json()).toEqual({ ok: true, courses: 1, db: databaseUrl.startsWith("postgres") ? "postgres" : "sqlite" });
+    expect((await call("GET", "/c/sample")).headers.get("content-type")).toContain("text/html");
+
+    // 2. sign up: the first account is the owner
+    const owner = await signUp("ada@example.org", "Ada Lovelace");
+    const me = (await (await call("GET", "/api/me", { cookie: owner })).json()) as { user: { id: string; roles: string[] } };
+    expect(me.user.roles).toContain("owner");
+
+    // 3. mark a lesson done
+    expect((await call("PUT", "/api/courses/sample/progress/m1-intro", { cookie: owner, body: { state: "done" } })).status).toBe(200);
+
+    // 4. a slide note on the video lesson's deck
+    const note = await call("POST", "/api/courses/sample/notes", { cookie: owner, body: { lessonId: "m1-video", anchorKind: "slide", anchorValue: 2, deckId: "d1", body: "Slide two matters" } });
+    expect(note.status).toBe(201);
+
+    // 5. run the sample exercise with the learner's runner, then save the passing attempt
+    const lesson = (await (await call("GET", "/api/courses/sample/lessons/m2-ex-add", { cookie: owner })).json()) as { browser: { starter: string; tests: string } };
+    const runner = createBrowserRunner("js");
+    const failing = await runner.run(lesson.browser.starter, lesson.browser.tests, 5000);
+    expect(failing.some((t) => !t.passed)).toBe(true);
+    const code = lesson.browser.starter.replace("a - b", "a + b");
+    const results = await runner.run(code, lesson.browser.tests, 5000);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((t) => t.passed)).toBe(true);
+    expect((await call("PUT", "/api/courses/sample/lessons/m2-ex-add/attempt", { cookie: owner, body: { code, passed: true, result: results, track: "js" } })).status).toBe(200);
+
+    // 6. read progress and notes back
+    const progress = (await (await call("GET", "/api/courses/sample/progress", { cookie: owner })).json()) as Record<string, { state: string }>;
+    expect(progress["m1-intro"]?.state).toBe("done");
+    expect(progress["m2-ex-add"]?.state).toBe("done");
+    const notes = (await (await call("GET", "/api/courses/sample/notes", { cookie: owner })).json()) as { body: string; anchorKind: string; deckId: string }[];
+    expect(notes.map((n) => [n.body, n.anchorKind, n.deckId])).toEqual([["Slide two matters", "slide", "d1"]]);
+
+    // 7. a second account is a plain learner: own data only, and the owner/author features refuse it
+    const lea = await signUp("lea@example.org", "Lea");
+    expect(await (await call("GET", "/api/courses/sample/progress", { cookie: lea })).json()).toEqual({});
+    expect((await call("GET", "/api/import/info", { cookie: lea })).status).toBe(403);
+    expect((await call("GET", "/api/studio/courses", { cookie: lea })).status).toBe(403);
+    expect((await call("GET", "/api/ai/admin/config", { cookie: lea })).status).toBe(403);
+    expect((await call("GET", "/api/import/info", { cookie: owner })).status).toBe(200);
+    expect((await call("GET", "/api/studio/courses", { cookie: owner })).status).toBe(200);
+    expect((await call("GET", "/api/ai/status", { cookie: owner })).status).toBe(200);
+
+    // 8. media: Range, nosniff
+    const clip = await call("GET", "/api/media/sample/media/clip.mp4", { cookie: lea });
+    expect(clip.headers.get("x-content-type-options")).toBe("nosniff");
+
+    // 9. the AI draft sink: studio-managed course -> the author's draft branch, as that user; other courses -> files
+    const studio = studioFeature(s.ctx, { watch: false });
+    try {
+      await studio.store.createCourse({ id: "gen-target", title: "Generated" }, { name: "Ada Lovelace", email: "ada@example.org" });
+      const sink = aiDraftSink(s.ctx, studio);
+      const onStudio = await sink.writeDraftFiles("gen-target", me.user.id, [{ path: "lessons/q.md", content: "# Q\n" }], "AI draft");
+      expect(onStudio.branch).toMatch(/^draft\//);
+      const repo = join(config.studioReposDir, "gen-target.git");
+      const author = (await Bun.$`git --git-dir=${repo} log -1 ${"--format=%an <%ae>"} ${onStudio.branch!}`.text()).trim();
+      expect(author).toBe("Ada Lovelace <ada@example.org>");
+      const onFiles = await sink.writeDraftFiles("sample", me.user.id, [{ path: "q.md", content: "# Q\n" }], "AI draft");
+      expect(onFiles.branch).toBeUndefined();
+      expect(onFiles.location!.startsWith(resolve(dataDir, "drafts", "sample"))).toBe(true);
+      expect(readFileSync(join(onFiles.location!, "q.md"), "utf8")).toBe("# Q\n");
+    } finally {
+      studio.stop();
+    }
+  } finally {
+    await s.stop();
+  }
+}
+
+describe("end to end", () => {
+  test("sign up, mark done, slide note, exercise, progress [sqlite]", () => run("sqlite://:memory:"), 60_000);
+  const pg = PG;
+  if (pg) {
+    test("sign up, mark done, slide note, exercise, progress [postgres]", async () => {
+      const { url, drop } = await pgSchema(pg);
+      try { await run(url); } finally { await drop(); }
+    }, 60_000);
+  }
+});

apps/server/test/pg.ts

@@ -0,0 +1,13 @@
+import { connect } from "@stc/db";
+
+export const PG = process.env.STC_TEST_PG_URL;
+
+/** A fresh Postgres schema (search_path in the URL), dropped by `drop()`. Same isolation as packages/db's forEachDb. */
+export async function pgSchema(base: string): Promise<{ url: string; drop(): Promise<void> }> {
+  const schema = `t_${Bun.randomUUIDv7().replaceAll("-", "")}`;
+  const admin = await connect(base);
+  await admin.sql.unsafe(`CREATE SCHEMA ${schema}`);
+  const u = new URL(base);
+  u.searchParams.set("options", `-c search_path=${schema}`);
+  return { url: u.toString(), drop: async () => { await admin.sql.unsafe(`DROP SCHEMA ${schema} CASCADE`); await admin.close(); } };
+}

apps/server/test/server.test.ts

@@ -1,5 +1,7 @@
 import { afterAll, beforeAll, expect, test } from "bun:test";
-import { resolve } from "node:path";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { loadConfig } from "@stc/core";
 import { startServer } from "../src/main";
 
@@ -7,7 +9,7 @@ let s: Awaited<ReturnType<typeof startServer>>;
 let base: string;
 beforeAll(async () => {
   const config = loadConfig({
-    STC_PORT: "0", STC_DATABASE_URL: "sqlite://:memory:", STC_SECRET: "t",
+    STC_PORT: "0", STC_DATABASE_URL: "sqlite://:memory:", STC_SECRET: "t", STC_DATA_DIR: mkdtempSync(join(tmpdir(), "stc-server-")),
     STC_COURSE_DIRS: resolve(import.meta.dir, "../../../fixtures/courses"),
   });
   s = await startServer(config, []);