@adula/kit 0.2.0-alpha.1

package/build/src/resource/define_resource.js

@@ -0,0 +1,48 @@
+export function identifier(value) {
+    if (!/^[a-z][a-z0-9_]*$/.test(value))
+        throw new Error(`Unsafe SQL identifier: ${value}`);
+    return value;
+}
+export function columnName(name) {
+    return identifier(name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`));
+}
+export function defineResource(input) {
+    identifier(input.name);
+    if (typeof input.scoped !== 'boolean')
+        throw new Error(`${input.name}: scoped must be explicit`);
+    if (!input.label.ar || !input.label.en)
+        throw new Error('Bilingual labels are required');
+    for (const [key, field] of Object.entries(input.fields)) {
+        columnName(key);
+        identifier(field.column ?? columnName(key));
+        if ([
+            'id',
+            'orgUnitId',
+            'createdBy',
+            'updatedBy',
+            'createdAt',
+            'updatedAt',
+            'deletedAt',
+            'version',
+            'docStatus',
+            'amendedFromId',
+        ].includes(key))
+            throw new Error(`Reserved field: ${key}`);
+        if (!field.label.ar || !field.label.en)
+            throw new Error(`${key}: bilingual labels are required`);
+    }
+    for (const keys of [
+        input.list,
+        input.form,
+        input.show,
+        input.hidden ?? [],
+        input.serialize ?? [],
+    ]) {
+        for (const key of keys)
+            if (!(key in input.fields))
+                throw new Error(`Unknown field: ${key}`);
+    }
+    if (!input.submittable && input.actions.some((a) => ['submit', 'cancel', 'amend'].includes(a)))
+        throw new Error('Document actions require submittable');
+    return Object.freeze({ ...input, version: input.version ?? input.submittable ?? false });
+}

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

@@ -0,0 +1,9 @@
+import type { Module, Resource } from './types.js';
+export declare class ResourceRegistry {
+    #private;
+    register(modules: readonly Module[]): this;
+    get(name: string): Resource;
+    all(): Resource[];
+    owner(name: string): string;
+    modules(): Module[];
+}

package/build/src/resource/registry.js

@@ -0,0 +1,59 @@
+import { identifier } from './define_resource.js';
+export class ResourceRegistry {
+    #resources = new Map();
+    #owners = new Map();
+    #modules = new Map();
+    register(modules) {
+        const next = new ResourceRegistry();
+        for (const module of modules) {
+            identifier(module.name);
+            if (next.#modules.has(module.name))
+                throw new Error(`Duplicate module: ${module.name}`);
+            for (const dep of module.dependsOn)
+                if (!next.#modules.has(dep))
+                    throw new Error(`Module ${module.name} must follow dependency ${dep}`);
+            next.#modules.set(module.name, module);
+            for (const resource of module.resources) {
+                if (next.#resources.has(resource.name))
+                    throw new Error(`Duplicate resource: ${resource.name}`);
+                next.#resources.set(resource.name, resource);
+                next.#owners.set(resource.name, module.name);
+            }
+        }
+        for (const resource of next.all()) {
+            for (const field of Object.values(resource.fields)) {
+                if (field.type !== 'belongsTo' && field.type !== 'hasMany')
+                    continue;
+                const target = next.get(field.resource);
+                const owner = next.owner(resource.name);
+                const targetOwner = next.owner(target.name);
+                if (owner !== targetOwner && !next.#modules.get(owner).dependsOn.includes(targetOwner))
+                    throw new Error(`Undeclared dependency: ${owner} -> ${targetOwner}`);
+                if (field.type === 'hasMany' && owner !== targetOwner)
+                    throw new Error('Inline children must belong to the same module');
+                if (field.type === 'hasMany' && !(field.foreignKey in target.fields))
+                    throw new Error(`Missing child foreign key: ${field.foreignKey}`);
+            }
+        }
+        this.#resources = next.#resources;
+        this.#owners = next.#owners;
+        this.#modules = next.#modules;
+        return this;
+    }
+    get(name) {
+        const resource = this.#resources.get(name);
+        if (!resource)
+            throw new Error(`Unknown resource: ${name}`);
+        return resource;
+    }
+    all() {
+        return [...this.#resources.values()];
+    }
+    owner(name) {
+        this.get(name);
+        return this.#owners.get(name);
+    }
+    modules() {
+        return [...this.#modules.values()];
+    }
+}

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

@@ -0,0 +1,80 @@
+import type { Knex } from 'knex';
+import type { LucidModel } from '@adonisjs/lucid/types/model';
+export type Label = {
+    ar: string;
+    en: string;
+};
+export type Action = 'view' | 'create' | 'update' | 'delete' | 'submit' | 'cancel' | 'amend';
+export type Scalar = string | number | boolean | null;
+export type RecordData = Record<string, unknown>;
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type SerializedRecord = Record<string, JsonValue>;
+export type Field = {
+    label: Label;
+    column?: string;
+    required?: boolean;
+    unique?: boolean;
+    sortable?: boolean;
+    searchable?: boolean;
+    filterable?: boolean;
+    permissionLevel?: number;
+    sequence?: string;
+} & ({
+    type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json' | 'attachment';
+} | {
+    type: 'belongsTo';
+    resource: string;
+} | {
+    type: 'hasMany';
+    resource: string;
+    foreignKey: string;
+    inline?: boolean;
+} | {
+    type: 'lookup';
+    group: string;
+});
+export type Resource = {
+    name: string;
+    label: Label;
+    model: LucidModel;
+    scoped: boolean;
+    submittable?: boolean;
+    version?: boolean;
+    customFields?: boolean;
+    fields: Record<string, Field>;
+    list: readonly string[];
+    form: readonly string[];
+    show: readonly string[];
+    serialize?: readonly string[];
+    hidden?: readonly string[];
+    actions: readonly Action[];
+    validator: {
+        validate(data: unknown): Promise<RecordData>;
+    };
+    hooks?: {
+        beforeSave?: (record: RecordData, context: HookContext) => Promise<void>;
+        afterSave?: (record: RecordData, context: HookContext) => Promise<void>;
+    };
+};
+export type HookContext = {
+    trx: Knex.Transaction;
+    userId: number;
+    action: Action;
+};
+export type Module = {
+    name: string;
+    reference?: boolean;
+    label: Label;
+    dependsOn: readonly string[];
+    resources: readonly Resource[];
+};
+export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize'> & {
+    fields: F;
+    list: readonly (keyof F & string)[];
+    form: readonly (keyof F & string)[];
+    show: readonly (keyof F & string)[];
+    hidden?: readonly (keyof F & string)[];
+    serialize?: readonly (keyof F & string)[];
+};

package/build/src/resource/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+import type { Field } from './types.js';
+export declare function canonicalDate(value: unknown, type: 'date' | 'datetime'): boolean;
+export declare function canonicalMoney(value: unknown): value is string;
+/** Normalize before CASL evaluates a prospective record, using its stored representation. */
+export declare function fieldValue(field: Field, value: unknown): unknown;

package/build/src/resource/values.js

@@ -0,0 +1,87 @@
+export function canonicalDate(value, type) {
+    if (typeof value !== 'string')
+        return false;
+    const normalized = type === 'date' ? `${value}T00:00:00.000Z` : value;
+    return (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(normalized) &&
+        !normalized.startsWith('0000') &&
+        Number.isFinite(Date.parse(normalized)) &&
+        new Date(normalized).toISOString() === normalized);
+}
+export function canonicalMoney(value) {
+    if (typeof value !== 'string' || !/^(0|-?[1-9]\d*)$/.test(value) || value.length > 20)
+        return false;
+    const integer = BigInt(value);
+    return integer >= -9223372036854775808n && integer <= 9223372036854775807n;
+}
+function isJson(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    if (!Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null)
+        return false;
+    // JSON.stringify changes holes into null; never silently alter a submitted value.
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++)
+            if (!Object.hasOwn(value, index))
+                return false;
+    }
+    ancestors.add(value);
+    const valid = Object.values(value).every((entry) => isJson(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
+}
+/** Normalize before CASL evaluates a prospective record, using its stored representation. */
+export function fieldValue(field, value) {
+    if (value === undefined || value === null)
+        return value;
+    switch (field.type) {
+        case 'money': {
+            const amount = typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : value;
+            if (!canonicalMoney(amount))
+                throw new Error('Money requires canonical integer minor units within PostgreSQL bigint range');
+            return amount;
+        }
+        case 'integer':
+        case 'belongsTo':
+            if (!Number.isInteger(value) ||
+                Number(value) < (field.type === 'belongsTo' ? 1 : -2147483648) ||
+                Number(value) > 2147483647)
+                throw new Error('Expected a PostgreSQL integer');
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                throw new Error('Expected a boolean');
+            return value;
+        case 'string':
+        case 'text':
+        case 'lookup':
+            if (typeof value !== 'string')
+                throw new Error('Expected a string');
+            return value;
+        case 'date':
+        case 'datetime': {
+            const normalized = field.type === 'datetime' && value instanceof Date && Number.isFinite(value.getTime())
+                ? value.toISOString()
+                : value;
+            if (!canonicalDate(normalized, field.type))
+                throw new Error('Expected a valid ISO date or canonical UTC timestamp');
+            return normalized;
+        }
+        case 'json':
+            if (!isJson(value))
+                throw new Error('Expected a JSON value without cycles or non-JSON values');
+            return value;
+        case 'attachment':
+            // Writes carry the id of an owned upload; reads are hydrated into summaries later.
+            if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 2147483647)
+                throw new Error('Expected the identifier of an uploaded attachment');
+            return value;
+        default:
+            return value;
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { Knex } from 'knex';
+export type BackupObject = {
+    key: string;
+    size: number;
+    modifiedAt: string;
+};
+export type BackupStatus = {
+    healthy: boolean;
+    reason: string;
+    checkedAt: string;
+};
+/** Check one complete recent snapshot; object existence is not a restore test. */
+export declare function assessBackup(objects: BackupObject[], now?: number, prefix?: string): BackupStatus;
+export declare function verifyBackup(db: Knex, inspect: () => Promise<BackupObject[]>, now?: number, prefix?: string): Promise<BackupStatus>;

package/build/src/services/backup.js

@@ -0,0 +1,59 @@
+import { Settings, notify } from './settings.js';
+/** Check one complete recent snapshot; object existence is not a restore test. */
+export function assessBackup(objects, now = Date.now(), prefix = 'adula') {
+    if (!/^adula(?:\/[a-zA-Z0-9_-]+)*$/.test(prefix))
+        throw new Error('Invalid backup prefix');
+    const root = prefix + '/';
+    const snapshots = new Map();
+    for (const object of objects) {
+        if (!object.key.startsWith(root))
+            continue;
+        const match = /^(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)\/(database\.dump|uploads\.tar\.gz|SHA256SUMS|COMPLETE)$/.exec(object.key.slice(root.length));
+        const age = now - Date.parse(object.modifiedAt);
+        if (!match ||
+            !Number.isFinite(object.size) ||
+            (match[2] === 'COMPLETE' ? object.size < 0 : object.size <= 0) ||
+            !Number.isFinite(age) ||
+            age < 0 ||
+            age > 48 * 3600000)
+            continue;
+        const files = snapshots.get(match[1]) ?? new Set();
+        files.add(match[2]);
+        snapshots.set(match[1], files);
+    }
+    const healthy = [...snapshots.values()].some((files) => files.size === 4);
+    return {
+        healthy,
+        reason: healthy ? 'recent_complete_snapshot' : 'missing_recent_complete_snapshot',
+        checkedAt: new Date(now).toISOString(),
+    };
+}
+export async function verifyBackup(db, inspect, now = Date.now(), prefix = 'adula') {
+    let status;
+    try {
+        status = assessBackup(await inspect(), now, prefix);
+    }
+    catch {
+        status = {
+            healthy: false,
+            reason: 'offsite_check_failed',
+            checkedAt: new Date(now).toISOString(),
+        };
+    }
+    await db.transaction(async (trx) => {
+        await trx.raw('SELECT pg_advisory_xact_lock(?)', [19300210]);
+        const settings = new Settings(trx);
+        const previous = await settings.get('backup.health');
+        await settings.set('backup.health', status);
+        if (!status.healthy && (previous?.healthy !== false || previous.reason !== status.reason)) {
+            const admins = await trx('user_roles as ur')
+                .join('roles as r', 'r.id', 'ur.role_id')
+                .where('r.permission_level', '>=', 1)
+                .whereNull('ur.org_unit_id')
+                .distinct('ur.user_id');
+            for (const admin of admins)
+                await notify(trx, admin.user_id, 'تعذّر التحقق من النسخة الاحتياطية', 'تحقق من مخزن النسخ الخارجي ووجود نسخة كاملة خلال آخر 48 ساعة.');
+        }
+    });
+    return status;
+}

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

@@ -0,0 +1,9 @@
+import type { Knex } from 'knex';
+export declare class Settings {
+    private db;
+    constructor(db: Knex);
+    get<T>(key: string, scope?: string, scopeId?: string): Promise<T | undefined>;
+    set(key: string, value: unknown, scope?: string, scopeId?: string): Promise<void>;
+}
+export declare function sequence(trx: Knex.Transaction, key: string): Promise<string>;
+export declare function notify(db: Knex, userId: number, title: string, body: string): Promise<void>;

package/build/src/services/settings.js

@@ -0,0 +1,23 @@
+export class Settings {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async get(key, scope = 'system', scopeId = '0') {
+        const row = await this.db('settings').where({ key, scope, scope_id: scopeId }).first('value');
+        return row?.value;
+    }
+    async set(key, value, scope = 'system', scopeId = '0') {
+        await this.db('settings')
+            .insert({ key, scope, scope_id: scopeId, value: JSON.stringify(value) })
+            .onConflict(['key', 'scope', 'scope_id'])
+            .merge(['value']);
+    }
+}
+export async function sequence(trx, key) {
+    const result = await trx.raw('INSERT INTO sequences (key,value) VALUES (?,1) ON CONFLICT (key) DO UPDATE SET value=sequences.value+1 RETURNING value', [key]);
+    return `${key}-${String(result.rows[0].value).padStart(6, '0')}`;
+}
+export async function notify(db, userId, title, body) {
+    await db('notifications').insert({ user_id: userId, title, body });
+}

package/build/src/version.d.ts

@@ -0,0 +1 @@
+export declare const KIT_VERSION: string;

package/build/src/version.js

@@ -0,0 +1,2 @@
+import { createRequire } from 'node:module';
+export const KIT_VERSION = createRequire(import.meta.url)('@adula/kit/package.json').version;

package/build/stubs/README.md

@@ -0,0 +1,6 @@
+# The stubs directory
+
+The `stubs` directory stores all the stubs needed by your package. It could be config files you will publish during the initial setup or stubs you want to use within the scaffolding commands.
+
+- Inside the `package.json` file, we have defined a `copy:templates` script that copies the `stubs` folder to the `build` folder.
+- Ensure the `build/stubs` are always published to npm via the `files` array inside the `package.json` file.

package/build/stubs/controller.stub

@@ -0,0 +1,8 @@
+{{{ exports({ to: app.makePath('app/controllers/resources_controller.ts') }) }}}
+import { createResourceController } from '@adula/kit'
+import { kit } from '#services/kit'
+
+export default createResourceController(async (ctx) => {
+  const runtime = kit()
+  return { ...runtime, actor: await runtime.actors.load(ctx.auth.getUserOrFail().id) }
+})

package/build/stubs/main.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export declare const stubsRoot: string;

package/build/stubs/main.js

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export const stubsRoot = import.meta.dirname;

package/build/stubs/main.ts

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export const stubsRoot = import.meta.dirname

package/build/stubs/modules.stub

@@ -0,0 +1,6 @@
+{{{ exports({ to: app.makePath('start/modules.ts') }) }}}
+import { ResourceRegistry } from '@adula/kit'
+import type { Module } from '@adula/kit'
+// adula:imports
+export const modules: Module[] = [/* adula:modules */]
+export const registry = new ResourceRegistry().register(modules)

package/build/stubs/resource_contract.stub

@@ -0,0 +1 @@
+{{{ exports({ to: app.makePath('tests/helpers/resource_contract.ts') }) }}}