Michael ColeandClaude Opus 4.8
63df38105d
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>
60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# ditto.site Compiler
|
|
|
|
This workspace contains the deterministic compiler used by ditto.site. It captures
|
|
a source URL, builds a render IR, infers assets/fonts/tokens/sections/recipes/SEO,
|
|
generates a Next.js App Router app by default or a Vite React app on request, and
|
|
validates the result with deterministic gates.
|
|
|
|
The full architecture overview lives in [../README.md](../README.md). This file
|
|
keeps only compiler-local commands and notes.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
cd compiler
|
|
npm install
|
|
npx playwright install chromium
|
|
|
|
npm run clone -- https://example.com/
|
|
npm run clone -- https://example.com/ --serve # then npm install + npm run dev
|
|
npm run clone -- https://example.com/ --open # ...and open the browser too
|
|
npm run clone -- https://example.com/ --mode=multi --styling=tailwind
|
|
npm run clone -- https://example.com/ --mode=single --framework=vite
|
|
npm run clone-site -- https://example.com/
|
|
npm run validate-site -- ../runs/site-example.com/<timestamp>
|
|
npm run clone -- https://example.com/ --mode=multi --concurrency=5
|
|
npm run clone -- https://example.com/ --mode=multi --validate --validate-concurrency=3 --viewport-concurrency=2
|
|
npm run validate-site -- ../runs/site-example.com/<timestamp> --validate-concurrency=3 --viewport-concurrency=2
|
|
npm run bench -- --tier=easy
|
|
npm run bench-site
|
|
npm run quality -- ../runs/example.com/<timestamp>
|
|
npm run audit -- ../runs/example.com/<timestamp>
|
|
npm test
|
|
npm run typecheck
|
|
```
|
|
|
|
Root-level scripts forward to these commands, so `npm run clone -- <url>` works
|
|
from the repository root too.
|
|
|
|
("Clone" here = generating a codebase from a live URL, not `git clone`; no source
|
|
repo required.) On success the CLI prints a copy-paste-safe summary: a single
|
|
quoted `cd … && npm install && npm run dev` line plus safe-to-edit pointers. Pass
|
|
`--serve` to run install + dev automatically, or `--open` to also launch the
|
|
browser. Without `--out`, a `runs/<site>/latest` symlink always points at the
|
|
newest run so paths aren't timestamp-fragile.
|
|
|
|
Multi-page generation defaults to the fast no-validation path. Use `--validate`
|
|
when the clone command itself should run the full build/render/gates QA pass, or
|
|
run `validate-site` separately. `--concurrency` controls source route capture;
|
|
`--validate-concurrency` controls how many routes validation grades at once; and
|
|
`--viewport-concurrency` controls how many clone viewports each route renders at
|
|
once.
|
|
|
|
## Generated App Shape
|
|
|
|
Default Next generated apps use `src/app/ditto.css` and optional helpers under
|
|
`src/app/ditto/`. Vite generated apps use `src/ditto.css` and optional helpers
|
|
under `src/ditto/`, with multi-route pages under `src/routes/`. Validation builds
|
|
keep `data-cid` attributes for source/clone alignment; delivered apps strip those
|
|
validation ids and keep only required `data-ditto-id` anchors.
|