@diagonal-hq/cli 0.2.0 → 0.3.0

package/README.md

@@ -49,15 +49,46 @@ The build reads each file with a parser. It runs only the workflow tests.
 
 - `defineConfig`, `defineResource`, `defineNavigation`, and the first argument of `definePage` must be static literals. The `field.<type>({...})` calls are the only calls that the build accepts in this data.
 - Each `resources/*.ts` file goes through the resource checks in [Resources and fields](#resources-and-fields).
-- The build removes imports from `@diagonal-hq/cli`. Pages, layouts, components, and workflow scripts can import workspace files through `@app/`. Workflow scripts can also import `@diagonal/workflow` and `@diagonal/workflow/workspace`. Other external imports in these source files are rejected.
+- The build removes imports from `@diagonal-hq/cli`. Pages, layouts, components, and workflow scripts can import workspace files through `@app/`. A resource file can import only `@app/generated/resources`. Workflow scripts can also import `@diagonal/workflow` and `@diagonal/workflow/workspace`. Other external imports in these source files are rejected.
 - The second argument of `definePage`, and the default export of a layout or component file, must be one function.
-- Pages, layouts, and components go through the page lint gate: syntax, scope, the component return shape, and a type check against the page Sdk contract and the workspace resources. A page can name a resource by id or by slug, for example `Sdk.resource('members')`.
-- 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 (by slug, name, or id), the workflow paths of `workflowEvent` triggers, and the run-as rules. A `recordEvent`, `recordSchedule`, `scheduled`, or `workflowEvent` workflow needs `runAs`.
+- Pages, layouts, and components go through the page lint gate: syntax, scope, the component return shape, and a type check against the page Sdk contract and the workspace resources. A page names a resource by slug, for example `Sdk.resource(Resources.Members)`.
+- 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 the resource ids from `@diagonal/workflow/workspace`. 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`.
+- `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 does not read `notifications/` or `email-layouts/` yet. The editor type-checks the shape of their definitions. See [Notifications](#notifications).
 
+## Resource references
+
+The file name is the resource slug: `resources/job-postings.ts` declares the resource `job-postings`. A file name must start with a lowercase letter and contain only a-z, 0-9, `_`, and `-`. A resource has no `id` in source. The platform derives the stored id from the workspace and the slug, so each branch and environment has its own ids.
+
+`diagonal check` writes `generated/resources.ts` from the `resources/` folder. Commit the file:
+
+```ts
+// AUTO-GENERATED by `diagonal check`. Do not edit.
+export const Resources = {
+  JobPostings: 'job-postings',
+  User: 'user'
+} as const;
+```
+
+Each property is the studly case of a slug, and its value is the slug. A deploy fails when the file does not match the folder, and the error gives the expected content. Two slugs with the same name, such as `job-postings` and `job_postings`, are an error.
+
+Refer to a resource with `Resources.<Name>` from `@app/generated/resources` everywhere: `field.relation({ resource: Resources.User })`, a workflow `trigger.resource` and `runAs.resource`, a page `authorizer.resource` and `params.<name>.resource`, `Sdk.resource(Resources.User)`, `data.search({ resource: Resources.User })`, and `v.record(Resources.User)`. The build reads `Resources.<Name>` like a literal. An unknown name is an error at its location, and the editor reports it too.
+
+A slug string, such as `resource: 'user'`, builds with a warning. A resource id, a resource name, a singular name, or a slug without a file is an error.
+
+The platform provisions some resources itself, such as the staff resource, the roles, and the permissions. A new repository has a reference file for each one, for example `resources/roles.ts`:
+
+```ts
+import { defineResource } from '@diagonal-hq/cli';
+
+export default defineResource({ platform: true });
+```
+
+The file gives the resource its `Resources` entry, so source names it like any other resource. The platform owns its fields, and the deploy does not change it. The build does not know its fields, so a data call types its records loosely, and a relation to it cannot declare an inverse. A deploy fails when the workspace has no platform resource with the slug of the file.
+
 ## Notifications
 
 A notification has a type, one or more templates, and optionally an email layout. Each definition is a static literal. Its Liquid is inline text or a `.liquid` file next to it, written as `{ file: './standard.email.liquid' }`.
@@ -82,15 +113,16 @@ email-layouts/
 The type sets the recipient resource, the variables, and the default template. The recipient resource maps the email and phone fields. A type without `recipient` sends to email addresses. A variable uses a `field` builder other than `field.relation`, or `{ resource }` for one record of a resource. Templates read a record variable's fields, for example `{{ first_event.name }}`.
 
 ```ts
+import { Resources } from '@app/generated/resources';
 import { defineNotificationType, field } from '@diagonal-hq/cli';
 
 export default defineNotificationType({
   key: 'member-welcome',
   name: 'Member welcome',
-  recipient: { resource: 'members' },
+  recipient: { resource: Resources.Members },
   variables: {
     joined_on: field.date({ label: 'Joined on', required: true }),
-    first_event: { resource: 'events', label: 'First event' }
+    first_event: { resource: Resources.Events, label: 'First event' }
   },
   defaultTemplate: 'standard'
 });
@@ -157,7 +189,7 @@ Fixtures are sample data for previews. They are not tests, and they are never se
 
 ## Resources and fields
 
-`defineResource` takes `id`, `slug`, `name`, `singularName`, `displayField`, `searchableFields`, `fieldOrder`, `fields`, `indexes`, `embeddings`, `dataApi`, `static`, `policies`, and `capabilities`. The build refuses an unknown property, an unknown setting, and a duplicate key, and gives the line and column. It does not remove anything without a diagnostic.
+`defineResource` takes `name`, `singularName`, `displayField`, `searchableFields`, `fieldOrder`, `fields`, `indexes`, `embeddings`, `dataApi`, `static`, `policies`, and `capabilities`. The build refuses an unknown property, an unknown setting, and a duplicate key, and gives the line and column. It does not remove anything without a diagnostic.
 
 - `searchableFields` lists the field keys and relation paths that record search matches, for example `['title', 'author.full_name']`. The build checks each path against the related resources. Without it, search matches the display field and every text and markdown field.
 - `fieldOrder` lists every field key once. It sets the order of the fields in forms and tables. The default is the order of `fields`.
@@ -165,7 +197,7 @@ Fixtures are sample data for previews. They are not tests, and they are never se
 - `dataApi.endpoints` turns off data API endpoints, for example `{ delete_many: { enabled: false } }`. An omitted endpoint stays enabled.
 - `static: true` refuses normal record writes to the resource.
 
-There is one `field.<type>` builder for each resource field type, in camel case: `field.eventSchedule()` stores an `event_schedule` field. `field.file()` stores a `file_reference` field, and `field.longText()` stores a `text` field. `fields.generated.js` implements the builders, `fields.generated.d.ts` declares them, and `field-catalog.json` lists their settings. `npm run generate-types` generates both from the platform field types. Do not edit them.
+There is one `field.<type>` builder for each resource field type, in camel case: `field.eventSchedule()` stores an `event_schedule` field. `field.file()` stores a `file_reference` field, and `field.longText()` stores a `text` field. `fields.generated.d.ts` declares the builders, `fields.generated.js` implements them, and `field-catalog.json` lists their settings. `npm run generate-types` generates the three files from the platform field types. Do not edit them.
 
 A builder takes these options:
 
@@ -176,7 +208,7 @@ A builder takes these options:
 - `getter`: a resolver tree that transforms the stored value when it is read.
 - `setter`: a resolver tree that computes the stored value before each create and update. `setterWhenEmpty: true` runs it only when the value is null or empty.
 
-`field.select` takes `options` and `field.relation` takes `resource` (an id or slug) and `type` as options. Other settings go in `settings`. A setting that an option writes, such as `settings.unique`, is refused. A relation can declare `settings.inverse: { key, label?, settings? }`. The build then adds the inverse relation field to the target resource. A target that declares a field with the same key is an error.
+`field.select` takes `options` and `field.relation` takes `resource` (`Resources.<Name>`) and `type` as options. Other settings go in `settings`. A setting that an option writes, such as `settings.unique`, is refused. A relation can declare `settings.inverse: { key, label?, settings? }`. The build then adds the inverse relation field to the target resource. A target that declares a field with the same key is an error.
 
 The platform deploy validates every field again with the rules of the resource builder, so a value that the build cannot check, such as an unknown guard rule, fails the deploy with the file path.
 
@@ -234,7 +266,7 @@ Add a `tsconfig.json` with `"types": ["@diagonal-hq/cli", "node"]` and `@types/n
 }
 ```
 
-In the editor, `resources` from `@diagonal/workflow/workspace` maps every name to a string, and record data is untyped. `diagonal check` compiles against the workspace resources and their fields.
+In the editor, a data call takes any resource string, and record data is untyped. `Resources` from `@app/generated/resources` catches a wrong resource name. `diagonal check` compiles against the workspace resources and their fields. In a file-based workspace, `@diagonal/workflow/workspace` exports no `resources` map.
 
 `globals.d.ts` at the package root has loose `Sdk` and `React` types. The source `index.d.ts` uses them before the package is built.