@adula/kit 1.0.0 → 1.2.0

package/build/src/commands/gap_report.js

@@ -1,12 +1,110 @@
+export 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 const GAP_FIELDS = [
+    { label: 'Package', id: 'package', required: true },
+    { label: 'Needed by', id: 'needed', required: true },
+    { label: 'Tried', id: 'tried', required: true },
+    { label: 'Blocked because', id: 'blocked', required: true },
+    { label: 'Proposed kit change', id: 'proposal', required: true },
+    { label: 'Reproduction', id: 'reproduction', required: true },
+    { label: 'Acceptance', id: 'acceptance', required: true },
+    { label: 'Workaround', id: 'workaround', required: false },
+];
+export const GAPS_TEMPLATE = `# Kit gaps
+
+Record each limitation of the kit as one entry. Describe the kit capability, not this
+project: reproduce it on a new application from create-app. Run \`node ace adula:gaps report\`
+to open the kit's gap form prefilled, then write the issue number in \`Issue:\`.
+
+<!--
+## GAP-001 — Short title naming the kit capability
+Package: @adula/kit 1.0.0
+Needed by: the kit capability that is missing, stated without project details
+Tried: the kit extension points tried
+Blocked because: why none of them works
+Proposed kit change: the API, option or fix the kit should offer
+Reproduction: steps on a new application from create-app
+Acceptance: the test that proves the gap is closed
+Workaround: none, or what the project does meanwhile
+Issue:
+-->
+`;
+/** Longest value put in one prefilled field; GitHub rejects very long URLs. */
+const FIELD_LIMIT = 1500;
+const labels = [...GAP_FIELDS.map((field) => field.label), 'Issue'];
+const fieldLine = new RegExp(`^(${labels.join('|')}):\\s*(.*)$`);
+function parseGaps(masked) {
+    const gaps = [];
+    let current;
+    let field;
+    let comment = false;
+    for (const line of masked.split(/\r?\n/)) {
+        if (line.trim().startsWith('<!--'))
+            comment = true;
+        if (comment) {
+            if (line.includes('-->'))
+                comment = false;
+            continue;
+        }
+        const heading = line.match(/^## (GAP-\d+.*)$/);
+        if (heading) {
+            current = { title: heading[1].trim(), fields: {}, issue: '', missing: [] };
+            gaps.push(current);
+            field = undefined;
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('#')) {
+            current = undefined;
+            continue;
+        }
+        const match = line.match(fieldLine);
+        if (match) {
+            field = match[1];
+            if (field === 'Issue')
+                current.issue = match[2].trim();
+            else
+                current.fields[field] = match[2].trim();
+        }
+        else if (field && field !== 'Issue') {
+            current.fields[field] = `${current.fields[field]}\n${line}`.trim();
+        }
+    }
+    return gaps;
+}
+function clip(value) {
+    return value.length > FIELD_LIMIT
+        ? `${value.slice(0, FIELD_LIMIT)}\n… (shortened; copy the rest from the masked report)`
+        : value;
+}
 /**
  * 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 function gapReport(content) {
+export function gapReport(content, issuesUrl = KIT_ISSUES_URL) {
     const masked = content
         .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, '<email>')
         .replace(/https?:\/\/[^\s)]+/g, '<url>')
         .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<ip>');
-    const titles = (masked.match(/^## GAP-\d+.*$/gm) ?? []).map((title) => title.replace(/^## /, ''));
-    return { masked, titles };
+    const gaps = parseGaps(masked);
+    for (const gap of gaps) {
+        gap.missing = GAP_FIELDS.filter((field) => field.required && !gap.fields[field.label]).map((field) => field.label);
+        if (gap.issue)
+            continue;
+        const url = new URL(`${issuesUrl}/new`);
+        url.searchParams.set('template', 'gap.yml');
+        url.searchParams.set('title', gap.title.replace(/^GAP-\d+\s*[—–-]?\s*/, ''));
+        for (const field of GAP_FIELDS) {
+            const value = gap.fields[field.label];
+            if (value)
+                url.searchParams.set(field.id, clip(value));
+        }
+        gap.url = url.toString();
+    }
+    return { masked, titles: gaps.map((gap) => gap.title), gaps };
 }

package/build/src/commands/generator.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile, access, glob } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { identifier } from '../resource/define_resource.js';
-import { appendMarkedItem } from './source_markers.js';
+import { appendMarkedItem, moduleSource } from './source_markers.js';
 export async function generateResource(root, name, module) {
     identifier(name);
     identifier(module);
@@ -10,7 +10,7 @@ export async function generateResource(root, name, module) {
     const base = resolve(root, 'app/modules', module);
     const title = name.replace(/_/g, ' ');
     const relative = `app/modules/${module}`;
-    const resourceSource = `import { defineResource } from '@adula/kit'\nimport Model from '#modules/${module}/models/${name}'\nimport { validator } from '#modules/${module}/validators/${name}'\n\nexport default defineResource({\n  name: '${name}', label: { ar: '${title}', en: '${title}' }, model: Model, scoped: true,\n  fields: { title: { type: 'string', label: { ar: 'العنوان', en: 'Title' }, required: true, searchable: true } },\n  list: ['title'], form: ['title'], show: ['title'],\n  actions: ['view', 'create', 'update', 'delete'], validator,\n})\n`;
+    const resourceSource = `import { defineResource } from '@adula/kit'\nimport Model from '#modules/${module}/models/${name}'\nimport { validator } from '#modules/${module}/validators/${name}'\n\nexport default defineResource({\n  name: '${name}', label: { ar: '${title}', en: '${title}' },\n  recordLabel: { ar: '${title}', en: '${title}' }, model: Model, scoped: true,\n  fields: { title: { type: 'string', label: { ar: 'العنوان', en: 'Title' }, required: true, searchable: true } },\n  list: ['title'], form: ['title'], show: ['title'],\n  actions: ['view', 'create', 'update', 'delete'], validator,\n})\n`;
     const migration = {
         name,
         scoped: true,
@@ -39,7 +39,7 @@ export async function generateResource(root, name, module) {
     catch (error) {
         if (error.code !== 'ENOENT')
             throw error;
-        current = `// adula:imports\nexport default { name: '${module}', label: { ar: '${module}', en: '${module}' }, dependsOn: [], resources: [/* adula:resources */] }\n`;
+        current = moduleSource(module);
     }
     if (!current.includes('// adula:imports') || !current.includes('/* adula:resources */'))
         throw new Error('Module registration markers are missing; no files were changed');

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

@@ -0,0 +1,28 @@
+import type { Resource } from '../resource/types.js';
+/**
+ * The part of a resource definition createResourceTable reads, as a generated
+ * create-migration embeds it. Labels are kept so the migration stays readable.
+ */
+export declare function resourceSnapshot(resource: Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields' | 'fields'>): {
+    fields: {
+        [k: string]: {
+            sequence?: string | undefined;
+            searchable?: boolean | undefined;
+            unique?: boolean | undefined;
+            required?: boolean | undefined;
+            column?: string | undefined;
+            resource?: string | undefined;
+            type: "string" | "boolean" | "text" | "integer" | "money" | "date" | "datetime" | "json" | "attachment" | "belongsTo" | "user" | "hasMany" | "lookup";
+            label: import("../resource/types.js").Label;
+        };
+    };
+    customFields?: boolean | undefined;
+    submittable?: boolean | undefined;
+    version?: boolean | undefined;
+    name: string;
+    scoped: boolean;
+};
+/** The resource name embedded in a generated create-migration, if the source is one. */
+export declare function embeddedResource(source: string): string | undefined;
+/** Replaces the embedded definition of a generated create-migration (#20). */
+export declare function rewriteResourceSnapshot(source: string, snapshot: ReturnType<typeof resourceSnapshot>): string;

package/build/src/commands/snapshot.js

@@ -0,0 +1,48 @@
+const EMBEDDED = /(createResourceTable\([^,]+,\s*)(\{[\s\S]*\})(\s*\)\s*\})/;
+/**
+ * The part of a resource definition createResourceTable reads, as a generated
+ * create-migration embeds it. Labels are kept so the migration stays readable.
+ */
+export function resourceSnapshot(resource) {
+    return {
+        name: resource.name,
+        scoped: resource.scoped,
+        ...(resource.version ? { version: true } : {}),
+        ...(resource.submittable ? { submittable: true } : {}),
+        ...(resource.customFields ? { customFields: true } : {}),
+        fields: Object.fromEntries(Object.entries(resource.fields)
+            .filter(([, field]) => field.type !== 'hasMany')
+            .map(([key, field]) => [
+            key,
+            {
+                type: field.type,
+                label: field.label,
+                ...(field.type === 'belongsTo' ? { resource: field.resource } : {}),
+                ...(field.column ? { column: field.column } : {}),
+                ...(field.required ? { required: true } : {}),
+                ...(field.unique ? { unique: true } : {}),
+                ...(field.searchable ? { searchable: true } : {}),
+                ...(field.sequence ? { sequence: field.sequence } : {}),
+            },
+        ])),
+    };
+}
+/** The resource name embedded in a generated create-migration, if the source is one. */
+export function embeddedResource(source) {
+    const embedded = EMBEDDED.exec(source)?.[2];
+    if (!embedded)
+        return undefined;
+    try {
+        const parsed = JSON.parse(embedded);
+        return typeof parsed?.name === 'string' ? parsed.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Replaces the embedded definition of a generated create-migration (#20). */
+export function rewriteResourceSnapshot(source, snapshot) {
+    if (embeddedResource(source) !== snapshot.name)
+        throw new Error(`The migration does not embed the ${snapshot.name} definition`);
+    return source.replace(EMBEDDED, (_, before, _old, after) => `${before}${JSON.stringify(snapshot, null, 2)}${after}`);
+}

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

@@ -1,2 +1,11 @@
-/** Append to a marked literal array, including when the last item has no trailing comma. */
+/**
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
+ */
 export declare function appendMarkedItem(source: string, marker: string, expression: string): string;
+/** A new module definition, already in the project's Prettier layout. */
+export declare function moduleSource(name: string, options?: {
+    reference?: boolean;
+    typed?: boolean;
+}): string;

package/build/src/commands/source_markers.js

@@ -1,9 +1,41 @@
-/** Append to a marked literal array, including when the last item has no trailing comma. */
+/**
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
+ */
 export function appendMarkedItem(source, marker, expression) {
     const offset = source.indexOf(marker);
     if (offset < 0 || source.indexOf(marker, offset + marker.length) >= 0)
         throw new Error(`Expected one registration marker: ${marker}`);
-    const before = source.slice(0, offset).trimEnd();
-    const separator = /[\[,]$/.test(before) ? '' : ', ';
-    return source.replace(marker, `${separator}${expression}, ${marker}`);
+    const open = source.lastIndexOf('[', offset);
+    const close = source.indexOf(']', offset + marker.length);
+    if (open < 0 || close < 0)
+        throw new Error(`Registration marker ${marker} must be inside an array`);
+    const listed = source.slice(open + 1, offset);
+    if (/[()[\]{}'"`]|\/\/|\/\*/.test(listed) || source.slice(offset + marker.length, close).trim())
+        throw new Error(`Registration list around ${marker} is not a plain list; add ${expression} by hand`);
+    const items = listed
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    const lineStart = source.lastIndexOf('\n', open) + 1;
+    const indent = /^[ \t]*/.exec(source.slice(lineStart, open))[0];
+    const inner = `${indent}  `;
+    const lines = [...items, expression].map((item) => `${inner}${item},\n`).join('');
+    return `${source.slice(0, open)}[\n${lines}${inner}${marker}\n${indent}]${source.slice(close + 1)}`;
+}
+/** A new module definition, already in the project's Prettier layout. */
+export function moduleSource(name, options = {}) {
+    return [
+        ...(options.typed ? ["import type { Module } from '@adula/kit'"] : []),
+        '// adula:imports',
+        'export default {',
+        `  name: '${name}',`,
+        `  label: { ar: '${name}', en: '${name}' },`,
+        ...(options.reference === undefined ? [] : [`  reference: ${options.reference},`]),
+        '  dependsOn: [],',
+        '  resources: [/* adula:resources */],',
+        `}${options.typed ? ' satisfies Module' : ''}`,
+        '',
+    ].join('\n');
 }

package/build/src/core/administration_guard.js

@@ -1,4 +1,5 @@
 import { buildAbility } from '../auth/ability.js';
+import { resolveActorConditions } from '../auth/conditions.js';
 import { KitError } from '../admin/errors.js';
 /** Same CASL decision as the admin middleware, with fresh rows inside the transaction. */
 async function administrators(db) {
@@ -16,7 +17,8 @@ async function administrators(db) {
             subject: row.subject,
             action: row.action,
             inverted: row.inverted,
-            conditions: row.conditions ?? undefined,
+            // Only subject 'all' is read here, so no field accepts the placeholder.
+            conditions: resolveActorConditions(row.conditions ?? undefined, Number(row.user_id), () => false),
             fields: row.fields ?? undefined,
         });
         users.set(row.user_id, rules);

package/build/src/core/message_templates.d.ts

@@ -1,4 +1,5 @@
 import type { Knex } from 'knex';
+import { type NotificationTarget } from '../services/settings.js';
 export type TemplateDefinition = {
     label: string;
     subject: string;
@@ -51,12 +52,14 @@ export declare class MessageTemplates {
  * Inserts a templated notification in the caller's transaction. Templates with
  * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
  */
-export declare function notifyWithTemplate(db: Knex, userId: number, key: string, variables: Record<string, unknown>, templates?: MessageTemplates): Promise<void>;
+export declare function notifyWithTemplate(db: Knex, userId: number, key: string, variables: Record<string, unknown>, templates?: MessageTemplates, target?: NotificationTarget | null): Promise<void>;
 export type MailSender = (message: {
     to: string;
     name: string | null;
     subject: string;
     text: string;
+    /** The record the notification is about; build an absolute link from the application URL. */
+    target?: NotificationTarget | null;
 }) => Promise<void>;
 /**
  * Delivers pending notification e-mails. Rows are claimed with SKIP LOCKED so

package/build/src/core/message_templates.js

@@ -1,4 +1,5 @@
 import { KitError } from '../admin/errors.js';
+import { targetColumns } from '../services/settings.js';
 /**
  * Package-owned defaults. Projects edit wording in the message_templates table;
  * an upgrade can change a default without overwriting a project's edit.
@@ -166,7 +167,7 @@ export class MessageTemplates {
  * Inserts a templated notification in the caller's transaction. Templates with
  * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
  */
-export async function notifyWithTemplate(db, userId, key, variables, templates = new MessageTemplates(db)) {
+export async function notifyWithTemplate(db, userId, key, variables, templates = new MessageTemplates(db), target) {
     const message = await templates.render(key, variables, db);
     await db('notifications').insert({
         user_id: userId,
@@ -174,6 +175,7 @@ export async function notifyWithTemplate(db, userId, key, variables, templates =
         body: message.body,
         template_key: key,
         mail_state: message.mail ? 'pending' : null,
+        ...targetColumns(target),
     });
 }
 /**
@@ -191,7 +193,7 @@ export async function deliverNotificationMail(db, send, limit = 50) {
             .limit(limit)
             .forUpdate('n')
             .skipLocked()
-            .select('n.id', 'n.title', 'n.body', 'n.mail_attempts', 'u.email', 'u.full_name', 'u.disabled_at');
+            .select('n.id', 'n.title', 'n.body', 'n.mail_attempts', 'n.resource', 'n.record_id', 'u.email', 'u.full_name', 'u.disabled_at');
         for (const row of rows) {
             if (row.disabled_at) {
                 await trx('notifications').where('id', row.id).update({ mail_state: 'skipped' });
@@ -203,6 +205,9 @@ export async function deliverNotificationMail(db, send, limit = 50) {
                     name: row.full_name ? String(row.full_name) : null,
                     subject: String(row.title),
                     text: String(row.body),
+                    target: row.resource && row.record_id !== null
+                        ? { resource: String(row.resource), recordId: Number(row.record_id) }
+                        : null,
                 });
                 await trx('notifications')
                     .where('id', row.id)

package/build/src/core/module_seed.d.ts

@@ -0,0 +1,15 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+export type ModuleSeedResult = {
+    /** Lookup rows inserted now; rows that already existed are left as they are. */
+    lookups: number;
+    created: string[];
+    adopted: string[];
+    kept: string[];
+};
+/**
+ * Applies the lookups and default roles declared by registered modules. It is
+ * idempotent and additive: existing lookup rows and roles are never changed, so
+ * administrator edits survive every later installation (adula:install runs it).
+ */
+export declare function seedModules(db: Knex, registry: ResourceRegistry, actorId: number): Promise<ModuleSeedResult>;

package/build/src/core/module_seed.js

@@ -0,0 +1,31 @@
+import { RolesAdmin } from './roles.js';
+/**
+ * Applies the lookups and default roles declared by registered modules. It is
+ * idempotent and additive: existing lookup rows and roles are never changed, so
+ * administrator edits survive every later installation (adula:install runs it).
+ */
+export async function seedModules(db, registry, actorId) {
+    return db.transaction(async (trx) => {
+        await trx.raw('SELECT pg_advisory_xact_lock(717012)');
+        let lookups = 0;
+        for (const module of registry.modules())
+            for (const [group, rows] of Object.entries(module.lookups ?? {}))
+                for (const [index, row] of rows.entries()) {
+                    const inserted = await trx('lookups')
+                        .insert({
+                        group,
+                        key: row.key,
+                        label_ar: row.label.ar,
+                        label_en: row.label.en,
+                        sort: row.sort ?? index,
+                        active: true,
+                    })
+                        .onConflict(['group', 'key'])
+                        .ignore()
+                        .returning('id');
+                    lookups += inserted.length;
+                }
+        const roles = await new RolesAdmin(trx, registry).ensureDefaults(actorId, registry.modules().flatMap((module) => [...(module.defaultRoles ?? [])]));
+        return { lookups, ...roles };
+    });
+}

package/build/src/core/notifications.d.ts

@@ -1,10 +1,20 @@
 import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
 export type Notification = {
     id: number;
     title: string;
     body: string;
     readAt: string | null;
     createdAt: string;
+    /**
+     * The record the notification is about, while its resource is still registered.
+     * The record page authorizes the reader when the link is opened.
+     */
+    target: {
+        resource: string;
+        recordId: number;
+        href: string;
+    } | null;
 };
 export type NotificationPage = {
     data: Notification[];
@@ -13,13 +23,20 @@ export type NotificationPage = {
 };
 export declare class NotificationsAdmin {
     private db;
-    constructor(db: Knex);
+    /** Without a registry, stored targets are returned as they are. */
+    private registry?;
+    constructor(db: Knex, 
+    /** Without a registry, stored targets are returned as they are. */
+    registry?: Pick<ResourceRegistry, "has"> | undefined);
+    private target;
     /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
     list(userId: number, options?: {
         cursor?: string;
         limit?: number;
     }): Promise<NotificationPage>;
     markRead(userId: number, id: number): Promise<void>;
+    /** Marks the notification read and returns where it points (null without a target). */
+    open(userId: number, id: number): Promise<string | null>;
     markAllRead(userId: number): Promise<number>;
     unreadCount(userId: number): Promise<number>;
 }

package/build/src/core/notifications.js

@@ -2,8 +2,21 @@ import { KitError } from '../admin/errors.js';
 import { pageLimit } from './activity.js';
 export class NotificationsAdmin {
     db;
-    constructor(db) {
+    registry;
+    constructor(db, 
+    /** Without a registry, stored targets are returned as they are. */
+    registry) {
         this.db = db;
+        this.registry = registry;
+    }
+    target(row) {
+        if (!row.resource || row.record_id === null || row.record_id === undefined)
+            return null;
+        const resource = String(row.resource);
+        if (this.registry && !this.registry.has(resource))
+            return null;
+        const recordId = Number(row.record_id);
+        return { resource, recordId, href: `/resources/${resource}/${recordId}` };
     }
     /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
     async list(userId, options = {}) {
@@ -34,6 +47,7 @@ export class NotificationsAdmin {
                 body: row.body,
                 readAt: row.read_at ? new Date(row.read_at).toISOString() : null,
                 createdAt: new Date(row.created_at).toISOString(),
+                target: this.target(row),
             })),
             nextCursor: rows.length > limit ? `${last.read_at ? 'r' : 'u'}:${last.id}` : null,
             unread: await this.unreadCount(userId),
@@ -48,6 +62,18 @@ export class NotificationsAdmin {
             .whereNull('read_at')
             .update({ read_at: this.db.fn.now() });
     }
+    /** Marks the notification read and returns where it points (null without a target). */
+    async open(userId, id) {
+        const row = await this.db('notifications').where({ id, user_id: userId }).first();
+        if (!row)
+            throw new KitError(404, 'E_NOTIFICATION_NOT_FOUND', 'الإشعار غير موجود');
+        if (!row.read_at)
+            await this.db('notifications')
+                .where({ id, user_id: userId })
+                .whereNull('read_at')
+                .update({ read_at: this.db.fn.now() });
+        return this.target(row)?.href ?? null;
+    }
     async markAllRead(userId) {
         return this.db('notifications')
             .where('user_id', userId)

package/build/src/core/roles.d.ts

@@ -1,9 +1,14 @@
 import type { Knex } from 'knex';
 import type { ResourceRegistry } from '../resource/registry.js';
-import type { Label } from '../resource/types.js';
+import type { Label, ModuleRole } from '../resource/types.js';
 import type { Conditions } from '../auth/conditions.js';
 export type RoleSummary = {
     id: number;
+    /**
+     * Stable identifier addressed by workflows and module defaults. The display name
+     * can change freely; the key is set once.
+     */
+    key: string | null;
     name: string;
     permissionLevel: number;
     rules: number;
@@ -32,6 +37,8 @@ export type MatrixField = {
     label: Label;
     type: string;
     conditionable: boolean;
+    /** Accepts the current user ("$actor.id") as a condition value: user fields, createdBy, updatedBy. */
+    actor?: boolean;
 };
 export type MatrixSubject = {
     name: string;
@@ -46,6 +53,8 @@ export type RoleMatrix = {
     subjects: MatrixSubject[];
 };
 export declare const ALL_SUBJECT_LABEL: Label;
+/** A role key: lower-case letters, digits and underscores, starting with a letter. */
+export declare function roleKey(value: unknown): string;
 export declare class RolesAdmin {
     private db;
     private registry;
@@ -54,12 +63,19 @@ export declare class RolesAdmin {
     get(id: number): Promise<RoleDetail>;
     create(actorId: number, input: {
         name: string;
+        key?: string | null;
         permissionLevel?: number;
     }): Promise<{
         id: number;
+        key: string | null;
         name: string;
         permissionLevel: number;
     }>;
+    /**
+     * Gives a role its stable key. A key is set once: workflows and module defaults
+     * depend on it, so changing it would silently detach them.
+     */
+    setKey(actorId: number, id: number, value: string): Promise<void>;
     rename(actorId: number, id: number, value: string): Promise<void>;
     setPermissionLevel(actorId: number, id: number, value: number): Promise<void>;
     delete(actorId: number, id: number): Promise<void>;
@@ -67,6 +83,16 @@ export declare class RolesAdmin {
     matrix(): RoleMatrix;
     setRule(actorId: number, roleId: number, input: RuleInput): Promise<RoleRule>;
     removeRule(actorId: number, roleId: number, ruleId: number): Promise<void>;
+    /**
+     * Creates module default roles that no role holds the key of yet, with their rules
+     * validated exactly like setRule. Existing roles are never modified. A keyless role
+     * with the same display name is adopted by receiving the key, rules untouched.
+     */
+    ensureDefaults(actorId: number, roles: readonly ModuleRole[]): Promise<{
+        created: string[];
+        adopted: string[];
+        kept: string[];
+    }>;
     private validateRule;
     private find;
 }