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>

packages/core/test/app.test.ts

@@ -97,5 +97,13 @@ test("canView matrix", async () => {
   const pub = ctx.courses.get("sample")!, priv = ctx.courses.get("secret")!;
   expect(canView(null, pub, [])).toBe(true);
   expect(canView(null, priv, [])).toBe(false);
+  const u = (roles: AuthUser["roles"], groups: string[] = []): AuthUser => ({ id: "u1", email: "u@x", name: "U", roles, groups });
+  expect(canView(u(["learner"]), priv, [])).toBe(false);
+  expect(canView(u(["owner"]), priv, [])).toBe(true);
+  expect(canView(u(["author"]), priv, [])).toBe(true); // R14: the global author role views every course
+  expect(canView(u(["learner"]), priv, [], true)).toBe(true); // per-course author
+  expect(canView(u(["learner"]), priv, [{ principal_type: "user", principal_id: "u1" }])).toBe(true);
+  expect(canView(u(["learner"], ["g"]), priv, [{ principal_type: "group", principal_id: "g" }])).toBe(true);
+  expect(canView(u(["learner"], ["h"]), priv, [{ principal_type: "group", principal_id: "g" }])).toBe(false);
   await db.close();
 });

packages/core/test/compose.test.ts

@@ -0,0 +1,51 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import type { AuthUser, Feature, ServerContext } from "@stc/contracts";
+import { composeServer, resolveConfig } from "../src";
+
+const FIXTURES = resolve(import.meta.dir, "../../../fixtures/courses");
+const config = () => resolveConfig({ dataDir: mkdtempSync(join(tmpdir(), "stc-compose-")), databaseUrl: "sqlite://:memory:", courseDirs: [FIXTURES] });
+
+test("factories get the context; the queue is built from the union of their jobs; auth and stop are honoured", async () => {
+  const seen: string[] = [];
+  let stopped = 0;
+  const user: AuthUser = { id: "u", email: "u@x", name: "U", roles: ["owner"], groups: [] };
+  let early: unknown = null;
+  const a = (ctx: ServerContext): Feature => {
+    // the handle exists while factories run, but enqueuing must wait for the real queue
+    try { void ctx.jobs.enqueue("b.work", {}); } catch (e) { early = e; }
+    return {
+      name: "a",
+      routes: { "/api/a": { GET: async (_r, rc) => Response.json({ who: rc.user?.id ?? null, courses: ctx.courses.list().length }) } },
+      jobs: { "a.work": async (p) => { seen.push(`a:${JSON.stringify(p)}`); return null; } },
+      auth: { userFromRequest: async () => user },
+      stop: () => { stopped++; },
+    };
+  };
+  const b = (ctx: ServerContext): Feature => ({
+    name: "b",
+    routes: { "/api/b": { POST: async () => Response.json({ id: await ctx.jobs.enqueue("a.work", { n: 1 }) }) } },
+    jobs: { "b.work": async () => null },
+  });
+  const s = await composeServer(config(), [a, b]);
+  try {
+    expect(String(early)).toMatch(/not ready/);
+    expect(await (await s.app.fetch(new Request("http://x/api/a"))).json()).toEqual({ who: "u", courses: 1 });
+    const { id } = (await (await s.app.fetch(new Request("http://x/api/b", { method: "POST" }))).json()) as { id: string };
+    for (let i = 0; i < 200 && (await s.ctx.jobs.get(id))?.status !== "done"; i++) await Bun.sleep(10);
+    expect((await s.ctx.jobs.get(id))?.status).toBe("done");
+    expect(seen).toEqual(['a:{"n":1}']);
+  } finally {
+    await s.stop();
+  }
+  expect(stopped).toBe(1);
+});
+
+test("duplicate job kinds and two auth services are refused", async () => {
+  const f = (name: string, extra: Partial<Feature>) => (): Feature => ({ name, routes: {}, ...extra });
+  await expect(composeServer(config(), [f("x", { jobs: { k: async () => null } }), f("y", { jobs: { k: async () => null } })])).rejects.toThrow(/Duplicate job kind "k"/);
+  const auth = { userFromRequest: async () => null };
+  await expect(composeServer(config(), [f("x", { auth }), f("y", { auth })])).rejects.toThrow(/AuthService/);
+});

packages/core/test/config.test.ts

@@ -1,5 +1,6 @@
 import { expect, test, spyOn } from "bun:test";
-import { loadConfig } from "../src";
+import { resolve } from "node:path";
+import { cachePaths, loadConfig, resolveConfig } from "../src";
 
 test("defaults", () => {
   const warn = spyOn(console, "warn").mockImplementation(() => {});
@@ -7,21 +8,59 @@ test("defaults", () => {
   expect(c.port).toBe(3000);
   expect(c.databaseUrl).toBe("sqlite://./data/stcourses.db");
   expect(c.dataDir).toBe("./data");
-  expect(c.courseDirs).toEqual(["./overlays", "./courses"]);
+  // configured dirs first, then the importer's folders and the studio's published worktrees
+  expect(c.courseDirs).toEqual(["./overlays", "./courses", resolve("./data/courses"), resolve("./data/worktrees")]);
+  expect(c.importedCoursesDir).toBe(resolve("./data/courses"));
+  expect(c.studioReposDir).toBe(resolve("./data/studio/repos"));
+  expect(c.studioWorktreesDir).toBe(resolve("./data/worktrees"));
+  expect(c.cacheDir).toBe(resolve("./data/cache"));
+  expect(c.importRoots).toEqual([resolve("./data/import-inbox")]);
+  expect(c.uploadMaxMb).toBe(100);
+  expect(c.aiAllowedBaseUrls).toEqual([]);
+  expect(c.transcribeUrl).toBeNull();
+  expect(c.python).toBe("python3");
   expect(c.publicUrl).toBe("http://localhost:3000");
   expect(warn).toHaveBeenCalledTimes(1);
   warn.mockRestore();
 });
 
 test("colon splitting and overrides", () => {
-  const c = loadConfig({ STC_PORT: "8080", STC_COURSE_DIRS: "/a b:/c", STC_SECRET: "s", STC_PUBLIC_URL: "https://x.test" });
+  const c = loadConfig({
+    STC_PORT: "8080", STC_COURSE_DIRS: "/a b:/c", STC_SECRET: "s", STC_PUBLIC_URL: "https://x.test", STC_DATA_DIR: "/d",
+    STC_IMPORT_ROOTS: "/in box:/other", STC_UPLOAD_MAX_MB: "5", STC_AI_ALLOWED_BASE_URLS: "http://gw.lan:8080, https://x.test",
+    STC_TRANSCRIBE_URL: "http://whisper.lan/v1/audio/transcriptions", STC_PYTHON: "/opt/py/bin/python",
+  });
   expect(c.port).toBe(8080);
-  expect(c.courseDirs).toEqual(["/a b", "/c"]);
+  expect(c.courseDirs).toEqual(["/a b", "/c", "/d/courses", "/d/worktrees"]);
   expect(c.secret).toBe("s");
   expect(c.publicUrl).toBe("https://x.test");
+  expect(c.importRoots).toEqual(["/in box", "/other"]);
+  expect(c.uploadMaxMb).toBe(5);
+  expect(c.aiAllowedBaseUrls).toEqual(["http://gw.lan:8080", "https://x.test"]);
+  expect(c.transcribeUrl).toBe("http://whisper.lan/v1/audio/transcriptions");
+  expect(c.python).toBe("/opt/py/bin/python");
+});
+
+test("configured dirs that already name the derived dirs are not repeated", () => {
+  const c = loadConfig({ STC_SECRET: "s", STC_DATA_DIR: "/d", STC_COURSE_DIRS: "/d/courses:/x" });
+  expect(c.courseDirs).toEqual(["/d/courses", "/x", "/d/worktrees"]);
+  expect(resolveConfig({ dataDir: "/d", courseDirs: ["/d/worktrees/"] }).courseDirs).toEqual(["/d/worktrees/", "/d/courses"]);
+});
+
+test("invalid upload cap throws", () => {
+  expect(() => loadConfig({ STC_SECRET: "s", STC_UPLOAD_MAX_MB: "lots" })).toThrow(/STC_UPLOAD_MAX_MB/);
 });
 
 test("production without a secret throws", () => {
   expect(() => loadConfig({ NODE_ENV: "production" })).toThrow(/STC_SECRET/);
   expect(loadConfig({ NODE_ENV: "production", STC_SECRET: "x" }).secret).toBe("x");
 });
+
+test("cachePaths: the importer's layout, no escaping segments", () => {
+  const p = cachePaths({ cacheDir: "/d/cache" });
+  expect(p.deckDir("c", "deck1")).toBe("/d/cache/decks/c/deck1");
+  expect(p.coversDir("c")).toBe("/d/cache/covers/c");
+  expect(p.transcriptFile("c", "m1-l1")).toBe("/d/cache/transcripts/c/m1-l1.json");
+  expect(() => p.coversDir("..")).toThrow();
+  expect(() => p.deckDir("c", "a/b")).toThrow();
+});

packages/core/test/media.test.ts

@@ -57,3 +57,36 @@ test("non-ASCII filename gets a valid filename*", async () => {
 test("missing file is 404", async () => {
   expect((await serveMedia(req(), join(dir, "nope.mp4"))).status).toBe(404);
 });
+
+test("every response is nosniff; script-capable types get a sandbox CSP", async () => {
+  const d = mkdtempSync(join(tmpdir(), "stc-media-csp-"));
+  const { MEDIA_SANDBOX_CSP } = await import("../src");
+  for (const [name, body, sandboxed] of [
+    ["x.svg", "<svg xmlns='http://www.w3.org/2000/svg'><script>alert(1)</script></svg>", true],
+    ["page.html", "<script>alert(1)</script>", true],
+    ["Page.HTM", "<p>x</p>", true],
+    ["code.js", "alert(1)", true],
+    ["mod.mjs", "export {}", true],
+    ["notes.md", "# hi", false],
+    ["clip.mp4", "x", false],
+  ] as const) {
+    writeFileSync(join(d, name), body);
+    for (const r of [await serveMedia(req(), join(d, name)), await serveMedia(req("bytes=0-0"), join(d, name))]) {
+      expect(r.headers.get("x-content-type-options")).toBe("nosniff");
+      expect([name, r.headers.get("content-security-policy")]).toEqual([name, sandboxed ? MEDIA_SANDBOX_CSP : null]);
+    }
+  }
+  expect(MEDIA_SANDBOX_CSP).toMatch(/^sandbox;/);
+  expect(MEDIA_SANDBOX_CSP).not.toContain("allow-scripts");
+});
+
+test("a range on an empty file is 416, never a negative Content-Range", async () => {
+  const d = mkdtempSync(join(tmpdir(), "stc-media-empty-"));
+  writeFileSync(join(d, "empty.txt"), "");
+  for (const range of ["bytes=0-", "bytes=-5", "bytes=0-0"]) {
+    const r = await serveMedia(req(range), join(d, "empty.txt"));
+    expect(r.status).toBe(416);
+    expect(r.headers.get("content-range")).toBe("bytes */0");
+  }
+  expect((await serveMedia(req(), join(d, "empty.txt"))).status).toBe(200);
+});