@adula/kit 0.2.0-alpha.1

package/build/src/core/setup.js

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { Settings } from '../services/settings.js';
+import { KitError } from '../admin/errors.js';
+import { logActivity } from './activity.js';
+export class InitialSetup {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async check(actorId, name, fingerprint, probe) {
+        const key = `setup.check.${name}`;
+        const state = {
+            status: 'checking',
+            checkedAt: new Date().toISOString(),
+            fingerprint,
+            attempt: randomUUID(),
+        };
+        await this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?)', [717013]);
+            const previous = await new Settings(trx).get(key);
+            if (previous &&
+                Date.now() - Date.parse(previous.checkedAt) <
+                    (previous.status === 'checking' ? 300_000 : 30_000))
+                throw new KitError(429, 'E_SETUP_COOLDOWN', 'انتظر قليلًا قبل إعادة الفحص');
+            await new Settings(trx).set(key, state);
+        });
+        try {
+            await probe();
+            state.status = 'passed';
+        }
+        catch {
+            state.status = 'failed';
+        }
+        await this.db.transaction(async (trx) => {
+            await trx('settings')
+                .where({ key, scope: 'system', scope_id: '0' })
+                .whereRaw("value->>'attempt' = ?", [state.attempt])
+                .update({ value: JSON.stringify(state) });
+            await logActivity(trx, {
+                resource: 'core.setup',
+                recordId: 0,
+                actorId,
+                action: 'check',
+                changes: { service: name, status: state.status },
+            });
+        });
+        if (state.status === 'failed')
+            throw new KitError(422, 'E_SETUP_CHECK_FAILED', 'لم ينجح الفحص. راجع إعدادات الخدمة واتصالها ثم أعد المحاولة.');
+    }
+    async acknowledgeIdentity(actorId, fingerprint) {
+        await this.db.transaction(async (trx) => {
+            await new Settings(trx).set('setup.identity', {
+                fingerprint,
+                actorId,
+                at: new Date().toISOString(),
+            });
+            await logActivity(trx, {
+                resource: 'core.setup',
+                recordId: 0,
+                actorId,
+                action: 'identity_confirmed',
+            });
+        });
+    }
+    async testNotification(actorId) {
+        return this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?, ?)', [717014, actorId]);
+            const settings = new Settings(trx);
+            const previous = await settings.get('setup.notification', 'user', String(actorId));
+            if (previous && Date.now() - Date.parse(previous.at) < 60_000)
+                throw new KitError(429, 'E_SETUP_COOLDOWN', 'انتظر دقيقة قبل إعادة الإشعار التجريبي');
+            const [notification] = await trx('notifications')
+                .insert({
+                user_id: actorId,
+                title: 'اختبار الإشعارات',
+                body: 'وصل هذا الإشعار من معالج الإعداد الأولي. حدده كمقروء ثم ارجع إلى الإعداد الأولي للتحقق من النتيجة.',
+            })
+                .returning('id');
+            await settings.set('setup.notification', { id: notification.id, at: new Date().toISOString() }, 'user', String(actorId));
+            await logActivity(trx, {
+                resource: 'core.setup',
+                recordId: notification.id,
+                actorId,
+                action: 'notification_test',
+            });
+            return notification.id;
+        });
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { Knex } from 'knex';
+export type CalendarSystem = 'gregory' | 'islamic-umalqura';
+export type CalendarPreference = CalendarSystem | 'both';
+export type UiPreferences = {
+    calendar: CalendarPreference;
+    confirmDialogClose: boolean;
+    pageTransitions: boolean;
+};
+export declare const UI_PREFERENCES_KEY = "ui.preferences";
+export declare const DEFAULT_UI_PREFERENCES: UiPreferences;
+export declare function validateUiPreferences(value: unknown): UiPreferences;
+export declare function uiPreferences(db: Knex): Promise<UiPreferences>;

package/build/src/core/ui_preferences.js

@@ -0,0 +1,30 @@
+import { Settings } from '../services/settings.js';
+import { KitError } from '../admin/errors.js';
+export const UI_PREFERENCES_KEY = 'ui.preferences';
+export const DEFAULT_UI_PREFERENCES = {
+    calendar: 'gregory',
+    confirmDialogClose: true,
+    pageTransitions: true,
+};
+export function validateUiPreferences(value) {
+    const input = value;
+    if (!input ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        !['gregory', 'islamic-umalqura', 'both'].includes(input.calendar) ||
+        typeof input.confirmDialogClose !== 'boolean' ||
+        typeof input.pageTransitions !== 'boolean' ||
+        Object.keys(input).some((key) => !(key in DEFAULT_UI_PREFERENCES)))
+        throw new KitError(422, 'E_UI_PREFERENCES', 'اختر تقويمًا صالحًا وحدد خيارات تأكيد الإغلاق والانتقالات');
+    return {
+        calendar: input.calendar,
+        confirmDialogClose: input.confirmDialogClose,
+        pageTransitions: input.pageTransitions,
+    };
+}
+export async function uiPreferences(db) {
+    const value = await new Settings(db).get(UI_PREFERENCES_KEY);
+    if (value === undefined)
+        return { ...DEFAULT_UI_PREFERENCES };
+    return validateUiPreferences(value);
+}

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

@@ -0,0 +1,23 @@
+import type { Knex } from 'knex';
+export type InvitationDelivery = {
+    email: string;
+    fullName: string;
+    token: string;
+};
+/** Pending invitations are not accounts. Password hashing and mail transport belong to the host. */
+export declare class UserInvitations {
+    private db;
+    constructor(db: Knex);
+    canInvite(actorId: number): Promise<boolean>;
+    invite(actorId: number, input: {
+        email: string;
+        fullName: string;
+    }, send: (invitation: InvitationDelivery) => Promise<void>): Promise<{
+        id: number;
+        email: string;
+    }>;
+    valid(token: string): Promise<boolean>;
+    accept(token: string, password: string, hashPassword: (password: string) => Promise<string>): Promise<{
+        id: number;
+    }>;
+}

package/build/src/core/user_invitations.js

@@ -0,0 +1,144 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { subject } from '@casl/ability';
+import { ActorStore } from '../auth/actor_store.js';
+import { buildAbility } from '../auth/ability.js';
+import { ResourceRegistry } from '../resource/registry.js';
+import { KitError } from '../admin/errors.js';
+import { logActivity } from './activity.js';
+const RESOURCE = 'core.users';
+const INVITATIONS = 'core.user_invitations';
+const digest = (token) => createHash('sha256').update(token).digest('hex');
+const invalid = () => new KitError(422, 'E_INVITATION_INVALID', 'الدعوة غير صالحة أو انتهت صلاحيتها. اطلب دعوة جديدة من المسؤول.');
+/** Pending invitations are not accounts. Password hashing and mail transport belong to the host. */
+export class UserInvitations {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async canInvite(actorId) {
+        const user = await this.db('users').where('id', actorId).first('disabled_at');
+        if (!user || user.disabled_at)
+            return false;
+        const actor = await new ActorStore(this.db, new ResourceRegistry()).load(actorId);
+        return buildAbility(actor.rules).can('invite', subject(RESOURCE, {}));
+    }
+    async invite(actorId, input, send) {
+        const email = typeof input.email === 'string' ? input.email.trim().toLowerCase() : '';
+        const fullName = typeof input.fullName === 'string' ? input.fullName.trim() : '';
+        if (!email ||
+            email.length > 254 ||
+            !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ||
+            !fullName ||
+            fullName.length > 120)
+            throw new KitError(422, 'E_INVITATION_INPUT', 'أدخل اسمًا وبريدًا إلكترونيًا صحيحين');
+        const token = randomBytes(32).toString('base64url');
+        const tokenHash = digest(token);
+        const id = await this.db.transaction(async (trx) => {
+            // Serialize resends and acceptance for the same normalized email.
+            await trx.raw('SELECT pg_advisory_xact_lock(hashtextextended(?, 0))', [email]);
+            if (!(await new UserInvitations(trx).canInvite(actorId)))
+                throw new KitError(403, 'E_FORBIDDEN', 'ليس لديك صلاحية دعوة المستخدمين');
+            if (await trx('users').whereRaw('lower(email) = ?', [email]).first('id'))
+                throw new KitError(409, 'E_USER_EXISTS', 'يوجد حساب بهذا البريد بالفعل');
+            const previous = await trx('user_invitations').where({ email }).first();
+            if (previous && Date.now() - new Date(previous.created_at).getTime() < 60_000)
+                throw new KitError(429, 'E_INVITATION_WAIT', 'انتظر دقيقة قبل إعادة إرسال الدعوة');
+            const [row] = await trx('user_invitations')
+                .insert({
+                email,
+                full_name: fullName,
+                invited_by: actorId,
+                token_hash: tokenHash,
+                expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000),
+                accepted_at: null,
+                created_at: trx.fn.now(),
+            })
+                .onConflict('email')
+                .merge()
+                .returning('id');
+            await logActivity(trx, {
+                resource: INVITATIONS,
+                recordId: row.id,
+                actorId,
+                action: 'invitation_created',
+                changes: { email },
+            });
+            return row.id;
+        });
+        try {
+            await send({ email, fullName, token });
+        }
+        catch {
+            // Revoke only this attempt; a newer resend must survive an older transport failure.
+            await this.db('user_invitations')
+                .where({ id, token_hash: tokenHash })
+                .whereNull('accepted_at')
+                .delete();
+            await logActivity(this.db, {
+                resource: INVITATIONS,
+                recordId: id,
+                actorId,
+                action: 'invitation_delivery_failed',
+                changes: { email },
+            });
+            throw new KitError(503, 'E_INVITATION_DELIVERY', 'تعذر إرسال الدعوة. تحقق من إعدادات البريد ثم أعد المحاولة.');
+        }
+        await logActivity(this.db, {
+            resource: INVITATIONS,
+            recordId: id,
+            actorId,
+            action: 'invitation_sent',
+            changes: { email },
+        });
+        return { id, email };
+    }
+    async valid(token) {
+        if (!/^[\w-]{43}$/.test(token))
+            return false;
+        return Boolean(await this.db('user_invitations')
+            .where('token_hash', digest(token))
+            .whereNull('accepted_at')
+            .where('expires_at', '>', this.db.fn.now())
+            .first('id'));
+    }
+    async accept(token, password, hashPassword) {
+        if (!(await this.valid(token)))
+            throw invalid();
+        if (typeof password !== 'string' || password.length < 8 || password.length > 32)
+            throw new KitError(422, 'E_PASSWORD', 'كلمة المرور من 8 إلى 32 حرفًا');
+        const passwordHash = await hashPassword(password);
+        return this.db.transaction(async (trx) => {
+            const pending = await trx('user_invitations').where('token_hash', digest(token)).first();
+            if (!pending)
+                throw invalid();
+            await trx.raw('SELECT pg_advisory_xact_lock(hashtextextended(?, 0))', [pending.email]);
+            const row = await trx('user_invitations')
+                .where({ id: pending.id, token_hash: digest(token) })
+                .whereNull('accepted_at')
+                .where('expires_at', '>', trx.fn.now())
+                .forUpdate()
+                .first();
+            if (!row || (await trx('users').whereRaw('lower(email) = ?', [row.email]).first('id')))
+                throw invalid();
+            const [user] = await trx('users')
+                .insert({
+                email: row.email,
+                full_name: row.full_name,
+                password: passwordHash,
+                created_at: trx.fn.now(),
+                updated_at: trx.fn.now(),
+            })
+                .returning('id');
+            await trx('user_invitations').where('id', row.id).update({ accepted_at: trx.fn.now() });
+            // No role or organizational membership can be supplied by either HTTP request.
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: user.id,
+                actorId: user.id,
+                action: 'invitation_accepted',
+                changes: { invitedBy: row.invited_by },
+            });
+            return { id: user.id };
+        });
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+export type UserRoleAssignment = {
+    id: number;
+    roleId: number;
+    role: string;
+    orgUnitId: number | null;
+    orgUnit: string | null;
+};
+export type UserOrgUnit = {
+    id: number;
+    name: string;
+    path: string;
+};
+export type UserSummary = {
+    id: number;
+    fullName: string | null;
+    email: string;
+    disabledAt: string | null;
+    roles: UserRoleAssignment[];
+    orgUnits: UserOrgUnit[];
+};
+export type UserPage = {
+    data: UserSummary[];
+    nextCursor: number | null;
+};
+/** Host applications own the users table; the kit expects id, email, full_name and disabled_at. */
+export declare class UsersAdmin {
+    private db;
+    constructor(db: Knex);
+    list(options?: {
+        search?: string;
+        cursor?: number;
+        limit?: number;
+    }): Promise<UserPage>;
+    get(id: number): Promise<UserSummary>;
+    assignRole(actorId: number, userId: number, roleId: number, orgUnitId?: number | null): Promise<number>;
+    removeRole(actorId: number, userId: number, assignmentId: number): Promise<void>;
+    assignOrgUnit(actorId: number, userId: number, orgUnitId: number): Promise<void>;
+    removeOrgUnit(actorId: number, userId: number, orgUnitId: number): Promise<void>;
+    disable(actorId: number, userId: number): Promise<void>;
+    enable(actorId: number, userId: number): Promise<void>;
+    private find;
+    private hydrate;
+}

package/build/src/core/users.js

@@ -0,0 +1,182 @@
+import { KitError } from '../admin/errors.js';
+import { logActivity, pageLimit } from './activity.js';
+import { administrationGuard } from './administration_guard.js';
+const RESOURCE = 'core.users';
+const escapeLike = (value) => value.replace(/[\\%_]/g, '\\$&');
+/** Host applications own the users table; the kit expects id, email, full_name and disabled_at. */
+export class UsersAdmin {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async list(options = {}) {
+        const limit = pageLimit(options.limit);
+        const query = this.db('users')
+            .select('id', 'email', 'full_name', 'disabled_at')
+            .orderBy('id')
+            .limit(limit + 1);
+        const search = options.search?.trim();
+        if (search) {
+            const pattern = `%${escapeLike(search)}%`;
+            query.where((where) => where.whereILike('email', pattern).orWhereILike('full_name', pattern));
+        }
+        if (options.cursor)
+            query.where('id', '>', options.cursor);
+        const rows = await query;
+        const page = rows.slice(0, limit);
+        const data = await this.hydrate(page);
+        return { data, nextCursor: rows.length > limit ? page[page.length - 1].id : null };
+    }
+    async get(id) {
+        const [user] = await this.hydrate([await this.find(this.db, id)]);
+        return user;
+    }
+    async assignRole(actorId, userId, roleId, orgUnitId = null) {
+        return this.db.transaction(async (trx) => {
+            const verifyAccess = await administrationGuard(trx, actorId);
+            await this.find(trx, userId);
+            const role = await trx('roles').where('id', roleId).first();
+            if (!role)
+                throw new KitError(404, 'E_ROLE_NOT_FOUND', 'الدور غير موجود');
+            if (orgUnitId !== null && !(await trx('org_units').where('id', orgUnitId).first()))
+                throw new KitError(404, 'E_ORG_NOT_FOUND', 'الوحدة التنظيمية غير موجودة');
+            const duplicate = await trx('user_roles')
+                .where({ user_id: userId, role_id: roleId })
+                .andWhere((where) => orgUnitId === null
+                ? where.whereNull('org_unit_id')
+                : where.where('org_unit_id', orgUnitId))
+                .first();
+            if (duplicate)
+                throw new KitError(409, 'E_ROLE_ASSIGNED', 'هذا الدور مسند بالفعل');
+            const [row] = await trx('user_roles')
+                .insert({ user_id: userId, role_id: roleId, org_unit_id: orgUnitId })
+                .returning('id');
+            await verifyAccess();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: userId,
+                actorId,
+                action: 'assign_role',
+                changes: { roleId, role: role.name, orgUnitId },
+            });
+            return row.id;
+        });
+    }
+    async removeRole(actorId, userId, assignmentId) {
+        return this.db.transaction(async (trx) => {
+            const verifyAccess = await administrationGuard(trx, actorId);
+            const [row] = await trx('user_roles')
+                .where({ id: assignmentId, user_id: userId })
+                .delete()
+                .returning('*');
+            if (!row)
+                throw new KitError(404, 'E_ROLE_NOT_ASSIGNED', 'الإسناد غير موجود');
+            await verifyAccess();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: userId,
+                actorId,
+                action: 'remove_role',
+                changes: { roleId: row.role_id, orgUnitId: row.org_unit_id },
+            });
+        });
+    }
+    async assignOrgUnit(actorId, userId, orgUnitId) {
+        return this.db.transaction(async (trx) => {
+            await this.find(trx, userId);
+            const unit = await trx('org_units').where('id', orgUnitId).first();
+            if (!unit)
+                throw new KitError(404, 'E_ORG_NOT_FOUND', 'الوحدة التنظيمية غير موجودة');
+            if (await trx('user_org_units').where({ user_id: userId, org_unit_id: orgUnitId }).first())
+                throw new KitError(409, 'E_MEMBERSHIP_EXISTS', 'المستخدم عضو في هذه الوحدة بالفعل');
+            await trx('user_org_units').insert({ user_id: userId, org_unit_id: orgUnitId });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: userId,
+                actorId,
+                action: 'assign_org_unit',
+                changes: { orgUnitId, orgUnit: unit.name },
+            });
+        });
+    }
+    async removeOrgUnit(actorId, userId, orgUnitId) {
+        return this.db.transaction(async (trx) => {
+            const removed = await trx('user_org_units')
+                .where({ user_id: userId, org_unit_id: orgUnitId })
+                .delete();
+            if (!removed)
+                throw new KitError(404, 'E_MEMBERSHIP_NOT_FOUND', 'العضوية غير موجودة');
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: userId,
+                actorId,
+                action: 'remove_org_unit',
+                changes: { orgUnitId },
+            });
+        });
+    }
+    async disable(actorId, userId) {
+        if (actorId === userId)
+            throw new KitError(422, 'E_SELF_DISABLE', 'لا يمكنك تعطيل حسابك الحالي');
+        return this.db.transaction(async (trx) => {
+            const verifyAccess = await administrationGuard(trx, actorId);
+            await this.find(trx, userId);
+            await trx('users')
+                .where('id', userId)
+                .whereNull('disabled_at')
+                .update({ disabled_at: trx.fn.now() });
+            await verifyAccess();
+            await logActivity(trx, { resource: RESOURCE, recordId: userId, actorId, action: 'disable' });
+        });
+    }
+    async enable(actorId, userId) {
+        return this.db.transaction(async (trx) => {
+            await this.find(trx, userId);
+            await trx('users').where('id', userId).update({ disabled_at: null });
+            await logActivity(trx, { resource: RESOURCE, recordId: userId, actorId, action: 'enable' });
+        });
+    }
+    async find(db, id) {
+        const user = await db('users')
+            .select('id', 'email', 'full_name', 'disabled_at')
+            .where('id', id)
+            .first();
+        if (!user)
+            throw new KitError(404, 'E_USER_NOT_FOUND', 'المستخدم غير موجود');
+        return user;
+    }
+    async hydrate(rows) {
+        if (!rows.length)
+            return [];
+        const ids = rows.map((row) => row.id);
+        const roles = await this.db('user_roles as ur')
+            .join('roles as r', 'r.id', 'ur.role_id')
+            .leftJoin('org_units as o', 'o.id', 'ur.org_unit_id')
+            .whereIn('ur.user_id', ids)
+            .select('ur.id', 'ur.user_id', 'ur.role_id', 'r.name as role', 'ur.org_unit_id', 'o.name as org_unit')
+            .orderBy(['r.name', 'ur.id']);
+        const units = await this.db('user_org_units as m')
+            .join('org_units as o', 'o.id', 'm.org_unit_id')
+            .whereIn('m.user_id', ids)
+            .select('m.user_id', 'o.id', 'o.name', 'o.path')
+            .orderBy('o.path');
+        return rows.map((row) => ({
+            id: row.id,
+            fullName: row.full_name ?? null,
+            email: row.email,
+            disabledAt: row.disabled_at ? new Date(row.disabled_at).toISOString() : null,
+            roles: roles
+                .filter((role) => role.user_id === row.id)
+                .map((role) => ({
+                id: role.id,
+                roleId: role.role_id,
+                role: role.role,
+                orgUnitId: role.org_unit_id ?? null,
+                orgUnit: role.org_unit ?? null,
+            })),
+            orgUnits: units
+                .filter((unit) => unit.user_id === row.id)
+                .map((unit) => ({ id: unit.id, name: unit.name, path: String(unit.path) })),
+        }));
+    }
+}

package/build/src/database/configure.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseConfig } from '@adonisjs/lucid/types/database';
+/** Migration names stay relative across source, packed and production installs. */
+export declare function withKitDatabase<T extends DatabaseConfig>(config: T, root: string): T;

package/build/src/database/configure.js

@@ -0,0 +1,41 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Migration names stay relative across source, packed and production installs. */
+export function withKitDatabase(config, root) {
+    const name = config.connection;
+    const connection = name ? config.connections[name] : undefined;
+    if (!connection || connection.client !== 'pg')
+        throw new Error('adula-kit requires a configured PostgreSQL connection');
+    let modules = [];
+    try {
+        modules = readdirSync(join(root, 'app/modules'), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && /^[a-z][a-z0-9_]*$/.test(entry.name))
+            .map((entry) => `app/modules/${entry.name}/migrations`)
+            .sort();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const migrations = connection.migrations ?? {};
+    return {
+        ...config,
+        connections: {
+            ...config.connections,
+            [name]: {
+                ...connection,
+                migrations: {
+                    ...migrations,
+                    naturalSort: true,
+                    paths: [
+                        ...new Set([
+                            ...(migrations.paths ?? ['database/migrations']),
+                            'node_modules/@adula/kit/build/database/migrations',
+                            ...modules,
+                        ]),
+                    ],
+                },
+            },
+        },
+    };
+}

package/build/src/database/schema.d.ts

@@ -0,0 +1,7 @@
+import type { Knex } from 'knex';
+import type { Resource } from '../resource/types.js';
+export declare function createCoreSchema(db: Knex): Promise<void>;
+/** Attachment metadata lives in one table so ownership, restore drills and disk moves see every file. */
+export declare function createAttachmentsSchema(db: Knex): Promise<void>;
+export declare function createSavedViewsSchema(db: Knex): Promise<void>;
+export declare function createResourceTable(db: Knex, resource: Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields' | 'fields'>): Promise<void>;