The 2026-07-06 prod outage was a missed manual migration: the 0002
job_events migration never ran against prod, so the worker crash-looped
on every job. Make the deploy pipeline own it:
- railway.json sets `npm run db:migrate` as the pre-deploy command.
Railway runs it with the service's env before starting the new
deployment; a failed migration fails the deploy and the old version
keeps serving.
- runMigrations() now serializes on a Postgres advisory lock so api and
worker pre-deploys firing off the same push can't race Drizzle's
journal writes.
- DEPLOY.md: document the automatic path; keep the manual command for
first-time setup.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Audited docs against the fork-salvage API surface (PR #17). SERVICE.md fixes:
- Event stream: events are the compiler's granular {t, ...} log stream plus
service phases, not a fixed capture/generate/verify enum. Corrected the
"{seq, t, ...payload}" claim — returned bodies carry `t` but NOT `seq`.
Documented that `after` is a seq cursor (DB filters seq > N) and that the
in-memory backend ignores `after` and returns the full list each poll.
- preview.html: new Preview section — the flat, self-contained generate-time
artifact (file-map path `preview.html`, manifest `preview_html`, always
present), fetched via /v1/clones/:id/files/preview.html. Documented its
arrival on the `generated` event, relative `public/assets/...` resolution
through the files route, the authenticated-iframe caveat + proxy
recommendation, and the original→preview.html→deployed staging. Stated
plainly that it is static/runtime-free: frozen animations, no interactions.
- Added the `preview` option and clarified app-preview (built export) vs the
flat preview.html.
DEPLOY.md migration list (0000/0001/0002) verified accurate — no change.
README.md / docs/README.md make no stale API claims — no change.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
SERVICE.md documents the /events polling endpoint, the event persistence
model, the in-memory backend's enqueue-202 contract, and the app-preview
route; DEPLOY.md notes the job_events migration and that db:migrate is
journal-tracked/idempotent (with the manual-psql alternative).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A successful clone printed a bare, timestamped app path that wrapped mid-word
in the terminal, so users' `cd` failed and `npm install && npm run dev` ran in
the wrong directory — a confusing failure from a successful clone. Plus there
was no first-party "see it locally" path, no central docs page, "clone" was
conflated with `git clone`, and key hygiene wasn't stated.
CLI (compiler):
- Add compiler/src/cliSummary.ts: a copy-paste-safe success block on stderr — a
single QUOTED `cd "<app>" && npm install && npm run dev` line that survives
terminal wrapping — plus the AGENTS.md safe-to-edit pointers (content.ts,
components/). The machine-readable {"event":"done",...} JSON stays on stdout.
- Add --serve (npm install + npm run dev in the generated app) and --open
(also open the browser at the detected dev URL). Wired into single + multi.
- Add writeLatestPointer(): refresh a runs/<site>/latest symlink to the newest
run so there's a stable, timestamp-free cd/script target. The reuse/regen
scanners already filter to digit-prefixed run dirs, so `latest` is ignored.
- Tests: cliSummary (quoting, single-line command, Next/Vite roots, stable-path
preference, --serve/--open hint) and runsLayout (symlink write + in-place
refresh, timestamp-free stable path).
Docs:
- Add docs/README.md as a central documentation index.
- State prominently that ditto "cloning" = generating a codebase from a live
URL, NOT `git clone` (no source repo required), in README + docs hub.
- Add "keys are secrets: use $DITTO_API_KEY, never inline/commit, rotate
anytime" beside the key/auth examples in README + docs/SERVICE.md.
- Document --serve/--open and the latest symlink in README + compiler/README.
Note: the live ditto.site/docs web route and the dashboard's inline-token
snippet live in the marketing-site repo and still need a change there.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The REST API returns a clone as a giant `files` map JSON blob with no
first-party way to use it — users were left staring at kilobytes of
escaped JSON with no path from "you got JSON" to "here's a project".
Add packages/cli: a zero-dependency `ditto` CLI whose `unpack` command
walks the files{} map from POST /v1/clones (or GET .../result) and
writes a real project tree to disk:
- text files written from inline content;
- binary assets materialized from inline base64, else fetched from their
reference URL using $DITTO_API_URL / $DITTO_API_KEY (--no-fetch writes
just the text tree and lists skipped assets);
- path-traversal guards (clone results are untrusted) and sha256
integrity checks;
- reads JSON from stdin ("-") so a curl response pipes straight in;
- clear errors for queued jobs with no files yet, and a tip pointing at
the /bundle endpoint when assets can't be fetched.
Document the pipe-from-curl one-liner prominently next to the REST
examples in README.md and docs/SERVICE.md, add a package README, a
Repository Map row, a root `unpack` script, and a CHANGELOG entry.
Covered by 9 tests (text tree, stdin, inline base64, live URL fetch with
auth + relative-URL resolution, --no-fetch, traversal refusal, queued-job
detection, sha256 mismatch).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
