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>
2.8 KiB
2.8 KiB
ditto.site Documentation
The central index for ditto.site's docs. Start here.
First, the word "clone." In ditto.site, cloning means generating a codebase from a live URL — it is not
git clone. You do not need an existing Git repository, and you do not need the target site's source code. You give ditto.site a public URL; it captures what the page renders in a browser and writes you a fresh, runnable project. (The onlygit cloneinvolved is optionally cloning this tool's repository to run the compiler locally.)
Get started
| I want to… | Go to |
|---|---|
| Understand what ditto.site is and see it run | Project README |
| Call the hosted REST API or MCP server | Project README → Usage, SERVICE.md |
| Turn a clone result JSON into files on disk | ditto unpack CLI |
| Run the compiler locally from the command line | compiler/README.md |
| Deploy the service | DEPLOY.md |
| Read the development & evaluation method | METHODOLOGY.md |
| Understand responsible-use boundaries | RESPONSIBLE_USE.md |
| Cut a release | RELEASING.md |
API keys are secrets
Keys look like dtto_live_.... Keep them in an environment variable and reference
it in commands:
export DITTO_API_KEY="dtto_live_..."
curl -sS -H "authorization: Bearer $DITTO_API_KEY" "$DITTO_API_URL/v1/clones"
Never paste a raw key inline (it leaks into shell history, logs, and chat), and never commit one. Rotate a leaked key anytime from the dashboard. See SERVICE.md for the full auth model.
The short version of the workflow
- Clone a URL →
POST /v1/clones(API) ornpm run clone -- <url>(local CLI). - Get the app → unpack the result JSON with
ditto unpack, download thebundle?format=tgzarchive, or read files fromruns/<site>/latest/. - Preview it →
cdinto the app andnpm install && npm run dev(or let the local CLI do it for you with--serve/--open). - Edit safely → each generated app ships an
AGENTS.mddescribing what's safe to change (copy insrc/app/content.ts, components insrc/app/components/, etc.).
Full doc list
- SERVICE.md — REST + MCP service reference (endpoints, options, env vars).
- DEPLOY.md — production deployment.
- METHODOLOGY.md — how the compiler is developed and evaluated.
- RESPONSIBLE_USE.md — acceptable-use boundaries.
- RELEASING.md — release process.
- ../compiler/README.md — local compiler commands.
- ../packages/cli/README.md — the
ditto unpackCLI.