@diagonal-hq/cli 0.4.1 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 This package is the authoring SDK for file-based workspaces. A workspace repository installs it as a dev dependency. It gives these things:
 
-- The configuration helpers: `defineConfig`, `defineResource`, `definePage`, `defineNavigation`, `defineNotificationType`, `defineNotificationTemplate`, `defineEmailLayout`, and the `field` builders. Each `define*` function returns its first argument. Each `field.<type>(options)` call returns `{ $field, ...options }`, where `$field` is the stored field type. The package root exports them as ESM JavaScript with declarations, so a Vite build or a Node script can import a configuration file.
+- The configuration helpers: `defineConfig`, `defineResource`, `definePage`, `defineNavigation`, `defineAssets`, `asset.version`, `defineNotificationType`, `defineNotificationTemplate`, `defineEmailLayout`, and the `field` builders. Each `define*` function returns its first argument. Each `field.<type>(options)` call returns `{ $field, ...options }`, where `$field` is the stored field type. The package root exports them as ESM JavaScript with declarations, so a Vite build or a Node script can import a configuration file.
 - Types for the helpers, `WorkflowConfig`, and the `Sdk` and `React` globals.
 - Editor types for the workflow script SDK: `@diagonal/workflow`, `@diagonal/workflow/testing`, and `@diagonal/workflow/workspace`.
 - The `diagonal check` command. It runs the same build and checks that a platform deploy runs, including the workflow tests.
@@ -55,7 +55,7 @@ The build reads each file with a parser. It runs only the workflow tests.
 - Each `workflows/<name>.ts` is a script workflow. It has one `export const config = { title, trigger, runAs? } satisfies WorkflowConfig` and one `export default defineWorkflow(...)`. The config must be a static literal. The build validates it: the trigger fields, the resources (see [Resource references](#resource-references)), the workflow paths of `workflowEvent` triggers, and the run-as rules. A `recordEvent`, `recordSchedule`, `scheduled`, or `workflowEvent` workflow needs `runAs`.
 - The build removes the config and the `@diagonal-hq/cli` imports from the workflow, with spaces in their place, and compiles the rest with the workflow script compiler against the workspace resources. A compiler error has the line and column of the workflow file.
 - `workflows/<name>.test.ts` tests `workflows/<name>.ts` with `node:test` and `node:assert`. It imports the workflow, `runWorkflow` and `MockTransport` from `@diagonal/workflow/testing`, and `Resources` from `@app/generated/resources`. The build transpiles the test and the workflows and runs them in one Node process. The process can read only its own temporary directory, cannot start processes, and has an empty environment. Each failing test is an error at the test. A test file without a workflow is an error.
-- The build ignores the files at the root other than `diagonal.config.ts`, dotfiles, and `node_modules`. It does not build the files in `generated/`, but it checks `generated/resources.ts`.
+- The build ignores the files at the root other than `diagonal.config.ts` and `assets.ts`, dotfiles, and `node_modules`. It does not build the files in `generated/`, but it checks `generated/resources.ts`.
 
 - The build does not read `notifications/` or `email-layouts/` yet. The editor type-checks the shape of their definitions. See [Notifications](#notifications).
 
@@ -250,6 +250,24 @@ export default defineResource({
 
 A workflow script reads the capabilities of each resource from `@diagonal/workflow/workspace`. An input that needs a capability, such as the `resource` of `notification.setConsent`, accepts only a resource that declares it.
 
+## Application asset references
+
+Upload an image in two steps. `POST /api/files/uploads` with a multipart `file` returns `{key}`. `POST /api/application-assets` with `{"upload_key": "<key>"}` then returns the asset and its immutable version `reference`. Declare it in the optional root `assets.ts`:
+
+```ts
+import { defineAssets, asset } from '@diagonal-hq/cli';
+
+export default defineAssets({
+  hero: asset.version('0199f000-0000-7000-8000-000000000001')
+});
+```
+
+Use `background: url(asset:hero)` in a CSS file. The hosted build replaces it with the version's delivery URL and records its verified digest in the deployment manifest. SVG and font uploads are not supported yet.
+
+`diagonal check` validates this file offline. Each key must be a camelCase name of at most 64 letters and digits that starts with a lowercase letter, such as `hero`; otherwise the check reports `Asset key "<key>" must be a camelCase name ...` at the key. The manifest can have at most 500 entries. Each value must be `asset.version()` with one lower-case UUID string literal written without escapes. The default export must be `defineAssets({...})`. Other calls and non-literal expressions fail at their source location. The hosted build also checks that each version belongs to this application's asset library.
+
+The check follows CSS imports from pages, layouts, and components. An unknown `asset:` key fails with its file, line, and column. `asset:` in `@import` fails. A `url(asset:` value in a TypeScript or TSX module also fails. Move that value to a CSS file.
+
 ## Editor types
 
 A page, layout, component, or workflow can import any other file of the workspace by its path from the root with `@app/`, for example `import { formatPrice } from '@app/lib/money'`. The extension is optional, and a folder's `index` file is found. The build links each imported file into the importing page or workflow, so the files need no folder of their own; a file outside the build's folders, such as `lib/`, is built only when something imports it. An imported module can import other `@app/` files, `@diagonal-hq/cli`, and, in a workflow, `@diagonal/workflow`. Add `"@app/*": ["./*"]` to the `paths` of `tsconfig.json` so the editor resolves them too.