@diagonal-hq/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2026 Diagonal Software Corp. All rights reserved.
+
+This software is the proprietary property of Diagonal Software Corp. ("Diagonal"). It is
+licensed, not sold.
+
+Diagonal grants you a limited, non-exclusive, non-transferable, revocable
+license to install and use this software only to develop, check, build, and
+deploy workspaces for the Diagonal platform, in accordance with your agreement
+with Diagonal.
+
+You may not:
+
+- modify, adapt, translate, or create derivative works of this software;
+- copy, distribute, sublicense, sell, or otherwise make this software available
+  to any third party, except as an unmodified dependency of a Diagonal
+  workspace;
+- use this software with any service other than the Diagonal platform;
+- remove or change this notice.
+
+This license ends automatically when you stop using the Diagonal platform or
+when you breach its terms.
+
+THIS 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 DIAGONAL 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

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# `@diagonal-hq/cli`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+- 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.
+- The `diagonal workflows` and `diagonal run` commands. They list the deployed workflows and run a manual workflow by its file path.
+
+## Check a workspace
+
+```bash
+npm install
+npm run check
+```
+
+`npm run check` runs `diagonal check .`. The command options are:
+
+```text
+diagonal check [dir] [--json]
+```
+
+- `dir` is the workspace root. The default is the current directory.
+- `--json` prints `{ "ok": boolean, "diagnostics": [...] }`.
+
+Each diagnostic prints as `path:line:column severity message`. The command exits with 1 when an error exists, with 2 for a usage error, and with 0 otherwise.
+
+## Run a deployed workflow
+
+`diagonal workflows` and `diagonal run` call the runtime API of a deployed workspace. Set two environment variables first:
+
+- `DIAGONAL_URL` is the workspace URL, for example `https://acme.diagonal.app`.
+- `DIAGONAL_API_KEY` is an API key of an account with `manage_workflows`.
+
+```text
+diagonal workflows [--json]
+diagonal run <path> [--input '<json object>'] [--json]
+```
+
+- `diagonal workflows` prints the path, the trigger type, and the title of each workflow of the active deployment. `--json` prints the API response, which also has each workflow id and version id.
+- `diagonal run workflows/seed-catalog.ts` runs the manual workflow at that path in the active deployment and waits for it. It prints the terminal status, the execution id, and the output. `--input` gives the workflow input as a JSON object. `--json` prints the API response.
+
+`diagonal run` exits with 0 when the run succeeds, with 1 when the request or the run fails, and with 2 for a usage error or a missing environment variable. A workflow that is not manual, or a path that the active deployment does not have, is a request failure.
+
+## What the checks do
+
+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 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`.
+- 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`.
+- The build does not read `notifications/` or `email-layouts/` yet. The editor type-checks the shape of their definitions. See [Notifications](#notifications).
+
+## 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' }`.
+
+```text
+notifications/
+  member-welcome/
+    type.ts
+    standard.template.ts
+    standard.email.liquid
+    standard.sms.liquid
+    fixtures/
+      default.json
+email-layouts/
+  standard/
+    layout.ts
+    body.liquid
+    fixtures/
+      default.json
+```
+
+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 { defineNotificationType, field } from '@diagonal-hq/cli';
+
+export default defineNotificationType({
+  key: 'member-welcome',
+  name: 'Member welcome',
+  recipient: { resource: 'members' },
+  variables: {
+    joined_on: field.date({ label: 'Joined on', required: true }),
+    first_event: { resource: 'events', label: 'First event' }
+  },
+  defaultTemplate: 'standard'
+});
+```
+
+A template has an email, an SMS, or both. A channel is on when the template has it. The email gives a Liquid value for each field of its layout. `layout` defaults to `'default'`, the built-in layout, which has one field, `content`. `references` adds generators that the template reads as `{{ ref.<key> }}`.
+
+```ts
+import { defineNotificationTemplate } from '@diagonal-hq/cli';
+
+export default defineNotificationTemplate({
+  key: 'standard',
+  type: 'member-welcome',
+  name: 'Standard welcome',
+  email: {
+    subject: 'Welcome to {{ workspace.name }}, {{ record.name }}',
+    layout: 'standard',
+    fields: { heading: 'Welcome aboard', body: { file: './standard.email.liquid' } }
+  },
+  sms: { body: { file: './standard.sms.liquid' } },
+  references: {
+    portal_link: {
+      label: 'Member portal',
+      generator: 'page.url',
+      settings: { page: 'portal/home' }
+    }
+  }
+});
+```
+
+An email layout is the frame that templates fill in. Each field is a slot that a template fills with Liquid.
+
+```ts
+import { defineEmailLayout } from '@diagonal-hq/cli';
+
+export default defineEmailLayout({
+  key: 'standard',
+  name: 'Standard',
+  body: { file: './body.liquid' },
+  fields: {
+    heading: { label: 'Heading', required: true },
+    body: { label: 'Body', required: true }
+  }
+});
+```
+
+### Rules
+
+The editor checks the shape of each definition. These rules need other files or server data, so the editor does not check them yet:
+
+- A type cannot have a variable named `record` or `ref`. Templates read the recipient as `{{ record.* }}` and the generators as `{{ ref.* }}`.
+- A template's `type` names an existing type, and the type's `defaultTemplate` names one of its templates.
+- An email's `fields` match the fields of its layout, and fill each required field.
+- A layout cannot use the key `default`.
+- Each reference key starts with a lowercase letter. A template has at most 50 references, and each one names a generator that the server has.
+- The `recipient` resource can receive notifications.
+
+### Fixtures
+
+Fixtures are sample data for previews. They are not tests, and they are never sent. A type folder and a layout folder can each have a `fixtures/` folder of JSON files. `default.json` is the case that a preview opens first.
+
+- A layout fixture holds a value for each layout field, for example `{ "heading": "Welcome aboard", "body": "<p>Hi Avery.</p>" }`.
+- A notification fixture holds a template key, a sample recipient, and sample variables, for example `{ "template": "standard", "recipient": { "name": "Avery Shaw", "email": "avery@example.com", "phone": null }, "variables": { "joined_on": "2026-11-02", "first_event": { "name": "Open house" } } }`. A record variable holds the record's fields.
+
+## 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.
+
+- `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`.
+- `embeddings` is `{ enabled, fields }`. `fields` names fields of the resource, not relation paths.
+- `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.
+
+A builder takes these options:
+
+- `label`, `description`, `required`, `default`, `unique`, and `index`.
+- `guard`: more validation rules, for example `['max:255']`. Use `required` for the `required` and `nullable` rules.
+- `settings`: the settings of the field type, with their stored names, and `settings.ui` for the record form. The seeder settings `seed_type`, `faker_method`, `faker_parameters`, and `seed_data` apply to every type.
+- `computed`: a resolver tree that computes the value when a record is read. A computed field is not stored, so it cannot have `default`, `getter`, `setter`, `unique`, or `index`.
+- `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.
+
+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.
+
+## Capabilities
+
+A resource gets a platform capability, such as Authenticatable, Notifiable, Payable, Subscription, or Eventable, from its `capabilities` key. The settings have the names that the resource builder uses. A field reference names a field of the same resource by its key:
+
+```ts
+export default defineResource({
+  id: '0199f300-0000-7000-8000-000000000005',
+  slug: 'members',
+  name: 'Members',
+  singularName: 'Member',
+  fields: {
+    name: field.text({ required: true }),
+    email: field.email({ required: true, unique: true }),
+    password: field.password()
+  },
+  policies: [],
+  capabilities: {
+    authenticatable: { email_field: 'email', password_field: 'password' },
+    notifiable: { email_field: 'email' }
+  }
+});
+```
+
+`capabilities.generated.d.ts` declares the settings of each capability, and `capability-catalog.json` lists them. `npm run generate-types` generates both from the platform capabilities. Do not edit them.
+
+- The types accept only a field key whose field type the setting allows. For example, `notifiable.email_field` accepts only an `email` field.
+- A file cannot declare `role` or `permission`. Authorization provisioning owns the Role and Permission resources. It also maps `authenticatable.roles_field`, so a file cannot set it.
+- A file cannot set a page reference, such as `authenticatable.login_page`. A page reference names a page row, and the pages of a file-based workspace are files.
+- The build checks the setting names, the required settings, the select values, and each field reference. A relation path, such as an Itemizable offering path, names a relation of each resource on the way.
+- Each field reference is stored as the field id, as the resource builder stores it. This includes a nested reference, such as an Eventable excluded field, and each key of a relation path.
+- The deploy validates each capability with the resource builder's rules against the deployed schema. These rules include the required select options, the field types, and the capability of each resource that a relation setting targets. A capability that fails rejects the deploy, and the previous deployment keeps serving.
+- After the deploy, the platform runs the same provisioning as the resource builder. It creates the system fields of a Subscription, the accounting entity fields, the billing relations, the record indexes, and the booking and schedule setup. For an Authenticatable resource, it creates the Role and Permission resources, so members can sign in.
+- A setting that provisioning fills can be left out. A Subscription starts from the builder's default settings, so set only the defaults that change.
+- Provisioning can create a field, for example `accounting_entity`. The files cannot declare a field with the same key later. The deploy refuses it until you delete the field in the resource builder or use another key.
+- A capability change in the resource builder is drift. The next deploy reports it and restores the capability from the files.
+
+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.
+
+## 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.
+
+Add a `tsconfig.json` with `"types": ["@diagonal-hq/cli", "node"]` and `@types/node` as a dev dependency. `dist/globals.d.ts` gives the `Sdk` global from the generated page Sdk contract (`dist/sdk-contract.d.ts`). The editor does not know the workspace resources and components, so `Sdk.resource(...)` and `Sdk.Custom.*` have loose types there. `diagonal check` types them.
+
+`dist/workflow/` holds the declarations of the workflow script SDK. Map the module names to them with `paths`:
+
+```json
+"paths": {
+  "@diagonal/workflow": ["./node_modules/@diagonal-hq/cli/dist/workflow/index.d.ts"],
+  "@diagonal/workflow/testing": ["./node_modules/@diagonal-hq/cli/dist/workflow/testing/index.d.ts"],
+  "@diagonal/workflow/workspace": ["./node_modules/@diagonal-hq/cli/dist/workflow/workspace.d.ts"]
+}
+```
+
+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.
+
+`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.
+
+## Build the package
+
+`npm run build:cli-package` (`scripts/build-cli-package.mjs`) writes `dist/` and packs `scripts/dist/npm/diagonal-hq-cli-<version>.tgz`. `dist/cli.mjs` bundles every dependency, the TypeScript lib files, the workflow script compiler with the script SDK sources, and the bundled script SDK that workflow tests import, so the command needs no Diagonal checkout. The script needs the page Sdk contract and `scripts/generated/typeCheckLibs.mjs`. `npm run generate-typescript` makes both and then runs the script.
+
+`node scripts/smoke-cli-package.mjs [tarball]` installs the packed tarball in a copy of the starter template outside the repository, with one workflow and its test added. It checks the packed file list, imports the helpers through the `exports` map, runs `tsc` against the packed declarations, and runs `diagonal check`. The `generated-assets` job of PR CI runs it.
+
+## Publish the package
+
+The `Publish npm package` workflow (`.github/workflows/publish-npm-package.yml`) publishes the package to npm after each push to `main`. You can also run it from the Actions tab.
+
+1. The build job builds and packs the package. It compares the packed files with the tarball that npm has for the version in `package.json`. The `version` field does not count.
+2. When the files differ, a model reads the diff and the commit subjects since that publish. It classifies the change as breaking, feature, or fix. Before 1.0.0, a breaking change raises the minor part, and other changes raise the patch part. From 1.0.0, the workflow follows semantic versioning.
+3. The build job packs the package again at the new version and runs the smoke test on the tarball.
+4. The commit job commits the new version to `main` with an `[automated] release:` commit.
+5. The publish job runs in the `npm-publish` environment and publishes the tested bytes with npm trusted publishing. It does not build again. It refuses a version that npm already has.
+
+To choose a version yourself, such as 1.0.0 or a prerelease, set `version` in `package.json` to a version that npm does not have, and merge the change. The workflow publishes that version as it is. A version with a prerelease part, such as `0.2.0-next.1`, gets the `next` tag. Other versions get `latest`. The workflow does not raise a prerelease version. Set the next version by hand.
+
+The model call uses the `OPENROUTER_API_KEY` secret. When the call fails, the release fails. The workflow does not guess a version.
+
+npm must list `Diagonal-HQ/diagonal`, the `publish-npm-package.yml` workflow, and the `npm-publish` environment as the trusted publisher of `@diagonal-hq/cli`.

package/bin/diagonal.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The installed package has no path aliases.
+// oxlint-disable-next-line local/no-relative-imports
+import { main } from '../dist/cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2), {
+  cwd: process.cwd(),
+  env: process.env,
+  stdout: process.stdout,
+  stderr: process.stderr
+});