@adula/kit 1.0.0 → 1.2.0

package/build/src/collaboration/assignments.js

@@ -2,6 +2,7 @@ import { KitError } from '../admin/errors.js';
 import { notifyWithTemplate } from '../core/message_templates.js';
 const TITLE_LIMIT = 200;
 const NOTE_LIMIT = 2000;
+const REASON_LIMIT = 500;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 function dateOnly(value) {
     if (value === null || value === undefined)
@@ -19,10 +20,12 @@ export class Assignments {
     db;
     resources;
     actors;
-    constructor(db, resources, actors) {
+    options;
+    constructor(db, resources, actors, options = {}) {
         this.db = db;
         this.resources = resources;
         this.actors = actors;
+        this.options = options;
     }
     async forRecord(name, id, actor) {
         await this.resources.access(name, id, actor);
@@ -30,7 +33,7 @@ export class Assignments {
             .where({ 'a.resource': name, 'a.record_id': id })
             .orderByRaw("(a.status = 'open') DESC, a.id DESC")
             .limit(100);
-        return rows.map((row) => this.present(row, actor));
+        return this.titled(rows.map((row) => this.present(row, actor)), actor);
     }
     async assign(name, id, actor, input) {
         await this.resources.access(name, id, actor, 'update');
@@ -86,6 +89,7 @@ export class Assignments {
                 due_on: input.dueOn ?? null,
                 workflow_run_id: input.workflowRunId ?? null,
                 workflow_step: input.workflowStep ?? null,
+                managed: input.managed ?? false,
             })
                 .returning('id');
             await notifyWithTemplate(trx, input.assigneeId, input.kind === 'approval' ? 'assignment.approval' : 'assignment.created', {
@@ -93,7 +97,7 @@ export class Assignments {
                 resource: this.label(input.resource),
                 id: input.recordId,
                 due: input.dueOn ?? '',
-            });
+            }, undefined, { resource: input.resource, recordId: input.recordId });
             return this.query(trx).where('a.id', row.id).first();
         };
         return 'isTransaction' in db && db.isTransaction ? insert(db) : this.db.transaction(insert);
@@ -107,6 +111,10 @@ export class Assignments {
             query.where('a.status', 'open');
         if (status === 'done')
             query.whereNot('a.status', 'open');
+        if (options.kind === 'approval')
+            query.whereNotNull('a.workflow_run_id');
+        if (options.kind === 'task')
+            query.whereNull('a.workflow_run_id');
         let last = null;
         if (options.cursor !== undefined && options.cursor !== '') {
             last = Number(options.cursor);
@@ -135,20 +143,29 @@ export class Assignments {
                     data.push(this.present(row, actor));
             }
         }
-        const [{ count }] = await this.db('assignments')
+        const [{ count, approvals }] = await this.db('assignments')
             .where({ assignee_id: actor.id, status: 'open' })
-            .count('* as count');
+            .select(this.db.raw('count(*) as count'), this.db.raw('count(workflow_run_id) as approvals'));
         return {
-            data,
+            data: await this.titled(data, actor),
             nextCursor: more && last !== null ? String(last) : null,
             open: Number(count),
+            approvals: Number(approvals),
         };
     }
-    /** The assignee marks the task done, or the assigner cancels it. */
-    async complete(assignmentId, actor, outcome = 'done') {
+    /**
+     * The assignee marks the task done, or the assigner cancels it, with a closing note. The
+     * note is required when the application's policy says so and for managed tasks.
+     */
+    async complete(assignmentId, actor, outcome = 'done', input = {}) {
         const id = Number(assignmentId);
         if (!Number.isSafeInteger(id) || id <= 0)
             throw new KitError(404, 'E_ASSIGNMENT_NOT_FOUND', 'المهمة غير موجودة');
+        if (input.note !== undefined && input.note !== null && typeof input.note !== 'string')
+            throw new KitError(422, 'E_ASSIGNMENT_NOTE', 'ملاحظة الإغلاق غير صالحة');
+        const note = typeof input.note === 'string' ? input.note.trim() : '';
+        if (note.length > REASON_LIMIT)
+            throw new KitError(422, 'E_ASSIGNMENT_NOTE', 'ملاحظة الإغلاق لا تتجاوز 500 حرف');
         return this.db.transaction(async (trx) => {
             const row = await trx('assignments').where('id', id).forUpdate().first();
             if (!row)
@@ -164,19 +181,90 @@ export class Assignments {
                 throw new KitError(403, 'E_FORBIDDEN', 'يلغي المهمة من أسندها فقط');
             if (row.status !== 'open')
                 throw new KitError(409, 'E_ASSIGNMENT_CLOSED', 'المهمة مغلقة بالفعل');
+            if (!note && this.closeNote(row) === 'required')
+                throw new KitError(422, 'E_ASSIGNMENT_NOTE', 'اكتب ملاحظة الإغلاق قبل إغلاق المهمة');
             await trx('assignments')
                 .where('id', id)
-                .update({ status: outcome, completed_at: trx.fn.now(), completed_by: actor.id });
+                .update({
+                status: outcome,
+                completed_at: trx.fn.now(),
+                completed_by: actor.id,
+                close_reason: note || null,
+            });
+            // A managed task closed by hand leaves the note in the record's history.
+            if (row.managed)
+                await trx('activities').insert({
+                    resource: row.resource,
+                    record_id: row.record_id,
+                    actor_id: actor.id,
+                    action: 'assignment_closed',
+                    changes: JSON.stringify({
+                        fields: [],
+                        assignmentId: id,
+                        outcome,
+                        reason: note,
+                    }),
+                });
             const notify = outcome === 'done' ? row.assigned_by : row.assignee_id;
             if (notify && notify !== actor.id)
-                await notifyWithTemplate(trx, notify, outcome === 'done' ? 'assignment.done' : 'assignment.cancelled', { title: row.title, resource: this.label(row.resource), id: row.record_id });
+                await notifyWithTemplate(trx, notify, outcome === 'done' ? 'assignment.done' : 'assignment.cancelled', { title: row.title, resource: this.label(row.resource), id: row.record_id }, undefined, { resource: String(row.resource), recordId: Number(row.record_id) });
         });
     }
+    /**
+     * Closes the open managed tasks of a record when module code decides that its work is
+     * finished (or no longer needed), for example from a listener on the record's final
+     * state. Recorded in the record's activity log with the reason; the assigner (done) or
+     * the assignee (cancelled) is notified as for a manual close. Returns the closed count.
+     */
+    async close(resource, recordId, options) {
+        const outcome = options.outcome ?? 'done';
+        if (outcome !== 'done' && outcome !== 'cancelled')
+            throw new KitError(422, 'E_ASSIGNMENT_OUTCOME', 'Unsupported assignment outcome');
+        if (!Number.isSafeInteger(options.actorId) || options.actorId <= 0)
+            throw new KitError(422, 'E_ACTOR', 'Closing tasks requires the author user id');
+        const reason = options.reason?.trim() || null;
+        if (reason && reason.length > REASON_LIMIT)
+            throw new KitError(422, 'E_ASSIGNMENT_REASON', 'سبب الإغلاق لا يتجاوز 500 حرف');
+        const run = async (trx) => {
+            const rows = await trx('assignments')
+                .where({ resource, record_id: recordId, status: 'open', managed: true })
+                .whereNull('workflow_run_id')
+                .forUpdate()
+                .orderBy('id');
+            for (const row of rows) {
+                await trx('assignments').where('id', row.id).update({
+                    status: outcome,
+                    completed_at: trx.fn.now(),
+                    completed_by: options.actorId,
+                    close_reason: reason,
+                });
+                await trx('activities').insert({
+                    resource,
+                    record_id: recordId,
+                    actor_id: options.actorId,
+                    action: 'assignment_closed',
+                    changes: JSON.stringify({
+                        fields: [],
+                        system: true,
+                        assignmentId: Number(row.id),
+                        outcome,
+                        ...(reason ? { reason } : {}),
+                    }),
+                });
+                const notify = outcome === 'done' ? row.assigned_by : row.assignee_id;
+                if (notify && notify !== options.actorId)
+                    await notifyWithTemplate(trx, notify, outcome === 'done' ? 'assignment.done' : 'assignment.cancelled', { title: row.title, resource: this.label(row.resource), id: row.record_id }, undefined, { resource: String(row.resource), recordId: Number(row.record_id) });
+            }
+            return rows.length;
+        };
+        return options.trx ? run(options.trx) : this.db.transaction(run);
+    }
     query(db = this.db) {
         return db('assignments as a')
             .leftJoin('users as u', 'u.id', 'a.assignee_id')
             .leftJoin('users as b', 'b.id', 'a.assigned_by')
-            .select('a.*', 'u.full_name as assignee_name', 'b.full_name as assigned_by_name');
+            .leftJoin('workflow_runs as wr', 'wr.id', 'a.workflow_run_id')
+            .select('a.*', 'u.full_name as assignee_name', 'b.full_name as assigned_by_name', 'wr.status as run_status', 'wr.current_step as run_step');
     }
     present(row, actor) {
         const open = row.status === 'open';
@@ -185,6 +273,7 @@ export class Assignments {
             resource: String(row.resource),
             resourceLabel: this.label(row.resource),
             recordId: Number(row.record_id),
+            recordTitle: null,
             assigneeId: Number(row.assignee_id),
             assigneeName: row.assignee_name ? String(row.assignee_name) : null,
             assignedBy: row.assigned_by === null ? null : Number(row.assigned_by),
@@ -198,10 +287,35 @@ export class Assignments {
             createdAt: new Date(row.created_at).toISOString(),
             completedAt: row.completed_at ? new Date(row.completed_at).toISOString() : null,
             workflowRunId: row.workflow_run_id ? String(row.workflow_run_id) : null,
+            managed: Boolean(row.managed),
+            closeNote: this.closeNote(row),
+            closeReason: row.close_reason ? String(row.close_reason) : null,
             canComplete: open && !row.workflow_run_id && Number(row.assignee_id) === actor.id,
             canCancel: open && !row.workflow_run_id && Number(row.assigned_by) === actor.id,
+            // The same checks WorkflowEngine.decide() applies before accepting a decision.
+            canDecide: open &&
+                Boolean(row.workflow_run_id) &&
+                row.run_status === 'waiting' &&
+                row.run_step === row.workflow_step &&
+                Number(row.assignee_id) === actor.id,
         };
     }
+    /** Adds record titles in one read per resource, under the viewer's field access. */
+    async titled(list, actor) {
+        const byResource = new Map();
+        for (const item of list)
+            byResource.set(item.resource, [...(byResource.get(item.resource) ?? []), item.recordId]);
+        for (const [resource, ids] of byResource) {
+            const titles = await this.resources.titles(resource, ids, actor);
+            for (const item of list)
+                if (item.resource === resource)
+                    item.recordTitle = titles.get(item.recordId) ?? null;
+        }
+        return list;
+    }
+    closeNote(row) {
+        return row.managed || this.options.closeNote === 'required' ? 'required' : 'optional';
+    }
     label(name) {
         try {
             return this.resources.label(name);

package/build/src/collaboration/record_collaboration.js

@@ -126,12 +126,7 @@ export class RecordCollaboration {
             const authorName = author?.full_name ? String(author.full_name) : `مستخدم #${actor.id}`;
             const label = this.label(name);
             for (const userId of mentioned)
-                await notifyWithTemplate(trx, userId, 'comment.mentioned', {
-                    author: authorName,
-                    resource: label,
-                    id,
-                    excerpt: body.slice(0, 200),
-                });
+                await notifyWithTemplate(trx, userId, 'comment.mentioned', { author: authorName, resource: label, id, excerpt: body.slice(0, 200) }, undefined, { resource: name, recordId: id });
             const followers = await trx('followers')
                 .where({ resource: name, record_id: id })
                 .whereNot('user_id', actor.id)
@@ -140,12 +135,7 @@ export class RecordCollaboration {
             for (const userId of followers) {
                 if (!(await this.canView(name, id, Number(userId))))
                     continue;
-                await notifyWithTemplate(trx, Number(userId), 'comment.created', {
-                    author: authorName,
-                    resource: label,
-                    id,
-                    excerpt: body.slice(0, 200),
-                });
+                await notifyWithTemplate(trx, Number(userId), 'comment.created', { author: authorName, resource: label, id, excerpt: body.slice(0, 200) }, undefined, { resource: name, recordId: id });
             }
             const names = mentioned.length
                 ? await trx('users').whereIn('id', mentioned).select('id', 'full_name')
@@ -302,11 +292,9 @@ export class RecordCollaboration {
                 for (const userId of followers) {
                     if (event !== 'deleted' && !(await this.canView(resource, id, Number(userId))))
                         continue;
-                    await notifyWithTemplate(trx, Number(userId), 'record.changed', {
-                        change: verbs[event] ?? 'تحديث',
-                        resource: this.label(resource),
-                        id,
-                    });
+                    await notifyWithTemplate(trx, Number(userId), 'record.changed', { change: verbs[event] ?? 'تحديث', resource: this.label(resource), id }, undefined, 
+                    // A deleted record has no page to open.
+                    event === 'deleted' ? null : { resource, recordId: id });
                 }
             },
         };

package/build/src/commands/capabilities.js

@@ -1,4 +1,6 @@
 import { KIT_VERSION } from '../version.js';
+import { WORKFLOW_NAME_RULE } from '../workflows/define_workflow.js';
+import { ACTOR_ID } from '../auth/conditions.js';
 /** Field kinds accepted by defineResource, with their storage. */
 export const FIELD_TYPES = {
     string: 'varchar',
@@ -11,6 +13,7 @@ export const FIELD_TYPES = {
     json: 'jsonb',
     attachment: 'attachments row id; per-field accept/maxSize',
     belongsTo: 'foreign key, preloaded, restrict on delete',
+    user: 'users foreign key, restrict on delete; choices are active members of the record unit or its ancestors; related as { id, fullName }',
     hasMany: 'child resource; inline rows saved with the parent',
     lookup: 'lookups group key',
 };
@@ -26,6 +29,8 @@ export const FIELD_OPTIONS = [
 ];
 export const RESOURCE_OPTIONS = [
     'scoped (required)',
+    'scope.from (the unit follows a required belongsTo parent)',
+    'title (fields that name the record in relations, pickers, tasks and approvals)',
     'submittable (docStatus, submit/cancel/amend-by-copy)',
     'version (optimistic locking, default with submittable)',
     'customFields',
@@ -34,7 +39,16 @@ export const RESOURCE_OPTIONS = [
     'hooks.beforeSave / hooks.afterSave',
 ];
 export const CONDITION_OPERATORS = ['$eq', '$ne', '$in', '$lt', '$gt', '$like'];
-export const WORKFLOW_STEPS = ['condition', 'update', 'notify', 'approval', 'delay', 'http', 'end'];
+export const WORKFLOW_STEPS = [
+    'condition',
+    'update',
+    'notify',
+    'approval',
+    'decision',
+    'delay',
+    'http',
+    'end',
+];
 /**
  * Kit services by concern. Every name is a public export of @adula/kit; a test
  * checks this list against the package entry so the catalog cannot drift.
@@ -69,6 +83,7 @@ export const SERVICES = {
     'Integration': [
         'Webhooks',
         'signWebhook',
+        'InboundWebhooks',
         'openApiDocument',
         'ImportBatches',
         'renderPrintHtml',
@@ -90,11 +105,15 @@ export const SERVICES = {
 };
 export const EXTENSION_POINTS = [
     'Resource hooks (beforeSave, afterSave) inside the save transaction',
+    'ResourceService.systemSave for module-decided writes (validator, hooks and audit, no role rules); ResourceService.rehome after a parent moves',
+    'Assignment closing notes (Assignments closeNote: optional or required); managed assignments (managed: true) closed by module code with Assignments.close',
     'Page override: inertia/pages/<resource>/{index,form,show}.tsx replaces the generated page',
+    'Create links with defaults: /resources/<resource>/create?defaults[field]=value',
     'Domain events <module>.<resource>.{created,updated,deleted,submitted,cancelled,amended} with idempotent listeners',
     'Module workflows (Module.workflows) with versioned definitions',
     'Message templates edited per deployment',
     'Outgoing webhooks and the bearer-token /api/v1 API',
+    'Signed inbound webhooks raising inbound.<source>.<event> through the outbox',
 ];
 export const OUTSIDE_THE_KIT = [
     'Dynamic fields or a field editor screen',
@@ -120,9 +139,9 @@ export function capabilityCatalog(options = {}) {
         '',
         `Resource options: ${RESOURCE_OPTIONS.join(', ')}.`,
         '',
-        `Role rule conditions: ${CONDITION_OPERATORS.join(', ')} on scalar fields; unsupported conditions are refused. Organization scope is always added with AND.`,
+        `Role rule conditions: ${CONDITION_OPERATORS.join(', ')} on scalar fields; unsupported conditions are refused. Organization scope is always added with AND. \`${ACTOR_ID}\` names the signed-in user on user fields, createdBy and updatedBy ($eq, $ne, $in), bound per request.`,
         '',
-        `Workflow steps: ${WORKFLOW_STEPS.join(', ')}.`,
+        `Workflow steps: ${WORKFLOW_STEPS.join(', ')}. Workflow and step names: ${WORKFLOW_NAME_RULE} (for example release_approval, notify_approved).`,
         '',
         '## Services',
         '',

package/build/src/commands/doctor.d.ts

@@ -1,4 +1,7 @@
 import type { Settings } from '../services/settings.js';
+import type { Field, Resource } from '../resource/types.js';
+import type { WorkflowDefinition } from '../workflows/define_workflow.js';
+import type { RuntimeHealth } from '../core/health.js';
 export type Finding = {
     check: string;
     status: 'pass' | 'warn' | 'fail' | 'info';
@@ -9,3 +12,31 @@ export declare function diagnoseUploads(root: string): Promise<Finding>;
 export declare function diagnoseUi(root: string): Promise<Finding[]>;
 export declare function diagnoseAgentSkills(root: string): Promise<Finding>;
 export declare function diagnose(root: string, settings: Settings, production: boolean, env: Record<string, string | undefined>, now?: number): Promise<Finding[]>;
+type TableShape = Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields'> & {
+    fields: Record<string, Pick<Field, 'column' | 'required' | 'sequence' | 'unique' | 'searchable'> & {
+        type: string;
+        resource?: string;
+    }>;
+};
+/**
+ * A generated create-migration embeds the definition as it was at scaffold time. While it is
+ * still pending, compare that snapshot with the current resource so the table matches (#20).
+ */
+export declare function diagnoseResourceSnapshots(pending: {
+    file: string;
+    source: string;
+}[], resource: (name: string) => TableShape | undefined): Finding;
+/**
+ * Workflow recipients address roles by their stable key, or for compatibility by
+ * their editable display name. List references that match no role, and those that
+ * only match a display name, which a rename in the roles screen would break (#25).
+ */
+export declare function diagnoseWorkflowRoles(workflows: readonly Pick<WorkflowDefinition, 'name' | 'version' | 'steps'>[], roles: readonly (string | {
+    key: string | null;
+    name: string;
+})[]): Finding;
+/** Events wait in the outbox until a worker publishes them; a stale backlog means none runs (#50). */
+export declare function diagnoseOutbox(health: Pick<RuntimeHealth, 'outbox'> & {
+    heartbeats: Pick<RuntimeHealth['heartbeats'], 'worker'>;
+}): Finding;
+export {};

package/build/src/commands/doctor.js

@@ -2,9 +2,12 @@ import { lstat, readFile, readdir, realpath } from 'node:fs/promises';
 import { isAbsolute, join, relative } from 'node:path';
 import { KIT_VERSION } from '../version.js';
 import { agentAssets, managedRules, digest } from './agent_assets.js';
+import { columnName } from '../resource/define_resource.js';
 // The deployment volume and backup scripts share this application-relative path.
 const UPLOADS_PATH = 'storage/uploads';
 const UPLOADS_WARNING_BYTES = 5_000_000_000;
+/** An event the worker has not published within this age suggests that no worker runs. */
+const OUTBOX_STALE_MS = 60_000;
 async function assertContained(root, path) {
     const resolved = relative(await realpath(root), await realpath(path));
     if (resolved === '..' ||
@@ -259,3 +262,114 @@ export async function diagnose(root, settings, production, env, now = Date.now()
         findings.push(...(await diagnoseUi(root)));
     return findings;
 }
+/** The columns and indexes createResourceTable derives from a definition, one entry each. */
+function tableShape(resource) {
+    const shape = new Map();
+    for (const flag of ['scoped', 'version', 'submittable', 'customFields'])
+        if (resource[flag])
+            shape.set(flag, flag);
+    for (const [key, field] of Object.entries(resource.fields)) {
+        if (field.type === 'hasMany')
+            continue;
+        const column = field.column ?? columnName(key);
+        const traits = [
+            field.type === 'belongsTo' ? `belongsTo ${field.resource}` : field.type,
+            ...(field.required || field.sequence ? ['required'] : []),
+            ...(field.unique ? ['unique'] : []),
+            ...(field.searchable ? ['searchable'] : []),
+        ];
+        shape.set(column, `${column} (${traits.join(', ')})`);
+    }
+    return shape;
+}
+/**
+ * A generated create-migration embeds the definition as it was at scaffold time. While it is
+ * still pending, compare that snapshot with the current resource so the table matches (#20).
+ */
+export function diagnoseResourceSnapshots(pending, resource) {
+    const drift = [];
+    for (const { file, source } of pending) {
+        const embedded = /createResourceTable\([^,]+,\s*(\{[\s\S]*\})\s*\)\s*\}/.exec(source)?.[1];
+        if (!embedded)
+            continue;
+        let snapshot;
+        try {
+            snapshot = JSON.parse(embedded);
+        }
+        catch {
+            continue;
+        }
+        const current = resource(snapshot.name);
+        if (!current)
+            continue;
+        const [before, after] = [tableShape(snapshot), tableShape(current)];
+        const changed = [...new Set([...before.keys(), ...after.keys()])]
+            .filter((key) => before.get(key) !== after.get(key))
+            .map((key) => after.get(key) ?? `without ${before.get(key)}`);
+        if (changed.length)
+            drift.push(`${file} (${snapshot.name}): ${changed.join('; ')}`);
+    }
+    return {
+        check: 'resources.snapshots',
+        status: drift.length ? 'warn' : 'pass',
+        message: drift.length
+            ? `Pending create-migrations differ from their resource definitions; run node ace adula:resource:snapshot <name> (or update the embedded definition) before migration:run: ${drift.join(' | ')}`
+            : 'Pending resource migrations match their definitions',
+    };
+}
+/**
+ * Workflow recipients address roles by their stable key, or for compatibility by
+ * their editable display name. List references that match no role, and those that
+ * only match a display name, which a rename in the roles screen would break (#25).
+ */
+export function diagnoseWorkflowRoles(workflows, roles) {
+    const keys = new Set(roles.flatMap((role) => (typeof role === 'string' || !role.key ? [] : [role.key])));
+    const names = new Set(roles.map((role) => (typeof role === 'string' ? role : role.name)));
+    const missing = [];
+    const byName = [];
+    for (const workflow of workflows)
+        for (const [key, step] of Object.entries(workflow.steps)) {
+            const to = step.type === 'approval' ? step.assignees : step.type === 'notify' ? step.to : null;
+            if (!to || typeof to !== 'object' || !('role' in to) || keys.has(to.role))
+                continue;
+            const reference = `${workflow.name}@${workflow.version}.${key} → "${to.role}"`;
+            if (names.has(to.role))
+                byName.push(reference);
+            else
+                missing.push(reference);
+        }
+    // Plain name lists (older hosts) cannot tell keys from names; only missing roles matter.
+    const keyed = roles.some((role) => typeof role !== 'string');
+    const messages = [
+        ...(missing.length
+            ? [
+                `Workflow steps address roles that match no role key or name; approvals there fail: ${missing.join(', ')}`,
+            ]
+            : []),
+        ...(keyed && byName.length
+            ? [
+                `Workflow steps address roles by display name; give each role a key and address it by key so renaming cannot detach approvers: ${byName.join(', ')}`,
+            ]
+            : []),
+    ];
+    return {
+        check: 'workflows.roles',
+        status: messages.length ? 'warn' : 'pass',
+        message: messages.length
+            ? messages.join(' | ')
+            : 'Every role addressed by a workflow step exists',
+    };
+}
+/** Events wait in the outbox until a worker publishes them; a stale backlog means none runs (#50). */
+export function diagnoseOutbox(health) {
+    const { backlog, oldestAgeMs } = health.outbox;
+    const worker = health.heartbeats.worker.healthy ? 'running' : 'not running (no recent heartbeat)';
+    const stale = backlog > 0 && oldestAgeMs !== null && oldestAgeMs >= OUTBOX_STALE_MS;
+    return {
+        check: 'events.outbox',
+        status: stale ? 'warn' : 'pass',
+        message: stale
+            ? `${backlog} unpublished events, the oldest ${Math.round(oldestAgeMs / 1000)} s old; the worker is ${worker}. Listeners run only while \`node ace adula:worker\` runs`
+            : `No outbox event is older than ${OUTBOX_STALE_MS / 1000} s; the worker is ${worker}`,
+    };
+}

package/build/src/commands/gap_report.d.ts

@@ -1,8 +1,56 @@
+export declare const KIT_ISSUES_URL = "https://github.com/adulash/adula-kit/issues";
+/**
+ * KIT_GAPS.md entry fields, in the order of the kit's gap issue form
+ * (.github/ISSUE_TEMPLATE/gap.yml). `id` is the form field id used to prefill it.
+ */
+export declare const GAP_FIELDS: readonly [{
+    readonly label: "Package";
+    readonly id: "package";
+    readonly required: true;
+}, {
+    readonly label: "Needed by";
+    readonly id: "needed";
+    readonly required: true;
+}, {
+    readonly label: "Tried";
+    readonly id: "tried";
+    readonly required: true;
+}, {
+    readonly label: "Blocked because";
+    readonly id: "blocked";
+    readonly required: true;
+}, {
+    readonly label: "Proposed kit change";
+    readonly id: "proposal";
+    readonly required: true;
+}, {
+    readonly label: "Reproduction";
+    readonly id: "reproduction";
+    readonly required: true;
+}, {
+    readonly label: "Acceptance";
+    readonly id: "acceptance";
+    readonly required: true;
+}, {
+    readonly label: "Workaround";
+    readonly id: "workaround";
+    readonly required: false;
+}];
+export declare const GAPS_TEMPLATE = "# Kit gaps\n\nRecord each limitation of the kit as one entry. Describe the kit capability, not this\nproject: reproduce it on a new application from create-app. Run `node ace adula:gaps report`\nto open the kit's gap form prefilled, then write the issue number in `Issue:`.\n\n<!--\n## GAP-001 \u2014 Short title naming the kit capability\nPackage: @adula/kit 1.0.0\nNeeded by: the kit capability that is missing, stated without project details\nTried: the kit extension points tried\nBlocked because: why none of them works\nProposed kit change: the API, option or fix the kit should offer\nReproduction: steps on a new application from create-app\nAcceptance: the test that proves the gap is closed\nWorkaround: none, or what the project does meanwhile\nIssue:\n-->\n";
+export interface GapEntry {
+    title: string;
+    fields: Record<string, string>;
+    issue: string;
+    missing: string[];
+    url?: string;
+}
 /**
  * Prepares KIT_GAPS.md for sharing with the kit maintainers: e-mails, URLs and
- * IPv4 addresses are masked, and gap titles are listed for a quick review.
+ * IPv4 addresses are masked, gap titles are listed for a quick review, and each
+ * unreported gap gets a link that opens the kit's gap form prefilled. Nothing is sent.
  */
-export declare function gapReport(content: string): {
+export declare function gapReport(content: string, issuesUrl?: string): {
     masked: string;
     titles: string[];
+    gaps: GapEntry[];
 };