aem-eds-kit 0.4.16 → 0.4.22

package/CHANGELOG.md

@@ -6,7 +6,63 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.4.16] - 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
@@ -251,7 +307,10 @@ 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.16...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

package/README.md

@@ -128,6 +128,13 @@ Every step is also interactive when you omit the flags - run `eds` for the menu.
 
 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
@@ -140,11 +147,13 @@ 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: a document of sections + chosen blocks + a metadata block. 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** → registers the seeded blocks in `component-filters.json` and points you to the AEM editable template. Interactive when flags are omitted.
+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)
@@ -161,6 +170,29 @@ eds template new homepage --blocks hero,cards --push --org my-org --site my-site
 | `--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.
@@ -204,6 +236,23 @@ 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.