@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/commands/resource_snapshot.js

@@ -0,0 +1,61 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args } from '@adonisjs/core/ace';
+import { readFile, writeFile } from 'node:fs/promises';
+import { MigrationRunner } from '@adonisjs/lucid/migration';
+import { embeddedResource, resourceSnapshot, rewriteResourceSnapshot, } from '../src/commands/snapshot.js';
+/**
+ * Rewrites the definition embedded in a resource's generated create-migration from the
+ * current resource, while that migration has not run yet (#20). A migration that already
+ * ran is never edited: change the table with a new expand migration instead.
+ */
+export default class ResourceSnapshot extends BaseCommand {
+    static commandName = 'adula:resource:snapshot';
+    static description = "Refresh a pending generated create-migration from the resource's current definition";
+    static options = { startApp: true };
+    async run() {
+        const { default: db } = await import('@adonisjs/lucid/services/db');
+        const { registry } = (await this.app.import('#start/modules'));
+        let resource;
+        try {
+            resource = registry.get(this.name);
+        }
+        catch {
+            this.logger.error(`Unknown resource: ${this.name}. Register it in its module first.`);
+            this.exitCode = 1;
+            return;
+        }
+        const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
+        const matches = [];
+        for (const entry of migrations)
+            for (const extension of ['.ts', '.js'])
+                try {
+                    const file = `${entry.name}${extension}`;
+                    const source = await readFile(this.app.makePath(file), 'utf8');
+                    if (embeddedResource(source) === this.name)
+                        matches.push({ file, source, pending: entry.status === 'pending' });
+                    break;
+                }
+                catch { }
+        const pending = matches.filter((match) => match.pending);
+        if (!pending.length) {
+            this.logger.error(matches.length
+                ? `${matches[0].file} already ran; never edit it. Add an expand migration for the new columns instead.`
+                : `No generated create-migration embeds ${this.name}.`);
+            this.exitCode = 1;
+            return;
+        }
+        for (const match of pending) {
+            await writeFile(this.app.makePath(match.file), rewriteResourceSnapshot(match.source, resourceSnapshot(resource)));
+            this.logger.success(match.file);
+        }
+        this.logger.info('Update the model, factory and contract fixture to the same fields, then run migration:run.');
+    }
+}
+__decorate([
+    args.string({ description: 'Resource name' })
+], ResourceSnapshot.prototype, "name", void 0);

package/build/database/migrations/1770000000004_kit_collaboration.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitCollaboration extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000004_kit_collaboration.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createCollaborationSchema } from '../../src/database/schema.js';
+export default class KitCollaboration extends BaseSchema {
+    async up() {
+        await createCollaborationSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000005_kit_assignments.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitAssignments extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000005_kit_assignments.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createAssignmentsSchema } from '../../src/database/schema.js';
+export default class KitAssignments extends BaseSchema {
+    async up() {
+        await createAssignmentsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000006_kit_messaging.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitMessaging extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000006_kit_messaging.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createMessagingSchema } from '../../src/database/schema.js';
+export default class KitMessaging extends BaseSchema {
+    async up() {
+        await createMessagingSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000007_kit_webhooks.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitWebhooks extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000007_kit_webhooks.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createWebhooksSchema } from '../../src/database/schema.js';
+export default class KitWebhooks extends BaseSchema {
+    async up() {
+        await createWebhooksSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000008_kit_imports.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitImports extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000008_kit_imports.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createImportsSchema } from '../../src/database/schema.js';
+export default class KitImports extends BaseSchema {
+    async up() {
+        await createImportsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000010_kit_workflows.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitWorkflows extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000010_kit_workflows.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createWorkflowSchema } from '../../src/database/schema.js';
+export default class KitWorkflows extends BaseSchema {
+    async up() {
+        await createWorkflowSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000011_kit_managed_assignments.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitManagedAssignments extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000011_kit_managed_assignments.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createManagedAssignmentsSchema } from '../../src/database/schema.js';
+export default class KitManagedAssignments extends BaseSchema {
+    async up() {
+        await createManagedAssignmentsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000012_kit_role_keys.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitRoleKeys extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000012_kit_role_keys.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createRoleKeysSchema } from '../../src/database/schema.js';
+export default class KitRoleKeys extends BaseSchema {
+    async up() {
+        await createRoleKeysSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000013_kit_notification_targets.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitNotificationTargets extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000013_kit_notification_targets.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createNotificationTargetsSchema } from '../../src/database/schema.js';
+export default class KitNotificationTargets extends BaseSchema {
+    async up() {
+        await createNotificationTargetsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000014_kit_upload_grants.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitUploadGrants extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000014_kit_upload_grants.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createUploadGrantsSchema } from '../../src/database/schema.js';
+export default class KitUploadGrants extends BaseSchema {
+    async up() {
+        await createUploadGrantsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000015_kit_inbound_webhooks.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitInboundWebhooks extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000015_kit_inbound_webhooks.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createInboundWebhooksSchema } from '../../src/database/schema.js';
+export default class KitInboundWebhooks extends BaseSchema {
+    async up() {
+        await createInboundWebhooksSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/index.d.ts

@@ -11,16 +11,41 @@ export { packedResourceRules } from './src/auth/packed_rules.js';
 export type { Actor, Rule, KitAbility } from './src/auth/ability.js';
 export { ActorStore } from './src/auth/actor_store.js';
 export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js';
-export { ResourceService } from './src/admin/resource_service.js';
+export { ACTOR_ID, resolveActorConditions } from './src/auth/conditions.js';
+export { ResourceService, canQueryField } from './src/admin/resource_service.js';
+export type { AggregateOptions, AggregateRow, ListOptions } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
-export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, createManagedAssignmentsSchema, createRoleKeysSchema, createNotificationTargetsSchema, createUploadGrantsSchema, createInboundWebhooksSchema, } from './src/database/schema.js';
+export { defineWorkflow, nextStep } from './src/workflows/define_workflow.js';
+export type { WorkflowDefinition, WorkflowInput, WorkflowStep, WorkflowEvent, StepContext, Recipients, DecisionOutcome, } from './src/workflows/define_workflow.js';
+export { WorkflowEngine, workflowListeners } from './src/workflows/engine.js';
+export type { WorkflowRun, WorkflowRunStatus, WorkflowOptions, WorkflowDecisionForm, } from './src/workflows/engine.js';
+export { ImportBatches, importCell, IMPORT_ROW_LIMIT } from './src/integrations/imports.js';
+export type { ImportBatch, ImportStatus, ImportTarget, ActorSource, } from './src/integrations/imports.js';
+export { openApiDocument } from './src/integrations/openapi.js';
+export { renderPrintHtml, htmlToPdf } from './src/integrations/print.js';
+export type { PrintIdentity, PrintInput } from './src/integrations/print.js';
+export { Webhooks, signWebhook, WEBHOOK_MAX_ATTEMPTS } from './src/integrations/webhooks.js';
+export { InboundWebhooks, inboundEventName, INBOUND_BODY_LIMIT, INBOUND_RETENTION_DAYS, } from './src/integrations/inbound_webhooks.js';
+export type { InboundSource, InboundSourceInput, InboundDelivery, InboundReceipt, } from './src/integrations/inbound_webhooks.js';
+export type { SecretBox, Webhook, WebhookDelivery, WebhookOptions, HttpPoster, } from './src/integrations/webhooks.js';
+export { MessageTemplates, DEFAULT_TEMPLATES, renderTemplate, notifyWithTemplate, deliverNotificationMail, listenForNotifications, } from './src/core/message_templates.js';
+export type { TemplateDefinition, MessageTemplate, RenderedMessage, MailSender, NotificationSignal, } from './src/core/message_templates.js';
+export { Assignments } from './src/collaboration/assignments.js';
+export type { Assignment, AssignmentPage, AssignmentOptions, CloseNotePolicy, AssignmentStatus, } from './src/collaboration/assignments.js';
+export { RecordCollaboration, followerListeners } from './src/collaboration/record_collaboration.js';
+export type { ActorLoader, CommentEntry, FieldChangeEntry, RecordCollaborationState, MentionCandidate, } from './src/collaboration/record_collaboration.js';
+export type { FieldChange } from './src/events/record_mutation.js';
 export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, attachmentPolicy, pendingUploadCount, staleUploads, forgetUpload, DEFAULT_ATTACHMENT_EXTENSIONS, PENDING_UPLOAD_LIMIT, UNBOUND_UPLOAD_TTL_MS, } from './src/attachments/attachment_service.js';
 export type { AttachmentRecord, AttachmentSummary, UploadInput, ClaimInput, } from './src/attachments/attachment_service.js';
+export { grantUpload, redeemUploadGrant, pruneUploadGrants, UPLOAD_GRANT_MAX_TTL_MS, } from './src/attachments/upload_grants.js';
+export type { UploadGrantInput, UploadGrant, RedeemedUploadGrant, } from './src/attachments/upload_grants.js';
 export { migrateStorage } from './src/attachments/storage_migrate.js';
 export type { StorageDisk, StorageMigrationOptions, StorageMigrationResult, } from './src/attachments/storage_migrate.js';
 export { diagnoseAttachments } from './src/attachments/doctor.js';
 export { Settings, sequence, notify } from './src/services/settings.js';
+export type { NotificationTarget } from './src/services/settings.js';
 export { uiPreferences, validateUiPreferences, UI_PREFERENCES_KEY, DEFAULT_UI_PREFERENCES, } from './src/core/ui_preferences.js';
 export type { UiPreferences, CalendarSystem, CalendarPreference, } from './src/core/ui_preferences.js';
 export { moveOrgUnit } from './src/org/org_service.js';
@@ -33,6 +58,8 @@ export type { BackupObject, BackupStatus } from './src/services/backup.js';
 export { ActivityAdmin, logActivity } from './src/core/activity.js';
 export type { ActivityEntry, ActivityFilters, ActivityPage, ActivityRow, } from './src/core/activity.js';
 export { RolesAdmin, ALL_SUBJECT_LABEL } from './src/core/roles.js';
+export { seedModules } from './src/core/module_seed.js';
+export type { ModuleSeedResult } from './src/core/module_seed.js';
 export type { RoleSummary, RoleDetail, RoleRule, RuleInput, RoleMatrix, MatrixSubject, MatrixField, } from './src/core/roles.js';
 export { UsersAdmin } from './src/core/users.js';
 export { UserInvitations, type InvitationDelivery } from './src/core/user_invitations.js';
@@ -49,3 +76,5 @@ export { runtimeHealth, isBackupStale, backupStale, heartbeat, HEARTBEAT_MAX_AGE
 export type { RuntimeHealth, HeartbeatStatus, QueueSnapshot, QueueCounts, FailedJob, } from './src/core/health.js';
 export { MailDeliveryTest, MAIL_TEST_KEY, type MailTestState } from './src/core/mail_test.js';
 export { InitialSetup, type SetupCheck } from './src/core/setup.js';
+export { KIT_VERSION } from './src/version.js';
+export { capabilityCatalog, SERVICES as CAPABILITY_SERVICES, FIELD_TYPES, WORKFLOW_STEPS, } from './src/commands/capabilities.js';

package/build/index.js

@@ -7,11 +7,23 @@ export { buildAbility, canRecord, inOrgScope } from './src/auth/ability.js';
 export { packedResourceRules } from './src/auth/packed_rules.js';
 export { ActorStore } from './src/auth/actor_store.js';
 export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js';
-export { ResourceService } from './src/admin/resource_service.js';
+export { ACTOR_ID, resolveActorConditions } from './src/auth/conditions.js';
+export { ResourceService, canQueryField } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
-export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, createManagedAssignmentsSchema, createRoleKeysSchema, createNotificationTargetsSchema, createUploadGrantsSchema, createInboundWebhooksSchema, } from './src/database/schema.js';
+export { defineWorkflow, nextStep } from './src/workflows/define_workflow.js';
+export { WorkflowEngine, workflowListeners } from './src/workflows/engine.js';
+export { ImportBatches, importCell, IMPORT_ROW_LIMIT } from './src/integrations/imports.js';
+export { openApiDocument } from './src/integrations/openapi.js';
+export { renderPrintHtml, htmlToPdf } from './src/integrations/print.js';
+export { Webhooks, signWebhook, WEBHOOK_MAX_ATTEMPTS } from './src/integrations/webhooks.js';
+export { InboundWebhooks, inboundEventName, INBOUND_BODY_LIMIT, INBOUND_RETENTION_DAYS, } from './src/integrations/inbound_webhooks.js';
+export { MessageTemplates, DEFAULT_TEMPLATES, renderTemplate, notifyWithTemplate, deliverNotificationMail, listenForNotifications, } from './src/core/message_templates.js';
+export { Assignments } from './src/collaboration/assignments.js';
+export { RecordCollaboration, followerListeners } from './src/collaboration/record_collaboration.js';
 export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, attachmentPolicy, pendingUploadCount, staleUploads, forgetUpload, DEFAULT_ATTACHMENT_EXTENSIONS, PENDING_UPLOAD_LIMIT, UNBOUND_UPLOAD_TTL_MS, } from './src/attachments/attachment_service.js';
+export { grantUpload, redeemUploadGrant, pruneUploadGrants, UPLOAD_GRANT_MAX_TTL_MS, } from './src/attachments/upload_grants.js';
 export { migrateStorage } from './src/attachments/storage_migrate.js';
 export { diagnoseAttachments } from './src/attachments/doctor.js';
 export { Settings, sequence, notify } from './src/services/settings.js';
@@ -23,6 +35,7 @@ export { recordMutation } from './src/events/record_mutation.js';
 export { assessBackup, verifyBackup } from './src/services/backup.js';
 export { ActivityAdmin, logActivity } from './src/core/activity.js';
 export { RolesAdmin, ALL_SUBJECT_LABEL } from './src/core/roles.js';
+export { seedModules } from './src/core/module_seed.js';
 export { UsersAdmin } from './src/core/users.js';
 export { UserInvitations } from './src/core/user_invitations.js';
 export { OrgUnitsAdmin } from './src/core/org_units.js';
@@ -32,3 +45,5 @@ export { SettingsAdmin, isProtectedSetting, parseSettingValue, SETTING_SCOPES, P
 export { runtimeHealth, isBackupStale, backupStale, heartbeat, HEARTBEAT_MAX_AGE_MS, BACKUP_MAX_AGE_MS, } from './src/core/health.js';
 export { MailDeliveryTest, MAIL_TEST_KEY } from './src/core/mail_test.js';
 export { InitialSetup } from './src/core/setup.js';
+export { KIT_VERSION } from './src/version.js';
+export { capabilityCatalog, SERVICES as CAPABILITY_SERVICES, FIELD_TYPES, WORKFLOW_STEPS, } from './src/commands/capabilities.js';

package/build/src/admin/contracts.d.ts

@@ -10,3 +10,10 @@ export declare function serialize(resource: Resource, record: RecordData, abilit
 export declare function writableInput(resource: Resource, input: RecordData): {
     [k: string]: unknown;
 };
+/**
+ * Values module code may write through ResourceService.systemSave: every stored field
+ * except sequences and inline children, plus the organization unit when it is not inherited.
+ */
+export declare function systemInput(resource: Resource, input: RecordData): {
+    [k: string]: unknown;
+};

package/build/src/admin/contracts.js

@@ -13,24 +13,33 @@ export function selectedFields(resource, ability, options = {}) {
             ...(options.write
                 ? Object.keys(resource.fields)
                 : (resource.serialize ?? [...resource.list, ...resource.show])),
-            ...Object.keys(resource.fields).filter((k) => resource.fields[k].type === 'belongsTo'),
+            ...Object.keys(resource.fields).filter((k) => ['belongsTo', 'user'].includes(resource.fields[k].type)),
             ...(options.extra ?? []),
             ...conditionFields(ability, resource),
         ]),
     ].filter((key) => key !== 'orgPath' && resource.fields[key]?.type !== 'hasMany');
 }
+const rowKeys = new WeakMap();
+/** Record keys and their columns for a resource, computed once per definition. */
+function keysOf(resource) {
+    let keys = rowKeys.get(resource);
+    if (!keys) {
+        keys = [
+            ...standard,
+            'orgUnitId',
+            'version',
+            'docStatus',
+            'amendedFromId',
+            'orgPath',
+            ...Object.keys(resource.fields),
+        ].map((key) => [key, resource.fields[key]?.column ?? columnName(key)]);
+        rowKeys.set(resource, keys);
+    }
+    return keys;
+}
 export function fromRow(row, resource) {
     const result = {};
-    for (const key of [
-        ...standard,
-        'orgUnitId',
-        'version',
-        'docStatus',
-        'amendedFromId',
-        'orgPath',
-        ...Object.keys(resource.fields),
-    ]) {
-        const column = resource.fields[key]?.column ?? columnName(key);
+    for (const [key, column] of keysOf(resource)) {
         if (column in row) {
             const value = row[column];
             result[key] =
@@ -83,7 +92,7 @@ export function serialize(resource, record, ability, actor) {
 export function writableInput(resource, input) {
     const allowed = new Set([
         ...resource.form,
-        ...(resource.scoped ? ['orgUnitId'] : []),
+        ...(resource.scoped && !resource.scope ? ['orgUnitId'] : []),
         ...(resource.version ? ['version'] : []),
     ]);
     for (const key of Object.keys(input))
@@ -91,3 +100,16 @@ export function writableInput(resource, input) {
             throw new KitError(422, 'E_FIELD_NOT_WRITABLE', `Field is not writable: ${key}`);
     return Object.fromEntries(Object.entries(input).filter(([key]) => resource.form.includes(key)));
 }
+/**
+ * Values module code may write through ResourceService.systemSave: every stored field
+ * except sequences and inline children, plus the organization unit when it is not inherited.
+ */
+export function systemInput(resource, input) {
+    for (const key of Object.keys(input)) {
+        const field = resource.fields[key];
+        const unit = key === 'orgUnitId' && resource.scoped && !resource.scope;
+        if (!unit && (!field || field.type === 'hasMany' || field.sequence))
+            throw new KitError(422, 'E_FIELD_NOT_WRITABLE', `Field is not writable: ${key}`);
+    }
+    return Object.fromEntries(Object.entries(input).filter(([key]) => key in resource.fields));
+}

package/build/src/admin/controller.d.ts

@@ -22,9 +22,11 @@ export interface ResourceController {
     destroy(ctx: HttpContext): Promise<unknown>;
     submit(ctx: HttpContext): Promise<unknown>;
     cancel(ctx: HttpContext): Promise<unknown>;
+    amend(ctx: HttpContext): Promise<unknown>;
     create(ctx: HttpContext): Promise<unknown>;
     edit(ctx: HttpContext): Promise<unknown>;
     options(ctx: HttpContext): Promise<unknown>;
+    aggregate(ctx: HttpContext): Promise<unknown>;
 }
 /** The host supplies its authenticated actor; ResourceService authorizes every action. */
 export declare function createResourceController(resolveRuntime: (ctx: HttpContext) => Promise<ResourceRuntime>, renderList?: (ctx: HttpContext, resource: Resource, result: ResourceList) => unknown, renderForm?: (ctx: HttpContext, resource: Resource, editor: ResourceEditor) => unknown, renderShow?: (ctx: HttpContext, resource: Resource, result: ResourceShow) => unknown): new () => ResourceController;

package/build/src/admin/controller.js

@@ -4,7 +4,13 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
     return class ResourcesController {
         async create(ctx) {
             return this.#execute(ctx, async ({ resources, actor }, resource) => {
-                const editor = await resources.editor(resource.name, actor);
+                // `?defaults[field]=value` pre-fills the form; the service authorizes each value.
+                const defaults = ctx.request.qs().defaults;
+                const editor = await resources.editor(resource.name, actor, undefined, {
+                    defaults: defaults && typeof defaults === 'object' && !Array.isArray(defaults)
+                        ? defaults
+                        : undefined,
+                });
                 return renderForm && ctx.request.accepts(['html', 'json']) === 'html'
                     ? renderForm(ctx, resource, editor)
                     : editor;
@@ -27,6 +33,7 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
                     sort: ctx.request.input('sort'),
                     direction: ctx.request.input('direction'),
                     filters: ctx.request.input('filters'),
+                    tag: ctx.request.input('tag'),
                     estimate: ctx.request.input('estimate') !== 'false' && ctx.request.input('estimate') !== false,
                 });
                 return renderList && ctx.request.accepts(['html', 'json']) === 'html'
@@ -49,8 +56,47 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
                     : this.#positiveId(ctx.request.input('id')),
                 search: ctx.request.input('search'),
                 cursor: ctx.request.input('cursor'),
+                orgUnitId: ctx.request.input('orgUnitId') === undefined || ctx.request.input('orgUnitId') === ''
+                    ? undefined
+                    : this.#positiveId(ctx.request.input('orgUnitId')),
+                purpose: ctx.request.input('purpose') === 'filter' ? 'filter' : 'form',
             }));
         }
+        /**
+         * GET …/aggregate?groupBy=status,priority&sum=total&filters[x]=…&where={json}
+         * Counts and totals over the records the actor may view (ResourceService.aggregate).
+         */
+        async aggregate(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const list = (value) => value === undefined || value === ''
+                    ? []
+                    : Array.isArray(value)
+                        ? value.map(String)
+                        : String(value).split(',').filter(Boolean);
+                let where;
+                const raw = ctx.request.input('where');
+                if (typeof raw === 'string' && raw) {
+                    try {
+                        where = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new KitError(422, 'E_FILTER', 'where must be a JSON object');
+                    }
+                }
+                else if (raw && typeof raw === 'object')
+                    where = raw;
+                return {
+                    data: await resources.aggregate(resource.name, actor, {
+                        groupBy: list(ctx.request.input('groupBy')),
+                        sum: list(ctx.request.input('sum')),
+                        count: ctx.request.input('count') !== 'false',
+                        filters: ctx.request.input('filters'),
+                        where: where,
+                        search: ctx.request.input('search'),
+                    }),
+                };
+            });
+        }
         async store(ctx) {
             return this.#execute(ctx, async ({ resources, actor }, resource) => ctx.response.created({
                 data: await resources.save(resource.name, actor, ctx.request.body()),
@@ -70,6 +116,11 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
         async cancel(ctx) {
             return this.#transition(ctx, 'cancel');
         }
+        async amend(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => ctx.response.created({
+                data: await resources.amend(resource.name, this.#id(ctx), actor),
+            }));
+        }
         #id(ctx) {
             return this.#positiveId(ctx.params.id);
         }

package/build/src/admin/presentation.d.ts

@@ -6,6 +6,10 @@ export type RecordPermissions = Partial<Record<Action, boolean>>;
 export type ResourceDescription = {
     name: string;
     label: string;
+    /** Singular record noun in Arabic, or null when the resource does not declare one. */
+    recordLabel: string | null;
+    /** Arabic create-button text, or null to derive «إضافة <recordLabel>» (or «إضافة سجل»). */
+    createLabel: string | null;
     fields: ResourceField[];
     list: string[];
     show: string[];
@@ -19,4 +23,6 @@ export type ResourceNavigation = {
     label: string;
     href: string;
     module: string;
+    /** Arabic module label, for grouping the navigation by module (1.2; optional for compatibility). */
+    moduleLabel?: string;
 }[];

package/build/src/admin/record_title.d.ts

@@ -0,0 +1,14 @@
+import type { Resource, SerializedRecord } from '../resource/types.js';
+/**
+ * The fields that name a record wherever it is referenced (#47, #32): the resource's
+ * `title`, or else its first sequence field and its first text field in `list`. Lookup
+ * keys are never shown raw; declared lookup fields are shown by their Arabic label.
+ */
+export declare function titleFields(resource: Pick<Resource, 'fields' | 'list' | 'title'>): string[];
+/** Definition check: title fields exist, are readable and have a displayable type. */
+export declare function assertTitle(resource: Pick<Resource, 'name' | 'fields' | 'list' | 'show' | 'serialize' | 'title'>): void;
+/**
+ * The title of one serialized record, read after field-level filtering so it never shows
+ * a value the viewer may not read. Returns null when no title field has a value.
+ */
+export declare function formatTitle(resource: Pick<Resource, 'fields' | 'list' | 'title'>, record: SerializedRecord, lookupLabel: (group: string, key: string) => string | undefined): string | null;