aem-eds-kit 0.4.57 → 0.4.60

package/CHANGELOG.md

@@ -29,6 +29,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   Version links point at npm; the GitHub release links never existed.
 
 ### Fixed
+- **`eds draft preview|accept|refine --version` printed the CLI version**
+  (EDS-089) instead of picking a draft version: the program's own `--version`
+  flag won. The version is now an argument (`eds draft preview hero 2`,
+  `eds draft accept hero 1 --branch feature/hero`) and `refine` takes
+  `--from <n>`.
+- **The site has a menu on phones** (EDS-079). Below 720px the nav links were
+  hidden with nothing to bring them back; a menu button (with `aria-expanded`,
+  closing on Esc, a link tap or widening the window) now opens them as a
+  full-width list on every page, with GitHub and npm inside it under 480px,
+  each with its mark (EDS-081).
 - **Scraped designs keep section backgrounds and one-sided lines** (EDS-067).
   A full-width band with no background of its own now carries the colour painted
   behind it (`inheritedBackground`, usually the page background), which the prompt
@@ -50,6 +60,24 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   where the Universal Editor boilerplate actually lives.
 
 ### Added
+- **`--json` event stream** (EDS-087) for `block from-design` and the `draft`
+  commands: one JSON object per line on stdout (`v`, `type`), the usual output
+  on stderr, ending with a `result`. Events: `start`, `log`, `agent` (each tool
+  call), `agent-result` (duration and cost), `draft`, `drafts`, `preview`,
+  `accepted`, `discarded`, `prompt`, `result`. With `--json` nothing prompts,
+  no browser opens, and an agent's own stdout goes to stderr. This is the
+  interface aem-eds-studio uses.
+- **Drafts: review rounds before a block reaches the repository** (EDS-085).
+  `block from-design --draft` keeps the result as a version under
+  `tmp/eds-cli/drafts/<name>/` and leaves `blocks/` untouched; `eds draft
+  preview | refine "<feedback>" | accept [--commit|--branch] | discard | list`
+  reviews it, adds a version per round and, on accept, copies it into
+  `blocks/<name>/` and commits it with the rounds in the message.
+- **A docs gate in CI** (EDS-083). On a PR, a change under `src/` fails without
+  a `CHANGELOG.md` entry, and a change to the CLI surface (`src/bin/eds.ts`) fails
+  without `README.md` (the npm page) and `site/docs.html` updates. Plus a PR
+  template with a docs checklist, and the rule in `CODING_STANDARDS.md` /
+  `CLAUDE.md`.
 - **Any web page is a design source** (EDS-065). `block from-design` scrapes
   every http(s) link that isn't Figma, Framer or Stitch (`--provider web`): a
   live site you're rebuilding, an HTML mock-up, or the project's own example page

package/README.md

@@ -435,6 +435,7 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 | `--refresh` | Ignore the cached snapshot and re-fetch |
 | `--sample` | Use the bundled sample design, the example file's hero (no URL, token or MCP) |
 | `--serve` | Auto-start the live preview (non-interactive runs only) |
+| `--draft` | Generate a draft for review instead of writing `blocks/<name>/` (see [`eds draft`](#eds-draft)) |
 | `--yes` | Skip confirmation prompts |
 
 Set a **Figma Personal Access Token** (scope `file_content:read`) to use the REST path — via `FIGMA_TOKEN` env or `figma.token` in config. The block generation model defaults to the fastest (Haiku); override with `model` in config.
@@ -455,6 +456,46 @@ Interactive wizard that:
 3. Shows install commands if not
 4. Saves preferences to `~/.eds/config.json`
 
+### `eds draft`
+
+Review a block before it reaches the repository. With `--draft`, `block from-design` keeps its result as a **draft version** under `tmp/eds-cli/drafts/<name>/v1/`. `blocks/<name>/` stays exactly as it was: an existing block is set aside while the agent works and always put back. Each review round adds a version; nothing is written to `blocks/` until the draft is accepted, either right away or after a few rounds.
+
+```bash
+eds block from-design "<design link>" --name hero --draft   # → draft v1
+eds draft preview hero                                      # review it (latest version)
+eds draft refine hero "bigger headline, orange buttons"     # one more round → v2
+eds draft accept hero --branch feature/hero                 # → blocks/hero/, committed
+eds draft list                                              # drafts and their versions
+eds draft discard hero                                      # drop it; blocks/ untouched
+```
+
+`accept --commit` (or `--branch <name>`, created if missing) commits only `blocks/<name>/`, with the review rounds in the message (`v1: first version`, `v2: "bigger headline, orange buttons"`). `preview` and `accept` take a version (`eds draft preview hero 2`, `eds draft accept hero 1 --branch feature/hero`; default: the latest). `refine` starts from the latest version, or `--from <n>`, and reuses the agent and model that made the draft unless you pass `--agent` / `--model`.
+
+**For tools: `--json`.** `block from-design` and the `draft` commands take the global `--json` flag and print **one JSON event per line on stdout** (the usual output stays on stderr). It never prompts, so pass the design, the name and `--draft`. Every event has `v` (the schema version, currently `1`) and `type`, and the stream ends with one `result`. [aem-eds-studio](https://github.com/piotrgodycki/aem-eds-studio) reads it.
+
+```bash
+eds --json block from-design "<design link>" --name hero --draft
+```
+```jsonl
+{"v":1,"type":"start","command":"block from-design","cli":"0.4.59"}
+{"v":1,"type":"agent","tool":"Write","label":"✎ blocks/hero/hero.css","durationMs":18}
+{"v":1,"type":"agent-result","durationMs":152455,"costUsd":0.031}
+{"v":1,"type":"draft","name":"hero","version":1,"ok":true,"dir":"tmp/eds-cli/drafts/hero/v1","files":["hero.css","hero.js"]}
+{"v":1,"type":"result","ok":true,"exitCode":0}
+```
+
+| Event | When |
+|---|---|
+| `start` | first line: the command and the CLI version |
+| `log` | every message the command prints (`level`: debug, info, success, warn, error), as plain text |
+| `agent` / `agent-result` | each tool call the agent made, then its duration and cost (Claude Code) |
+| `draft` | a version was stored: `name`, `version`, `ok` (checks passed), `dir`, `files`, `feedback` |
+| `drafts` | `draft list`: every draft with its versions |
+| `preview` | `draft preview`: the server is up at `url` (no browser is opened) |
+| `accepted` / `discarded` | `draft accept` (with `commit`, `branch`) / `draft discard` |
+| `prompt` | `--dry-run`: where the prompt was saved |
+| `result` | last line: `ok` and `exitCode` |
+
 ### `eds block list`
 
 Lists all blocks in the project with their file status and Figma source info.
@@ -734,7 +775,7 @@ Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.
 |---|---|
 | `--verbose` | Debug-level output |
 | `--quiet` | Errors only |
-| `--json` | Machine-readable JSON output (`doctor`, `audit loading`, `audit security`, `block list`) |
+| `--json` | Machine-readable output: one JSON document (`doctor`, `audit loading`, `audit security`, `block list`), or JSON-lines events (`block from-design`, `draft`; see [`eds draft`](#eds-draft)) |
 | `--no-color` | Disable colors (also respects `NO_COLOR` env) |
 
 ## Development
@@ -744,6 +785,8 @@ git clone https://github.com/piotrgodycki/aem-eds-kit.git && cd aem-eds-kit
 npm install
 ```
 
+Each change goes through an issue (`EDS-NNN`), a `feature/EDS-NNN` or `bug/EDS-NNN` branch and a PR, and **ships with its docs**: a `CHANGELOG.md` entry, `README.md` (this file is also the npm page) and the site pages it touches. CI's docs gate (`scripts/check-docs.mjs`) fails a PR that changes `src/` without a changelog entry, or the commands and flags in `src/bin/eds.ts` without `README.md` and `site/docs.html`. See [`CODING_STANDARDS.md`](https://github.com/piotrgodycki/aem-eds-kit/blob/main/CODING_STANDARDS.md).
+
 ### Scripts
 
 ```bash