@khester/create-dynamics-app 2.6.5 → 2.6.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 khester
+
+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

@@ -38,6 +38,9 @@ npm run metadata:pull -- --entities account,contact  # live metadata → typed s
 | id | What it scaffolds | Fluent |
 |----|-------------------|--------|
 | `react-custom-page` | React SPA for a model-driven custom page | v8 |
+| `host-swap` | **One component, three hosts** — one host-agnostic `Component.tsx` (coded against an injected `IApiService`) + a thin per-host wrapper; pick PCF, a custom page, or a web resource with `--host` (see below) | v8 |
+| `grid-starter` | React custom page rendering a grid-kit `<DataGrid>` over a cell-renderer registry | v8 |
+| `starter-page` | Dynamics page built on a selectable `@dataverse-kit/surface-kit` surface (`--surface`) | v8 |
 | `power-pages` | Power Pages portal starter | v8 |
 | `pcf-field` | PCF field control (property-type aware: text/number/boolean/date) | v8 |
 | `pcf-dataset` | PCF dataset/grid control — grid-kit `<ReadOnlyGrid>` (sort/filter/columns/search), **model-driven, React 18** | v8 |
@@ -49,13 +52,33 @@ npm run metadata:pull -- --entities account,contact  # live metadata → typed s
 
 Run with no flags for an interactive picker.
 
+### Host-swap — write once, switch host
+
+The `host-swap` artifact is the host-portability story: you write **one** `src/Component.tsx`
+against the injected `IApiService` data-access seam, and a thin per-host wrapper supplies the
+service and mounts it. The component source never changes — only the wrapper does. Pick the
+host with `--host`:
+
+```bash
+npx @khester/create-dynamics-app my-control --artifact host-swap --host pcf
+#   --host custom-page   → Vite app mounted as a Dynamics custom page (ServiceFactory ladder)
+#   --host pcf           → pcf-scripts virtual ReactControl (same-origin FetchApiService, React 18)
+#   --host web-resource  → webpack-bundled web resource (same-origin FetchApiService)
+```
+
+Each host builds the **same** component under its own toolchain (Vite / pcf-scripts / webpack);
+all three are exercised by CI build gates. To retarget, scaffold with another `--host` and copy
+your `src/Component.tsx` across.
+
 ## Flags
 
 - `-a, --artifact <id>` — artifact to scaffold (see table).
 - `--v8` / `--v9` (or `-l, --library fluent-v8|fluent-v9`) — Fluent version for artifacts that support a choice. Only the chosen library is installed.
 - `-n, --namespace`, `--component-name`, `--property-type` — PCF options.
+- `--host <custom-page|pcf|web-resource>` — host target for the `host-swap` artifact (default `custom-page`).
+- `--surface <form|panel|dashboard|master-detail>` — surface for the `starter-page` artifact.
 - `--graph` — include Microsoft Graph (teams-app).
-- `--with-components` — install [`@khester/reusable-components`](https://www.npmjs.com/package/@khester/reusable-components) (a curated Fluent **v8** React set: `ReusableCard`, `CustomSection`, `FileUploadField`, `SearchComponent`, `DetailsListComponent`, the localhost-gated `logger`, …) plus its `@fluentui/react` v8 peer. Honored for the v8 React hosts — `react-custom-page`, `power-pages`, `web-resource`, `dialog-form`; warned-and-ignored elsewhere; **errors** if combined with `--v9`.
+- `--with-components` — install [`@khester/reusable-components`](https://www.npmjs.com/package/@khester/reusable-components) (a curated Fluent **v8** React set: `ReusableCard`, `CustomSection`, `FileUploadField`, `SearchComponent`, `DetailsListComponent`, the localhost-gated `logger`, …) plus its `@fluentui/react` v8 peer. Opt-in for the v8 React hosts that don't already bundle it — `power-pages`, `web-resource`, `dialog-form` (`react-custom-page`, `grid-starter`, and `host-swap` ship it as a base dependency already); warned-and-ignored elsewhere; **errors** if combined with `--v9`.
 - `--from-design <file>` — generate from a form-builder export (a `FormBuilderProject` JSON, e.g. from `/generate-form`). Wraps `@dataverse-kit/export-engine` to produce a deployable project (host + form code + a design-derived data layer). Supported targets: `web-resource`, `pcf`, `static-web-app`. From-design output is generated by the export engine and is structurally different from a blank starter (it ships its own token tooling); `package.json.dynamicsKit.artifact` records which.
 - `--skip-git`, `--skip-install`.
 
@@ -69,6 +92,7 @@ See `CHANGELOG.md`. In short: removed the consulting flags (`-c/-e/-p/-d/--gener
 
 ## Testing & coverage boundaries
 
-- Unit + smoke tests (`npm test`) run the scaffold pipeline for all 9 artifacts (zero-residual-token + variant/prune checks) but do **not** `npm install` or build the generated projects.
+- Unit + smoke tests (`npm test`) run the scaffold pipeline for all 12 artifacts (zero-residual-token + variant/prune checks) but do **not** `npm install` or build the generated projects, except the build gates below.
+- Build gates (`npm run test:e2e`) scaffold + `npm install` + build the React custom-page templates (Vite), the PCF templates (`pcf-scripts`), and **all three `host-swap` hosts** (custom-page → Vite, pcf → pcf-scripts, web-resource → webpack) — the host-swap gates prove one `Component.tsx` builds under every host toolchain.
 - React artifacts are verified to `tsc --noEmit` clean for v8 and v9 via manual installs; **PCF** type-correctness (against generated `ManifestTypes` from `pcf-scripts refreshTypes`) is verified manually, not in CI.
 - The `--from-design` generated-project build is verified manually.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@khester/create-dynamics-app",
-  "version": "2.6.5",
+  "version": "2.6.6",
+  "license": "MIT",
   "description": "Unified CLI to scaffold Dynamics 365 / Power Platform artifacts",
   "main": "dist/index.js",
   "type": "module",
@@ -25,7 +26,7 @@
     "clean": "rimraf dist tsconfig.tsbuildinfo"
   },
   "dependencies": {
-    "@dataverse-kit/export-engine": "^1.25.1",
+    "@dataverse-kit/export-engine": "^1.25.2",
     "@khester/dynamics-ui-components": "^1.0.0",
     "chalk": "^5.3.0",
     "commander": "^11.1.0",