@diagonal-hq/cli 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+import './globals';
+import type { ResourceCapabilities } from './capabilities.generated';
+import type { DataApiEndpoint, FieldDefinition, FieldType } from './fields.generated';
+
+// The configuration helpers of file-based workspaces. The workspace build
+// reads these calls as static data. index.js implements each define* function
+// as an identity function and each field builder as `{ $field, ...options }`.
+
+export type StaticValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly StaticValue[]
+  | { readonly [key: string]: StaticValue };
+
+export type ConfigDefinition = {
+  name: string;
+  brand?: { readonly [key: string]: StaticValue };
+  settings?: { readonly [key: string]: StaticValue };
+};
+
+export declare function defineConfig<const T extends ConfigDefinition>(config: T): T;
+
+export { field } from './fields.generated';
+export type {
+  CommonFieldSettings,
+  DataApiEndpoint,
+  FieldDefinition,
+  FieldSchemaDefinition,
+  FieldSchemaSetting,
+  FieldType,
+  RelationFieldOptions,
+  RelationInverse,
+  Resolver
+} from './fields.generated';
+export type { CapabilityType, FieldKeyOf, ResourceCapabilities } from './capabilities.generated';
+
+export type PolicyScope =
+  | 'index'
+  | 'show'
+  | 'count'
+  | 'aggregate'
+  | 'store'
+  | 'storeMany'
+  | 'update'
+  | 'destroy'
+  | 'restore'
+  | 'validate';
+
+export type PolicyAccess = 'public' | 'protected';
+
+export type PolicyDefinition = {
+  name: string;
+  scope: 'all' | readonly PolicyScope[];
+  access: PolicyAccess;
+  description?: string | null;
+};
+
+export type IndexDefinition<TKey extends string = string> = {
+  fields: readonly TKey[];
+  unique?: boolean;
+};
+
+export type ResourceEmbeddings<TKey extends string = string> = {
+  enabled?: boolean;
+  /** Field keys. Relation paths are not allowed. */
+  fields?: readonly TKey[] | null;
+};
+
+export type ResourceDataApi = {
+  /** An omitted endpoint stays enabled. */
+  endpoints?: Partial<Record<DataApiEndpoint, { enabled?: boolean }>>;
+};
+
+export type ResourceDefinition<
+  TFields extends Record<string, FieldDefinition> = Record<string, FieldDefinition>
+> = {
+  /**
+   * A lowercase UUID v7, for example '0199f000-0000-7000-8000-000000000001'.
+   * `diagonal check` suggests a new one when the id is not v7. Keep it
+   * stable: records and workflows refer to it.
+   */
+  id: string;
+  slug: string;
+  name: string;
+  singularName: string;
+  displayField?: Extract<keyof TFields, string>;
+  /**
+   * The field keys and relation paths that record search matches, for example
+   * `['title', 'body', 'author.full_name']`. Without it, search matches the
+   * display field and every text and markdown field.
+   */
+  searchableFields?: readonly (
+    | Extract<keyof TFields, string>
+    | `${Extract<keyof TFields, string>}.${string}`
+  )[];
+  /** Every field key once, in the order that forms and tables show them. Defaults to the order of `fields`. */
+  fieldOrder?: readonly Extract<keyof TFields, string>[];
+  fields: TFields;
+  indexes?: readonly IndexDefinition<Extract<keyof TFields, string>>[];
+  embeddings?: ResourceEmbeddings<Extract<keyof TFields, string>>;
+  dataApi?: ResourceDataApi;
+  /** A static resource refuses normal record writes. */
+  static?: boolean;
+  policies: readonly PolicyDefinition[];
+  /**
+   * The platform capabilities of the resource, keyed by capability. A field
+   * reference names a field of this resource by its key. The deploy validates
+   * each capability against the deployed schema and runs its provisioning.
+   */
+  capabilities?: ResourceCapabilities<TFields>;
+};
+
+export declare function defineResource<const TFields extends Record<string, FieldDefinition>>(
+  resource: ResourceDefinition<TFields>
+): ResourceDefinition<TFields>;
+
+/** A TipTap document whose mentions resolve against the page's bound records. */
+export type PageMetaResolver = { readonly type: string; readonly [key: string]: unknown };
+
+export type PageRouteParam = {
+  /** The slug or id of the resource whose record the parameter names. */
+  resource: string;
+  /** The field the parameter matches. Defaults to the record id. */
+  lookupField?: string | null;
+  /** Relation fields to load with the record. */
+  relations?: readonly string[];
+  scope?: 'active' | 'activeOrArchived' | 'archived' | null;
+};
+
+export type PageAuthorizer =
+  | null
+  | 'authenticated'
+  | {
+      /** The slug or id of the resource whose signed-in records may view the page. */
+      resource?: string | null;
+      /** Permission ids. A viewer needs any one of them. */
+      permissions?: readonly string[];
+    };
+
+export type PageDefinition = {
+  /** The URL pattern. Route parameters use `{name}`, for example `/members/{id}`. */
+  route: string;
+  /** The name in the admin. Defaults to the title. */
+  name?: string | null;
+  title?: string | PageMetaResolver | null;
+  description?: string | PageMetaResolver | null;
+  /** A public workspace file id, or a resolver that names one. */
+  ogImage?: string | PageMetaResolver | null;
+  /** HTML added to the page's `<head>`. */
+  headHtml?: string | null;
+  /** The file name of a layout in `layouts/`, without the extension. */
+  layout?: string | null;
+  /** `print` renders without a layout. */
+  renderProfile?: 'standard' | 'print';
+  /** Whether the sitemap lists the page. Defaults to true, or false for a print page. */
+  sitemap?: boolean;
+  /** The host of a connected custom domain. A page with a domain serves only there. */
+  domain?: string | null;
+  /** A paused page does not serve. */
+  paused?: boolean;
+  authorizer?: PageAuthorizer;
+  /** The record each route parameter binds to, keyed by parameter name. */
+  params?: Readonly<Record<string, PageRouteParam>>;
+};
+
+export type PageComponent = () => unknown;
+
+export declare function definePage<const T extends PageDefinition>(
+  page: T,
+  component: PageComponent
+): T;
+
+export type LayoutProps = { children?: React.ReactNode };
+
+export type NavigationItem = { label: string; route: string; icon?: string | null };
+
+export type NavigationDefinition = { id: string; items: readonly NavigationItem[] };
+
+export declare function defineNavigation<const T extends NavigationDefinition>(navigation: T): T;
+
+/** The slug, name, or id of a resource. */
+export type ResourceReference = string;
+
+export type WorkflowRunAs =
+  | 'system'
+  /** Only for request workflows: the signed-in user who calls the route. */
+  | 'session'
+  | {
+      resource: ResourceReference;
+      /** The lowercase UUID of the identity record. */
+      record: string;
+    };
+
+export type RequestTrigger = {
+  type: 'request';
+  /** The route. Route parameters use `{name}`, for example `/api/members/{id}`. */
+  path: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+};
+
+export type RecordEventTrigger = {
+  type: 'recordEvent';
+  resource: ResourceReference;
+  event: 'created' | 'updated' | 'deleted' | 'restored' | 'saved';
+  filters?: StaticValue;
+};
+
+export type RecordLifecycleTrigger = {
+  type: 'recordLifecycle';
+  resource: ResourceReference;
+  hook: 'creating' | 'updating' | 'saving' | 'deleting' | 'restoring';
+};
+
+export type RecordScheduleTrigger = {
+  type: 'recordSchedule';
+  resource: ResourceReference;
+  /** The key of a date or datetime field of the resource. */
+  dateField: string;
+  /** Signed ISO 8601 durations in days, hours, or minutes, for example `'-P1D'` or `'+PT2H'`. */
+  offsets: readonly string[];
+};
+
+export type ScheduledTrigger = {
+  type: 'scheduled';
+  /** A cron expression with 5 fields, for example `'0 2 * * *'`. */
+  expression: string;
+};
+
+export type WorkflowEventTrigger = {
+  type: 'workflowEvent';
+  /** The path of another workflow, for example `'workflows/welcome.ts'`. */
+  workflow: `workflows/${string}.ts`;
+  event: 'execution.success' | 'execution.error';
+};
+
+export type ManualTrigger = { type: 'manual' };
+
+type ConfigBase = { title: string; description?: string | null };
+
+/**
+ * The `export const config` of a `workflows/<name>.ts` file. The build reads it as static data and
+ * never runs it. A background trigger (recordEvent, recordSchedule, scheduled, workflowEvent)
+ * needs `runAs`. A request workflow runs as the caller (`'session'`) by default.
+ */
+export type WorkflowConfig =
+  | (ConfigBase & {
+      trigger: RequestTrigger;
+      runAs?: WorkflowRunAs;
+      authorizer?: 'authenticated';
+    })
+  | (ConfigBase & {
+      trigger: RecordEventTrigger | RecordScheduleTrigger | ScheduledTrigger | WorkflowEventTrigger;
+      runAs: Exclude<WorkflowRunAs, 'session'>;
+    })
+  | (ConfigBase & { trigger: ManualTrigger; runAs?: Exclude<WorkflowRunAs, 'session'> })
+  | (ConfigBase & { trigger: RecordLifecycleTrigger });
+
+/**
+ * Liquid source: inline text, or the path of a `.liquid` file relative to the
+ * definition file, for example `{ file: './standard.email.liquid' }`.
+ */
+export type LiquidSource = string | { readonly file: `./${string}.liquid` };
+
+/** The key of a notification type. */
+export type NotificationTypeReference = string;
+
+/** The key of a template, unique within its notification type. */
+export type NotificationTemplateReference = string;
+
+/** The key of an email layout, or `'default'` for the built-in layout. */
+export type EmailLayoutReference = string;
+
+/** A variable whose value is one record. The sender passes the record id. */
+export type RecordVariableDefinition = {
+  /** The slug of the resource whose record the sender passes. */
+  resource: ResourceReference;
+  label?: string;
+  description?: string | null;
+  required?: boolean;
+};
+
+/**
+ * A value that the sender passes to the notification. The name cannot be
+ * `record` or `ref`: templates read the recipient as `{{ record.* }}` and the
+ * generators as `{{ ref.* }}`.
+ */
+export type NotificationVariableDefinition =
+  | FieldDefinition<Exclude<FieldType, 'relation'>>
+  | RecordVariableDefinition;
+
+/** A `notifications/<key>/type.ts` file. */
+export type NotificationTypeDefinition = {
+  /**
+   * Lowercase letters, digits, and hyphens, for example `'member-welcome'`.
+   * Templates, fixtures, and workflows refer to it. Moving the file keeps it.
+   */
+  key: string;
+  name: string;
+  /**
+   * The resource that receives the notification. The resource maps the email
+   * and phone fields. Leave it out to send to email addresses.
+   */
+  recipient?: { resource: ResourceReference };
+  variables?: { readonly [key: string]: NotificationVariableDefinition };
+  defaultTemplate: NotificationTemplateReference;
+};
+
+export declare function defineNotificationType<const T extends NotificationTypeDefinition>(
+  type: T
+): T;
+
+export type NotificationReference = {
+  label: string;
+  /** The server generator, for example `'page.url'` or `'workspace.login_url'`. */
+  generator: string;
+  settings?: { readonly [setting: string]: StaticValue };
+};
+
+export type NotificationTemplateEmail = {
+  subject: string;
+  /** Defaults to `'default'`, the built-in layout with one field, `content`. */
+  layout?: EmailLayoutReference;
+  /** A value for each field of the layout. */
+  fields: { readonly [field: string]: LiquidSource };
+};
+
+export type NotificationTemplateSms = { body: LiquidSource };
+
+/** A `notifications/<type key>/<key>.template.ts` file. A template has an email, an SMS, or both. */
+export type NotificationTemplateDefinition = {
+  /** Unique within its type, for example `'standard'`. */
+  key: string;
+  type: NotificationTypeReference;
+  name: string;
+  /** Generators that the template reads as `{{ ref.<key> }}`. */
+  references?: { readonly [key: string]: NotificationReference };
+} & (
+  | { email: NotificationTemplateEmail; sms?: NotificationTemplateSms }
+  | { email?: NotificationTemplateEmail; sms: NotificationTemplateSms }
+);
+
+export declare function defineNotificationTemplate<const T extends NotificationTemplateDefinition>(
+  template: T
+): T;
+
+/** A slot in the layout body. A template fills it with Liquid. */
+export type EmailLayoutFieldDefinition = {
+  label: string;
+  description?: string | null;
+  required?: boolean;
+};
+
+/** An `email-layouts/<key>/layout.ts` file. */
+export type EmailLayoutDefinition = {
+  /**
+   * Lowercase letters, digits, and hyphens, for example `'standard'`. Templates
+   * refer to it. `'default'` is the built-in layout.
+   */
+  key: string;
+  name: string;
+  body: LiquidSource;
+  /** The fields that each template fills in. The body reads them as `{{ <field> }}`. */
+  fields?: { readonly [key: string]: EmailLayoutFieldDefinition };
+};
+
+export declare function defineEmailLayout<const T extends EmailLayoutDefinition>(layout: T): T;

package/dist/index.js

@@ -0,0 +1,26 @@
+// The configuration helpers. The workspace build reads these calls as static
+// data, so the helpers only return their argument. A Vite build or a Node
+// script that imports a configuration file runs them.
+//
+// The field builders come from fields.generated.js, which
+// `artisan app:generate-custom-typescript` generates from the field types.
+//
+// Each function must not refer to anything outside its own body:
+// scripts/lib/runtime-build/app-modules.mjs copies their source into the
+// workspace modules that a page or a workflow imports.
+
+export const defineConfig = (config) => config;
+
+export const defineResource = (resource) => resource;
+
+export const definePage = (page, _component) => page;
+
+export const defineNavigation = (navigation) => navigation;
+
+export const defineNotificationType = (type) => type;
+
+export const defineNotificationTemplate = (template) => template;
+
+export const defineEmailLayout = (layout) => layout;
+
+export { field } from './fields.generated.js';