@adula/kit 0.2.0-alpha.1

package/build/src/auth/sql.js

@@ -0,0 +1,114 @@
+import { abilitySchemas } from './ability.js';
+import { predicates } from './conditions.js';
+import { columnName } from '../resource/define_resource.js';
+import { canonicalDate, canonicalMoney } from '../resource/values.js';
+export function conditionSql(conditions, resource) {
+    const allowed = new Set([
+        ...Object.keys(resource.fields),
+        'id',
+        'orgUnitId',
+        'createdBy',
+        'updatedBy',
+        'docStatus',
+        'version',
+        'orgPath',
+    ]);
+    const parts = predicates(conditions, allowed);
+    const bindings = [];
+    const text = parts
+        .map(({ field, operator, value }) => {
+        const column = field === 'orgPath' ? 'ou.path' : `r.${resource.fields[field]?.column ?? columnName(field)}`;
+        if (resource.fields[field]?.type === 'hasMany')
+            throw new Error('Conditions on collections are unsupported');
+        const type = resource.fields[field]?.type;
+        if (type === 'json' || type === 'attachment')
+            throw new Error(`Conditions on ${type} fields require a typed adapter`);
+        const expected = ['id', 'orgUnitId', 'createdBy', 'updatedBy', 'version', 'docStatus'].includes(field) ||
+            type === 'integer' ||
+            type === 'belongsTo'
+            ? 'number'
+            : type === 'boolean'
+                ? 'boolean'
+                : 'string';
+        for (const operand of Array.isArray(value) ? value : [value]) {
+            const operandType = typeof operand;
+            if (operand !== null && operandType !== expected)
+                throw new Error(`Condition type mismatch for ${field}: expected ${expected}`);
+            if (typeof operand === 'number' && !Number.isSafeInteger(operand))
+                throw new Error('Integer conditions require safe integers');
+            if (type === 'money' && operand !== null && !canonicalMoney(operand))
+                throw new Error('Money conditions require canonical integer strings');
+            if ((type === 'date' || type === 'datetime') && operand !== null) {
+                if (!canonicalDate(operand, type))
+                    throw new Error('Date conditions require a valid ISO date or canonical UTC timestamp');
+                if (operator === '$like')
+                    throw new Error('LIKE is supported on text fields only');
+            }
+        }
+        if (operator === '$in') {
+            const values = value;
+            if (!values.length)
+                return 'FALSE';
+            bindings.push(column, ...values.filter((v) => v !== null));
+            const nonNull = values.filter((v) => v !== null);
+            let clause = nonNull.length
+                ? `COALESCE(?? IN (${nonNull.map(() => '?').join(',')}), FALSE)`
+                : '?? IS NULL';
+            if (nonNull.length && values.includes(null)) {
+                bindings.push(column);
+                clause = `(${clause} OR ?? IS NULL)`;
+            }
+            return clause;
+        }
+        bindings.push(column);
+        if (operator === '$eq' || operator === '$ne') {
+            bindings.push(value);
+            return operator === '$eq' ? '?? IS NOT DISTINCT FROM ?' : '?? IS DISTINCT FROM ?';
+        }
+        bindings.push(value);
+        if (operator === '$like')
+            return "COALESCE(CAST(?? AS text) LIKE ? ESCAPE '', FALSE)";
+        const collation = ['string', 'text', 'lookup'].includes(type ?? '') ? ' COLLATE "C"' : '';
+        return `COALESCE(??${collation} ${operator === '$lt' ? '<' : '>'} ?, FALSE)`;
+    })
+        .join(' AND ');
+    return { text: text || 'TRUE', bindings };
+}
+export function authorizationSql(ability, action, resource, field) {
+    // CASL rulesFor returns highest-priority rules first. CASE preserves last-rule-wins.
+    const rules = ability
+        .rulesFor(action, resource.name, field)
+        .filter((rule) => !(field === undefined && rule.inverted && rule.fields));
+    const bindings = [];
+    const branches = rules.map((rule) => {
+        for (const predicate of predicates(rule.conditions)) {
+            if (resource.fields[predicate.field]?.type === 'money' &&
+                ['$lt', '$gt'].includes(predicate.operator) &&
+                !abilitySchemas
+                    .get(ability)
+                    ?.some((schema) => schema.name === resource.name && schema.fields[predicate.field]?.type === 'money'))
+                throw new Error('Ordered money rules require buildAbility(rules, resourceSchemas)');
+        }
+        const where = conditionSql(rule.conditions, resource);
+        bindings.push(...where.bindings);
+        return `WHEN (${where.text}) THEN ${rule.inverted ? 'FALSE' : 'TRUE'}`;
+    });
+    return {
+        text: branches.length ? `(CASE ${branches.join(' ')} ELSE FALSE END)` : 'FALSE',
+        bindings,
+    };
+}
+export function accessibleBy(query, ability, actor, action, resource) {
+    const sql = authorizationSql(ability, action, resource);
+    query.whereRaw(sql.text, sql.bindings);
+    if (resource.scoped) {
+        query.join('org_units as ou', 'ou.id', 'r.org_unit_id');
+        query.where((scope) => {
+            if (!actor.orgPaths.length)
+                scope.whereRaw('FALSE');
+            for (const path of actor.orgPaths)
+                scope.orWhereRaw('ou.path <@ ?::ltree', [path]);
+        });
+    }
+    return query;
+}

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

@@ -0,0 +1,7 @@
+export declare const digest: (text: string) => string;
+export declare function managedRules(text: string): string;
+export declare function agentAssets(): Promise<{
+    rules: string;
+    skills: Record<string, string>;
+}>;
+export declare function syncAgentAssets(root: string): Promise<void>;

package/build/src/commands/agent_assets.js

@@ -0,0 +1,54 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { KIT_VERSION } from '../version.js';
+const endMarker = '<!-- adula-kit:end -->';
+export const digest = (text) => createHash('sha256').update(text.replace(/\r\n/g, '\n')).digest('hex');
+export function managedRules(text) {
+    const start = text.indexOf('<!-- adula-kit:start');
+    const end = text.indexOf(endMarker);
+    return start >= 0 && end > start
+        ? text.slice(start, end + endMarker.length).replace(/\r\n/g, '\n')
+        : '';
+}
+export async function agentAssets() {
+    const skills = {};
+    for (const [source, target] of [
+        ['idea-review', 'adula-idea-review'],
+        ['adula-frontend-design', 'adula-frontend-design'],
+    ]) {
+        skills[`.agents/skills/${target}/SKILL.md`] = await readFile(new URL(`../../agent/skills/${source}/SKILL.md`, import.meta.url), 'utf8');
+    }
+    return {
+        rules: managedRules(await readFile(new URL('../../agent/AGENTS.template.md', import.meta.url), 'utf8')),
+        skills,
+    };
+}
+export async function syncAgentAssets(root) {
+    const assets = await agentAssets();
+    const path = join(root, 'AGENTS.md');
+    let existing = '';
+    try {
+        existing = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const old = managedRules(existing);
+    if (!old && (existing.includes('<!-- adula-kit:start') || existing.includes(endMarker)))
+        throw new Error('Malformed managed AGENTS.md boundaries; repair markers before updating');
+    const normalized = existing.replace(/\r\n/g, '\n');
+    await writeFile(path, old
+        ? normalized.replace(old, assets.rules)
+        : `${assets.rules}\n\n${existing || '## Project rules\n'}`);
+    for (const [skill, content] of Object.entries(assets.skills)) {
+        await mkdir(dirname(join(root, skill)), { recursive: true });
+        await writeFile(join(root, skill), content);
+    }
+    await writeFile(join(root, 'adula.lock.json'), `${JSON.stringify({
+        version: KIT_VERSION,
+        managedRules: digest(assets.rules),
+        skills: Object.fromEntries(Object.entries(assets.skills).map(([skillPath, content]) => [skillPath, digest(content)])),
+    }, null, 2)}\n`);
+}

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

@@ -0,0 +1,11 @@
+import type { Settings } from '../services/settings.js';
+export type Finding = {
+    check: string;
+    status: 'pass' | 'warn' | 'fail' | 'info';
+    message: string;
+};
+export declare function assessUploadSize(bytes: number): Finding;
+export declare function diagnoseUploads(root: string): Promise<Finding>;
+export declare function diagnoseUi(root: string): Promise<Finding[]>;
+export declare function diagnoseAgentSkills(root: string): Promise<Finding>;
+export declare function diagnose(root: string, settings: Settings, production: boolean, env: Record<string, string | undefined>, now?: number): Promise<Finding[]>;

package/build/src/commands/doctor.js

@@ -0,0 +1,261 @@
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative } from 'node:path';
+import { KIT_VERSION } from '../version.js';
+import { agentAssets, managedRules, digest } from './agent_assets.js';
+// The deployment volume and backup scripts share this application-relative path.
+const UPLOADS_PATH = 'storage/uploads';
+const UPLOADS_WARNING_BYTES = 5_000_000_000;
+async function assertContained(root, path) {
+    const resolved = relative(await realpath(root), await realpath(path));
+    if (resolved === '..' ||
+        resolved.startsWith('../') ||
+        resolved.startsWith('..\\') ||
+        isAbsolute(resolved))
+        throw new Error('Path resolves outside the application');
+}
+async function visitFiles(root, directory, visit) {
+    const path = join(root, directory);
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    await assertContained(root, path);
+    const walk = async (current) => {
+        const entry = await lstat(current);
+        if (entry.isSymbolicLink())
+            throw new Error('Symbolic links require manual inspection');
+        if (entry.isFile()) {
+            await visit(relative(root, current).replaceAll('\\', '/'), entry.size);
+            return;
+        }
+        if (!entry.isDirectory())
+            throw new Error('Unsupported filesystem entry');
+        const children = await readdir(current);
+        for (const child of children.sort())
+            await walk(join(current, child));
+    };
+    const entry = await lstat(path);
+    if (!entry.isDirectory())
+        throw new Error('Expected a directory');
+    await walk(path);
+    return true;
+}
+export function assessUploadSize(bytes) {
+    const large = bytes > UPLOADS_WARNING_BYTES;
+    return {
+        check: 'storage.uploads',
+        status: large ? 'warn' : 'pass',
+        message: `${UPLOADS_PATH} contains ${bytes} bytes (${(bytes / 1_000_000_000).toFixed(2)} GB); ${large
+            ? 'above 5 GB, plan an S3 migration and verify the uploaded files before removing local copies'
+            : 'within the 5 GB local-storage warning threshold'}`,
+    };
+}
+export async function diagnoseUploads(root) {
+    try {
+        let bytes = 0;
+        const exists = await visitFiles(root, UPLOADS_PATH, (_path, size) => {
+            bytes += size;
+        });
+        return exists
+            ? assessUploadSize(bytes)
+            : {
+                check: 'storage.uploads',
+                status: 'pass',
+                message: `${UPLOADS_PATH} does not exist; no local uploads volume to measure`,
+            };
+    }
+    catch {
+        return {
+            check: 'storage.uploads',
+            status: 'warn',
+            message: `Cannot completely measure ${UPLOADS_PATH}; check permissions, directory structure and symbolic links. Size is unknown`,
+        };
+    }
+}
+async function diagnosePages(root, changed) {
+    if (!changed.length)
+        return {
+            check: 'ui.pages',
+            status: 'pass',
+            message: 'No copied UI drift detected; page compatibility still requires typecheck and page tests',
+        };
+    const pages = [];
+    const collect = (file) => {
+        if (/\.[jt]sx$/.test(file))
+            pages.push(file);
+    };
+    try {
+        await visitFiles(root, 'inertia/pages', collect);
+        // Module-local page overrides are also project-owned extension points.
+        await visitFiles(root, 'app/modules', (file) => {
+            if (/^app\/modules\/[^/]+\/pages\//.test(file))
+                collect(file);
+        });
+    }
+    catch {
+        return {
+            check: 'ui.pages',
+            status: 'warn',
+            message: `UI review required (${changed.join('; ')}), but page sources could not be completely inventoried. Check source permissions and symbolic links, then run typecheck and page tests`,
+        };
+    }
+    return {
+        check: 'ui.pages',
+        status: 'warn',
+        message: `UI review required (${changed.join('; ')}). ${pages.length
+            ? `Review all ${pages.length} project-owned page sources: ${pages.sort().join(', ')}`
+            : 'No page sources found in inertia/pages or app/modules/*/pages; review overrides in the source checkout'}. This is a conservative inventory, not import dependency analysis; run typecheck and page tests`,
+    };
+}
+export async function diagnoseUi(root) {
+    try {
+        const lock = JSON.parse(await readFile(join(root, 'ui.lock.json'), 'utf8'));
+        if (typeof lock.version !== 'string' ||
+            typeof lock.kitCompatibility !== 'string' ||
+            !lock.files ||
+            typeof lock.files !== 'object' ||
+            Array.isArray(lock.files))
+            throw new Error('Invalid UI lock');
+        const compatible = lock.kitCompatibility === KIT_VERSION.split('.').slice(0, 2).join('.');
+        const customized = [];
+        for (const [file, entry] of Object.entries(lock.files)) {
+            if (!/^inertia\/components\/ui\/[a-z][a-z0-9_-]*\.tsx?$/.test(file) ||
+                !entry ||
+                typeof entry.hash !== 'string' ||
+                !/^[a-f0-9]{64}$/.test(entry.hash))
+                throw new Error('Invalid UI lock entry');
+            const path = join(root, file);
+            await assertContained(root, path);
+            const info = await lstat(path);
+            if (!info.isFile())
+                throw new Error('UI component must be a regular file');
+            if (digest(await readFile(path, 'utf8')) !== entry.hash)
+                customized.push(file);
+        }
+        const changes = [
+            ...(!compatible ? ['UI registry compatibility differs from this kit version'] : []),
+            ...(customized.length ? [`copied UI changed: ${customized.sort().join(', ')}`] : []),
+        ];
+        return [
+            {
+                check: 'ui.compatibility',
+                status: compatible ? 'pass' : 'fail',
+                message: compatible
+                    ? 'UI registry is compatible with this kit version'
+                    : 'UI registry version requires a compatibility review',
+            },
+            {
+                check: 'ui.customizations',
+                status: customized.length ? 'warn' : 'pass',
+                message: customized.length
+                    ? `${customized.length} project-owned UI files are customized; review diffs before updates`
+                    : 'UI files match the installed registry snapshot',
+            },
+            await diagnosePages(root, changes),
+        ];
+    }
+    catch {
+        return [
+            {
+                check: 'ui.registry',
+                status: 'fail',
+                message: 'UI lock or component files are missing or invalid; run adula:ui add all',
+            },
+        ];
+    }
+}
+export async function diagnoseAgentSkills(root) {
+    let valid = false;
+    try {
+        const assets = await agentAssets();
+        const lock = JSON.parse(await readFile(join(root, 'adula.lock.json'), 'utf8'));
+        valid = lock.version === KIT_VERSION && lock.managedRules === digest(assets.rules);
+        for (const [skillPath, content] of Object.entries(assets.skills)) {
+            const actual = await readFile(join(root, skillPath), 'utf8');
+            valid =
+                valid && lock.skills?.[skillPath] === digest(content) && digest(actual) === digest(content);
+        }
+    }
+    catch {
+        valid = false;
+    }
+    return {
+        check: 'agent.skills',
+        status: valid ? 'pass' : 'fail',
+        message: valid
+            ? 'Managed skill hashes match this kit version'
+            : 'Run adula:install to synchronize managed rules and skills',
+    };
+}
+export async function diagnose(root, settings, production, env, now = Date.now()) {
+    const findings = [];
+    findings.push(await diagnoseUploads(root));
+    const version = await settings.get('kit.version');
+    findings.push({
+        check: 'kit.version',
+        status: version === KIT_VERSION ? 'pass' : 'fail',
+        message: version === KIT_VERSION
+            ? `Kit ${KIT_VERSION} is installed`
+            : 'Run adula:install after migrations; installed kit version differs',
+    });
+    const template = await readFile(new URL('../../agent/AGENTS.template.md', import.meta.url), 'utf8');
+    let agents = '';
+    try {
+        agents = await readFile(join(root, 'AGENTS.md'), 'utf8');
+    }
+    catch { }
+    const managed = managedRules;
+    findings.push({
+        check: 'agent.rules',
+        status: managed(agents) === managed(template) ? 'pass' : 'fail',
+        message: managed(agents) === managed(template)
+            ? 'Managed rules match'
+            : 'Managed AGENTS.md was changed or is missing',
+    });
+    const keys = [
+        'BACKUP_S3_ENDPOINT',
+        'BACKUP_S3_BUCKET',
+        'BACKUP_S3_REGION',
+        'BACKUP_S3_ACCESS_KEY_ID',
+        'BACKUP_S3_SECRET_ACCESS_KEY',
+    ];
+    const configured = keys.every((key) => Boolean(env[key]));
+    findings.push({
+        check: 'backup.config',
+        status: configured ? 'pass' : production ? 'fail' : 'warn',
+        message: configured ? 'Offsite settings are present' : 'Offsite backup is not configured',
+    });
+    for (const [key, maxDays] of [
+        ['backup.lastOffsite', 2],
+        ['backup.lastRestoreTest', 90],
+    ]) {
+        const date = await settings.get(key);
+        const fresh = date &&
+            Number.isFinite(Date.parse(date)) &&
+            now - Date.parse(date) >= 0 &&
+            now - Date.parse(date) < maxDays * 86400000;
+        findings.push({
+            check: key,
+            status: fresh ? 'pass' : production ? 'fail' : 'warn',
+            message: fresh ? `${key} is current` : `${key} is missing or older than ${maxDays} days`,
+        });
+    }
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    findings.push({
+        check: 'boundaries',
+        status: pkg.dependencies?.['patch-package'] ||
+            pkg.devDependencies?.['patch-package'] ||
+            pkg.pnpm?.patchedDependencies
+            ? 'fail'
+            : 'pass',
+        message: 'Application may not patch kit internals',
+    });
+    findings.push(await diagnoseAgentSkills(root));
+    if (pkg.dependencies?.['@adula/ui'] || pkg.devDependencies?.['@adula/ui'])
+        findings.push(...(await diagnoseUi(root)));
+    return findings;
+}

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

@@ -0,0 +1 @@
+export declare function generateResource(root: string, name: string, module: string): Promise<string[]>;

package/build/src/commands/generator.js

@@ -0,0 +1,70 @@
+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';
+export async function generateResource(root, name, module) {
+    identifier(name);
+    identifier(module);
+    for await (const existing of glob(`app/modules/*/resources/${name}.ts`, { cwd: root }))
+        throw new Error(`Refusing to overwrite resource registered at ${existing}`);
+    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 migration = {
+        name,
+        scoped: true,
+        fields: {
+            title: {
+                type: 'string',
+                label: { ar: 'العنوان', en: 'Title' },
+                required: true,
+                searchable: true,
+            },
+        },
+    };
+    const files = {
+        [`${relative}/resources/${name}.ts`]: resourceSource,
+        [`${relative}/models/${name}.ts`]: `import { BaseModel, column } from '@adonisjs/lucid/orm'\nimport { DateTime } from 'luxon'\n\nexport default class extends BaseModel {\n  static table = '${name}'\n  @column({ isPrimary: true }) declare id: number\n  @column() declare title: string\n  @column() declare orgUnitId: number\n  @column() declare createdBy: number\n  @column() declare updatedBy: number\n  @column.dateTime({ autoCreate: true }) declare createdAt: DateTime\n  @column.dateTime({ autoCreate: true, autoUpdate: true }) declare updatedAt: DateTime\n  @column.dateTime() declare deletedAt: DateTime | null\n}\n`,
+        [`${relative}/validators/${name}.ts`]: `import vine from '@vinejs/vine'\nexport const validator = vine.create({ title: vine.string().trim().minLength(1).maxLength(255) })\n`,
+        [`${relative}/migrations/${Date.now()}_create_${name}.ts`]: `import { BaseSchema } from '@adonisjs/lucid/schema'\nimport { createResourceTable } from '@adula/kit'\nexport default class extends BaseSchema {\n  async up() { await createResourceTable(this.db.getWriteClient(), ${JSON.stringify(migration, null, 2)}) }\n  async down() { throw new Error('Use an expand/contract migration or restore a backup') }\n}\n`,
+        [`${relative}/factories/${name}.ts`]: `import factory from '@adonisjs/lucid/factories'\nimport Model from '#modules/${module}/models/${name}'\nexport default factory.define(Model, ({ faker }) => ({ title: faker.lorem.words(3) })).build()\n`,
+        [`tests/functional/${name}.spec.ts`]: `import { resourceContract } from '#tests/helpers/resource_contract'\n\n// Extend this fixture whenever the resource form or its validator changes.\nresourceContract('${name}', ({ unique }) => ({\n  input: { title: 'سجل ' + unique },\n  expected: { title: 'سجل ' + unique },\n  update: { title: 'سجل محدث ' + unique },\n  updated: { title: 'سجل محدث ' + unique },\n}))\n`,
+    };
+    const modulePath = join(base, 'module.ts');
+    let current;
+    try {
+        current = await readFile(modulePath, 'utf8');
+    }
+    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`;
+    }
+    if (!current.includes('// adula:imports') || !current.includes('/* adula:resources */'))
+        throw new Error('Module registration markers are missing; no files were changed');
+    const modulesPath = join(root, 'start/modules.ts');
+    const modules = await readFile(modulesPath, 'utf8');
+    if (!modules.includes('// adula:imports') || !modules.includes('/* adula:modules */'))
+        throw new Error('Module index markers are missing; no files were changed');
+    for (const file of Object.keys(files)) {
+        try {
+            await access(join(root, file));
+            throw new Error(`Refusing to overwrite ${file}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    for (const [file, content] of Object.entries(files)) {
+        const path = join(root, file);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, { flag: 'wx' });
+    }
+    await mkdir(base, { recursive: true });
+    await writeFile(modulePath, appendMarkedItem(current.replace('// adula:imports', `import resource_${name} from './resources/${name}.js'\n// adula:imports`), '/* adula:resources */', `resource_${name}`));
+    if (!modules.includes(`'#modules/${module}/module'`))
+        await writeFile(modulesPath, appendMarkedItem(modules.replace('// adula:imports', `import module_${module} from '#modules/${module}/module'\n// adula:imports`), '/* adula:modules */', `module_${module}`));
+    return Object.keys(files);
+}

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

@@ -0,0 +1,2 @@
+/** Append to a marked literal array, including when the last item has no trailing comma. */
+export declare function appendMarkedItem(source: string, marker: string, expression: string): string;

package/build/src/commands/source_markers.js

@@ -0,0 +1,9 @@
+/** Append to a marked literal array, including when the last item has no trailing comma. */
+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}`);
+}

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

@@ -0,0 +1,43 @@
+import type { Knex } from 'knex';
+import type { JsonValue } from '../resource/types.js';
+export type ActivityEntry = {
+    resource: string;
+    recordId: number;
+    actorId: number;
+    action: string;
+    changes?: Record<string, unknown>;
+};
+export type ActivityFilters = {
+    resource?: string;
+    actorId?: number;
+    action?: string;
+    from?: string;
+    to?: string;
+    cursor?: string;
+    limit?: number;
+};
+export type ActivityRow = {
+    id: string;
+    resource: string;
+    recordId: number;
+    actorId: number;
+    actor: string | null;
+    action: string;
+    changes: JsonValue;
+    createdAt: string;
+};
+export type ActivityPage = {
+    data: ActivityRow[];
+    nextCursor: string | null;
+};
+export declare function pageLimit(limit: unknown, fallback?: number): number;
+export declare function logActivity(db: Knex, entry: ActivityEntry): Promise<void>;
+export declare class ActivityAdmin {
+    private db;
+    constructor(db: Knex);
+    list(filters?: ActivityFilters): Promise<ActivityPage>;
+    facets(): Promise<{
+        resources: string[];
+        actions: string[];
+    }>;
+}

package/build/src/core/activity.js

@@ -0,0 +1,77 @@
+import { KitError } from '../admin/errors.js';
+export function pageLimit(limit, fallback = 50) {
+    const value = Number(limit ?? fallback);
+    if (!Number.isSafeInteger(value) || value < 1)
+        return fallback;
+    return Math.min(value, 100);
+}
+export async function logActivity(db, entry) {
+    await db('activities').insert({
+        resource: entry.resource,
+        record_id: entry.recordId,
+        actor_id: entry.actorId,
+        action: entry.action,
+        changes: JSON.stringify(entry.changes ?? {}),
+    });
+}
+function boundary(value, end) {
+    const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+    const parsed = Date.parse(dateOnly ? `${value}T00:00:00Z` : value);
+    if (!Number.isFinite(parsed))
+        throw new KitError(422, 'E_ACTIVITY_DATE', 'تاريخ غير صالح');
+    return new Date(dateOnly && end ? parsed + 86400000 : parsed);
+}
+export class ActivityAdmin {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async list(filters = {}) {
+        const limit = pageLimit(filters.limit);
+        const query = this.db('activities as a')
+            .leftJoin('users as u', 'u.id', 'a.actor_id')
+            .select('a.*', 'u.email as actor_email')
+            .orderBy('a.id', 'desc')
+            .limit(limit + 1);
+        if (filters.resource)
+            query.where('a.resource', filters.resource);
+        if (filters.actorId)
+            query.where('a.actor_id', filters.actorId);
+        if (filters.action)
+            query.where('a.action', filters.action);
+        if (filters.from)
+            query.where('a.created_at', '>=', boundary(filters.from, false));
+        if (filters.to) {
+            const end = /^\d{4}-\d{2}-\d{2}$/.test(filters.to);
+            query.where('a.created_at', end ? '<' : '<=', boundary(filters.to, end));
+        }
+        if (filters.cursor) {
+            if (!/^\d{1,18}$/.test(filters.cursor))
+                throw new KitError(422, 'E_ACTIVITY_CURSOR', 'مؤشر الصفحة غير صالح');
+            query.where('a.id', '<', filters.cursor);
+        }
+        const rows = await query;
+        const page = rows.slice(0, limit);
+        return {
+            data: page.map((row) => ({
+                id: String(row.id),
+                resource: row.resource,
+                recordId: row.record_id,
+                actorId: row.actor_id,
+                actor: row.actor_email ?? null,
+                action: row.action,
+                changes: row.changes,
+                createdAt: new Date(row.created_at).toISOString(),
+            })),
+            nextCursor: rows.length > limit ? String(page[page.length - 1].id) : null,
+        };
+    }
+    async facets() {
+        const resources = await this.db('activities').distinct('resource').orderBy('resource');
+        const actions = await this.db('activities').distinct('action').orderBy('action');
+        return {
+            resources: resources.map((row) => row.resource),
+            actions: actions.map((row) => row.action),
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Knex } from 'knex';
+/** Serialize access-changing mutations, including simultaneous requests by different admins. */
+export declare function administrationGuard(trx: Knex.Transaction, actorId: number): Promise<() => Promise<void>>;