@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/resource/types.d.ts

@@ -1,5 +1,7 @@
 import type { Knex } from 'knex';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
+import type { WorkflowDefinition } from '../workflows/define_workflow.js';
+import type { Conditions } from '../auth/conditions.js';
 export type Label = {
     ar: string;
     en: string;
@@ -35,6 +37,13 @@ export type Field = {
 } | {
     type: 'belongsTo';
     resource: string;
+}
+/**
+ * A user of this deployment (foreign key to users). Choices are active members of
+ * the record's organization unit or its ancestors; readers see only the display name.
+ */
+ | {
+    type: 'user';
 } | {
     type: 'hasMany';
     resource: string;
@@ -46,9 +55,26 @@ export type Field = {
 });
 export type Resource = {
     name: string;
+    /** The list heading, usually plural (for example «الحسابات»). */
     label: Label;
+    /**
+     * The singular record noun (for example «حساب»). Generated pages say «إضافة حساب»
+     * instead of the generic «إضافة سجل».
+     */
+    recordLabel?: Label;
+    /** Full create-button text when «إضافة <recordLabel>» does not fit (for example «مهمة جديدة»). */
+    createLabel?: Label;
     model: LucidModel;
     scoped: boolean;
+    /**
+     * The organization unit of a scoped record follows a required belongsTo parent, for
+     * example a clinic follows its facility. The unit is copied from the parent before
+     * authorization, the actor must be able to view the parent, and the form has no unit
+     * picker. `ResourceService.rehome` moves the children after the parent moves.
+     */
+    scope?: {
+        from: string;
+    };
     submittable?: boolean;
     version?: boolean;
     customFields?: boolean;
@@ -58,6 +84,12 @@ export type Resource = {
     show: readonly string[];
     serialize?: readonly string[];
     hidden?: readonly string[];
+    /**
+     * Fields that name a record wherever it is referenced: relation cells and pickers,
+     * "My tasks" and the approvals inbox. Joined with « · ». Defaults to the first
+     * sequence field and the first text field in `list`.
+     */
+    title?: readonly string[];
     actions: readonly Action[];
     validator: {
         validate(data: unknown): Promise<RecordData>;
@@ -72,18 +104,52 @@ export type HookContext = {
     userId: number;
     action: Action;
 };
+/** A changeable list value a module needs before its records can be saved. */
+export type ModuleLookup = {
+    key: string;
+    label: Label;
+    sort?: number;
+};
+/** A role a module ships; its rules go through the same validation as the roles screen. */
+export type ModuleRole = {
+    /** Stable key that workflows address ({ role: key }); see roles.key. */
+    key: string;
+    /** Arabic display name; administrators may rename it later. */
+    name: string;
+    permissionLevel?: number;
+    rules: readonly {
+        subject: string;
+        action: string;
+        inverted?: boolean;
+        conditions?: Conditions | null;
+        fields?: string[] | null;
+    }[];
+};
 export type Module = {
     name: string;
     reference?: boolean;
     label: Label;
     dependsOn: readonly string[];
     resources: readonly Resource[];
+    /** Versioned workflows of this module's submittable resources (phase 4). */
+    workflows?: readonly WorkflowDefinition[];
+    /**
+     * Lookup rows by group. adula:install inserts missing rows and never changes or
+     * removes existing ones, so administrator edits survive upgrades.
+     */
+    lookups?: Readonly<Record<string, readonly ModuleLookup[]>>;
+    /**
+     * Roles created by adula:install when no role has their key yet. An existing role
+     * is never modified, so administrators own every role after installation.
+     */
+    defaultRoles?: readonly ModuleRole[];
 };
-export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize'> & {
+export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize' | 'title'> & {
     fields: F;
     list: readonly (keyof F & string)[];
     form: readonly (keyof F & string)[];
     show: readonly (keyof F & string)[];
     hidden?: readonly (keyof F & string)[];
     serialize?: readonly (keyof F & string)[];
+    title?: readonly (keyof F & string)[];
 };

package/build/src/resource/values.js

@@ -48,8 +48,9 @@ export function fieldValue(field, value) {
         }
         case 'integer':
         case 'belongsTo':
+        case 'user':
             if (!Number.isInteger(value) ||
-                Number(value) < (field.type === 'belongsTo' ? 1 : -2147483648) ||
+                Number(value) < (field.type === 'integer' ? -2147483648 : 1) ||
                 Number(value) > 2147483647)
                 throw new Error('Expected a PostgreSQL integer');
             return value;

package/build/src/services/settings.d.ts

@@ -6,4 +6,16 @@ export declare class Settings {
     set(key: string, value: unknown, scope?: string, scopeId?: string): Promise<void>;
 }
 export declare function sequence(trx: Knex.Transaction, key: string): Promise<string>;
-export declare function notify(db: Knex, userId: number, title: string, body: string): Promise<void>;
+/** The record a notification is about; opening the notification opens the record. */
+export type NotificationTarget = {
+    resource: string;
+    recordId: number;
+};
+export declare function targetColumns(target?: NotificationTarget | null): {
+    resource?: undefined;
+    record_id?: undefined;
+} | {
+    resource: string;
+    record_id: number;
+};
+export declare function notify(db: Knex, userId: number, title: string, body: string, target?: NotificationTarget | null): Promise<void>;

package/build/src/services/settings.js

@@ -18,6 +18,13 @@ export async function sequence(trx, key) {
     const result = await trx.raw('INSERT INTO sequences (key,value) VALUES (?,1) ON CONFLICT (key) DO UPDATE SET value=sequences.value+1 RETURNING value', [key]);
     return `${key}-${String(result.rows[0].value).padStart(6, '0')}`;
 }
-export async function notify(db, userId, title, body) {
-    await db('notifications').insert({ user_id: userId, title, body });
+export function targetColumns(target) {
+    if (!target)
+        return {};
+    if (!/^[a-z][a-z0-9_]*$/.test(target.resource) || !Number.isSafeInteger(target.recordId))
+        throw new Error('Invalid notification target');
+    return { resource: target.resource, record_id: target.recordId };
+}
+export async function notify(db, userId, title, body, target) {
+    await db('notifications').insert({ user_id: userId, title, body, ...targetColumns(target) });
 }

package/build/src/workflows/define_workflow.d.ts

@@ -0,0 +1,124 @@
+import { type AnyStateMachine } from 'xstate';
+import type { Knex } from 'knex';
+import type { RecordData } from '../resource/types.js';
+/** Everything a step callback may read: the current record and the run facts. */
+export type StepContext = {
+    record: RecordData;
+    run: {
+        id: string;
+        resource: string;
+        recordId: number;
+        startedBy: number | null;
+    };
+    db: Knex;
+};
+export type Recipients = 'creator' | 'submitter'
+/**
+ * The members of a role, addressed by its stable key (roles.key). A role without a
+ * key is still found by its display name, which administrators can rename.
+ */
+ | {
+    role: string;
+} | {
+    users: number[];
+} | ((context: StepContext) => number[] | Promise<number[]>);
+/** One decision an approver can take at a decision step (#42). */
+export type DecisionOutcome = {
+    label: string;
+    next: string;
+    /** Whether the decision needs a comment; defaults to optional. */
+    comment?: 'optional' | 'required';
+};
+export type WorkflowStep = {
+    type: 'condition';
+    label?: string;
+    when: (record: RecordData) => boolean;
+    then: string;
+    else: string;
+} | {
+    type: 'update';
+    label?: string;
+    values: RecordData | ((context: StepContext) => RecordData);
+    next: string;
+} | {
+    type: 'notify';
+    label?: string;
+    to: Recipients;
+    /** A message template key; defaults to workflow.decided. */
+    template?: string;
+    variables?: (context: StepContext) => Record<string, unknown>;
+    next: string;
+} | {
+    type: 'approval';
+    label: string;
+    assignees: Recipients;
+    dueInDays?: number;
+    approve: string;
+    reject: string;
+} | {
+    /**
+     * An approval with named outcomes, for example approve, reject and return. Each
+     * outcome names its next step (a later or an earlier one) and may require a comment.
+     * The submitted document stays locked: a decision never changes its fields.
+     */
+    type: 'decision';
+    label: string;
+    assignees: Recipients;
+    dueInDays?: number;
+    outcomes: Record<string, DecisionOutcome>;
+} | {
+    type: 'delay';
+    label?: string;
+    ms: number;
+    next: string;
+} | {
+    type: 'http';
+    label?: string;
+    url: string | ((context: StepContext) => string);
+    body?: (context: StepContext) => unknown;
+    next: string;
+} | {
+    type: 'end';
+    label?: string;
+    outcome: 'approved' | 'rejected' | 'completed';
+    /** Cancel the submitted document when the workflow ends (for example on rejection). */
+    cancelDocument?: boolean;
+};
+export type WorkflowInput = {
+    /** Lower-case letters, digits and underscores, starting with a letter (for example release_approval). */
+    name: string;
+    version: number;
+    resource: string;
+    label: string;
+    start: string;
+    /** Step names follow the workflow name rule (for example notify_approved). */
+    steps: Record<string, WorkflowStep>;
+    /** Failed step attempts before the run stops as failed (default 5). */
+    maxAttempts?: number;
+};
+export type WorkflowDefinition = WorkflowInput & {
+    machine: AnyStateMachine;
+};
+export type WorkflowEvent = {
+    type: 'EVALUATE';
+    record: RecordData;
+} | {
+    type: 'DONE';
+} | {
+    type: 'APPROVE';
+} | {
+    type: 'REJECT';
+} | {
+    type: 'DECIDE';
+    outcome: string;
+};
+export declare const WORKFLOW_NAME_RULE = "use lower-case letters, digits and underscores, starting with a letter";
+/**
+ * Declares a versioned workflow. Steps compile to an XState machine; the engine
+ * performs each step's effect and asks the machine for the next step. Runs keep
+ * the version they started with, so publishing a new version never changes a
+ * running workflow (migrate explicitly with WorkflowEngine.migrateRuns).
+ */
+export declare function defineWorkflow(input: WorkflowInput): WorkflowDefinition;
+/** The step reached from `current` by `event`, or an error if the step does not accept it. */
+export declare function nextStep(definition: WorkflowDefinition, current: string, event: WorkflowEvent): string;

package/build/src/workflows/define_workflow.js

@@ -0,0 +1,123 @@
+import { createMachine, getNextSnapshot } from 'xstate';
+const IDENTIFIER = /^[a-z][a-z0-9_]*$/;
+export const WORKFLOW_NAME_RULE = 'use lower-case letters, digits and underscores, starting with a letter';
+/** Names the rule and a valid spelling, since dotted event-style names are a natural first try. */
+function assertIdentifier(kind, value) {
+    if (IDENTIFIER.test(value))
+        return;
+    const suggestion = value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^[^a-z]+|_+$/g, '');
+    const example = IDENTIFIER.test(suggestion)
+        ? suggestion
+        : kind === 'workflow'
+            ? 'release_approval'
+            : 'notify_approved';
+    throw new Error(`Invalid ${kind} name "${value}": ${WORKFLOW_NAME_RULE} (for example ${example}).`);
+}
+function targets(step) {
+    switch (step.type) {
+        case 'condition':
+            return [step.then, step.else];
+        case 'approval':
+            return [step.approve, step.reject];
+        case 'decision':
+            return Object.values(step.outcomes).map((outcome) => outcome.next);
+        case 'end':
+            return [];
+        default:
+            return [step.next];
+    }
+}
+/**
+ * Declares a versioned workflow. Steps compile to an XState machine; the engine
+ * performs each step's effect and asks the machine for the next step. Runs keep
+ * the version they started with, so publishing a new version never changes a
+ * running workflow (migrate explicitly with WorkflowEngine.migrateRuns).
+ */
+export function defineWorkflow(input) {
+    assertIdentifier('workflow', input.name);
+    if (!Number.isInteger(input.version) || input.version < 1)
+        throw new Error('Workflow version must be a positive integer');
+    if (!(input.start in input.steps))
+        throw new Error(`Unknown start step: ${input.start}`);
+    const keys = Object.keys(input.steps);
+    for (const key of keys) {
+        assertIdentifier('step', key);
+        for (const target of targets(input.steps[key]))
+            if (!(target in input.steps))
+                throw new Error(`Step ${key} points to unknown step ${target}`);
+        const step = input.steps[key];
+        if (step.type === 'delay' && (!Number.isInteger(step.ms) || step.ms < 0))
+            throw new Error(`Step ${key} needs a non-negative integer delay`);
+        if (step.type === 'decision') {
+            const outcomes = Object.entries(step.outcomes ?? {});
+            if (outcomes.length < 2)
+                throw new Error(`Decision step ${key} needs at least two outcomes`);
+            for (const [name, outcome] of outcomes) {
+                if (!IDENTIFIER.test(name) || name.length > 20)
+                    throw new Error(`Invalid outcome name "${name}" in step ${key}: ${WORKFLOW_NAME_RULE}, at most 20 characters`);
+                if (!outcome.label)
+                    throw new Error(`Outcome ${name} of step ${key} needs a label`);
+            }
+        }
+    }
+    if (!keys.some((key) => input.steps[key].type === 'end'))
+        throw new Error('A workflow needs at least one end step');
+    const machine = createMachine({
+        id: `${input.name}@${input.version}`,
+        initial: input.start,
+        states: Object.fromEntries(keys.map((key) => {
+            const step = input.steps[key];
+            switch (step.type) {
+                case 'condition':
+                    return [
+                        key,
+                        {
+                            on: {
+                                EVALUATE: [
+                                    {
+                                        target: step.then,
+                                        guard: ({ event }) => event.type === 'EVALUATE' && step.when(event.record),
+                                    },
+                                    { target: step.else },
+                                ],
+                            },
+                        },
+                    ];
+                case 'approval':
+                    return [key, { on: { APPROVE: step.approve, REJECT: step.reject } }];
+                case 'decision':
+                    return [
+                        key,
+                        {
+                            on: {
+                                DECIDE: Object.entries(step.outcomes).map(([name, outcome]) => ({
+                                    target: outcome.next,
+                                    guard: ({ event }) => event.type === 'DECIDE' && event.outcome === name,
+                                })),
+                            },
+                        },
+                    ];
+                case 'end':
+                    return [key, { type: 'final' }];
+                default:
+                    return [key, { on: { DONE: step.next } }];
+            }
+        })),
+    });
+    return { ...input, machine };
+}
+/** The step reached from `current` by `event`, or an error if the step does not accept it. */
+export function nextStep(definition, current, event) {
+    if (!(current in definition.steps))
+        throw new Error(`Step ${current} is not part of ${definition.name}@${definition.version}`);
+    const snapshot = definition.machine.resolveState({ value: current, context: {} });
+    const next = getNextSnapshot(definition.machine, snapshot, event);
+    const value = String(next.value);
+    if (value === current)
+        throw new Error(`Step ${current} does not accept ${event.type}`);
+    return value;
+}

package/build/src/workflows/engine.d.ts

@@ -0,0 +1,141 @@
+import type { Knex } from 'knex';
+import type { Actor } from '../auth/ability.js';
+import type { ResourceService } from '../admin/resource_service.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { JsonValue } from '../resource/types.js';
+import type { DomainEvent, Listener } from '../events/outbox.js';
+import type { HttpPoster } from '../integrations/webhooks.js';
+import type { Assignments } from '../collaboration/assignments.js';
+import { type WorkflowDefinition } from './define_workflow.js';
+export type WorkflowRunStatus = 'pending_definition' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+export type WorkflowRun = {
+    id: string;
+    resource: string;
+    resourceLabel: string;
+    recordId: number;
+    /** The record title for the approver (#32); null in admin views or when not readable. */
+    recordTitle: string | null;
+    definition: string;
+    label: string;
+    version: number;
+    status: WorkflowRunStatus;
+    step: string | null;
+    stepLabel: string | null;
+    outcome: string | null;
+    attempts: number;
+    lastError: string | null;
+    wakeAt: string | null;
+    createdAt: string;
+    completedAt: string | null;
+    history: {
+        step: string | null;
+        event: string;
+        actorName: string | null;
+        detail: {
+            [key: string]: JsonValue;
+        };
+        at: string;
+    }[];
+    /** Open approval assigned to the viewer for this run, if any. */
+    myApproval: {
+        assignmentId: number;
+        title: string;
+        /** Set at a decision step: its outcomes in declaration order (#42). */
+        decision?: WorkflowDecisionForm;
+    } | null;
+};
+/** What an approver needs to take a decision at a decision step. */
+export type WorkflowDecisionForm = {
+    outcomes: {
+        key: string;
+        label: string;
+        comment: 'optional' | 'required';
+    }[];
+};
+export type WorkflowOptions = {
+    post?: HttpPoster;
+    /** Test hook simulating a crash after a step's effect and before its commit. */
+    beforeCommit?: (run: {
+        id: string;
+        step: string;
+    }) => void | Promise<void>;
+    now?: () => Date;
+};
+/**
+ * Durable workflow engine over workflow_runs. Every step runs inside the run's
+ * row lock (FOR UPDATE); its database effects and the transition commit together,
+ * so a crash repeats at most the step's external calls (HTTP carries a stable
+ * Idempotency-Key). Failed steps retry with growing delays up to maxAttempts.
+ */
+export declare class WorkflowEngine {
+    #private;
+    private db;
+    private registry;
+    private resources;
+    private actors;
+    private assignments;
+    private options;
+    constructor(db: Knex, registry: ResourceRegistry, resources: ResourceService, actors: {
+        load(id: number): Promise<Actor>;
+    }, assignments: Assignments, definitions: readonly WorkflowDefinition[], options?: WorkflowOptions);
+    register(definition: WorkflowDefinition): this;
+    /** The newest version of each workflow attached to a resource. */
+    private latestFor;
+    private definition;
+    /** Listeners: submitted documents start their workflow; cancelled ones stop it. */
+    listeners(): Listener[];
+    /** Claims the submission envelope written in the submit transaction. */
+    start(trx: Knex.Transaction, event: DomainEvent): Promise<void>;
+    /** Worker step: advances due runs, each under its own row lock. */
+    tick(limit?: number): Promise<number>;
+    /**
+     * Runs steps until the run waits, ends, fails or is scheduled later. The caller
+     * holds the row lock. Each step executes in a savepoint so a failing step leaves
+     * no partial effects behind.
+     */
+    private advance;
+    private execute;
+    /**
+     * Records an approver's decision. Only an open approval assigned to the actor
+     * counts, and the run is locked so concurrent decisions cannot both apply.
+     */
+    decide(runId: string, actor: Actor, decision: string, comment?: unknown): Promise<WorkflowRun>;
+    /** Administrators put a failed run back to its failed step. */
+    retry(runId: string, actorId: number): Promise<void>;
+    /**
+     * Explicit version migration for runs that have not finished: `mapStep` returns
+     * the equivalent step name in the new version.
+     */
+    migrateRuns(name: string, from: number, to: number, mapStep: (step: string) => string): Promise<number>;
+    runsFor(name: string, id: number, actor: Actor): Promise<WorkflowRun[]>;
+    run(runId: string, actor: Actor): Promise<WorkflowRun>;
+    /** Runs waiting for the actor's decision, newest first, on records they can still read. */
+    /**
+     * Runs waiting for this user's decision, newest first (at most 100). `runIds` narrows the
+     * inbox to those runs, for pages that list their own rows (My tasks).
+     */
+    inbox(actor: Actor, options?: {
+        runIds?: readonly string[];
+    }): Promise<WorkflowRun[]>;
+    failed(limit?: number): Promise<WorkflowRun[]>;
+    private present;
+    /** The outcomes an approver can choose at a decision step. */
+    private decisionForm;
+    private fail;
+    private cancelRuns;
+    private context;
+    /** Workflow writes are system writes attributed to the submitter, with history. */
+    private updateRecord;
+    private cancelDocument;
+    private recipients;
+    /** A role reference is its stable key; for compatibility a display name also matches. */
+    private roleId;
+    private canView;
+    private log;
+    private now;
+}
+/**
+ * Listeners resolved per call, so hosts can build the engine lazily (for example
+ * per request) while the listener list is fixed at boot from the registry.
+ */
+export declare function workflowListeners(registry: ResourceRegistry, engine: () => WorkflowEngine): Listener[];