@olenbetong/appframe-vite 6.15.0 → 6.17.0

package/README.md

@@ -1,340 +1,340 @@
-# @olenbetong/appframe-vite
-
-Tools to develop and build Vite applications that run inside Appframe articles.
-
-- Provides a Vite plugin you add in `vite.config.*`.
-- Proxies API and static routes to an Appframe server during `pnpm start`.
-- Logs in automatically and refreshes the session on an interval.
-- Serves real article HTML from Appframe in dev, but swaps production assets for your local entry.
-- Caches i18n strings locally to speed up development loads.
-- Shapes production builds to Appframe paths and filenames, with optional React externals.
-
-## Installation
-
-```sh
-pnpm add -D @olenbetong/appframe-vite
-```
-
-## Usage (Vite)
-
-```ts
-// vite.config.mjs or vite.config.ts
-import appframe from "@olenbetong/appframe-vite";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-	plugins: [appframe()],
-});
-```
-
-Then run your app:
-
-```sh
-pnpm --filter <app> start
-```
-
-The dev server logs in with the credentials `@olenbetong/appframe-auth` finds for the site:
-`APPFRAME_LOGIN_<ENV>` / `APPFRAME_PWD_<ENV>`, then `APPFRAME_LOGIN` / `APPFRAME_PWD`, then the
-password `af auth <env>` saved in the OS keychain. It never asks for one; without credentials it
-stops and says which `af auth` to run.
-
-On first run, the plugin logs in, configures Vite’s proxy for Appframe routes, and serves the article HTML with your local entry injected.
-
-### MUI X license key
-
-The plugin injects the MUI X Premium license key into the bundle as the global `__MUI_X_LICENSE_KEY__`, for both `serve` and `build`. `@olenbetong/appframe-ds/grid` reads it and registers the license itself, so an app using the Designsystemet `AfGrid` does not need its own `LicenseInfo.setLicenseKey()` call.
-
-The key is resolved from, in order:
-
-1. the `MUI_X_LICENSE_KEY` environment variable (CI, a local `.env`, or the shell),
-2. the `MUI_X_LICENSE_KEY` constant declared in the app's `src/shared/licenses.ts`.
-
-The fallback keeps existing apps working with no changes; setting the environment variable is the forward path for getting the key out of the repository.
-
-## Project configuration (package.json)
-
-This package reads `package.json.appframe` to know what to proxy and how to build.
-
-```jsonc
-{
-	"appframe": {
-		"article": {
-			"id": "my-article", // Required
-			"altNames": ["my-article-dev"], // Optional: alternate root paths
-		},
-		"deploy": { "hostname": "dev.obet.no" }, // Default server if proxy not set
-		"proxy": {
-			"hostname": "dev.obet.no", // Optional override for dev proxy
-			"routes": ["^/custom/.*"], // Optional: extra proxied routes
-		},
-		"build": {
-			"platform": true, // Import React and the af packages from the site's platform bundle
-			"externals": true, // Legacy: map React and ReactDOM to globals
-		},
-	},
-}
-```
-
-### `build.platform`
-
-Apps on the 2026 site templates (`ob.2026.application`) set `"platform": true`. The production
-build then leaves `react`, `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`,
-`react-dom/client`, `@olenbetong/appframe-core` and `@olenbetong/appframe-data` as bare imports,
-which the template's import map resolves to `@olenbetong/synergi-platform` — one cached React
-per page, shared with the site chrome. The `af.data` global redirect (`dataGlobal`) then only
-applies to the dev server, which has no import map. The build also writes `dist/platform.json`
-with the platform version the app was built alongside (the workspace's
-`packages/synergi-platform`) and the versions it compiled against; `scripts/app-deploy.ts` pins
-the article to that platform version (its `PlatformHead` and `PlatformStyles` blocks) and
-refuses to deploy when the article is not on a 2026 template, that version is not served on the
-target site, or its manifest carries other versions than the app (override with
-`--allow-platform-mismatch`).
-
-## What it does (at a glance)
-
-- Dev server
-  - Proxies Appframe routes (e.g. `/api`, `/file`, `/lib`, etc.) to the configured hostname.
-  - Performs an initial login and refreshes the session every 5 minutes to prevent 403 errors.
-  - Serves the real article HTML from Appframe, but removes production assets and injects your local entry (`/src/index.*`).
-  - Caches localized strings under `node_modules/.appframe/localizeCache.json` and injects them into the page to avoid many small HTTP 1.1 requests.
-- Build
-  - Enables `manifest` and `sourcemap`.
-  - Writes filenames to Appframe paths, using the article ID, e.g.:
-    - `file/article/script/<ARTICLE_ID>/main.[hash].min.js`
-    - `file/article/style/<ARTICLE_ID>/style.[hash].min.css`
-  - With `build.platform`, leaves React and the af packages as bare imports for the template's import map and writes `dist/platform.json`; the legacy `build.externals` maps `react` and `react-dom` to `React` and `ReactDOM` globals instead.
-  - Adds a Rollup visualizer report at `dist/stats.html`.
-- Resolve
-  - Adds the alias `~/` to `/src/` so imports like `~/components/Button` resolve to `src/components/Button`.
-- DevTools API (see below)
-
-## DevTools
-
-In dev mode the plugin exposes a small JSON API at `/__appframe_devtools__/api` for the **Appframe DevTools
-browser extension** (`packages/appframe-devtools` in the SynergiWeb repo). The extension adds an "Appframe"
-panel to Chrome/Edge DevTools with a live view of the app's data objects, an editor for `resources.yaml`
-and a browser for the data API catalog. Nothing is injected into the page — the toolbar that older
-versions added to every dev-served page is gone.
-
-| Endpoint                    | Purpose                                                                                                               |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `GET /api/config`           | Discovery: `{ appframe: true, apiVersion, hostname, articleId, articleHostname, appName, appVersion, pluginVersion }` |
-| `GET /api/resources`        | Parsed `resources.yaml`                                                                                               |
-| `POST /api/resources`       | Add an entry (`type: "dataObject" \| "procedure"` plus the entry fields)                                              |
-| `PUT /api/resources/:id`    | Replace an entry                                                                                                      |
-| `DELETE /api/resources/:id` | Remove an entry and its generated output file                                                                         |
-| `POST /api/catalog`         | Register a `dbObjectId` as a data API resource on dev, stage and prod                                                 |
-| `GET /api/release`          | Current session (`session: null` when none) and the capabilities derived from the app's scripts                       |
-| `POST /api/release`         | Start a job: `{ kind: "release", dry?, force? }` or `{ kind: "deploy", target, copyDatasources? }`; 409 while running |
-| `DELETE /api/release`       | Cancel the running job                                                                                                |
-| `POST /api/release/input`   | Answer one of the script's questions (`{ name, value }`: the release type and notes, or the apply confirmation)       |
-| `GET /api/release/events`   | Server-sent events: the session snapshot, then every step, log line and question as it happens                        |
-
-The release job runs whatever `scripts.release` is in the app's package.json, from the app directory, with
-`--ui` appended. The deploy job runs `pnpm run build`, optionally `pnpm run cd` (or `copy-datasources`) and
-`pnpm run deploy` with `APPFRAME_DEPLOY_HOSTNAME` set to the target, which `app-deploy.ts` and
-`app-copy-datasources.ts` honour over the hostnames in package.json. The script is expected to follow the protocol in `scripts/lib/releaseUi.ts` (JSON event lines
-prefixed with `@@appframe-devtools ` on stdout, answers as JSON lines on stdin).
-
-Disable it with `appframe({ devtools: false })` when there is no article context (Storybook does this).
-The extension page has host permissions for `localhost`, so the API needs no CORS headers.
-
-## CLI — `appframe-vite`
-
-The package ships a CLI (`appframe-vite`) alongside the Vite plugin.
-
-### `generate-types`
-
-Generates TypeScript type definitions from the article's data objects and procedures:
-
-```sh
-appframe-vite generate-types
-```
-
-### `resources generate`
-
-Reads `resources.yaml` and regenerates all data object / procedure files:
-
-```sh
-appframe-vite resources generate
-# custom config file path:
-appframe-vite resources generate --config path/to/resources.yaml
-```
-
-### `resources add`
-
-Interactive wizard — prompts for resource, ID, output path, permissions, fields, and more, then appends an entry to `resources.yaml` and generates the output file:
-
-```sh
-appframe-vite resources add
-```
-
-### `resources edit [id]`
-
-Interactive editor — pre-fills the wizard with the current values from `resources.yaml` and regenerates the file on save:
-
-```sh
-appframe-vite resources edit dsAccountGroups
-# or without an id (shows a searchable list):
-appframe-vite resources edit
-```
-
-### `resources migrate [id]`
-
-Migrates data objects and procedures that are configured on the article in the appdesigner over to `resources.yaml`. The article's data sources and their fields are read from the CMS, converted to `resources.yaml` entries, and the output files are generated.
-
-Each migrated view/procedure is also registered as a Data API resource if needed (the same thing `af resources add` does), because `af.data.generateApiDataObject` and `af.ProcedureAPI` go through `/api/data` instead of the article's data sources.
-
-```sh
-# migrate everything on the article
-appframe-vite resources migrate
-# migrate a single data object or procedure
-appframe-vite resources migrate dsVouchers
-# preview without changing anything
-appframe-vite resources migrate --dry-run
-```
-
-Options:
-
-| Option                   | Description                                                    |
-| ------------------------ | -------------------------------------------------------------- |
-| `-c, --config <path>`    | Path to the resources config file (default: `resources.yaml`)  |
-| `-o, --output-dir <dir>` | Directory for the generated files (default: `src/data`)        |
-| `--dry-run`              | Show what would be migrated without writing anything           |
-| `--no-generate`          | Only update `resources.yaml`, do not generate the output files |
-
-Existing `resources.yaml` entries with the same id are updated in place. Field aliases have no `resources.yaml` equivalent and are reported as warnings.
-
-After migrating, import the generated files from your app, remove the data objects and procedures from the article in the appdesigner, and run `pnpm generate-types`.
-
-## `resources.yaml` config file
-
-Place `resources.yaml` at the project root to declare all data objects and procedures for an app. The Vite dev server watches this file and auto-regenerates all output files when it changes.
-
-**Example:**
-
-```yaml
-dataObjects:
-  - id: dsAccountGroups
-    resource: atbv_Accounting_SubsidiaryLedgerGroups
-    global: true
-    types: true
-    maxRecords: -1
-    expose: true
-    fields:
-      - Domain
-      - SubsidiaryLedgerGroup
-      - PrimKey
-      - Description
-    output: src/data/dsAccountGroups.ts
-
-  - id: dsSubsidiaryLedger
-    resource: atbv_Accounting_SubsidiaryLedger
-    global: true
-    types: true
-    permissions: IUD
-    output: src/data/dsSubsidiaryLedger.ts
-
-  - id: dsProjectLocations
-    resource: aviw_Accounting_ProjectsLocations
-    global: true
-    types: true
-    master: dsProjects
-    linkFields:
-      - Domain
-      - ProjectID
-    output: src/data/dsProjectLocations.ts
-
-procedures:
-  - id: procCreateCustomer
-    resource: astp_Accounting_SubsidiaryLedger_Create
-    global: true
-    types: true
-    expose: true
-    output: src/data/procCreateCustomer.ts
-```
-
-**Supported fields per entry:**
-
-| Field         | Type                 | Description                                                                     |
-| ------------- | -------------------- | ------------------------------------------------------------------------------- |
-| `id`          | `string`             | Variable name used in generated code (e.g. `dsAccountGroups`)                   |
-| `resource`    | `string`             | Database object ID (e.g. `atbv_Accounting_SubsidiaryLedgerGroups`)              |
-| `output`      | `string`             | Output file path relative to project root                                       |
-| `global`      | `boolean`            | Use `af.data.generateApiDataObject` / `new af.ProcedureAPI` globals             |
-| `types`       | `boolean`            | Emit TypeScript type definitions                                                |
-| `permissions` | `string`             | Permissions: I = insert, U = update, D = delete (e.g. `IUD`)                    |
-| `maxRecords`  | `number`             | Max records to fetch (default `50`; `-1` for all)                               |
-| `sortOrder`   | `string \| string[]` | Sort order, e.g. `Created:Desc` or `[Created:Desc, Name]`                       |
-| `master`      | `string`             | Master data object name (or `name:importPath`)                                  |
-| `linkFields`  | `string \| string[]` | Fields linking child to master                                                  |
-| `expose`      | `boolean \| string`  | Expose on `af.article.dataObjects` / `af.article.procedures`                    |
-| `dynamic`     | `boolean`            | Enable dynamic loading                                                          |
-| `unique`      | `string`             | Unique table name for update/delete                                             |
-| `overrides`   | `string \| string[]` | Type overrides, e.g. `MyField:string[]`                                         |
-| `distinct`    | `boolean`            | Fetch distinct rows                                                             |
-| `aggregates`  | `string \| string[]` | Aggregate bindings, e.g. `Qty:SUM`                                              |
-| `groupBy`     | `string \| string[]` | Group-by fields                                                                 |
-| `where`       | `string`             | Initial where clause                                                            |
-| `fields`      | `string \| string[]` | Fields to include (all if omitted)                                              |
-| `transaction` | `boolean`            | Procedures only. `false` stops the framework wrapping the call in a transaction |
-| `timeout`     | `number`             | Procedures only. Milliseconds before the call is abandoned (default `30000`)    |
-| `returnType`  | `object[] \| string` | Procedures only. The result type; see below                                     |
-
-A top-level `server` key can override the hostname (defaults to `appframe.proxy.hostname` from `package.json`).
-
-**Master/child relationships:** set both `master` and `linkFields` on the child object. The generated data object will include `masterDataObject` and `linkFields` in the `generateApiDataObject(...)` options.
-
-**Procedure result types:** the server only describes a procedure's parameters, so its result is
-typed `{ Table?: unknown[] }` unless `returnType` says otherwise. Never type the result by editing
-the generated file — every regeneration (a `resources.yaml` change seen by the dev server, a
-`git pull --rebase` that touches it, `resources generate`) writes the file from scratch. With
-`returnType` (and `types: true`) the generated file exports the type under the procedure's name,
-next to the parameters type — `procIndexDNA` gets `IndexDNAParams` and `IndexDNAResult` — so
-components import it from the generated file.
-
-`returnType` is either a list of result sets, in the order the procedure returns them (`Table`,
-`Table1`, …; `table` overrides the key), with each field's TypeScript type:
-
-```yaml
-procedures:
-  - id: procIndexDNA
-    resource: astp_Operations_IndexDNA
-    global: true
-    types: true
-    returnType:
-      - fields:
-          - name: IndexName
-            type: string
-          - name: CurrentFF
-            type: number
-      - fields:
-          - name: PageSort
-            type: number
-    output: src/features/IndexDetails/procIndexDNA.ts
-```
-
-or a TypeScript type written out as a string, for anything the list cannot express. It may refer
-to types in the app's `custom.d.ts` through the `Custom.` prefix, which adds the import:
-
-```yaml
-returnType: "Custom.IndexDNAResult"
-```
-
-`procedureReturnTypes` in `types.json`, keyed by the procedure's database name, does the same
-and is used when the entry has no `returnType`.
-
-## `@olenbetong/appframe-vite/resources` export
-
-Shared code generation utilities for Node.js consumers:
-
-```ts
-import {
-	fetchAndGenerate,
-	buildYamlConfig,
-	parseYamlConfig,
-	writeGeneratedFile,
-	getCustomImportPath,
-	type CLIOptions,
-} from "@olenbetong/appframe-vite/resources";
-```
+# @olenbetong/appframe-vite
+
+Tools to develop and build Vite applications that run inside Appframe articles.
+
+- Provides a Vite plugin you add in `vite.config.*`.
+- Proxies API and static routes to an Appframe server during `pnpm start`.
+- Logs in automatically and refreshes the session on an interval.
+- Serves real article HTML from Appframe in dev, but swaps production assets for your local entry.
+- Caches i18n strings locally to speed up development loads.
+- Shapes production builds to Appframe paths and filenames, with optional React externals.
+
+## Installation
+
+```sh
+pnpm add -D @olenbetong/appframe-vite
+```
+
+## Usage (Vite)
+
+```ts
+// vite.config.mjs or vite.config.ts
+import appframe from "@olenbetong/appframe-vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [appframe()],
+});
+```
+
+Then run your app:
+
+```sh
+pnpm --filter <app> start
+```
+
+The dev server logs in with the credentials `@olenbetong/appframe-auth` finds for the site:
+`APPFRAME_LOGIN_<ENV>` / `APPFRAME_PWD_<ENV>`, then `APPFRAME_LOGIN` / `APPFRAME_PWD`, then the
+password `af auth <env>` saved in the OS keychain. It never asks for one; without credentials it
+stops and says which `af auth` to run.
+
+On first run, the plugin logs in, configures Vite’s proxy for Appframe routes, and serves the article HTML with your local entry injected.
+
+### MUI X license key
+
+The plugin injects the MUI X Premium license key into the bundle as the global `__MUI_X_LICENSE_KEY__`, for both `serve` and `build`. `@olenbetong/appframe-ds/grid` reads it and registers the license itself, so an app using the Designsystemet `AfGrid` does not need its own `LicenseInfo.setLicenseKey()` call.
+
+The key is resolved from, in order:
+
+1. the `MUI_X_LICENSE_KEY` environment variable (CI, a local `.env`, or the shell),
+2. the `MUI_X_LICENSE_KEY` constant declared in the app's `src/shared/licenses.ts`.
+
+The fallback keeps existing apps working with no changes; setting the environment variable is the forward path for getting the key out of the repository.
+
+## Project configuration (package.json)
+
+This package reads `package.json.appframe` to know what to proxy and how to build.
+
+```jsonc
+{
+	"appframe": {
+		"article": {
+			"id": "my-article", // Required
+			"altNames": ["my-article-dev"], // Optional: alternate root paths
+		},
+		"deploy": { "hostname": "dev.obet.no" }, // Default server if proxy not set
+		"proxy": {
+			"hostname": "dev.obet.no", // Optional override for dev proxy
+			"routes": ["^/custom/.*"], // Optional: extra proxied routes
+		},
+		"build": {
+			"platform": true, // Import React and the af packages from the site's platform bundle
+			"externals": true, // Legacy: map React and ReactDOM to globals
+		},
+	},
+}
+```
+
+### `build.platform`
+
+Apps on the 2026 site templates (`ob.2026.application`) set `"platform": true`. The production
+build then leaves `react`, `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`,
+`react-dom/client`, `@olenbetong/appframe-core` and `@olenbetong/appframe-data` as bare imports,
+which the template's import map resolves to `@olenbetong/synergi-platform` — one cached React
+per page, shared with the site chrome. The `af.data` global redirect (`dataGlobal`) then only
+applies to the dev server, which has no import map. The build also writes `dist/platform.json`
+with the platform version the app was built alongside (the workspace's
+`packages/synergi-platform`) and the versions it compiled against; `scripts/app-deploy.ts` pins
+the article to that platform version (its `PlatformHead` and `PlatformStyles` blocks) and
+refuses to deploy when the article is not on a 2026 template, that version is not served on the
+target site, or its manifest carries other versions than the app (override with
+`--allow-platform-mismatch`).
+
+## What it does (at a glance)
+
+- Dev server
+  - Proxies Appframe routes (e.g. `/api`, `/file`, `/lib`, etc.) to the configured hostname.
+  - Performs an initial login and refreshes the session every 5 minutes to prevent 403 errors.
+  - Serves the real article HTML from Appframe, but removes production assets and injects your local entry (`/src/index.*`).
+  - Caches localized strings under `node_modules/.appframe/localizeCache.json` and injects them into the page to avoid many small HTTP 1.1 requests.
+- Build
+  - Enables `manifest` and `sourcemap`.
+  - Writes filenames to Appframe paths, using the article ID, e.g.:
+    - `file/article/script/<ARTICLE_ID>/main.[hash].min.js`
+    - `file/article/style/<ARTICLE_ID>/style.[hash].min.css`
+  - With `build.platform`, leaves React and the af packages as bare imports for the template's import map and writes `dist/platform.json`; the legacy `build.externals` maps `react` and `react-dom` to `React` and `ReactDOM` globals instead.
+  - Adds a Rollup visualizer report at `dist/stats.html`.
+- Resolve
+  - Adds the alias `~/` to `/src/` so imports like `~/components/Button` resolve to `src/components/Button`.
+- DevTools API (see below)
+
+## DevTools
+
+In dev mode the plugin exposes a small JSON API at `/__appframe_devtools__/api` for the **Appframe DevTools
+browser extension** (`packages/appframe-devtools` in the SynergiWeb repo). The extension adds an "Appframe"
+panel to Chrome/Edge DevTools with a live view of the app's data objects, an editor for `resources.yaml`
+and a browser for the data API catalog. Nothing is injected into the page — the toolbar that older
+versions added to every dev-served page is gone.
+
+| Endpoint                    | Purpose                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `GET /api/config`           | Discovery: `{ appframe: true, apiVersion, hostname, articleId, articleHostname, appName, appVersion, pluginVersion }` |
+| `GET /api/resources`        | Parsed `resources.yaml`                                                                                               |
+| `POST /api/resources`       | Add an entry (`type: "dataObject" \| "procedure"` plus the entry fields)                                              |
+| `PUT /api/resources/:id`    | Replace an entry                                                                                                      |
+| `DELETE /api/resources/:id` | Remove an entry and its generated output file                                                                         |
+| `POST /api/catalog`         | Register a `dbObjectId` as a data API resource on dev, stage and prod                                                 |
+| `GET /api/release`          | Current session (`session: null` when none) and the capabilities derived from the app's scripts                       |
+| `POST /api/release`         | Start a job: `{ kind: "release", dry?, force? }` or `{ kind: "deploy", target, copyDatasources? }`; 409 while running |
+| `DELETE /api/release`       | Cancel the running job                                                                                                |
+| `POST /api/release/input`   | Answer one of the script's questions (`{ name, value }`: the release type and notes, or the apply confirmation)       |
+| `GET /api/release/events`   | Server-sent events: the session snapshot, then every step, log line and question as it happens                        |
+
+The release job runs whatever `scripts.release` is in the app's package.json, from the app directory, with
+`--ui` appended. The deploy job runs `pnpm run build`, optionally `pnpm run cd` (or `copy-datasources`) and
+`pnpm run deploy` with `APPFRAME_DEPLOY_HOSTNAME` set to the target, which `app-deploy.ts` and
+`app-copy-datasources.ts` honour over the hostnames in package.json. The script is expected to follow the protocol in `scripts/lib/releaseUi.ts` (JSON event lines
+prefixed with `@@appframe-devtools ` on stdout, answers as JSON lines on stdin).
+
+Disable it with `appframe({ devtools: false })` when there is no article context (Storybook does this).
+The extension page has host permissions for `localhost`, so the API needs no CORS headers.
+
+## CLI — `appframe-vite`
+
+The package ships a CLI (`appframe-vite`) alongside the Vite plugin.
+
+### `generate-types`
+
+Generates TypeScript type definitions from the article's data objects and procedures:
+
+```sh
+appframe-vite generate-types
+```
+
+### `resources generate`
+
+Reads `resources.yaml` and regenerates all data object / procedure files:
+
+```sh
+appframe-vite resources generate
+# custom config file path:
+appframe-vite resources generate --config path/to/resources.yaml
+```
+
+### `resources add`
+
+Interactive wizard — prompts for resource, ID, output path, permissions, fields, and more, then appends an entry to `resources.yaml` and generates the output file:
+
+```sh
+appframe-vite resources add
+```
+
+### `resources edit [id]`
+
+Interactive editor — pre-fills the wizard with the current values from `resources.yaml` and regenerates the file on save:
+
+```sh
+appframe-vite resources edit dsAccountGroups
+# or without an id (shows a searchable list):
+appframe-vite resources edit
+```
+
+### `resources migrate [id]`
+
+Migrates data objects and procedures that are configured on the article in the appdesigner over to `resources.yaml`. The article's data sources and their fields are read from the CMS, converted to `resources.yaml` entries, and the output files are generated.
+
+Each migrated view/procedure is also registered as a Data API resource if needed (the same thing `af resources add` does), because `af.data.generateApiDataObject` and `af.ProcedureAPI` go through `/api/data` instead of the article's data sources.
+
+```sh
+# migrate everything on the article
+appframe-vite resources migrate
+# migrate a single data object or procedure
+appframe-vite resources migrate dsVouchers
+# preview without changing anything
+appframe-vite resources migrate --dry-run
+```
+
+Options:
+
+| Option                   | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| `-c, --config <path>`    | Path to the resources config file (default: `resources.yaml`)  |
+| `-o, --output-dir <dir>` | Directory for the generated files (default: `src/data`)        |
+| `--dry-run`              | Show what would be migrated without writing anything           |
+| `--no-generate`          | Only update `resources.yaml`, do not generate the output files |
+
+Existing `resources.yaml` entries with the same id are updated in place. Field aliases have no `resources.yaml` equivalent and are reported as warnings.
+
+After migrating, import the generated files from your app, remove the data objects and procedures from the article in the appdesigner, and run `pnpm generate-types`.
+
+## `resources.yaml` config file
+
+Place `resources.yaml` at the project root to declare all data objects and procedures for an app. The Vite dev server watches this file and auto-regenerates all output files when it changes.
+
+**Example:**
+
+```yaml
+dataObjects:
+  - id: dsAccountGroups
+    resource: atbv_Accounting_SubsidiaryLedgerGroups
+    global: true
+    types: true
+    maxRecords: -1
+    expose: true
+    fields:
+      - Domain
+      - SubsidiaryLedgerGroup
+      - PrimKey
+      - Description
+    output: src/data/dsAccountGroups.ts
+
+  - id: dsSubsidiaryLedger
+    resource: atbv_Accounting_SubsidiaryLedger
+    global: true
+    types: true
+    permissions: IUD
+    output: src/data/dsSubsidiaryLedger.ts
+
+  - id: dsProjectLocations
+    resource: aviw_Accounting_ProjectsLocations
+    global: true
+    types: true
+    master: dsProjects
+    linkFields:
+      - Domain
+      - ProjectID
+    output: src/data/dsProjectLocations.ts
+
+procedures:
+  - id: procCreateCustomer
+    resource: astp_Accounting_SubsidiaryLedger_Create
+    global: true
+    types: true
+    expose: true
+    output: src/data/procCreateCustomer.ts
+```
+
+**Supported fields per entry:**
+
+| Field         | Type                 | Description                                                                     |
+| ------------- | -------------------- | ------------------------------------------------------------------------------- |
+| `id`          | `string`             | Variable name used in generated code (e.g. `dsAccountGroups`)                   |
+| `resource`    | `string`             | Database object ID (e.g. `atbv_Accounting_SubsidiaryLedgerGroups`)              |
+| `output`      | `string`             | Output file path relative to project root                                       |
+| `global`      | `boolean`            | Use `af.data.generateApiDataObject` / `new af.ProcedureAPI` globals             |
+| `types`       | `boolean`            | Emit TypeScript type definitions                                                |
+| `permissions` | `string`             | Permissions: I = insert, U = update, D = delete (e.g. `IUD`)                    |
+| `maxRecords`  | `number`             | Max records to fetch (default `50`; `-1` for all)                               |
+| `sortOrder`   | `string \| string[]` | Sort order, e.g. `Created:Desc` or `[Created:Desc, Name]`                       |
+| `master`      | `string`             | Master data object name (or `name:importPath`)                                  |
+| `linkFields`  | `string \| string[]` | Fields linking child to master                                                  |
+| `expose`      | `boolean \| string`  | Expose on `af.article.dataObjects` / `af.article.procedures`                    |
+| `dynamic`     | `boolean`            | Enable dynamic loading                                                          |
+| `unique`      | `string`             | Unique table name for update/delete                                             |
+| `overrides`   | `string \| string[]` | Type overrides, e.g. `MyField:string[]`                                         |
+| `distinct`    | `boolean`            | Fetch distinct rows                                                             |
+| `aggregates`  | `string \| string[]` | Aggregate bindings, e.g. `Qty:SUM`                                              |
+| `groupBy`     | `string \| string[]` | Group-by fields                                                                 |
+| `where`       | `string`             | Initial where clause                                                            |
+| `fields`      | `string \| string[]` | Fields to include (all if omitted)                                              |
+| `transaction` | `boolean`            | Procedures only. `false` stops the framework wrapping the call in a transaction |
+| `timeout`     | `number`             | Procedures only. Milliseconds before the call is abandoned (default `30000`)    |
+| `returnType`  | `object[] \| string` | Procedures only. The result type; see below                                     |
+
+A top-level `server` key can override the hostname (defaults to `appframe.proxy.hostname` from `package.json`).
+
+**Master/child relationships:** set both `master` and `linkFields` on the child object. The generated data object will include `masterDataObject` and `linkFields` in the `generateApiDataObject(...)` options.
+
+**Procedure result types:** the server only describes a procedure's parameters, so its result is
+typed `{ Table?: unknown[] }` unless `returnType` says otherwise. Never type the result by editing
+the generated file — every regeneration (a `resources.yaml` change seen by the dev server, a
+`git pull --rebase` that touches it, `resources generate`) writes the file from scratch. With
+`returnType` (and `types: true`) the generated file exports the type under the procedure's name,
+next to the parameters type — `procIndexDNA` gets `IndexDNAParams` and `IndexDNAResult` — so
+components import it from the generated file.
+
+`returnType` is either a list of result sets, in the order the procedure returns them (`Table`,
+`Table1`, …; `table` overrides the key), with each field's TypeScript type:
+
+```yaml
+procedures:
+  - id: procIndexDNA
+    resource: astp_Operations_IndexDNA
+    global: true
+    types: true
+    returnType:
+      - fields:
+          - name: IndexName
+            type: string
+          - name: CurrentFF
+            type: number
+      - fields:
+          - name: PageSort
+            type: number
+    output: src/features/IndexDetails/procIndexDNA.ts
+```
+
+or a TypeScript type written out as a string, for anything the list cannot express. It may refer
+to types in the app's `custom.d.ts` through the `Custom.` prefix, which adds the import:
+
+```yaml
+returnType: "Custom.IndexDNAResult"
+```
+
+`procedureReturnTypes` in `types.json`, keyed by the procedure's database name, does the same
+and is used when the entry has no `returnType`.
+
+## `@olenbetong/appframe-vite/resources` export
+
+Shared code generation utilities for Node.js consumers:
+
+```ts
+import {
+	fetchAndGenerate,
+	buildYamlConfig,
+	parseYamlConfig,
+	writeGeneratedFile,
+	getCustomImportPath,
+	type CLIOptions,
+} from "@olenbetong/appframe-vite/resources";
+```

package/lib/appEntry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolves the app's entry module. Apps have no `index.html`: the dev server fetches the
+ * article's HTML from Synergi and injects a `<script type="module">` pointing at this file,
+ * and the production build uses it as the single rolldown input.
+ *
+ * `relative` is a POSIX path from the root, usable as a glob pattern (`optimizeDeps.entries`
+ * takes globs, and an absolute Windows path would be read as one with escapes in it).
+ * The last candidate is returned even when it does not exist, so a missing entry fails
+ * with a resolve error that names the file instead of a vaguer one later on.
+ */
+export declare function getAppEntry(root?: string): {
+    absolute: string;
+    relative: string;
+    url: string;
+};

package/lib/appEntry.js

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/** The entry file candidates, in the order they are tried, relative to the app root. */
+const ENTRY_CANDIDATES = ["src/index.tsx", "src/index.ts", "src/index.js"];
+/**
+ * Resolves the app's entry module. Apps have no `index.html`: the dev server fetches the
+ * article's HTML from Synergi and injects a `<script type="module">` pointing at this file,
+ * and the production build uses it as the single rolldown input.
+ *
+ * `relative` is a POSIX path from the root, usable as a glob pattern (`optimizeDeps.entries`
+ * takes globs, and an absolute Windows path would be read as one with escapes in it).
+ * The last candidate is returned even when it does not exist, so a missing entry fails
+ * with a resolve error that names the file instead of a vaguer one later on.
+ */
+export function getAppEntry(root = process.cwd()) {
+    let found = ENTRY_CANDIDATES.find((candidate) => existsSync(resolve(root, candidate)));
+    let relative = found ?? ENTRY_CANDIDATES[ENTRY_CANDIDATES.length - 1];
+    return { absolute: resolve(root, relative), relative, url: `/${relative}` };
+}

package/lib/appframeDataGlobal.js

@@ -19,6 +19,8 @@ export const GLOBAL_EXPORTS = [
     "Procedure",
     "ProcedureAPI",
     "SortOrder",
+    "UploadManager",
+    "UploadTask",
     "generateApiDataHandler",
     "generateApiDataObject",
     "getDefaultClient",

package/lib/build.js

@@ -1,8 +1,8 @@
-import { existsSync } from "node:fs";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { visualizer } from "rollup-plugin-visualizer";
 import { esmExternalRequirePlugin } from "vite";
+import { getAppEntry } from "./appEntry.js";
 import { importJson } from "./importJson.js";
 /**
  * The bare specifiers the 2026 site templates resolve through their import map to the
@@ -202,16 +202,9 @@ export async function addAppframeBuildConfig(config) {
         sourcemap: true,
     };
     config.plugins = config.plugins ?? [];
-    let entry = resolve(process.cwd(), "./src/index.tsx");
-    if (!existsSync(resolve(entry))) {
-        entry = resolve(process.cwd(), "./src/index.ts");
-    }
-    if (!existsSync(resolve(entry))) {
-        entry = resolve(process.cwd(), "./src/index.js");
-    }
     config.appType = "custom";
     config.build.rolldownOptions = {
-        input: { main: entry },
+        input: { main: getAppEntry().absolute },
         plugins: [
             // Cast visualizer plugin to any to avoid Rollup type version clashes
             visualizer({ filename: "./dist/stats.html", gzipSize: true }),

package/lib/cli-resources-migrate.js

@@ -182,6 +182,10 @@ function dataObjectToEntry(datasource, fields, outputDir, warnings) {
     if (sortFields.length > 0) {
         entry.sortOrder = sortFields.map((f) => {
             let direction = (f.AscDesc ?? "asc").toLowerCase();
+            // Keep the null placement of AscNullsLast / DescNullsFirst
+            if (direction === "ascnullslast" || direction === "descnullsfirst") {
+                return { field: f.FieldName, direction };
+            }
             return direction.startsWith("desc") ? { field: f.FieldName, direction: "desc" } : { field: f.FieldName };
         });
     }

package/lib/devServer.js

@@ -5,6 +5,7 @@ import { AuthenticationError, authenticate, loginHint, resolveCredentials } from
 import { Client } from "@olenbetong/appframe-data";
 import dotenv from "dotenv";
 import { JSDOM } from "jsdom";
+import { getAppEntry } from "./appEntry.js";
 import { importJson } from "./importJson.js";
 import { getStringCache } from "./localization.js";
 import { diagnoseServerResponse } from "./utils.js";
@@ -68,16 +69,7 @@ export function getProxyRoutes() {
  * @returns
  */
 async function transformArticleHtml(html) {
-    let entry;
-    if (existsSync(resolve(process.cwd(), "./src/index.tsx"))) {
-        entry = "/src/index.tsx";
-    }
-    else if (existsSync(resolve(process.cwd(), "./src/index.ts"))) {
-        entry = "/src/index.ts";
-    }
-    else {
-        entry = "/src/index.js";
-    }
+    let entry = getAppEntry().url;
     let article = appframe.article?.id;
     let { hostname } = await getAppHostname();
     let dom = new JSDOM(html);

package/lib/index.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import bodyParser from "body-parser";
 import { watch } from "chokidar";
+import { getAppEntry } from "./appEntry.js";
 import { appframeDataGlobal } from "./appframeDataGlobal.js";
 import { addAppframeBuildConfig, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, usesPlatform, } from "./build.js";
 import { generateFromConfig } from "./cli-resources-generate.js";
@@ -184,6 +185,19 @@ export default function appframe(options = {}) {
                     ...config.server,
                     proxy,
                 };
+                // Apps have no index.html, so the dependency scanner Vite runs at startup has
+                // nothing to crawl (it globs "**/*.html") and skips pre-bundling altogether. Every
+                // dependency is then discovered when a module first imports it: the ones behind
+                // the initial page load are batched, but a lazy route that pulls in a new one
+                // re-runs the optimizer and forces a full reload, which lands back on the page
+                // you navigated from. Crawling from the entry module finds the lazy imports up
+                // front, so the deps are ready before the browser asks for them.
+                if (!config.optimizeDeps?.entries) {
+                    config.optimizeDeps = {
+                        ...config.optimizeDeps,
+                        entries: [getAppEntry().relative],
+                    };
+                }
             }
             return config;
         },

package/lib/resourceGenerate.d.ts

@@ -32,6 +32,8 @@ export type CLIOptions = {
     output?: string;
     typesJsonParamOverrides?: Record<string, string>;
     typesJsonReturnType?: string | null;
+    /** Columns of the `unique` table; fields outside it are marked ignored so saves skip them. */
+    uniqueFields?: string[];
 };
 /**
  * Serialize the generation options to a `/* af:config ... *\/` YAML comment block.

package/lib/resourceGenerate.js

@@ -169,6 +169,13 @@ export function parseYamlConfig(fileContent) {
 // ---------------------------------------------------------------------------
 // Code generation helpers
 // ---------------------------------------------------------------------------
+/**
+ * A field name as an object key in generated code, quoted when it is not a valid identifier,
+ * such as a view column named `EU-Neste`.
+ */
+function propertyKey(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
 /**
  * Convert Appframe (SQL) data types to typescript/field definition types
  */
@@ -361,6 +368,9 @@ export function getDataObjectDefinition(name, viewDefinition, options) {
         if (field.Identity) {
             fieldDefinition.identity = true;
         }
+        if (options.uniqueFields && !options.uniqueFields.includes(field.Name)) {
+            fieldDefinition.ignored = true;
+        }
         if (aggregates[field.Name]) {
             fieldDefinition.aggregate = aggregates[field.Name];
         }
@@ -394,7 +404,7 @@ export function getDataObjectDefinition(name, viewDefinition, options) {
                     type += " | null";
                 }
             }
-            fieldTypes += `  ${field.name}: ${type};\n`;
+            fieldTypes += `  ${propertyKey(field.name)}: ${type};\n`;
         }
         types = `export type ${typeName} = {
 ${fieldTypes}}`;
@@ -465,7 +475,7 @@ ${fieldTypes}}`;
                     order = "DescNullsFirst";
                     break;
             }
-            return `{ ${field}: ${sortPrefix}${order} }`;
+            return `{ ${propertyKey(field)}: ${sortPrefix}${order} }`;
         })
             .join(", ");
         parametersOption.push(`sortOrder: [${sortOrder}]`);
@@ -553,6 +563,17 @@ export async function fetchAndGenerate(resourceName, options, client) {
     options.typesJsonParamOverrides = typesJson.parameterTypes?.[resourceName] ?? {};
     // Structured returnType from resources.yaml takes precedence over the raw types.json string
     options.typesJsonReturnType = options.typesJsonReturnType ?? typesJson.procedureReturnTypes?.[resourceName] ?? null;
+    // A view saved through another table (`unique`) usually carries joined columns that table
+    // lacks. CMS data objects know to leave those out of a save; mark them ignored so these do too.
+    if (definition.ObjectType === "V" && options.unique) {
+        try {
+            let uniqueDefinition = await fetchResourceDefinition(client, options.unique);
+            options.uniqueFields = (uniqueDefinition.Parameters ?? []).map((p) => p.Name);
+        }
+        catch (error) {
+            console.warn(`Could not read the unique table '${options.unique}' for '${resourceName}', so no fields are marked ignored: ${error instanceof Error ? error.message.split(" — ")[0] : error}`);
+        }
+    }
     return definition.ObjectType === "V"
         ? getDataObjectDefinition(resourceName, definition, options)
         : getProcedureDefinition(resourceName, definition, options);

package/lib/uniqueIgnoredFields.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/uniqueIgnoredFields.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { getDataObjectDefinition } from "./resourceGenerate.js";
+import { entryToCLIOptions } from "./resourcesConfig.js";
+const definition = {
+    ObjectType: "V",
+    Parameters: [
+        { Name: "PrimKey", DataType: "uniqueidentifier", Nullable: false },
+        { Name: "ProjectID", DataType: "nvarchar", Nullable: false },
+        { Name: "ProjectName", DataType: "nvarchar", Nullable: true },
+    ],
+};
+function generate(uniqueFields) {
+    let options = entryToCLIOptions({
+        id: "dsPlans",
+        resource: "aviw_Production_Plans",
+        unique: "atbv_Production_Plans",
+        output: "src/dsPlans.ts",
+        global: true,
+        permissions: "IUD",
+    }, "example.com");
+    options.uniqueFields = uniqueFields;
+    return getDataObjectDefinition("aviw_Production_Plans", definition, options);
+}
+describe("fields outside the unique table", () => {
+    it("marks joined fields ignored so saves leave them out", () => {
+        let output = generate(["PrimKey", "ProjectID"]);
+        expect(output).toMatch(/"name": "ProjectName",[^}]*"ignored": true/);
+        expect(output).not.toMatch(/"name": "ProjectID",[^}]*"ignored": true/);
+    });
+    it("marks nothing when the unique table could not be read", () => {
+        expect(generate(undefined)).not.toContain('"ignored"');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-vite",
-  "version": "6.15.0",
+  "version": "6.17.0",
   "description": "Tools to use and deploy Vite applications to Appframe",
   "main": "./lib/index.js",
   "type": "module",
@@ -30,24 +30,24 @@
   "license": "MIT",
   "dependencies": {
     "@olenbetong/appframe-auth": "^0.1.0",
-    "@olenbetong/appframe-data": "^1.8.2",
+    "@olenbetong/appframe-data": "^1.8.4",
     "body-parser": "^2.3.0",
     "chalk": "6.0.1",
     "chokidar": "^5.0.0",
     "commander": "15.0.0",
-    "dotenv": "^18.0.4",
+    "dotenv": "^18.0.8",
     "fuzzy": "^0.1.3",
-    "inquirer": "^14.2.2",
+    "inquirer": "^14.2.4",
     "inquirer-autocomplete-standalone": "^0.8.1",
-    "jsdom": "30.1.1",
+    "jsdom": "30.1.3",
     "rollup-plugin-visualizer": "^7.1.1",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/jsdom": "^30.0.0",
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
-    "vite": "8.3.1"
+    "vite": "8.3.5"
   },
   "peerDependencies": {
     "vite": ">=8.1.5"