- Media exclusions move from the editable root .gitignore to the repo's
info/exclude, and dirtyFiles never counts files listed in media.json, so an
author's or remote's .gitignore cannot block publish or Sync. Publish and
Sync refuse commits that track a file over referenced media.
- Importer jobs (code-repo, pdf-deck, transcribe) and the cover route run
under the course lock now shared with the studio (core withCourseLock) and
re-check the course inside it; after conversion they fail with "this course
is now edited in the studio". Convert answers 409 while an import job for
the course is queued or running, and the job re-checks.
- Crash-safe conversion: the import folder is hidden (.converting-<id>) before
the published worktree exists; cross-filesystem moves copy into a staging
dir, fsync, verify size and sha256, then rename; the source is retired as
.converted-<id>.<n>. Recovery runs at server start and before every convert;
a re-run of a finished conversion reports success. The loader skips
dot-folders.
- Minor: no raw NUL bytes in source, link fallback only on EXDEV/EPERM/EMLINK,
referenced media are not read whole by the editor, missing media are logged,
mediaDir JSDoc, docs on per-author copies across filesystems.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Owner sees what conversion does, starts it, follows progress and lands in the
workbench; other authors are told only the owner can. Existing tokens only.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
POST /api/studio/courses/:id/convert (owner only, CSRF-guarded by core) queues
studio.convert-import; GET /api/studio/jobs/:id reports progress. Read-only
responses say whether the caller may convert. Resolves TODO(studio) (ruling R9).
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Small files are committed unchanged (visibility and source.kind stay); large media
are referenced from .stcourses/media.json, ignored, and hard-linked into every
worktree from <dataDir>/media/<id>, where the import folder is moved. Studio writes
to referenced media are refused and never write through a shared inode.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Critical 1 (CSRF): core wrap refuses every POST/PUT/PATCH/DELETE whose Origin
(Referer as fallback) is not publicUrl's origin or STC_ALLOWED_ORIGINS, and
any body that is not application/json (multipart only on declared upload
routes). Better Auth routes go through the same guard; only declared
identity-provider callbacks (SAML ACS/SLO, OAuth callbacks) are exempt.
Better Auth trustedOrigins use the same list. Session cookie stays Lax
(Strict breaks OAuth/OIDC/SAML returns); documented.
- Important 4 / learner minor 4: the first-owner claim and the role row are
one transaction guarded by "no owner yet"; only a unique violation means
learner; any other error fails the sign-up with 500 and removes the
half-created user. Serialised per DB handle (Bun's SQLite connection).
- Important 2 / learner minor 12: code zips stream entry by entry (large
files stored in 256 KB chunks with a data descriptor and incremental
CRC-32), so memory stays at one chunk; the cap is now 1 GiB (ZIP32).
- Important 3 / learner minor 10: the e2e runs the production wiring
(productFeatures order, AI drafts through the real sink) against a
restricted course and asserts 404/401 for learner and anonymous on
course, lesson, media, cover, code, zip, notes, progress, attempts, AI
chat, library, search and AI status; a real Range request (206, 416);
forged writes (foreign Origin, text/plain, no Origin) are 403 and the MCP
test command never runs.
- Minors 7-9: compose passes every documented variable; the health check
uses STC_PORT; productFeatures checks the studio-before-AI order.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
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 <[email protected]>
C1: writes lstat every path component and refuse symlinks (dangling included),
check the parent's real path after mkdir, and open with O_NOFOLLOW.
I1: only https://, ssh:// and git@host: remotes; protocol.file/ext/fd=never on
every fetch and push; global/system git config ignored.
I2: STC_UPLOAD_MAX_MB cap (default 100) by Content-Length and while streaming;
extension allowlist (415); stcourse.yaml refused; 409 unless overwrite=true;
sandboxing CSP on draft raw files.
I3: owner-only visibility/source.kind rule checked on the merged result at
publish and sync, and at resolve; publish also validates the merged tree.
I4: bare repos in <dataDir>/studio/repos/<id>.git; imported courses read-only.
I5: list status comes from the bare repo; drafts are created lazily.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
