adula 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/LICENSE.md +10 -0
  2. package/README.md +40 -2
  3. package/build/agent/AGENTS.template.md +28 -0
  4. package/build/agent/capabilities.md +60 -0
  5. package/build/agent/skills/adula-frontend-design/SKILL.md +59 -0
  6. package/build/agent/skills/idea-review/SKILL.md +31 -0
  7. package/build/agent/skills/module-review/SKILL.md +22 -0
  8. package/build/agent/skills/perf-review/SKILL.md +24 -0
  9. package/build/agent/skills/schema-review/SKILL.md +22 -0
  10. package/build/agent/skills/security-review/SKILL.md +24 -0
  11. package/build/agent/skills/ui-review/SKILL.md +22 -0
  12. package/build/commands/capabilities.d.ts +10 -0
  13. package/build/commands/capabilities.js +40 -0
  14. package/build/commands/doctor.d.ts +9 -0
  15. package/build/commands/doctor.js +72 -0
  16. package/build/commands/gaps.d.ts +12 -0
  17. package/build/commands/gaps.js +62 -0
  18. package/build/commands/install.d.ts +9 -0
  19. package/build/commands/install.js +105 -0
  20. package/build/commands/main.d.ts +8 -0
  21. package/build/commands/main.js +33 -0
  22. package/build/commands/module_add.d.ts +8 -0
  23. package/build/commands/module_add.js +57 -0
  24. package/build/commands/module_remove.d.ts +10 -0
  25. package/build/commands/module_remove.js +94 -0
  26. package/build/commands/resource.d.ts +8 -0
  27. package/build/commands/resource.js +29 -0
  28. package/build/commands/resource_snapshot.d.ts +15 -0
  29. package/build/commands/resource_snapshot.js +61 -0
  30. package/build/commands/storage_migrate.d.ts +12 -0
  31. package/build/commands/storage_migrate.js +39 -0
  32. package/build/commands/ui.d.ts +11 -0
  33. package/build/commands/ui.js +210 -0
  34. package/build/commands/upgrade.d.ts +15 -0
  35. package/build/commands/upgrade.js +34 -0
  36. package/build/configure.d.ts +2 -0
  37. package/build/configure.js +79 -0
  38. package/build/database/migrations/1770000000000_core.d.ts +5 -0
  39. package/build/database/migrations/1770000000000_core.js +10 -0
  40. package/build/database/migrations/1770000000001_attachments.d.ts +5 -0
  41. package/build/database/migrations/1770000000001_attachments.js +10 -0
  42. package/build/database/migrations/1770000000002_saved_views.d.ts +5 -0
  43. package/build/database/migrations/1770000000002_saved_views.js +10 -0
  44. package/build/database/migrations/1770000000003_user_invitations.d.ts +5 -0
  45. package/build/database/migrations/1770000000003_user_invitations.js +18 -0
  46. package/build/database/migrations/1770000000004_collaboration.d.ts +5 -0
  47. package/build/database/migrations/1770000000004_collaboration.js +10 -0
  48. package/build/database/migrations/1770000000005_assignments.d.ts +5 -0
  49. package/build/database/migrations/1770000000005_assignments.js +10 -0
  50. package/build/database/migrations/1770000000006_messaging.d.ts +5 -0
  51. package/build/database/migrations/1770000000006_messaging.js +10 -0
  52. package/build/database/migrations/1770000000007_webhooks.d.ts +5 -0
  53. package/build/database/migrations/1770000000007_webhooks.js +10 -0
  54. package/build/database/migrations/1770000000008_imports.d.ts +5 -0
  55. package/build/database/migrations/1770000000008_imports.js +10 -0
  56. package/build/database/migrations/1770000000010_workflows.d.ts +5 -0
  57. package/build/database/migrations/1770000000010_workflows.js +10 -0
  58. package/build/database/migrations/1770000000011_managed_assignments.d.ts +5 -0
  59. package/build/database/migrations/1770000000011_managed_assignments.js +10 -0
  60. package/build/database/migrations/1770000000012_role_keys.d.ts +5 -0
  61. package/build/database/migrations/1770000000012_role_keys.js +10 -0
  62. package/build/database/migrations/1770000000013_notification_targets.d.ts +5 -0
  63. package/build/database/migrations/1770000000013_notification_targets.js +10 -0
  64. package/build/database/migrations/1770000000014_upload_grants.d.ts +5 -0
  65. package/build/database/migrations/1770000000014_upload_grants.js +10 -0
  66. package/build/database/migrations/1770000000015_inbound_webhooks.d.ts +5 -0
  67. package/build/database/migrations/1770000000015_inbound_webhooks.js +10 -0
  68. package/build/database/migrations/1770000000016_adulajs_names.d.ts +6 -0
  69. package/build/database/migrations/1770000000016_adulajs_names.js +11 -0
  70. package/build/index.d.ts +80 -0
  71. package/build/index.js +49 -0
  72. package/build/providers/adula_provider.d.ts +6 -0
  73. package/build/providers/adula_provider.js +10 -0
  74. package/build/src/admin/contracts.d.ts +19 -0
  75. package/build/src/admin/contracts.js +115 -0
  76. package/build/src/admin/controller.d.ts +32 -0
  77. package/build/src/admin/controller.js +167 -0
  78. package/build/src/admin/errors.d.ts +5 -0
  79. package/build/src/admin/errors.js +9 -0
  80. package/build/src/admin/presentation.d.ts +28 -0
  81. package/build/src/admin/presentation.js +1 -0
  82. package/build/src/admin/record_title.d.ts +14 -0
  83. package/build/src/admin/record_title.js +50 -0
  84. package/build/src/admin/resource_service.d.ts +376 -0
  85. package/build/src/admin/resource_service.js +1448 -0
  86. package/build/src/attachments/attachment_service.d.ts +100 -0
  87. package/build/src/attachments/attachment_service.js +270 -0
  88. package/build/src/attachments/doctor.d.ts +4 -0
  89. package/build/src/attachments/doctor.js +28 -0
  90. package/build/src/attachments/storage_migrate.d.ts +39 -0
  91. package/build/src/attachments/storage_migrate.js +64 -0
  92. package/build/src/attachments/upload_grants.d.ts +44 -0
  93. package/build/src/attachments/upload_grants.js +105 -0
  94. package/build/src/auth/ability.d.ts +24 -0
  95. package/build/src/auth/ability.js +34 -0
  96. package/build/src/auth/actor_store.d.ts +14 -0
  97. package/build/src/auth/actor_store.js +70 -0
  98. package/build/src/auth/conditions.d.ts +26 -0
  99. package/build/src/auth/conditions.js +117 -0
  100. package/build/src/auth/packed_rules.d.ts +4 -0
  101. package/build/src/auth/packed_rules.js +13 -0
  102. package/build/src/auth/sql.d.ts +11 -0
  103. package/build/src/auth/sql.js +118 -0
  104. package/build/src/collaboration/assignments.d.ts +129 -0
  105. package/build/src/collaboration/assignments.js +333 -0
  106. package/build/src/collaboration/record_collaboration.d.ts +86 -0
  107. package/build/src/collaboration/record_collaboration.js +348 -0
  108. package/build/src/commands/agent_assets.d.ts +7 -0
  109. package/build/src/commands/agent_assets.js +66 -0
  110. package/build/src/commands/capabilities.d.ts +19 -0
  111. package/build/src/commands/capabilities.js +179 -0
  112. package/build/src/commands/doctor.d.ts +42 -0
  113. package/build/src/commands/doctor.js +375 -0
  114. package/build/src/commands/gap_report.d.ts +56 -0
  115. package/build/src/commands/gap_report.js +110 -0
  116. package/build/src/commands/generator.d.ts +1 -0
  117. package/build/src/commands/generator.js +70 -0
  118. package/build/src/commands/snapshot.d.ts +28 -0
  119. package/build/src/commands/snapshot.js +48 -0
  120. package/build/src/commands/source_markers.d.ts +11 -0
  121. package/build/src/commands/source_markers.js +41 -0
  122. package/build/src/core/activity.d.ts +43 -0
  123. package/build/src/core/activity.js +77 -0
  124. package/build/src/core/administration_guard.d.ts +3 -0
  125. package/build/src/core/administration_guard.js +39 -0
  126. package/build/src/core/health.d.ts +42 -0
  127. package/build/src/core/health.js +44 -0
  128. package/build/src/core/mail_test.d.ts +18 -0
  129. package/build/src/core/mail_test.js +88 -0
  130. package/build/src/core/message_templates.d.ts +83 -0
  131. package/build/src/core/message_templates.js +293 -0
  132. package/build/src/core/module_seed.d.ts +15 -0
  133. package/build/src/core/module_seed.js +31 -0
  134. package/build/src/core/notifications.d.ts +42 -0
  135. package/build/src/core/notifications.js +91 -0
  136. package/build/src/core/org_units.d.ts +30 -0
  137. package/build/src/core/org_units.js +123 -0
  138. package/build/src/core/roles.d.ts +98 -0
  139. package/build/src/core/roles.js +447 -0
  140. package/build/src/core/saved_views.d.ts +37 -0
  141. package/build/src/core/saved_views.js +164 -0
  142. package/build/src/core/settings.d.ts +29 -0
  143. package/build/src/core/settings.js +113 -0
  144. package/build/src/core/setup.d.ts +14 -0
  145. package/build/src/core/setup.js +89 -0
  146. package/build/src/core/ui_preferences.d.ts +12 -0
  147. package/build/src/core/ui_preferences.js +30 -0
  148. package/build/src/core/user_invitations.d.ts +23 -0
  149. package/build/src/core/user_invitations.js +144 -0
  150. package/build/src/core/users.d.ts +44 -0
  151. package/build/src/core/users.js +182 -0
  152. package/build/src/database/configure.d.ts +3 -0
  153. package/build/src/database/configure.js +41 -0
  154. package/build/src/database/schema.d.ts +52 -0
  155. package/build/src/database/schema.js +538 -0
  156. package/build/src/eslint/index.d.ts +3 -0
  157. package/build/src/eslint/index.js +90 -0
  158. package/build/src/events/adonis_jobs.d.ts +9 -0
  159. package/build/src/events/adonis_jobs.js +13 -0
  160. package/build/src/events/outbox.d.ts +19 -0
  161. package/build/src/events/outbox.js +33 -0
  162. package/build/src/events/record_mutation.d.ts +24 -0
  163. package/build/src/events/record_mutation.js +62 -0
  164. package/build/src/integrations/imports.d.ts +74 -0
  165. package/build/src/integrations/imports.js +333 -0
  166. package/build/src/integrations/inbound_webhooks.d.ts +94 -0
  167. package/build/src/integrations/inbound_webhooks.js +276 -0
  168. package/build/src/integrations/openapi.d.ts +39 -0
  169. package/build/src/integrations/openapi.js +323 -0
  170. package/build/src/integrations/print.d.ts +37 -0
  171. package/build/src/integrations/print.js +124 -0
  172. package/build/src/integrations/webhooks.d.ts +98 -0
  173. package/build/src/integrations/webhooks.js +298 -0
  174. package/build/src/mcp/tools.d.ts +8 -0
  175. package/build/src/mcp/tools.js +156 -0
  176. package/build/src/org/org_service.d.ts +2 -0
  177. package/build/src/org/org_service.js +16 -0
  178. package/build/src/resource/define_resource.d.ts +5 -0
  179. package/build/src/resource/define_resource.js +68 -0
  180. package/build/src/resource/registry.d.ts +12 -0
  181. package/build/src/resource/registry.js +101 -0
  182. package/build/src/resource/types.d.ts +155 -0
  183. package/build/src/resource/types.js +1 -0
  184. package/build/src/resource/values.d.ts +5 -0
  185. package/build/src/resource/values.js +88 -0
  186. package/build/src/services/backup.d.ts +14 -0
  187. package/build/src/services/backup.js +59 -0
  188. package/build/src/services/settings.d.ts +21 -0
  189. package/build/src/services/settings.js +30 -0
  190. package/build/src/upgrade/legacy.d.ts +27 -0
  191. package/build/src/upgrade/legacy.js +58 -0
  192. package/build/src/upgrade/rename.d.ts +17 -0
  193. package/build/src/upgrade/rename.js +94 -0
  194. package/build/src/version.d.ts +1 -0
  195. package/build/src/version.js +2 -0
  196. package/build/src/workflows/define_workflow.d.ts +124 -0
  197. package/build/src/workflows/define_workflow.js +123 -0
  198. package/build/src/workflows/engine.d.ts +141 -0
  199. package/build/src/workflows/engine.js +752 -0
  200. package/build/stubs/README.md +6 -0
  201. package/build/stubs/controller.stub +8 -0
  202. package/build/stubs/main.d.ts +5 -0
  203. package/build/stubs/main.js +5 -0
  204. package/build/stubs/main.ts +5 -0
  205. package/build/stubs/modules.stub +6 -0
  206. package/build/stubs/resource_contract.stub +1 -0
  207. package/build/stubs/resource_contract.txt +452 -0
  208. package/build/stubs/routes.stub +16 -0
  209. package/build/stubs/service.stub +9 -0
  210. package/package.json +95 -3
@@ -0,0 +1,48 @@
1
+ const EMBEDDED = /(createResourceTable\([^,]+,\s*)(\{[\s\S]*\})(\s*\)\s*\})/;
2
+ /**
3
+ * The part of a resource definition createResourceTable reads, as a generated
4
+ * create-migration embeds it. Labels are kept so the migration stays readable.
5
+ */
6
+ export function resourceSnapshot(resource) {
7
+ return {
8
+ name: resource.name,
9
+ scoped: resource.scoped,
10
+ ...(resource.version ? { version: true } : {}),
11
+ ...(resource.submittable ? { submittable: true } : {}),
12
+ ...(resource.customFields ? { customFields: true } : {}),
13
+ fields: Object.fromEntries(Object.entries(resource.fields)
14
+ .filter(([, field]) => field.type !== 'hasMany')
15
+ .map(([key, field]) => [
16
+ key,
17
+ {
18
+ type: field.type,
19
+ label: field.label,
20
+ ...(field.type === 'belongsTo' ? { resource: field.resource } : {}),
21
+ ...(field.column ? { column: field.column } : {}),
22
+ ...(field.required ? { required: true } : {}),
23
+ ...(field.unique ? { unique: true } : {}),
24
+ ...(field.searchable ? { searchable: true } : {}),
25
+ ...(field.sequence ? { sequence: field.sequence } : {}),
26
+ },
27
+ ])),
28
+ };
29
+ }
30
+ /** The resource name embedded in a generated create-migration, if the source is one. */
31
+ export function embeddedResource(source) {
32
+ const embedded = EMBEDDED.exec(source)?.[2];
33
+ if (!embedded)
34
+ return undefined;
35
+ try {
36
+ const parsed = JSON.parse(embedded);
37
+ return typeof parsed?.name === 'string' ? parsed.name : undefined;
38
+ }
39
+ catch {
40
+ return undefined;
41
+ }
42
+ }
43
+ /** Replaces the embedded definition of a generated create-migration (#20). */
44
+ export function rewriteResourceSnapshot(source, snapshot) {
45
+ if (embeddedResource(source) !== snapshot.name)
46
+ throw new Error(`The migration does not embed the ${snapshot.name} definition`);
47
+ return source.replace(EMBEDDED, (_, before, _old, after) => `${before}${JSON.stringify(snapshot, null, 2)}${after}`);
48
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
3
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
4
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
5
+ */
6
+ export declare function appendMarkedItem(source: string, marker: string, expression: string): string;
7
+ /** A new module definition, already in the project's Prettier layout. */
8
+ export declare function moduleSource(name: string, options?: {
9
+ reference?: boolean;
10
+ typed?: boolean;
11
+ }): string;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
3
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
4
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
5
+ */
6
+ export function appendMarkedItem(source, marker, expression) {
7
+ const offset = source.indexOf(marker);
8
+ if (offset < 0 || source.indexOf(marker, offset + marker.length) >= 0)
9
+ throw new Error(`Expected one registration marker: ${marker}`);
10
+ const open = source.lastIndexOf('[', offset);
11
+ const close = source.indexOf(']', offset + marker.length);
12
+ if (open < 0 || close < 0)
13
+ throw new Error(`Registration marker ${marker} must be inside an array`);
14
+ const listed = source.slice(open + 1, offset);
15
+ if (/[()[\]{}'"`]|\/\/|\/\*/.test(listed) || source.slice(offset + marker.length, close).trim())
16
+ throw new Error(`Registration list around ${marker} is not a plain list; add ${expression} by hand`);
17
+ const items = listed
18
+ .split(',')
19
+ .map((item) => item.trim())
20
+ .filter(Boolean);
21
+ const lineStart = source.lastIndexOf('\n', open) + 1;
22
+ const indent = /^[ \t]*/.exec(source.slice(lineStart, open))[0];
23
+ const inner = `${indent} `;
24
+ const lines = [...items, expression].map((item) => `${inner}${item},\n`).join('');
25
+ return `${source.slice(0, open)}[\n${lines}${inner}${marker}\n${indent}]${source.slice(close + 1)}`;
26
+ }
27
+ /** A new module definition, already in the project's Prettier layout. */
28
+ export function moduleSource(name, options = {}) {
29
+ return [
30
+ ...(options.typed ? ["import type { Module } from 'adula'"] : []),
31
+ '// adula:imports',
32
+ 'export default {',
33
+ ` name: '${name}',`,
34
+ ` label: { ar: '${name}', en: '${name}' },`,
35
+ ...(options.reference === undefined ? [] : [` reference: ${options.reference},`]),
36
+ ' dependsOn: [],',
37
+ ' resources: [/* adula:resources */],',
38
+ `}${options.typed ? ' satisfies Module' : ''}`,
39
+ '',
40
+ ].join('\n');
41
+ }
@@ -0,0 +1,43 @@
1
+ import type { Knex } from 'knex';
2
+ import type { JsonValue } from '../resource/types.js';
3
+ export type ActivityEntry = {
4
+ resource: string;
5
+ recordId: number;
6
+ actorId: number;
7
+ action: string;
8
+ changes?: Record<string, unknown>;
9
+ };
10
+ export type ActivityFilters = {
11
+ resource?: string;
12
+ actorId?: number;
13
+ action?: string;
14
+ from?: string;
15
+ to?: string;
16
+ cursor?: string;
17
+ limit?: number;
18
+ };
19
+ export type ActivityRow = {
20
+ id: string;
21
+ resource: string;
22
+ recordId: number;
23
+ actorId: number;
24
+ actor: string | null;
25
+ action: string;
26
+ changes: JsonValue;
27
+ createdAt: string;
28
+ };
29
+ export type ActivityPage = {
30
+ data: ActivityRow[];
31
+ nextCursor: string | null;
32
+ };
33
+ export declare function pageLimit(limit: unknown, fallback?: number): number;
34
+ export declare function logActivity(db: Knex, entry: ActivityEntry): Promise<void>;
35
+ export declare class ActivityAdmin {
36
+ private db;
37
+ constructor(db: Knex);
38
+ list(filters?: ActivityFilters): Promise<ActivityPage>;
39
+ facets(): Promise<{
40
+ resources: string[];
41
+ actions: string[];
42
+ }>;
43
+ }
@@ -0,0 +1,77 @@
1
+ import { AdulaError } from '../admin/errors.js';
2
+ export function pageLimit(limit, fallback = 50) {
3
+ const value = Number(limit ?? fallback);
4
+ if (!Number.isSafeInteger(value) || value < 1)
5
+ return fallback;
6
+ return Math.min(value, 100);
7
+ }
8
+ export async function logActivity(db, entry) {
9
+ await db('activities').insert({
10
+ resource: entry.resource,
11
+ record_id: entry.recordId,
12
+ actor_id: entry.actorId,
13
+ action: entry.action,
14
+ changes: JSON.stringify(entry.changes ?? {}),
15
+ });
16
+ }
17
+ function boundary(value, end) {
18
+ const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
19
+ const parsed = Date.parse(dateOnly ? `${value}T00:00:00Z` : value);
20
+ if (!Number.isFinite(parsed))
21
+ throw new AdulaError(422, 'E_ACTIVITY_DATE', 'تاريخ غير صالح');
22
+ return new Date(dateOnly && end ? parsed + 86400000 : parsed);
23
+ }
24
+ export class ActivityAdmin {
25
+ db;
26
+ constructor(db) {
27
+ this.db = db;
28
+ }
29
+ async list(filters = {}) {
30
+ const limit = pageLimit(filters.limit);
31
+ const query = this.db('activities as a')
32
+ .leftJoin('users as u', 'u.id', 'a.actor_id')
33
+ .select('a.*', 'u.email as actor_email')
34
+ .orderBy('a.id', 'desc')
35
+ .limit(limit + 1);
36
+ if (filters.resource)
37
+ query.where('a.resource', filters.resource);
38
+ if (filters.actorId)
39
+ query.where('a.actor_id', filters.actorId);
40
+ if (filters.action)
41
+ query.where('a.action', filters.action);
42
+ if (filters.from)
43
+ query.where('a.created_at', '>=', boundary(filters.from, false));
44
+ if (filters.to) {
45
+ const end = /^\d{4}-\d{2}-\d{2}$/.test(filters.to);
46
+ query.where('a.created_at', end ? '<' : '<=', boundary(filters.to, end));
47
+ }
48
+ if (filters.cursor) {
49
+ if (!/^\d{1,18}$/.test(filters.cursor))
50
+ throw new AdulaError(422, 'E_ACTIVITY_CURSOR', 'مؤشر الصفحة غير صالح');
51
+ query.where('a.id', '<', filters.cursor);
52
+ }
53
+ const rows = await query;
54
+ const page = rows.slice(0, limit);
55
+ return {
56
+ data: page.map((row) => ({
57
+ id: String(row.id),
58
+ resource: row.resource,
59
+ recordId: row.record_id,
60
+ actorId: row.actor_id,
61
+ actor: row.actor_email ?? null,
62
+ action: row.action,
63
+ changes: row.changes,
64
+ createdAt: new Date(row.created_at).toISOString(),
65
+ })),
66
+ nextCursor: rows.length > limit ? String(page[page.length - 1].id) : null,
67
+ };
68
+ }
69
+ async facets() {
70
+ const resources = await this.db('activities').distinct('resource').orderBy('resource');
71
+ const actions = await this.db('activities').distinct('action').orderBy('action');
72
+ return {
73
+ resources: resources.map((row) => row.resource),
74
+ actions: actions.map((row) => row.action),
75
+ };
76
+ }
77
+ }
@@ -0,0 +1,3 @@
1
+ import type { Knex } from 'knex';
2
+ /** Serialize access-changing mutations, including simultaneous requests by different admins. */
3
+ export declare function administrationGuard(trx: Knex.Transaction, actorId: number): Promise<() => Promise<void>>;
@@ -0,0 +1,39 @@
1
+ import { buildAbility } from '../auth/ability.js';
2
+ import { resolveActorConditions } from '../auth/conditions.js';
3
+ import { AdulaError } from '../admin/errors.js';
4
+ /** Same CASL decision as the admin middleware, with fresh rows inside the transaction. */
5
+ async function administrators(db) {
6
+ const rows = await db('user_roles as ur')
7
+ .join('users as u', 'u.id', 'ur.user_id')
8
+ .join('role_rules as rr', 'rr.role_id', 'ur.role_id')
9
+ .whereNull('u.disabled_at')
10
+ .whereNull('ur.org_unit_id')
11
+ .where('rr.subject', 'all')
12
+ .select('ur.user_id', 'rr.subject', 'rr.action', 'rr.inverted', 'rr.conditions', 'rr.fields');
13
+ const users = new Map();
14
+ for (const row of rows) {
15
+ const rules = users.get(row.user_id) ?? [];
16
+ rules.push({
17
+ subject: row.subject,
18
+ action: row.action,
19
+ inverted: row.inverted,
20
+ // Only subject 'all' is read here, so no field accepts the placeholder.
21
+ conditions: resolveActorConditions(row.conditions ?? undefined, Number(row.user_id), () => false),
22
+ fields: row.fields ?? undefined,
23
+ });
24
+ users.set(row.user_id, rules);
25
+ }
26
+ return new Set([...users].filter(([, rules]) => buildAbility(rules).can('manage', 'all')).map(([id]) => id));
27
+ }
28
+ /** Serialize access-changing mutations, including simultaneous requests by different admins. */
29
+ export async function administrationGuard(trx, actorId) {
30
+ await trx.raw('SELECT pg_advisory_xact_lock(717011)');
31
+ const before = await administrators(trx);
32
+ return async () => {
33
+ const after = await administrators(trx);
34
+ if (before.size && !after.size)
35
+ throw new AdulaError(409, 'E_LAST_ADMIN', 'لا يمكن تنفيذ هذا التغيير لأنه سيزيل آخر مدير نشط للنظام. عيّن مديرًا آخر أولًا.');
36
+ if (before.has(actorId) && !after.has(actorId))
37
+ throw new AdulaError(409, 'E_SELF_ADMIN_ACCESS', 'لا يمكنك إزالة صلاحية إدارة النظام من حسابك الحالي. اطلب من مدير آخر تعديلها.');
38
+ };
39
+ }
@@ -0,0 +1,42 @@
1
+ import type { Knex } from 'knex';
2
+ export type HeartbeatStatus = {
3
+ at: string | null;
4
+ ageMs: number | null;
5
+ healthy: boolean;
6
+ };
7
+ export type FailedJob = {
8
+ id: string;
9
+ name: string;
10
+ attemptsMade: number;
11
+ failedReason: string;
12
+ failedAt: string | null;
13
+ };
14
+ export type QueueCounts = Record<'waiting' | 'active' | 'delayed' | 'failed' | 'completed', number>;
15
+ /** Filled by the host from its queue backend; AdulaJS never talks to BullMQ. */
16
+ export type QueueSnapshot = {
17
+ name: string;
18
+ counts: QueueCounts;
19
+ failed: FailedJob[];
20
+ };
21
+ export type RuntimeHealth = {
22
+ outbox: {
23
+ backlog: number;
24
+ oldestAgeMs: number | null;
25
+ };
26
+ processedEvents: number;
27
+ heartbeats: {
28
+ scheduler: HeartbeatStatus;
29
+ worker: HeartbeatStatus;
30
+ };
31
+ backup: {
32
+ lastOffsite: string | null;
33
+ lastRestoreTest: string | null;
34
+ stale: boolean;
35
+ };
36
+ };
37
+ export declare const HEARTBEAT_MAX_AGE_MS = 60000;
38
+ export declare const BACKUP_MAX_AGE_MS: number;
39
+ export declare function heartbeat(value: unknown, now?: number): HeartbeatStatus;
40
+ export declare function backupStale(lastOffsite: unknown, now?: number): boolean;
41
+ export declare function isBackupStale(db: Knex, now?: number): Promise<boolean>;
42
+ export declare function runtimeHealth(db: Knex, now?: number): Promise<RuntimeHealth>;
@@ -0,0 +1,44 @@
1
+ import { Settings } from '../services/settings.js';
2
+ export const HEARTBEAT_MAX_AGE_MS = 60_000;
3
+ export const BACKUP_MAX_AGE_MS = 48 * 3_600_000;
4
+ function age(value, now) {
5
+ const at = typeof value === 'string' ? Date.parse(value) : Number.NaN;
6
+ return Number.isFinite(at) ? now - at : null;
7
+ }
8
+ export function heartbeat(value, now = Date.now()) {
9
+ const ageMs = age(value, now);
10
+ return {
11
+ at: ageMs === null ? null : String(value),
12
+ ageMs,
13
+ healthy: ageMs !== null && ageMs >= 0 && ageMs < HEARTBEAT_MAX_AGE_MS,
14
+ };
15
+ }
16
+ export function backupStale(lastOffsite, now = Date.now()) {
17
+ const ageMs = age(lastOffsite, now);
18
+ return ageMs === null || ageMs < 0 || ageMs >= BACKUP_MAX_AGE_MS;
19
+ }
20
+ export async function isBackupStale(db, now = Date.now()) {
21
+ return backupStale(await new Settings(db).get('backup.lastOffsite'), now);
22
+ }
23
+ export async function runtimeHealth(db, now = Date.now()) {
24
+ const settings = new Settings(db);
25
+ const outbox = await db('outbox')
26
+ .whereNull('published_at')
27
+ .select(db.raw('count(*) AS backlog'), db.raw('min(created_at) AS oldest'))
28
+ .first();
29
+ const processed = await db('processed_events').count('event_id as count').first();
30
+ const lastOffsite = (await settings.get('backup.lastOffsite')) ?? null;
31
+ const lastRestoreTest = (await settings.get('backup.lastRestoreTest')) ?? null;
32
+ return {
33
+ outbox: {
34
+ backlog: Number(outbox?.backlog ?? 0),
35
+ oldestAgeMs: outbox?.oldest ? Math.max(0, now - new Date(outbox.oldest).getTime()) : null,
36
+ },
37
+ processedEvents: Number(processed?.count ?? 0),
38
+ heartbeats: {
39
+ scheduler: heartbeat(await settings.get('scheduler.heartbeat'), now),
40
+ worker: heartbeat(await settings.get('worker.heartbeat'), now),
41
+ },
42
+ backup: { lastOffsite, lastRestoreTest, stale: backupStale(lastOffsite, now) },
43
+ };
44
+ }
@@ -0,0 +1,18 @@
1
+ import type { Knex } from 'knex';
2
+ export declare const MAIL_TEST_KEY = "mail.delivery_test";
3
+ export type MailTestState = {
4
+ id: string;
5
+ recipient: string;
6
+ fingerprint: string;
7
+ status: 'sending' | 'pending' | 'confirmed' | 'not_received' | 'failed';
8
+ requestedAt: string;
9
+ answeredAt?: string;
10
+ };
11
+ /** Receipt is an administrator attestation, never inferred from SMTP acceptance. */
12
+ export declare class MailDeliveryTest {
13
+ private db;
14
+ constructor(db: Knex);
15
+ current(actorId: number, recipient: string, fingerprint: string): Promise<MailTestState | null>;
16
+ send(actorId: number, recipient: string, fingerprint: string, deliver: (id: string) => Promise<void>): Promise<void>;
17
+ answer(actorId: number, recipient: string, fingerprint: string, id: unknown, received: unknown): Promise<void>;
18
+ }
@@ -0,0 +1,88 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { AdulaError } from '../admin/errors.js';
3
+ import { Settings } from '../services/settings.js';
4
+ import { logActivity } from './activity.js';
5
+ export const MAIL_TEST_KEY = 'mail.delivery_test';
6
+ /** Receipt is an administrator attestation, never inferred from SMTP acceptance. */
7
+ export class MailDeliveryTest {
8
+ db;
9
+ constructor(db) {
10
+ this.db = db;
11
+ }
12
+ async current(actorId, recipient, fingerprint) {
13
+ const state = await new Settings(this.db).get(MAIL_TEST_KEY, 'user', String(actorId));
14
+ return state?.recipient === recipient && state.fingerprint === fingerprint ? state : null;
15
+ }
16
+ async send(actorId, recipient, fingerprint, deliver) {
17
+ const state = {
18
+ id: randomUUID(),
19
+ recipient,
20
+ fingerprint,
21
+ status: 'sending',
22
+ requestedAt: new Date().toISOString(),
23
+ };
24
+ await this.db.transaction(async (trx) => {
25
+ await trx.raw('SELECT pg_advisory_xact_lock(?, ?)', [717012, actorId]);
26
+ const previous = await new Settings(trx).get(MAIL_TEST_KEY, 'user', String(actorId));
27
+ const cooldown = previous?.status === 'sending' ? 300_000 : 60_000;
28
+ if (previous && Date.now() - Date.parse(previous.requestedAt) < cooldown)
29
+ throw new AdulaError(429, 'E_MAIL_TEST_COOLDOWN', 'انتظر قليلًا قبل إعادة إرسال البريد التجريبي');
30
+ await new Settings(trx).set(MAIL_TEST_KEY, state, 'user', String(actorId));
31
+ await logActivity(trx, {
32
+ resource: 'core.mail',
33
+ recordId: actorId,
34
+ actorId,
35
+ action: 'test_requested',
36
+ changes: { testId: state.id },
37
+ });
38
+ });
39
+ let failed = false;
40
+ try {
41
+ await deliver(state.id);
42
+ }
43
+ catch {
44
+ failed = true;
45
+ }
46
+ // Match the attempt so a delayed response cannot overwrite a newer test.
47
+ await this.db.transaction(async (trx) => {
48
+ await trx('settings')
49
+ .where({ key: MAIL_TEST_KEY, scope: 'user', scope_id: String(actorId) })
50
+ .whereRaw("value->>'id' = ?", [state.id])
51
+ .update({ value: JSON.stringify({ ...state, status: failed ? 'failed' : 'pending' }) });
52
+ await logActivity(trx, {
53
+ resource: 'core.mail',
54
+ recordId: actorId,
55
+ actorId,
56
+ action: failed ? 'test_send_failed' : 'test_send_accepted',
57
+ changes: { testId: state.id },
58
+ });
59
+ });
60
+ if (failed)
61
+ throw new AdulaError(502, 'E_MAIL_TEST_SEND', 'تعذّر إرسال البريد التجريبي. راجع إعدادات البريد ثم أعد المحاولة.');
62
+ }
63
+ async answer(actorId, recipient, fingerprint, id, received) {
64
+ if (typeof received !== 'boolean' || typeof id !== 'string')
65
+ throw new AdulaError(422, 'E_MAIL_TEST_ANSWER', 'اختر هل وصلت الرسالة أم لم تصل');
66
+ await this.db.transaction(async (trx) => {
67
+ await trx.raw('SELECT pg_advisory_xact_lock(?, ?)', [717012, actorId]);
68
+ const state = await new MailDeliveryTest(trx).current(actorId, recipient, fingerprint);
69
+ if (!state ||
70
+ state.id !== id ||
71
+ state.status !== 'pending' ||
72
+ Date.now() - Date.parse(state.requestedAt) > 86_400_000)
73
+ throw new AdulaError(409, 'E_MAIL_TEST_STALE', 'هذه التجربة لم تعد قابلة للتأكيد. أرسل رسالة تجريبية جديدة.');
74
+ await new Settings(trx).set(MAIL_TEST_KEY, {
75
+ ...state,
76
+ status: received ? 'confirmed' : 'not_received',
77
+ answeredAt: new Date().toISOString(),
78
+ }, 'user', String(actorId));
79
+ await logActivity(trx, {
80
+ resource: 'core.mail',
81
+ recordId: actorId,
82
+ actorId,
83
+ action: received ? 'receipt_confirmed' : 'receipt_missing',
84
+ changes: { testId: state.id },
85
+ });
86
+ });
87
+ }
88
+ }
@@ -0,0 +1,83 @@
1
+ import type { Knex } from 'knex';
2
+ import { type NotificationTarget } from '../services/settings.js';
3
+ export type TemplateDefinition = {
4
+ label: string;
5
+ subject: string;
6
+ body: string;
7
+ /** Variables available as {{name}}; unknown placeholders are refused on edit. */
8
+ variables: string[];
9
+ /** Whether notifications from this template are also delivered by e-mail. */
10
+ mail: boolean;
11
+ };
12
+ export type MessageTemplate = TemplateDefinition & {
13
+ key: string;
14
+ customized: boolean;
15
+ updatedAt: string | null;
16
+ };
17
+ export type RenderedMessage = {
18
+ subject: string;
19
+ body: string;
20
+ mail: boolean;
21
+ };
22
+ /**
23
+ * Package-owned defaults. Projects edit wording in the message_templates table;
24
+ * an upgrade can change a default without overwriting a project's edit.
25
+ */
26
+ export declare const DEFAULT_TEMPLATES: Record<string, TemplateDefinition>;
27
+ export declare function renderTemplate(text: string, variables: Record<string, unknown>): string;
28
+ /** Message templates: package defaults plus per-deployment overrides edited by administrators. */
29
+ export declare class MessageTemplates {
30
+ private db;
31
+ private definitions;
32
+ constructor(db: Knex, definitions?: Record<string, TemplateDefinition>);
33
+ list(): Promise<MessageTemplate[]>;
34
+ render(key: string, variables: Record<string, unknown>, db?: Knex): Promise<RenderedMessage>;
35
+ update(key: string, input: {
36
+ subject: unknown;
37
+ body: unknown;
38
+ mail?: unknown;
39
+ }, actorId: number): Promise<void>;
40
+ reset(key: string): Promise<void>;
41
+ /** Example output with sample values, for the editor preview. */
42
+ preview(key: string, input: {
43
+ subject: string;
44
+ body: string;
45
+ }): {
46
+ subject: string;
47
+ body: string;
48
+ };
49
+ private definition;
50
+ }
51
+ /**
52
+ * Inserts a templated notification in the caller's transaction. Templates with
53
+ * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
54
+ */
55
+ export declare function notifyWithTemplate(db: Knex, userId: number, key: string, variables: Record<string, unknown>, templates?: MessageTemplates, target?: NotificationTarget | null): Promise<void>;
56
+ export type MailSender = (message: {
57
+ to: string;
58
+ name: string | null;
59
+ subject: string;
60
+ text: string;
61
+ /** The record the notification is about; build an absolute link from the application URL. */
62
+ target?: NotificationTarget | null;
63
+ }) => Promise<void>;
64
+ /**
65
+ * Delivers pending notification e-mails. Rows are claimed with SKIP LOCKED so
66
+ * several workers never send the same message; failures are retried three times.
67
+ */
68
+ export declare function deliverNotificationMail(db: Knex, send: MailSender, limit?: number): Promise<{
69
+ sent: number;
70
+ failed: number;
71
+ }>;
72
+ export type NotificationSignal = {
73
+ userId: number;
74
+ id: number;
75
+ };
76
+ /**
77
+ * Holds one database connection that LISTENs for committed notifications and
78
+ * calls onSignal for each. Reconnects after connection loss. Returns a stop function.
79
+ */
80
+ export declare function listenForNotifications(db: Knex, onSignal: (signal: NotificationSignal) => void, options?: {
81
+ retryMs?: number;
82
+ onError?: (error: unknown) => void;
83
+ }): () => Promise<void>;