aem-eds-kit 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-06
+
+Design-agnostic generation, a full interactive configurator, and the first version
+actually installable from npm (0.3.0 was unpublished before it shipped).
+
+### Added
+- **`eds block from-design [url]`** - generate a block from **Figma, Google Stitch,
+  Canva or Sketch**. The wizard's first step picks the design source; Figma keeps its
+  pixel-perfect MCP path (`get_design_context` / `get_variable_defs` /
+  `get_screenshot`), other providers pass a design reference read through their own MCP.
+- **Interactive configurator everywhere** - `eds` with no command opens a menu, and
+  `from-design`, `scaffold`, `integrate` and the Admin API are step-by-step wizards
+  when run without arguments.
+- **`eds scaffold ue` / `eds scaffold blocks`** - deterministic (no agent) Universal
+  Editor components + a `field-reference` block covering all 17 field types and a
+  multifield, plus standard Block Collection blocks.
+- **`eds integrate`** - add GTM / GA4 / chat / consent to `scripts/delayed.js`
+  (delayed phase, facade pattern for chat widgets).
+- Live, colour-coded agent log with per-phase timings and a spinner; the live preview
+  **auto-starts** after generating (and live-reloads if one is already running).
+
+### Changed
+- Renamed **`block from-figma` → `block from-design`** (the figma-named command is
+  gone). Not-yet-authored content uses lightweight **placeholders** instead of
+  bundling design assets, so the block is visible before Universal Editor takes over.
+- The brand logo prints **once per run** (no repeat when entering a command from the
+  menu); CLI logo + dots use the landing accent `#ff5a36`.
+
+## [0.3.0] - 2026-10-05
+
+First public release, published to npm as **`aem-eds-kit`** (the command stays `eds`).
+Delivers the full pipeline in one shot: **Figma → pixel-perfect block → Universal
+Editor authoring interface**.
+
+### Added
+- **`eds block from-figma <url>`** - translate a Figma frame/component into an EDS
+  block. Builds a prompt (project tokens + EDS conventions), runs it through your AI
+  agent (Claude Code / Cursor / Codex) which reads the design via Figma MCP
+  (`get_design_context`, `get_variable_defs`, `get_screenshot`), generates
+  pixel-perfect JS + CSS, and self-verifies against the screenshot. Post-generation
+  verification of the produced files.
+- **Universal Editor model by default** - `block create` and `block from-figma`
+  generate the UE model (`_<name>.json`, xwalk `definitions`/`models`/`filters`)
+  so blocks are authorable in UE immediately. Figma text/image/link layers and
+  component variants are mapped to UE fields (variants → `select` → CSS modifier).
+  Opt out with `--no-ue-model`.
+- **`eds block preview <name>`** - live, breakpoint-switchable preview served in the
+  browser (dependency-free in-memory server). Width-honest `<iframe>` switcher
+  (375 / 768 / 1280 / Full) reads breakpoints and the Figma link from the block's
+  `.eds-meta.json`. `--port`, `--widths`, `--no-open`.
+- **`eds block create <name>`** - scaffold a block (JS + CSS + UE model).
+- **`eds block list`** - list blocks with file/UE/Figma status (`--json`).
+- **`eds figma setup`** - configure Figma MCP for your AI agent.
+- **`eds doctor`** - project audit (fstab, head.html, per-block JS, UE model,
+  `console.log`, Figma-sync freshness, config). `--json`.
+- **`eds audit loading`** - three-phase loading / LCP-budget audit. `--json`.
+- **`eds audit security`** - `npm audit` (dependency vulnerabilities) + static
+  exploit scan (XSS, `eval`, dynamic `innerHTML`, secrets, AWS/private keys, bearer
+  tokens, mixed content, `target="_blank"` tabnabbing, `postMessage('*')`, inline
+  handlers). Severity-grouped, `--json`, non-zero exit on critical/high.
+- **`eds preview` / `eds publish <paths...>`** - preview/publish pages via the AEM
+  Admin API.
+- Branded CLI UX: gradient ANSI "EDS" wordmark (shown on help and command entry
+  points), Adobe Spectrum palette, aligned status tables and summary boxes.
+  Global flags `--verbose`, `--quiet`, `--json`, `--no-color`.
+- Conventions baked into generation: blocks are full-width (full-bleed) and
+  mobile-first by default; content capped for readability.
+
+### Notes
+- The CLI is a dev tool - it ships nothing to your site bundle (0 bytes, no LCP
+  impact). Published tarball ~74 kB.
+
+## [0.2.0] - internal
+
+Branded UX layer, shared presentation module, security audit, responsive preview
+harness, gradient ANSI logo. Not published (superseded by 0.3.0).
+
+## [0.1.0] - internal
+
+Initial CLI scaffold: `block create`, `block from-figma`, `block list`,
+`figma setup`, `doctor`, `preview`, `publish`. Not published.
+
+[Unreleased]: https://github.com/piotrgodycki/aem-eds-kit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.0
+[0.3.0]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piotr Godycki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,378 @@
-# Temporary Holding Version
+<p align="center"><img src=".github/assets/readme-banner.png" alt="aem-eds-kit - Figma frame in. EDS block out." width="100%"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# aem-eds-kit
+
+[![npm version](https://img.shields.io/npm/v/aem-eds-kit.svg)](https://www.npmjs.com/package/aem-eds-kit)
+[![npm downloads](https://img.shields.io/npm/dm/aem-eds-kit.svg)](https://www.npmjs.com/package/aem-eds-kit)
+[![CI](https://github.com/piotrgodycki/aem-eds-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/piotrgodycki/aem-eds-kit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
+**Turn a design into an EDS block** - JS, CSS and a Universal Editor model - without leaving your terminal.
+
+`aem-eds-kit` gives you the `eds` command. Paste a design link - Figma, Google Stitch, Canva or Sketch - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex); the agent reads it through MCP and writes production-ready code straight into your repo. It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
+
+It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
+
+## Install
+
+```bash
+npm install -g aem-eds-kit
+```
+
+Node.js 20 or newer. That's all the setup there is - `eds` now works in **any folder**. Step into your EDS project (anywhere with a `fstab.yaml`) and the CLI finds the project root for you:
+
+```bash
+cd ~/my-eds-site
+eds figma setup                              # one-time: connect your AI agent to Figma
+eds block from-design "<figma-url>" --name hero
+```
+
+`eds` runs on your machine, not on your site - it never adds a single byte to what your visitors download.
+
+## Interactive mode
+
+Run `eds` with no command and it opens an **interactive menu** that walks you through every feature (generate a block from a design, scaffold, create a block, add an integration, preview, Admin API, audits, Figma setup). Most commands are also interactive on their own when you omit arguments - e.g. `eds block from-design` (wizard), `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
+
+A full A-Z reference of every command lives on the docs page: **https://piotrgodycki.github.io/aem-eds-kit/docs.html**
+
+## Quick start
+
+```bash
+eds                              # interactive menu
+
+# One-time: configure Figma MCP for your AI agent
+eds figma setup
+
+# Generate a block from a Figma design (wizard, or pass a URL)
+eds block from-design
+
+# Scaffold the standard UE components + blocks
+eds scaffold ue
+eds scaffold blocks
+
+# Add a third-party service (GTM, GA4, chat…)
+eds integrate
+
+# Audit your project
+eds doctor
+```
+
+## Commands
+
+### `eds block create <name>`
+
+Scaffolds `blocks/<name>/` with `<name>.js`, `<name>.css`, **and a Universal Editor model `_<name>.json` by default** - so the block is authorable in UE the moment it's created. Validates kebab-case naming and checks for collisions.
+
+```bash
+eds block create hero-banner             # js + css + _hero-banner.json (UE model)
+eds block create hero-banner --no-ue-model   # skip the UE model
+```
+
+The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definitions` / `models` / `filters`) with starter fields (title + heading-level select + rich text). Extend it from the **full catalog of all 17 Universal Editor field types** - see [`docs/universal-editor-fields.md`](docs/universal-editor-fields.md). `eds block from-design` picks the right field type per Figma layer automatically.
+
+### `eds block from-design [design-url]`
+
+Translates a design - **Figma, Google Stitch, Canva or Sketch** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
+
+The agent reads the design through its MCP connection (for Figma: `get_design_context`, `get_variable_defs`, `get_screenshot`), generates pixel-perfect code (JS + CSS) **and its Universal Editor model** by default, uses lightweight **placeholders** for not-yet-authored content (so the block is visible before Universal Editor takes over), then self-verifies. You see a **live, colour-coded log** with per-phase timings, and on success the **live preview starts automatically**.
+
+```bash
+eds block from-design                               # interactive wizard
+eds block from-design "<figma-url>" --name hero     # non-interactive
+eds block from-design "<figma-url>" --dry-run       # just build the prompt
+```
+
+| Flag | Description |
+|---|---|
+| `--name <name>` | Override the inferred block name |
+| `--source <type>` | Content source: `document` \| `ue` \| `cf` \| `mixed` |
+| `--agent <type>` | Force `claude` \| `cursor` \| `codex` \| `none` |
+| `--dry-run` | Build the prompt only |
+| `--no-ue-model` | Skip the Universal Editor model |
+| `--no-screenshot` | Skip the screenshot (fewer tokens; structural verification) |
+| `--no-serve` | Don't auto-start the live preview |
+| `--yes` | Skip confirmation prompts |
+
+**Supported Figma URL formats:**
+- `figma.com/design/:fileKey/:name?node-id=...`
+- `figma.com/file/:fileKey/:name?node-id=...` (legacy)
+- `figma.com/design/:fileKey/branch/:branchKey/:name` (branches)
+- `figma.com/board/...`, `figma.com/make/...`, `figma.com/slides/...`
+
+### `eds figma setup`
+
+Interactive wizard that:
+1. Detects installed AI agents (Claude Code, Cursor, Codex)
+2. Checks if Figma MCP is configured for your agent
+3. Shows install commands if not
+4. Saves preferences to `~/.eds/config.json`
+
+### `eds block list`
+
+Lists all blocks in the project with their file status and Figma source info.
+
+```bash
+eds block list
+eds block list --json          # machine-readable output
+```
+
+### `eds block preview <name>`
+
+Serves a **live, breakpoint-switchable preview** of a block in your browser - no build, no files written to your project (the harness is served from memory). A dropdown switches widths inside an iframe, and **edits live-reload** the browser (the server watches the block folder).
+
+```bash
+eds block preview hero
+eds block preview hero --widths 375,768,1280   # custom breakpoints
+eds block preview hero --port 9000 --no-open
+```
+
+### `eds scaffold ue` · `eds scaffold blocks`
+
+Scaffold Universal Editor components deterministically (no agent). `eds scaffold ue` writes/merges the three UE config files with the default-content components and a **`field-reference` block showing all 17 field types** + a multifield. `eds scaffold blocks` scaffolds standard Block Collection blocks (hero, cards, columns, accordion, embed) with UE models. Run `eds scaffold` for an interactive picker.
+
+```bash
+eds scaffold ue
+eds scaffold blocks            # all, or: eds scaffold blocks hero cards
+```
+
+### `eds integrate [type]`
+
+Add a third-party service to `scripts/delayed.js` (the EDS-correct place - delayed phase, after LCP, zero CWV impact). Chat widgets use the facade pattern.
+
+```bash
+eds integrate                  # interactive
+eds integrate gtm              # gtm · ga4 · chat · cookiebot · custom
+```
+
+- A dropdown switches the block between breakpoints inside an `<iframe>`, so the block's media queries fire against the chosen width - a **width-honest** comparison that isn't distorted by your monitor size.
+- Breakpoints come from the block's `.eds-meta.json` (`breakpoints`, marking which widths have a real Figma frame → pixel-perfect) and fall back to `375 / 768 / 1280` or `--widths`.
+- If the block has a `.eds-meta.json` with a Figma source, an **Open in Figma** link is shown.
+- Authored sample content is read from `blocks/<name>/_<name>.preview.html` if present; otherwise a placeholder is used (and the chrome tells you to add one).
+
+> Not to be confused with `eds preview <paths...>` (lower down), which previews **pages** via the AEM Admin API.
+
+### `eds preview <path...>`
+
+Preview pages via the AEM Admin API (`admin.hlx.page`).
+
+```bash
+eds preview /index
+eds preview /blog/my-post /about
+eds preview /index --org my-org --site my-repo --ref main
+```
+
+### `eds publish <path...>`
+
+Publish pages to live via the AEM Admin API.
+
+```bash
+eds publish /index
+eds publish /blog/my-post /about
+```
+
+Both `preview` and `publish` read `org`, `site`, and `ref` from `.edsrc.json` so you don't need to pass flags every time:
+
+```json
+{
+  "admin": {
+    "org": "my-github-org",
+    "site": "my-repo",
+    "ref": "main"
+  }
+}
+```
+
+### `eds doctor`
+
+Audits your EDS project for common issues:
+- `fstab.yaml` exists and is valid YAML
+- `head.html` present
+- Every block folder has a matching `.js` file
+- Every block has a Universal Editor model (`_<name>.json` or an entry in `component-models.json`)
+- No `console.log` in block code
+- `helix-query.yaml` valid if present
+- Figma-generated blocks: warns if last sync > 30 days
+- CLI config present
+
+```bash
+eds doctor
+eds doctor --json
+```
+
+### `eds audit loading`
+
+Audits the EDS three-phase loading strategy and LCP budget:
+- No render-blocking scripts / extra stylesheets / preload-preconnect / font preloads in `head.html`
+- `scripts.js` has `loadEager` / `loadLazy` / `loadDelayed`; eager phase loads only the first section
+- `styles.css` within the LCP budget; no `@import` chains
+- No heavy libraries (`jquery`, `gsap`, `swiper`, …) or `document.write` in blocks
+- Block CSS is scoped to `.<block-name>` (prevents style leakage / CLS)
+
+```bash
+eds audit loading
+eds audit loading --json
+```
+
+### `eds audit security`
+
+Scans the project for **vulnerabilities** and **exploit patterns** - a defensive check you can run before every PR or in CI.
+
+- **Dependency vulnerabilities** - runs `npm audit` and summarizes critical/high/moderate/low (skipped gracefully if there's no `package.json`/lockfile).
+- **Exploit scan** - static analysis of `blocks/`, `scripts/`, and HTML for:
+  - `eval()`, `new Function()`, `document.write()` - code-execution vectors
+  - dynamic `innerHTML` / `insertAdjacentHTML` / `javascript:` URLs - XSS
+  - hardcoded secrets, AWS keys, private keys, bearer tokens
+  - `http://` resources (mixed content), `target="_blank"` without `rel="noopener"` (reverse tabnabbing)
+  - `postMessage('*')`, inline event handlers, leftover `console.log`
+
+Findings are grouped by severity (CRIT / HIGH / MOD / LOW). Exits non-zero if any **critical or high** issue is found - wire it straight into CI.
+
+```bash
+eds audit security
+eds audit security --json      # for CI / tooling
+```
+
+The vendored framework (`scripts/aem.js` / `lib-franklin.js`) is never flagged.
+
+## How Figma integration works
+
+You don't need a Figma API token. `aem-eds-kit` never talks to Figma directly - it writes a focused prompt and hands it to the AI agent you already use, which has its own Figma MCP connection. The agent reads the design and writes the files; `eds` orchestrates the handoff and checks the result.
+
+```
+┌──────────┐     prompt      ┌─────────────┐    MCP calls    ┌───────────┐
+│  eds-cli │ ──────────────→ │ Claude Code │ ──────────────→ │ Figma MCP │
+│          │                 │ / Cursor    │ ←────────────── │  Server   │
+│          │ ←────────────── │ / Codex     │   design data   └───────────┘
+│          │   block files   └─────────────┘
+└──────────┘
+```
+
+The prompt includes:
+- Figma file key and node ID to fetch
+- EDS block conventions (`decorate(block)`, vanilla JS, semantic HTML, full-width/mobile-first)
+- CSS custom properties from your `styles/styles.css`
+- Universal Editor model generation (fields mapped from Figma layers/variants) - on by default
+- Lighthouse performance requirements + pixel-perfect self-verification
+- Output file structure
+
+## Configuration
+
+Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.json` (global)
+
+**`~/.eds/config.json`** (created by `eds figma setup`):
+```json
+{
+  "agent": "claude"
+}
+```
+
+**`.edsrc.json`** (project root, optional):
+```json
+{
+  "admin": {
+    "org": "my-org",
+    "site": "my-site",
+    "ref": "main"
+  }
+}
+```
+
+## Global flags
+
+| Flag | Description |
+|---|---|
+| `--verbose` | Debug-level output |
+| `--quiet` | Errors only |
+| `--json` | Machine-readable JSON output |
+| `--no-color` | Disable colors (also respects `NO_COLOR` env) |
+
+## Development
+
+```bash
+git clone <repo-url> && cd eds-cli
+npm install
+```
+
+### Scripts
+
+```bash
+npm run dev -- --help          # run via tsx, no build needed
+npm run build                  # build to dist/
+npm test                       # vitest
+npm run typecheck              # tsc --noEmit
+npm run lint                   # biome check
+npm run lint:fix               # biome auto-fix
+```
+
+### Testing locally
+
+**Option A - global link (recommended):**
+
+```bash
+npm run build && npm link
+eds --help                     # available everywhere
+```
+
+After code changes, re-run `npm run build` to update.
+
+**Option B - dev mode (no build):**
+
+```bash
+npm run dev -- doctor
+npm run dev -- block create my-block
+npm run dev -- block from-design "https://www.figma.com/design/abc/File?node-id=1-2" --dry-run
+```
+
+**Option C - run from a test EDS project:**
+
+The repo includes a fixture project you can use:
+
+```bash
+cd tests/fixtures/sample-eds-project
+
+# with global link
+eds doctor
+eds block create my-block
+eds block from-design "https://www.figma.com/design/abc/File?node-id=1-2" --dry-run --name hero
+
+# without link
+npx tsx ../../../src/bin/eds.ts doctor
+```
+
+### Testing Figma integration (dry-run)
+
+You don't need a real Figma file to test prompt generation:
+
+```bash
+eds block from-design "https://www.figma.com/design/abc123/Test?node-id=42-100" \
+  --dry-run --name hero-banner
+```
+
+This parses the URL, builds the full agent prompt (with project tokens, EDS conventions), saves it to a temp file, and prints it. No agent or Figma access needed.
+
+### Running tests
+
+```bash
+npm test                       # run all tests once
+npm run test:watch             # watch mode
+```
+
+Tests use fixtures in `tests/fixtures/` - a sample EDS project and recorded Figma MCP responses.
+
+## Roadmap
+
+- **Design sources** - deepen Google Stitch, Canva and Sketch support alongside Figma (the wizard's first step already picks the source), and a generic `eds setup` in place of `eds figma setup`.
+- **Screenshot-to-block** - build a block from a plain image (harder: no structured layout/measurements, so pixel-perfect is tougher).
+- **Tokens & sync** - design variables → CSS custom properties, and incremental re-sync of an existing block (`--update`).
+- **Headless & CI** - a direct MCP client (no agent needed) for CI/CD, plus `eds lighthouse`, `eds rum` and `eds migrate page`.
+
+## Trademarks & affiliation
+
+`aem-eds-kit` is an independent, community project. It is **not affiliated with, endorsed by, or sponsored by Adobe or Figma.** It ships none of their code - it only generates code that follows the public, open-source AEM Edge Delivery Services conventions and interoperates with tools you install yourself.
+
+Adobe, AEM, Edge Delivery Services and Universal Editor are trademarks of Adobe Inc. Figma is a trademark of Figma, Inc. These names are used only to describe compatibility.
+
+## License
+
+MIT - see [LICENSE](LICENSE).