aem-eds-kit 0.4.7 → 0.4.12

package/CHANGELOG.md

@@ -6,6 +6,59 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.12] - 2026-10-08
+
+### Added
+- **Framer** as a design source for `block from-design` (alongside Figma, Google
+  Stitch, Canva and Sketch) - the agent reads the project through its Framer MCP
+  connection. Also added a copy-paste **AI-agent setup prompt** to the landing +
+  README (checks Node 20+, installs the CLI, verifies).
+
+### Changed
+- Landing version pill shows `v0.4` (minor) instead of chasing every patch.
+
+### Added
+- **`eds track block <name>`** - instrument a block's `decorate()` with dataLayer
+  tracking on demand: delegated `block_click` (links/buttons, label from
+  `data-track` or text) and `form_submit`, pushed via `trackEvent` from
+  `scripts/analytics.js`. Adds the import and injects at the top of decorate,
+  idempotent, keeps the real parameter name. `--no-click` / `--no-submit`. Also
+  offered right after `block from-design` and `migrate component`, and in the menu.
+
+## [0.4.10] - 2026-10-08
+
+### Changed
+- **`eds integrate gtm`** now emits a proper module instead of the inline IIFE:
+  `scripts/analytics.js` (exports `trackEvent` / `loadGTM`, **initialises the
+  dataLayer**, reads the id from `gtm-id` metadata with a configured fallback,
+  idempotent, `Date.now()`, no dead `<noscript>` iframe) and `scripts/page-meta.js`
+  (default-exported `pageMetaPush`). `delayed.js` imports both and pushes page
+  metadata before GTM initialises. Fixes the "dataLayer is undefined" crash of
+  the old snippet.
+
+### Added
+- `eds migrate component` now pulls the component's **clientlib CSS** off disk
+  into the block's CSS (auto-detected, or `--clientlib <dir>`): honours
+  `css.txt` ordering + `#base=`, concatenates the `.css`, and flags any
+  LESS/SCSS that needs a build. A starting point to review and scope under
+  `.<block>` (the faithful, rendered-CSS path comes in a later phase).
+
+## [0.4.8] - 2026-10-07
+
+### Added
+- **`eds migrate component <dir>`** - start migrating a classic AEM component to
+  EDS. Phase 1 (deterministic, no agent/network): parses the Touch UI dialog
+  (`_cq_dialog/.content.xml`) and maps its Granite/Coral fields onto the 17
+  Universal Editor field types - selects keep their options, multifields become
+  repeatable containers, tabs are preserved - then writes `blocks/<name>/` with
+  a UE model, a decorator stub, and a scoped CSS file to fill from the clientlib
+  or rendered page. Also in the `eds` menu.
+
+## [0.4.7] - 2026-10-07
+
+### Changed
+- Consistent "no EDS project markers found" message across every command.
+
 ## [0.4.6] - 2026-10-07
 
 ### Added
@@ -155,7 +208,13 @@ harness, gradient ANSI logo. Not published (superseded by 0.3.0).
 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.6...HEAD
+[Unreleased]: https://github.com/piotrgodycki/aem-eds-kit/compare/v0.4.12...HEAD
+[0.4.12]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.12
+[0.4.11]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.11
+[0.4.10]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.10
+[0.4.9]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.9
+[0.4.8]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.8
+[0.4.7]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.7
 [0.4.6]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.6
 [0.4.5]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.5
 [0.4.4]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.4

package/README.md

@@ -10,7 +10,7 @@
 
 **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.
+`aem-eds-kit` gives you the `eds` command. Paste a design link - Figma, Google Stitch, Canva, Sketch or Framer - 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.
 
@@ -20,6 +20,32 @@ It lives next to `@adobe/aem-cli` (your local dev server) and handles everything
 npm install -g aem-eds-kit
 ```
 
+<details>
+<summary><strong>Or let your AI agent install it</strong> (copy-paste prompt)</summary>
+
+```text
+Goal:
+Ensure Node.js v20 or newer is installed, then install the aem-eds-kit CLI and verify it.
+
+Check first: run `node --version`. If the major version is 20 or higher, do not install or modify Node.js.
+If Node.js is missing or older than v20, install an official Node.js release (major version 20 or higher).
+
+Install policy: use an existing package manager only if it is already installed. Do not install Homebrew,
+winget, Chocolatey, Scoop, nvm, fnm, or another package manager just for this task.
+- macOS: Homebrew if already installed, otherwise the official Node.js `.pkg` installer.
+- Windows: winget if already installed, otherwise the official Node.js `.msi` installer.
+- Linux: the system package manager if it can install v20+, otherwise NodeSource (Debian/Ubuntu, RHEL/Fedora)
+  or the official Node.js standalone Linux binary. Downloads: https://nodejs.org/download/release/latest/
+
+Verify Node: run `node --version` again; only continue if the major version is 20 or higher.
+Install the CLI: run `npm install -g aem-eds-kit`. Verify: run `eds --version`.
+
+Final step: from inside an EDS project (a folder with fstab.yaml, head.html, or scripts/scripts.js), run `eds`
+for the interactive menu, or `eds init` to set up a freshly cloned Adobe EDS boilerplate.
+```
+
+</details>
+
 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
@@ -32,7 +58,7 @@ eds block from-design "<figma-url>" --name hero
 
 ## 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.
+Run `eds` with no command and it opens an **interactive menu** that walks you through every feature (set up the project, generate a block from a design, migrate a classic AEM component, 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 init`, `eds block from-design` (wizard), `eds migrate component`, `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**
 
@@ -81,6 +107,28 @@ eds init --name my-site --authoring da --org my-org --site my-site --yes
 | `--no-ci` | Skip the GitHub Actions workflow |
 | `--yes` | Skip prompts; apply with flags/defaults |
 
+### `eds migrate component [dir]`
+
+Start migrating a **classic AEM component** to EDS. Phase 1 is deterministic (no agent, no network): it parses the component's Touch UI dialog (`_cq_dialog/.content.xml`) and maps its Granite/Coral fields onto the **17 Universal Editor field types** - selects keep their options, multifields become repeatable containers, tabs are preserved - then writes `blocks/<name>/` with a UE model (`_<name>.json`), a `decorate()` stub (port the HTL logic), and a scoped CSS file to fill from the component's clientlib or its rendered page.
+
+It also pulls the component's **clientlib CSS** off disk into the block's CSS when it can find one (auto-detected, or `--clientlib <dir>`): it honours `css.txt` ordering (and `#base=`), concatenates the `.css`, and flags any LESS/SCSS that needs a build. Treat it as a starting point - review the selectors and scope them under `.<block>`.
+
+```bash
+eds migrate component /path/to/apps/myproject/components/hero
+eds migrate component ./components/hero --name hero --clientlib ./ui.apps/.../hero/clientlib --yes
+```
+
+Dialogs map cleanly because Granite's `sling:resourceType` set is finite. The most faithful CSS actually comes from the **rendered page** (resolves LESS vars + cascade) - that capture lands in a later phase; for now the clientlib source gets you most of the way.
+
+### `eds track block <name>`
+
+Instrument a block's `decorate()` with **dataLayer** tracking on demand: a delegated `block_click` (links/buttons, label from `data-track` or the element text) and `form_submit`, both pushed through `trackEvent` from `scripts/analytics.js` (created by `eds integrate gtm`). It adds the import, injects at the top of `decorate()`, is idempotent, and keeps the real parameter name. You're also offered it right after `block from-design` and `migrate component`.
+
+```bash
+eds track block hero
+eds track block hero --no-submit        # clicks only
+```
+
 ### `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.
@@ -94,7 +142,7 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 ### `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.)*
+Translates a design - **Figma, Google Stitch, Canva, Sketch or Framer** - 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**.
 
@@ -167,7 +215,7 @@ eds scaffold ci
 
 ### `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.
+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. **GTM** gets a `scripts/analytics.js` module (exports `trackEvent` / `loadGTM`, initialises the dataLayer, reads the container id from the `gtm-id` metadata) plus a `scripts/page-meta.js` (default-exported `pageMetaPush`); `delayed.js` imports both and pushes page metadata before GTM initialises.
 
 ```bash
 eds integrate                  # interactive