aem-eds-kit 0.4.12 → 0.4.22

package/CHANGELOG.md

@@ -6,7 +6,106 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.4.12] - 2026-10-08
+### Added
+- **`eds init` writes a local-dev `.env` + `xwalk.json` by default.** `.env`
+  carries the `aem up` config (`AEM_OPEN=/`, `AEM_PORT=3007`, `AEM_PAGES_URL`
+  prefilled from the git remote); it's never overwritten and always gitignored.
+  `xwalk.json` (Universal Editor multi-field enabled) is written for UE projects.
+  Opt out with `--no-env` / `--no-xwalk`. Standalone `eds scaffold env` and
+  `eds scaffold xwalk` (re)generate either on demand.
+- **`eds ue check` / `eds ue open` - light Universal Editor helpers.** No Docker,
+  no local AEM SDK, no local UE Service. `ue check` is an offline readiness
+  report (UE config files present + which blocks have a model, so you know which
+  are editable). `ue open [path]` builds and opens the hosted Universal Editor
+  deep link for your cloud author, deriving the preview host
+  (`main--<repo>--<owner>.aem.page`) from the git remote; `--org`, `--ref`,
+  `--url`, `--no-open` to tweak.
+- **Sandbox never overwrites an existing repo.** `eds sandbox new` now checks
+  whether `<owner>/<name>` already exists and refuses up front with a clear
+  message (in addition to the GitHub template API, which never clobbers). Guards
+  both the API and `gh` paths.
+- **Secure GitHub sandboxes guide** (site): least-privilege setup - a fine-grained
+  token scoped to a single repo, or a dedicated sandbox org via `--org` - plus the
+  minimal permissions, token storage, and the overwrite/teardown safety notes.
+  Linked from the docs and README; added to the sitemap.
+
+## [0.4.19] - 2026-10-08
+
+### Added
+- **`eds sandbox login` / `logout` - GitHub auth without `gh`.** The sandbox now
+  authorizes GitHub itself: the OAuth **Device Flow** (browser authorize) when an
+  OAuth app is configured (`EDS_GITHUB_CLIENT_ID`), or a Personal Access Token
+  otherwise; `GITHUB_TOKEN`/`GH_TOKEN` and an authenticated `gh` are also accepted
+  (fallback). Repos are created/listed/deleted via the GitHub REST API. The token
+  is stored owner-only (mode 0600) in `~/.eds/github.json`. `login` guides you to
+  a **least-privilege fine-grained token** (ideally scoped to a dedicated sandbox
+  org via `--org`), so nothing outside your sandboxes is exposed. The CLI only
+  ever lists sandboxes (by the `eds-sandbox` topic) and targets named repos.
+
+## [0.4.18] - 2026-10-08
+
+### Added
+- **`eds sandbox`** - spin up and tear down disposable EDS sandbox repos on
+  GitHub (via the `gh` CLI). `sandbox new <name>` creates a repo from a boilerplate
+  (Document Authoring or Universal Editor / crosswalk), tags it `eds-sandbox`, and
+  a guided wizard walks you through visibility, opening the AEM Code Sync install
+  page, and running `eds init`. `sandbox list` shows your sandboxes with their
+  preview URLs; `sandbox rm <name>` deletes one (with confirmation). From an empty
+  folder to a live EDS environment - and gone again - in seconds. Needs the
+  globally installed CLI and an authenticated `gh`.
+
+### Added
+- **`eds template new` composes blocks in order.** The wizard adds blocks one by
+  one (repeats allowed) so you control the exact sequence and count, instead of
+  an unordered checkbox.
+- **Universal Editor initial content.** For the UE model, `template new` now
+  writes `templates/<name>.json` - the page's initial content as an **ordered
+  list of components with default field values** read from each block's model
+  (`_<block>.json`), plus registers the blocks so authors can add them. The EDS
+  analog of an AEM editable template's initial content.
+
+### Changed
+- **`eds template new` is now authoring-aware.** It detects the model from
+  `fstab.yaml` / project markers (or `--authoring da|gdrive|sharepoint|ue`) and
+  routes the generated page: **DA** push (existing), an **importable doc** for
+  **Google Docs / SharePoint**, and for **Universal Editor** it registers the
+  seeded blocks in `component-filters.json` (so authors can add them) and points
+  to the AEM editable template. Completes the per-model template paths shown as
+  an infographic on the docs page.
+
+### Added
+- **`eds template new <name>`** - generate EDS page **initial content** (the EDS
+  analog of an AEM template): a document of sections + chosen blocks + a metadata
+  block. Writes `templates/<name>.html` locally and, with `--push`, pushes it to
+  **DA (da.live)** via the source API (org/site from `.edsrc.json` or flags;
+  `DA_TOKEN` for protected projects). `--path`, `--title`, `--description`,
+  `--blocks`, `--area`. Also in the menu. (UE/crosswalk templates come next.)
+- Docs: a **"From zero to a published page"** step-by-step command path.
+
+## [0.4.14] - 2026-10-08
+
+### Added
+- **`eds schema block <name>` (JSON-LD)** - inject a schema.org structured-data
+  builder into a block's `decorate()`. Types: Article, FAQPage, BreadcrumbList,
+  Product, Organization, LocalBusiness, Event, VideoObject, Recipe, HowTo.
+  Idempotent, reads the block content via a `root` alias, appends a
+  `<script type="application/ld+json">` to the head. `--type`, interactive picker.
+- **`eds scaffold helpers`** - write `scripts/utils.js`, picking the helpers you
+  want in an interactive checkbox (dependencies pulled in automatically) or by
+  name: `toCamelCase`, `getPagePath` / `getLanguageRootPath`, `getSiteArea`
+  (top-level area, e.g. blog), `getEnvironment`, `getContentTopic`, `isUEEdit` /
+  `isUEPreview` / `isUE`, `getMetadata`. Also in the `eds scaffold` picker.
+
+## [0.4.13] - 2026-10-08
+
+### Added
+- **Model partials & helpers** - a library of reusable Universal Editor field
+  groups (heading, image, link, cta, cta-group, classes, eyebrow, richtext,
+  embed, teaser, card) built from typed field builders (correct `valueType` per
+  component), plus **`eds model add <block> [partials...]`** to compose them into
+  a block's `_<block>.json` (added by name, never duplicated). The from-design /
+  migrate prompt now lists the catalog so the agent reuses the standard groups
+  instead of inventing fields. Also in the menu.
 
 ### Added
 - **Framer** as a design source for `block from-design` (alongside Figma, Google
@@ -208,7 +307,14 @@ 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.12...HEAD
+[Unreleased]: https://github.com/piotrgodycki/aem-eds-kit/compare/v0.4.19...HEAD
+[0.4.19]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.19
+[0.4.18]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.18
+[0.4.17]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.17
+[0.4.16]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.16
+[0.4.15]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.15
+[0.4.14]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.14
+[0.4.13]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.13
 [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

package/README.md

@@ -87,12 +87,54 @@ eds integrate
 eds doctor
 ```
 
+## From zero to a published page
+
+The full path, command by command. This example targets **DA (da.live)** authoring.
+
+```bash
+# 1. Install the CLI
+npm i -g aem-eds-kit
+
+# 2. Set up the project (pick DA, enter org + site). Writes fstab + CI + naming.
+eds init --authoring da --org my-org --site my-site
+
+# 3. Scaffold the Universal Editor config + helper functions
+eds scaffold ue
+eds scaffold helpers
+
+# 4. Build blocks - from a design, from scratch, or migrated from classic AEM
+eds block from-design            # paste a Figma/Stitch/Canva/Sketch/Framer link
+# eds block create hero
+# eds migrate component ./components/hero
+
+# 5. Enrich a block (optional)
+eds model add hero teaser        # add reusable field-group partials
+eds schema block hero --type Article   # JSON-LD structured data
+eds track block hero             # dataLayer click + form-submit tracking
+
+# 6. Generate the page (initial content) and push it to DA
+eds template new homepage --blocks hero,cards --push --org my-org --site my-site
+
+# 7. Preview, then publish
+eds preview /templates/homepage
+eds publish /templates/homepage
+```
+
+Every step is also interactive when you omit the flags - run `eds` for the menu.
+
 ## Commands
 
 ### `eds init`
 
 Adapt a freshly cloned EDS boilerplate to your setup in one interactive wizard. Pick the authoring model - **Universal Editor (crosswalk), DA (da.live), Google Drive or SharePoint** - and `eds` sets the project name (`package.json` + boilerplate placeholders), writes `fstab.yaml` **only when the model needs it** (UE/crosswalk doesn't), scaffolds the crosswalk config + `paths.json` for UE, optionally adds the CI workflow, then walks the **external steps** (AEM Code Sync app, content-source share, Sidekick) as a clickable checklist.
 
+By default it also writes, out of the box:
+
+- a local-dev **`.env`** for `aem up` (`AEM_OPEN=/`, `AEM_PORT=3007`, `AEM_PAGES_URL` prefilled from your git remote) - never overwritten, always gitignored;
+- for Universal Editor projects, an **`xwalk.json`** enabling UE multi-field support.
+
+Opt out with `--no-env` / `--no-xwalk`, or (re)generate either later with `eds scaffold env` / `eds scaffold xwalk`.
+
 ```bash
 eds init                                           # interactive
 eds init --name my-site --authoring da --org my-org --site my-site --yes
@@ -105,8 +147,52 @@ eds init --name my-site --authoring da --org my-org --site my-site --yes
 | `--mountpoint <url>` | Content source URL (document models) |
 | `--org <org>` / `--site <site>` | DA org / site (`--authoring da`) |
 | `--no-ci` | Skip the GitHub Actions workflow |
+| `--no-env` | Skip the local-dev `.env` (aem up config) |
+| `--no-xwalk` | Skip `xwalk.json` (UE multi-field) |
 | `--yes` | Skip prompts; apply with flags/defaults |
 
+### `eds template new <name>`
+
+Generate EDS page **initial content** - the EDS analog of an AEM template. In the wizard you **compose the blocks in order** (add them one by one, repeats allowed - you control the sequence and count). It always writes `templates/<name>.html`, then **routes by your authoring model** (detected from `fstab.yaml` / project markers, or `--authoring`): **DA** → push to da.live (`--push`, org/site from `.edsrc.json`/flags, `DA_TOKEN` for protected projects); **Google Docs / SharePoint** → importable doc + the external steps; **Universal Editor** → writes `templates/<name>.json` (the page's initial content: an ordered list of components with default field values from each block's model) and registers the blocks so authors can add them. Interactive when flags are omitted; `--blocks hero,cards,cards` keeps order and repeats non-interactively.
+
+```bash
+eds template new homepage                         # interactive (blocks, DA push)
+eds template new homepage --blocks hero,cards --push --org my-org --site my-site
+```
+
+| Flag | Description |
+|---|---|
+| `--blocks <list>` | Comma-separated block ids to seed |
+| `--title` / `--description` / `--area` | Page title, description, metadata label |
+| `--path <path>` | Content path (default `/templates/<name>`) |
+| `--authoring <model>` | Force `da` \| `gdrive` \| `sharepoint` \| `ue` (else detected) |
+| `--push` | Push to DA (da.live) |
+| `--org` / `--site` | DA org / site (else from `.edsrc.json`) |
+| `--yes` | Skip prompts |
+
+### `eds sandbox`
+
+Spin up and tear down **disposable EDS sandbox repos** on GitHub - a rapid, throwaway environment you can stand up and delete in seconds, straight from an empty folder.
+
+**Authorize GitHub once** - no `gh` required: `eds sandbox login` runs the OAuth **Device Flow** (open `github.com/login/device`, enter the code) when an OAuth app is configured (`EDS_GITHUB_CLIENT_ID`), otherwise it accepts a Personal Access Token (scopes `repo`, `delete_repo`). A token in `GITHUB_TOKEN`/`GH_TOKEN` works too, and an authenticated `gh` is used as a fallback.
+
+```bash
+eds sandbox login                # authorize GitHub (device flow or token)
+eds sandbox new my-test          # guided: boilerplate, visibility, Code Sync, eds init
+eds sandbox new my-test --ue --private --yes
+eds sandbox list                 # your sandboxes (tagged eds-sandbox) + preview URLs
+eds sandbox rm my-test           # delete it (with confirmation)
+```
+
+`sandbox new` creates the repo from a boilerplate (Document Authoring `adobe/aem-boilerplate` or Universal Editor `adobe/aem-boilerplate-xwalk`) via the GitHub API, clones it, tags it `eds-sandbox`, then walks you through opening the AEM Code Sync install page and running `eds init`. The preview URL is `https://main--<repo>--<owner>.aem.page/`.
+
+Sandboxes are **throwaway test repos** - stand one up to debug or try an integration, then delete it; they work fine on a personal account. Two safety guarantees:
+
+- **Never overwrites an existing repo.** `sandbox new` checks first and refuses if `<owner>/<name>` already exists (and the GitHub template API never clobbers either way).
+- **Least privilege.** Scope the token to just your sandboxes - a fine-grained token limited to one repo, or a dedicated sandbox org used via `--org`. `eds sandbox login` links you straight to the token page with the minimal permissions. See the [Secure GitHub sandboxes guide](https://piotrgodycki.github.io/aem-eds-kit/secure-github-sandboxes.html).
+
+The token is stored owner-only (mode `0600`) in `~/.eds/github.json`; `eds sandbox logout` removes it. `list` only ever shows `eds-sandbox` repos and `rm` deletes only the named repo, with confirmation.
+
 ### `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.
@@ -129,6 +215,44 @@ eds track block hero
 eds track block hero --no-submit        # clicks only
 ```
 
+### `eds model add <block> [partials...]`
+
+Compose **reusable field groups (partials)** into a block's Universal Editor model (`_<block>.json`) instead of hand-writing fields. Fields are added **by name**, so re-running never duplicates. Partials are built from typed field helpers (each sets the right `valueType`), and the same catalog is referenced in the `from-design` / `migrate` prompt so the agent reuses the standard groups.
+
+```bash
+eds model add hero teaser              # image + eyebrow + title + text + cta
+eds model add cards card cta-group     # pick several
+eds model add hero                     # interactive checkbox picker
+```
+
+Built-in partials: `heading`, `eyebrow`, `image`, `richtext`, `link`, `cta`, `cta-group`, `classes` (section styles), `embed`, `teaser`, `card`.
+
+### `eds schema block <name>`
+
+Inject a **JSON-LD (schema.org) structured-data** builder into a block's `decorate()` for SEO / rich results. Pick a type - `Article`, `FAQPage`, `BreadcrumbList`, `Product`, `Organization`, `LocalBusiness`, `Event`, `VideoObject`, `Recipe`, `HowTo` - and it appends a `<script type="application/ld+json">` to the head, built from the block's content (aliased to `root`, so it's independent of the parameter name). Idempotent; some fields are heuristic or `TODO`, so review and validate with Google's Rich Results test.
+
+```bash
+eds schema block faq --type FAQPage
+eds schema block article              # interactive type picker
+```
+
+### `eds ue check` · `eds ue open [path]`
+
+Light **Universal Editor** helpers - no Docker, no local AEM SDK, no local UE Service to stand up.
+
+`eds ue check` is an **offline readiness report**: it confirms the project is UE-ready (`component-definition.json` + `component-models.json` + `component-filters.json`) and lists which blocks are actually **editable** - a block is editable when it has a model (`_<name>.json` or a `component-models.json` entry), so you catch a block that won't appear in the editor before you open it.
+
+`eds ue open [path]` builds and opens the **deep link** into the hosted Universal Editor for your **cloud author**, pointing the editor canvas at your preview host (derived from the git remote as `main--<repo>--<owner>.aem.page`).
+
+```bash
+eds ue check
+eds ue open /products
+eds ue open / --org my-org --ref dev
+eds ue open /blog --url main--site--owner.aem.page --no-open
+```
+
+Full workflow (proxy, `.env`, `xwalk.json`, editor deep link): [`docs/local-development.md`](docs/local-development.md).
+
 ### `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.
@@ -203,6 +327,14 @@ Scaffold Universal Editor components deterministically (no agent). `eds scaffold
 ```bash
 eds scaffold ue
 eds scaffold blocks            # all, or: eds scaffold blocks hero cards
+eds scaffold helpers           # scripts/utils.js with common EDS helpers
+```
+
+`eds scaffold helpers` writes `scripts/utils.js` - **tick the helpers you want** in an interactive checkbox (dependencies are pulled in automatically), or pass names. Available: `toCamelCase`, `getPagePath` / `getLanguageRootPath`, `getSiteArea` (top-level area like `blog`), `getEnvironment`, `getContentTopic`, `isUEEdit` / `isUEPreview` / `isUE`, and `getMetadata`.
+
+```bash
+eds scaffold helpers                    # interactive picker
+eds scaffold helpers getSiteArea getEnvironment
 ```
 
 ### `eds scaffold ci`