adula 2.1.0 → 2.3.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.
- package/README.md +149 -18
- package/build/agent/AGENTS.template.md +4 -4
- package/build/agent/capabilities.md +22 -12
- package/build/agent/skills/adula-frontend-design/SKILL.md +6 -4
- package/build/agent/skills/idea-review/SKILL.md +2 -2
- package/build/commands/adula_assistant_prune.d.ts +10 -0
- package/build/commands/adula_assistant_prune.js +12 -0
- package/build/commands/adula_outbox.d.ts +10 -0
- package/build/commands/adula_outbox.js +11 -0
- package/build/commands/adula_restore_reconcile.d.ts +10 -0
- package/build/commands/adula_restore_reconcile.js +34 -0
- package/build/commands/adula_runtime_health.d.ts +10 -0
- package/build/commands/adula_runtime_health.js +27 -0
- package/build/commands/adula_uploads_prune.d.ts +10 -0
- package/build/commands/adula_uploads_prune.js +16 -0
- package/build/commands/app.d.ts +10 -0
- package/build/commands/app.js +64 -0
- package/build/commands/backup_create.d.ts +11 -0
- package/build/commands/backup_create.js +99 -0
- package/build/commands/backup_open.d.ts +16 -0
- package/build/commands/backup_open.js +48 -0
- package/build/commands/backup_restore_files.d.ts +11 -0
- package/build/commands/backup_restore_files.js +44 -0
- package/build/commands/backup_restore_test.d.ts +12 -0
- package/build/commands/backup_restore_test.js +188 -0
- package/build/commands/backup_seal.d.ts +12 -0
- package/build/commands/backup_seal.js +36 -0
- package/build/commands/backup_services.d.ts +33 -0
- package/build/commands/backup_services.js +6 -0
- package/build/commands/backup_verify.d.ts +9 -0
- package/build/commands/backup_verify.js +59 -0
- package/build/commands/backup_verify_snapshot.d.ts +10 -0
- package/build/commands/backup_verify_snapshot.js +37 -0
- package/build/commands/client.d.ts +16 -0
- package/build/commands/client.js +71 -0
- package/build/commands/doctor.js +21 -1
- package/build/commands/install.d.ts +8 -0
- package/build/commands/install.js +69 -45
- package/build/commands/main.d.ts +3 -2
- package/build/commands/main.js +32 -0
- package/build/commands/module_add.js +4 -20
- package/build/commands/resource.d.ts +2 -0
- package/build/commands/resource.js +12 -3
- package/build/commands/resource_migration.d.ts +15 -0
- package/build/commands/resource_migration.js +81 -0
- package/build/commands/resource_snapshot.d.ts +2 -0
- package/build/commands/resource_snapshot.js +21 -4
- package/build/commands/sla_evaluate.d.ts +14 -0
- package/build/commands/sla_evaluate.js +16 -0
- package/build/commands/ui.js +4 -2
- package/build/commands/ui_css.d.ts +9 -0
- package/build/commands/ui_css.js +19 -0
- package/build/commands/upgrade.d.ts +1 -1
- package/build/commands/upgrade.js +1 -1
- package/build/configure.js +1 -1
- package/build/database/migrations/1770000000020_two_factor.d.ts +5 -0
- package/build/database/migrations/1770000000020_two_factor.js +10 -0
- package/build/database/migrations/1770000000041_import_modes.d.ts +5 -0
- package/build/database/migrations/1770000000041_import_modes.js +10 -0
- package/build/database/migrations/1770000000042_sync_jobs.d.ts +5 -0
- package/build/database/migrations/1770000000042_sync_jobs.js +10 -0
- package/build/database/migrations/1770000000043_notification_channels.d.ts +5 -0
- package/build/database/migrations/1770000000043_notification_channels.js +10 -0
- package/build/database/migrations/1770000000044_channel_confirmations.d.ts +5 -0
- package/build/database/migrations/1770000000044_channel_confirmations.js +10 -0
- package/build/database/migrations/1770000000045_import_leases.d.ts +5 -0
- package/build/database/migrations/1770000000045_import_leases.js +10 -0
- package/build/database/migrations/1770000000046_workflow_delegation_sla.d.ts +5 -0
- package/build/database/migrations/1770000000046_workflow_delegation_sla.js +10 -0
- package/build/database/migrations/1770000000049_print_templates.d.ts +5 -0
- package/build/database/migrations/1770000000049_print_templates.js +10 -0
- package/build/database/migrations/1770000000051_comment_notifications.d.ts +5 -0
- package/build/database/migrations/1770000000051_comment_notifications.js +10 -0
- package/build/database/migrations/1770000000054_cloud_backups.d.ts +5 -0
- package/build/database/migrations/1770000000054_cloud_backups.js +10 -0
- package/build/database/migrations/1770000000055_ai_assistant.d.ts +5 -0
- package/build/database/migrations/1770000000055_ai_assistant.js +10 -0
- package/build/database/migrations/1770000000056_appearance.d.ts +5 -0
- package/build/database/migrations/1770000000056_appearance.js +10 -0
- package/build/index.d.ts +87 -11
- package/build/index.js +50 -7
- package/build/providers/adula_provider.d.ts +2 -0
- package/build/providers/adula_provider.js +7 -0
- package/build/src/admin/contracts.js +1 -1
- package/build/src/admin/controller.d.ts +14 -1
- package/build/src/admin/controller.js +91 -13
- package/build/src/admin/errors.d.ts +32 -0
- package/build/src/admin/errors.js +63 -1
- package/build/src/admin/presentation.d.ts +21 -2
- package/build/src/admin/resource/editor.d.ts +60 -0
- package/build/src/admin/resource/editor.js +345 -0
- package/build/src/admin/resource/export.d.ts +54 -0
- package/build/src/admin/resource/export.js +262 -0
- package/build/src/admin/resource/lifecycle.d.ts +23 -0
- package/build/src/admin/resource/lifecycle.js +91 -0
- package/build/src/admin/resource/query.d.ts +111 -0
- package/build/src/admin/resource/query.js +595 -0
- package/build/src/admin/resource/read.d.ts +109 -0
- package/build/src/admin/resource/read.js +388 -0
- package/build/src/admin/resource/shared.d.ts +93 -0
- package/build/src/admin/resource/shared.js +265 -0
- package/build/src/admin/resource/trash.d.ts +10 -0
- package/build/src/admin/resource/trash.js +56 -0
- package/build/src/admin/resource/write.d.ts +57 -0
- package/build/src/admin/resource/write.js +603 -0
- package/build/src/admin/resource_service.d.ts +80 -193
- package/build/src/admin/resource_service.js +81 -1343
- package/build/src/admin/resource_tools.d.ts +111 -0
- package/build/src/admin/resource_tools.js +139 -0
- package/build/src/ai/assistant.d.ts +100 -0
- package/build/src/ai/assistant.js +487 -0
- package/build/src/ai/client.d.ts +49 -0
- package/build/src/ai/client.js +85 -0
- package/build/src/ai/prompt.d.ts +23 -0
- package/build/src/ai/prompt.js +83 -0
- package/build/src/ai/settings.d.ts +56 -0
- package/build/src/ai/settings.js +214 -0
- package/build/src/ai/usage.d.ts +16 -0
- package/build/src/ai/usage.js +33 -0
- package/build/src/appearance/appearance.d.ts +134 -0
- package/build/src/appearance/appearance.js +461 -0
- package/build/src/appearance/colors.d.ts +43 -0
- package/build/src/appearance/colors.js +99 -0
- package/build/src/appearance/logo.d.ts +32 -0
- package/build/src/appearance/logo.js +112 -0
- package/build/src/attachments/attachment_service.d.ts +46 -2
- package/build/src/attachments/attachment_service.js +96 -4
- package/build/src/auth/actor_store.d.ts +5 -1
- package/build/src/auth/actor_store.js +8 -4
- package/build/src/auth/conditions.d.ts +5 -0
- package/build/src/auth/conditions.js +26 -3
- package/build/src/auth/sql.js +17 -5
- package/build/src/auth/two_factor.d.ts +96 -0
- package/build/src/auth/two_factor.js +259 -0
- package/build/src/backups/archive.d.ts +52 -0
- package/build/src/backups/archive.js +362 -0
- package/build/src/backups/cloud_backups.d.ts +133 -0
- package/build/src/backups/cloud_backups.js +650 -0
- package/build/src/backups/doctor.d.ts +7 -0
- package/build/src/backups/doctor.js +55 -0
- package/build/src/backups/providers.d.ts +81 -0
- package/build/src/backups/providers.js +470 -0
- package/build/src/collaboration/assignments.d.ts +59 -2
- package/build/src/collaboration/assignments.js +196 -74
- package/build/src/collaboration/record_collaboration.d.ts +21 -4
- package/build/src/collaboration/record_collaboration.js +126 -51
- package/build/src/collaboration/shared.d.ts +24 -0
- package/build/src/collaboration/shared.js +34 -0
- package/build/src/commands/app_scaffold.d.ts +72 -0
- package/build/src/commands/app_scaffold.js +285 -0
- package/build/src/commands/capabilities.js +35 -9
- package/build/src/commands/doctor.d.ts +24 -2
- package/build/src/commands/doctor.js +81 -6
- package/build/src/commands/gap_report.d.ts +1 -1
- package/build/src/commands/gap_report.js +2 -2
- package/build/src/commands/generator.d.ts +37 -1
- package/build/src/commands/generator.js +61 -18
- package/build/src/commands/snapshot.d.ts +24 -13
- package/build/src/commands/snapshot.js +54 -14
- package/build/src/commands/source_markers.d.ts +10 -0
- package/build/src/commands/source_markers.js +29 -0
- package/build/src/core/activity.d.ts +2 -0
- package/build/src/core/activity.js +7 -1
- package/build/src/core/administrators.d.ts +38 -0
- package/build/src/core/administrators.js +145 -0
- package/build/src/core/avatar_image.d.ts +33 -0
- package/build/src/core/avatar_image.js +278 -0
- package/build/src/core/html_sanitizer.d.ts +20 -0
- package/build/src/core/html_sanitizer.js +261 -0
- package/build/src/core/like.d.ts +5 -0
- package/build/src/core/like.js +5 -0
- package/build/src/core/lookups.d.ts +80 -0
- package/build/src/core/lookups.js +319 -0
- package/build/src/core/mail_settings.d.ts +83 -0
- package/build/src/core/mail_settings.js +274 -0
- package/build/src/core/mail_test.d.ts +16 -0
- package/build/src/core/mail_test.js +81 -6
- package/build/src/core/message_templates.d.ts +15 -2
- package/build/src/core/message_templates.js +81 -11
- package/build/src/core/module_seed.js +2 -1
- package/build/src/core/notification_channels.d.ts +235 -0
- package/build/src/core/notification_channels.js +660 -0
- package/build/src/core/roles.js +26 -9
- package/build/src/core/saved_views.d.ts +8 -1
- package/build/src/core/saved_views.js +91 -26
- package/build/src/core/sequences.d.ts +32 -0
- package/build/src/core/sequences.js +97 -0
- package/build/src/core/settings.d.ts +5 -0
- package/build/src/core/settings.js +31 -3
- package/build/src/core/template_language.d.ts +61 -0
- package/build/src/core/template_language.js +141 -0
- package/build/src/core/ui_preferences.d.ts +10 -0
- package/build/src/core/ui_preferences.js +15 -1
- package/build/src/core/user_avatars.d.ts +79 -0
- package/build/src/core/user_avatars.js +186 -0
- package/build/src/core/user_invitations.d.ts +5 -1
- package/build/src/core/user_invitations.js +7 -1
- package/build/src/core/user_preferences.d.ts +36 -0
- package/build/src/core/user_preferences.js +125 -0
- package/build/src/core/users.d.ts +2 -0
- package/build/src/core/users.js +5 -3
- package/build/src/database/calendar_days.d.ts +19 -0
- package/build/src/database/calendar_days.js +36 -0
- package/build/src/database/schema.d.ts +201 -2
- package/build/src/database/schema.js +713 -59
- package/build/src/database/schema_diff.d.ts +70 -0
- package/build/src/database/schema_diff.js +190 -0
- package/build/src/events/record_mutation.d.ts +2 -1
- package/build/src/events/record_mutation.js +1 -0
- package/build/src/integrations/api_client.d.ts +37 -0
- package/build/src/integrations/api_client.js +567 -0
- package/build/src/integrations/import_adapters.d.ts +37 -0
- package/build/src/integrations/import_adapters.js +35 -0
- package/build/src/integrations/imports.d.ts +130 -16
- package/build/src/integrations/imports.js +434 -73
- package/build/src/integrations/openapi.d.ts +3 -1
- package/build/src/integrations/openapi.js +465 -31
- package/build/src/integrations/outbound.d.ts +94 -0
- package/build/src/integrations/outbound.js +276 -0
- package/build/src/integrations/print.d.ts +22 -1
- package/build/src/integrations/print.js +68 -22
- package/build/src/integrations/print_templates.d.ts +216 -0
- package/build/src/integrations/print_templates.js +1017 -0
- package/build/src/integrations/sync_jobs.d.ts +139 -0
- package/build/src/integrations/sync_jobs.js +416 -0
- package/build/src/integrations/webhooks.d.ts +12 -12
- package/build/src/integrations/webhooks.js +34 -43
- package/build/src/integrations/xlsx.d.ts +41 -0
- package/build/src/integrations/xlsx.js +519 -0
- package/build/src/languages/ar.d.ts +11 -0
- package/build/src/languages/ar.js +358 -0
- package/build/src/languages/ar_ui.d.ts +461 -0
- package/build/src/languages/ar_ui.js +464 -0
- package/build/src/languages/catalog.d.ts +66 -0
- package/build/src/languages/catalog.js +152 -0
- package/build/src/languages/en.d.ts +7 -0
- package/build/src/languages/en.js +352 -0
- package/build/src/languages/en_ui.d.ts +3 -0
- package/build/src/languages/en_ui.js +458 -0
- package/build/src/languages/validation.d.ts +26 -0
- package/build/src/languages/validation.js +60 -0
- package/build/src/lists/bulk_actions.d.ts +89 -0
- package/build/src/lists/bulk_actions.js +268 -0
- package/build/src/lists/dashboards.d.ts +138 -0
- package/build/src/lists/dashboards.js +290 -0
- package/build/src/mcp/tools.js +9 -104
- package/build/src/resource/define_resource.d.ts +18 -1
- package/build/src/resource/define_resource.js +212 -18
- package/build/src/resource/definition.d.ts +44 -0
- package/build/src/resource/definition.js +171 -0
- package/build/src/resource/registry.js +15 -4
- package/build/src/resource/types.d.ts +313 -16
- package/build/src/resource/values.d.ts +56 -1
- package/build/src/resource/values.js +237 -5
- package/build/src/services/settings.d.ts +2 -0
- package/build/src/services/settings.js +5 -1
- package/build/src/upgrade/legacy.js +2 -2
- package/build/src/workflows/calendar.d.ts +9 -0
- package/build/src/workflows/calendar.js +44 -0
- package/build/src/workflows/define_workflow.d.ts +48 -3
- package/build/src/workflows/define_workflow.js +57 -13
- package/build/src/workflows/delegations.d.ts +107 -0
- package/build/src/workflows/delegations.js +326 -0
- package/build/src/workflows/engine.d.ts +80 -4
- package/build/src/workflows/engine.js +466 -86
- package/build/src/workflows/sla.d.ts +15 -0
- package/build/src/workflows/sla.js +8 -0
- package/build/stubs/resource_contract.txt +12 -1
- package/package.json +9 -2
package/README.md
CHANGED
|
@@ -1,26 +1,159 @@
|
|
|
1
1
|
# adula
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
3
|
+
<div dir="rtl" lang="ar">
|
|
4
|
+
|
|
5
|
+
**أدولا (AdulaJS)** إطار عمل عربي أولًا لبناء أنظمة الأعمال. تنشئ كل شركة **نظامًا** واحدًا، وفي داخله **تطبيقات** لكل مجال عمل، مثل الإجازات أو الأصول أو الصيانة. تتشارك التطبيقات المستخدمين والأدوار والهيكل التنظيمي والإشعارات وصندوق المهام.
|
|
6
|
+
|
|
7
|
+
تكتب تعريف المورد (الجدول وحقوله) مرة واحدة في ملف واحد، فيُبنى منه تلقائيًا كل ما يلي:
|
|
8
|
+
|
|
9
|
+
• أعمدة قاعدة البيانات وترحيلاتها (ملفات تغيير بنية الجداول).
|
|
10
|
+
|
|
11
|
+
• التحقق من صحة كل إدخال.
|
|
12
|
+
|
|
13
|
+
• نماذج الإدخال وصفحات القوائم والعرض باتجاه من اليمين إلى اليسار.
|
|
14
|
+
|
|
15
|
+
• واجهة برمجة التطبيقات (API) ووصفها بمعيار OpenAPI.
|
|
16
|
+
|
|
17
|
+
• الصلاحيات حسب الدور والوحدة التنظيمية.
|
|
18
|
+
|
|
19
|
+
هذه الحزمة هي نواة الإطار. لإنشاء نظام جديد استخدم الأمر `npm create adulajs`.
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
|
|
23
|
+
`adula` is the core of AdulaJS, a resource framework for business systems on AdonisJS 7 and
|
|
24
|
+
PostgreSQL 17. One `defineResource` file decides a table's columns, validation, forms,
|
|
25
|
+
pages, API and authorization, and the package adds workflows, approvals, lists, dashboards,
|
|
26
|
+
imports and integration on top.
|
|
27
|
+
|
|
28
|
+
Node.js 24 or later. MIT licensed. The public API in `api/adula-api.json` follows semantic
|
|
29
|
+
versioning; published versions are listed in the
|
|
30
|
+
[releases](https://github.com/adulash/adulajs/blob/main/docs/releases.md) and the
|
|
31
|
+
[changelog](https://github.com/adulash/adulajs/blob/main/CHANGELOG.md).
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
npm create adulajs my-system
|
|
37
|
+
cd my-system
|
|
38
|
+
node ace adula:app leave_requests --label-ar="طلبات الإجازة" --label-en="Leave requests"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`create-adulajs` builds a complete system (AdonisJS host, sign-in, administration, the
|
|
42
|
+
Arabic UI, PostgreSQL and Redis); `adula:app` adds an application to it. A resource is one
|
|
43
|
+
file under `app/modules/<module>/resources/`:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { defineResource } from 'adula'
|
|
47
|
+
|
|
48
|
+
export default defineResource({
|
|
49
|
+
name: 'leave_requests',
|
|
50
|
+
label: { ar: 'طلبات الإجازة', en: 'Leave requests' },
|
|
51
|
+
recordLabel: { ar: 'طلب إجازة', en: 'Leave request' },
|
|
52
|
+
scoped: true,
|
|
53
|
+
submittable: true,
|
|
54
|
+
fields: {
|
|
55
|
+
title: { type: 'string', required: true, searchable: true, label: { ar: 'موضوع الطلب' } },
|
|
56
|
+
employee: { type: 'user', required: true, label: { ar: 'الموظف' } },
|
|
57
|
+
leaveType: {
|
|
58
|
+
type: 'enum',
|
|
59
|
+
required: true,
|
|
60
|
+
default: 'annual',
|
|
61
|
+
filterable: true,
|
|
62
|
+
options: [
|
|
63
|
+
{ value: 'annual', label: { ar: 'سنوية' } },
|
|
64
|
+
{ value: 'sick', label: { ar: 'مرضية' } },
|
|
65
|
+
],
|
|
66
|
+
label: { ar: 'نوع الإجازة' },
|
|
67
|
+
},
|
|
68
|
+
startDate: { type: 'date', required: true, label: { ar: 'تاريخ البداية' } },
|
|
69
|
+
days: { type: 'decimal', scale: 1, required: true, label: { ar: 'عدد الأيام' } },
|
|
70
|
+
medicalCertificate: {
|
|
71
|
+
type: 'attachment',
|
|
72
|
+
visibleWhen: { leaveType: 'sick' },
|
|
73
|
+
label: { ar: 'التقرير الطبي' },
|
|
74
|
+
},
|
|
75
|
+
},
|
|
76
|
+
// Names the record in pickers, "My tasks" and approvals.
|
|
77
|
+
title: ['title'],
|
|
78
|
+
list: ['title', 'employee', 'leaveType', 'startDate', 'days'],
|
|
79
|
+
form: ['title', 'employee', 'leaveType', 'startDate', 'days', 'medicalCertificate'],
|
|
80
|
+
show: ['title', 'employee', 'leaveType', 'startDate', 'days', 'medicalCertificate'],
|
|
81
|
+
actions: ['view', 'create', 'update', 'delete', 'submit', 'cancel', 'amend'],
|
|
82
|
+
})
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The [leave-requests tutorial](https://github.com/adulash/adulajs/blob/main/docs/tutorial-leave-requests.md)
|
|
86
|
+
builds this application end to end: migrations, roles, an approval workflow with delegation
|
|
87
|
+
and SLA, list filters, saved views and a dashboard.
|
|
88
|
+
|
|
89
|
+
## Features
|
|
90
|
+
|
|
91
|
+
* **Definition as the source of truth** (ADR 045). Field types `string`, `text`, `email`,
|
|
92
|
+
`phone`, `url`, `integer`, `money`, `decimal`, `percent`, `boolean`, `date`, `datetime`,
|
|
93
|
+
`json`, `enum`, `multiSelect`, `lookup`, `belongsTo`, `user`, `attachment`, `hasMany`
|
|
94
|
+
(inline child rows) and `manyToMany`; constraints, defaults, `visibleWhen`, unique
|
|
95
|
+
combinations. `adula:resource:migration` writes the additive migration a table lacks and
|
|
96
|
+
`adula:doctor` reports drift.
|
|
97
|
+
* **Authorization.** CASL role rules with conditions and field levels, organizational scope
|
|
98
|
+
over an org tree, and the same rules in every list, export, API call and dashboard.
|
|
99
|
+
* **Documents and workflows.** Draft, submit, cancel and amend-by-copy; versioned workflows
|
|
100
|
+
with condition, update, notify, approval, decision, delay, HTTP and end steps; approval
|
|
101
|
+
delegation while out of office; SLA deadlines with reminders and escalation (ADR 044).
|
|
102
|
+
* **Lists.** Range, multi-value and empty filters, saved views, filtered CSV export, bulk
|
|
103
|
+
actions, deleted records and restore, and dashboards computed as the viewer (ADR 046).
|
|
104
|
+
* **Files and printing.** One or several files per attachment field, with in-page preview of
|
|
105
|
+
images, PDF and text (ADR 047); print templates in code or written by administrators, printed
|
|
106
|
+
as HTML or PDF with the reader's permissions (ADR 048).
|
|
107
|
+
* **Collaboration.** Comments with mentions, followers, tags, field history, assignments and
|
|
108
|
+
one "my tasks" inbox, notifications by template with e-mail, realtime updates, SMS or
|
|
109
|
+
WhatsApp through a signed HTTP provider.
|
|
110
|
+
* **Integration.** A Bearer-token API under `/api/v1` with an OpenAPI document and a generated
|
|
111
|
+
TypeScript client, signed outgoing and inbound webhooks, CSV imports (dry run, upsert),
|
|
112
|
+
sync jobs, and an optional MCP adapter.
|
|
113
|
+
* **Sign-in.** Optional SSO through Google, GitHub and Microsoft Entra ID, and TOTP two-factor
|
|
114
|
+
authentication with recovery codes, which administrators can be required to use (ADR 042).
|
|
115
|
+
* **Arabic first.** Arabic is the base language of every screen and message; English and
|
|
116
|
+
other languages are optional per system (ADR 041).
|
|
117
|
+
* **Operations.** Outbox worker, scheduler, backups with restore drills, upload pruning,
|
|
118
|
+
runtime health, and `adula:doctor`.
|
|
119
|
+
|
|
120
|
+
## Documentation
|
|
121
|
+
|
|
122
|
+
| Topic | Guide |
|
|
123
|
+
| --- | --- |
|
|
124
|
+
| Create a system | [Installation](https://github.com/adulash/adulajs/blob/main/docs/installation.md) |
|
|
125
|
+
| Build an application step by step | [Leave-requests tutorial](https://github.com/adulash/adulajs/blob/main/docs/tutorial-leave-requests.md) |
|
|
126
|
+
| Applications in a system | [Applications](https://github.com/adulash/adulajs/blob/main/docs/applications.md) |
|
|
127
|
+
| Fields, validation, migrations | [Resource definitions](https://github.com/adulash/adulajs/blob/main/docs/resources.md), [defineResource reference](https://github.com/adulash/adulajs/blob/main/docs/reference/define-resource.md) |
|
|
128
|
+
| Workflows, lists, collaboration, printing | [Business features](https://github.com/adulash/adulajs/blob/main/docs/business-features.md) |
|
|
129
|
+
| Sign-in, SSO, two-factor | [Authentication](https://github.com/adulash/adulajs/blob/main/docs/authentication.md) |
|
|
130
|
+
| API client, imports, sync jobs, webhooks | [Integration](https://github.com/adulash/adulajs/blob/main/docs/integration.md) |
|
|
131
|
+
| Languages | [Languages](https://github.com/adulash/adulajs/blob/main/docs/languages.md) |
|
|
132
|
+
| Deploy, back up, restore | [Operations](https://github.com/adulash/adulajs/blob/main/docs/operations.md) |
|
|
133
|
+
| What exists, what is missing | [Implementation status](https://github.com/adulash/adulajs/blob/main/docs/implementation-status.md), [Gaps](https://github.com/adulash/adulajs/blob/main/GAPS.md) |
|
|
134
|
+
| Why a design was chosen | [Architecture decisions](https://github.com/adulash/adulajs/tree/main/docs/decisions) |
|
|
135
|
+
|
|
136
|
+
## Install into an existing AdonisJS application
|
|
137
|
+
|
|
138
|
+
Follow the canonical [installation guide](https://github.com/adulash/adulajs/blob/main/docs/installation.md). For a new system, the separate `create-adulajs` initializer (`npm create adulajs my-system`) installs the AdonisJS host and system screens from an empty directory. For an existing official AdonisJS 7 React/PostgreSQL application, install the core/UI archives and documented UI prerequisites, configure AdulaJS, migrate and create the intended administrator before `node ace adula:install`. The Ace command completes initialization inside that host. No educational customers/orders/tasks modules are installed by either path.
|
|
8
139
|
|
|
9
140
|
The managed rules require the bundled `.agents/skills/adula-frontend-design/SKILL.md` for UI work. It is tailored to business workflows, asks for missing company identity at project kickoff, and uses project-owned shadcn components with modal forms and record details by default. User-requested presentation exceptions remain supported. Company identity belongs in `docs/design-identity.md`, which installation never overwrites. Doctor verifies the design skill along with the idea-review skill.
|
|
10
141
|
|
|
11
142
|
## Contracts
|
|
12
143
|
|
|
13
|
-
`defineResource` declares fields, forms, serialization, actions and scope. `ResourceRegistry` validates module ownership and dependencies. `ResourceService` applies CASL and organizational scope to JSON operations, serialization, editor options and atomic inline reconciliation. Money is a canonical string of integer minor units within PostgreSQL bigint range; calendar dates are YYYY-MM-DD; timestamps are canonical UTC ISO strings with milliseconds. Versioned updates require the current version and stale writes return 409.
|
|
144
|
+
`defineResource` declares fields, forms, serialization, actions and scope, and is the source of truth (ADR 045): without a `validator`, writes use the VineJS validator derived from the fields (`definitionValidator`; extend it through `definitionSchema`), every stored value is checked against its field again (422 `E_FIELD_VALUE`), `model` is optional and never read, and `resourceSchema` gives the expected table that `createResourceTable` builds and `adula:doctor` (`resources.schema`) compares with the database. Field types, props and resource options are listed in the [resource definitions guide](https://github.com/adulash/adulajs/blob/main/docs/resources.md) and the [defineResource reference](https://github.com/adulash/adulajs/blob/main/docs/reference/define-resource.md). `@vinejs/vine` ^4.0.0 is a peer dependency. `ResourceRegistry` validates module ownership and dependencies. `ResourceService` applies CASL and organizational scope to JSON operations, serialization, editor options and atomic inline reconciliation. Money is a canonical string of integer minor units within PostgreSQL bigint range; decimal and percent values are decimal strings with the field's scale; calendar dates are YYYY-MM-DD (the provider registers a DATE parser so every PostgreSQL query returns that text); timestamps are canonical UTC ISO strings with milliseconds. Versioned updates require the current version and stale writes return 409.
|
|
14
145
|
|
|
15
146
|
Use `buildAbility(rules, registry.all())` for schema-aware money conditions. The SQL adapter rejects ordered money predicates without schemas. Browser code may import the same matcher through `adula/auth`. Organizational restrictions remain a separate AND condition.
|
|
16
147
|
|
|
17
|
-
|
|
148
|
+
`defineWorkflow` declares versioned workflows that `WorkflowEngine` runs from the step table (ADR 044); `WorkflowDefinition.machine` is deprecated and, with the `xstate` dependency, leaves in the next major version. `WorkflowDelegations` manages out-of-office delegation, and the `sla:evaluate` command runs SLA reminders and escalations. `defineDashboard`/`Dashboards`, `defineBulkActions`/`BulkActions` and `SavedViews` form the list layer (ADR 046).
|
|
149
|
+
|
|
150
|
+
Other exports include `ActorStore`, schema helpers, organizational moves, settings, sequences, notifications, jobs/outbox interfaces, packed rules, `TwoFactor`, `defineSyncJob`, the API client generator and the generic controller factory. Commands include `adula:app` (an application: module, example resource, default roles and a smoke test), `adula:resource` (`--validator` and `--model` opt in to those files), `adula:resource:migration` (an additive migration of the columns, join tables and unique indexes a table lacks, applied with `alterResourceTable`), the deprecated `adula:resource:snapshot`, `adula:install`, `adula:doctor`, `adula:module:add`, `adula:module:remove`, `adula:ui add`, `adula:client`, `sla:evaluate` and `adula:capabilities`.
|
|
18
151
|
|
|
19
152
|
The optional `adula/mcp` entry exports `createResourceTools`. Install @jrmc/adonis-mcp 2.0.0 and supply an authenticated actor resolver. Cookie-authenticated MCP routes must keep CSRF protection enabled. Tool inputs cannot supply identity or organizational scope.
|
|
20
153
|
|
|
21
154
|
## Generated HTTP contracts
|
|
22
155
|
|
|
23
|
-
Generated tests call the copied `resourceContract(name, fixture)` helper. Extend the application-owned fixture whenever fields or validation change. Supply `input` and a valid `update`, plus `expected` and `updated` values after normalization. Every form field needs an input fixture; every written scalar needs a storage expectation. Use `stored`/`updatedStored` for writable fields excluded from the response, and `inline`/`updatedInline` for the complete live child rows in ID order. Dates use YYYY-MM-DD, timestamps canonical UTC strings, and money integer-minor-unit strings in expectations. Fixture callbacks receive `userId`, `orgUnitId` and a unique suffix for creating real related records.
|
|
156
|
+
Generated tests call the copied `resourceContract(name, fixture)` helper. Extend the application-owned fixture whenever fields or validation change. Supply `input` and a valid `update`, plus `expected` and `updated` values after normalization. Every form field needs an input fixture; every written scalar needs a storage expectation, and every manyToMany field the ascending list of linked ids. Use `stored`/`updatedStored` for writable fields excluded from the response, and `inline`/`updatedInline` for the complete live child rows in ID order. Dates use YYYY-MM-DD, timestamps canonical UTC strings, and money integer-minor-unit strings in expectations. Fixture callbacks receive `userId`, `orgUnitId` and a unique suffix for creating real related records.
|
|
24
157
|
|
|
25
158
|
The harness creates database-backed roles and organization memberships, checks existing-record isolation across reads and writes, central-resource visibility, serialization, mapped storage, forbidden fields, stale versions, unique constraints and soft deletion. It refuses non-test databases. Configuration preserves existing copied helpers: consumers with the old one-argument helper must review and merge the new template before generating tests that use fixtures.
|
|
26
159
|
|
|
@@ -28,14 +161,12 @@ Doctor measures the deployment's `storage/uploads` directory and warns above 5 d
|
|
|
28
161
|
|
|
29
162
|
## Current limitations
|
|
30
163
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
human security review is deferred to 2.0 (ADR 027).
|
|
39
|
-
- XLSX import is not available (GAP-006); CSV is.
|
|
164
|
+
* Impersonation was reviewed by automated adversarial and black-box tests only, not by
|
|
165
|
+
a human security review; two-factor authentication has had no written human ASVS review
|
|
166
|
+
yet.
|
|
167
|
+
* XLSX import is not available; CSV is (format adapters are the registration point).
|
|
168
|
+
* SLA hours are wall-clock hours (no business calendar) and an overdue step escalates once.
|
|
169
|
+
* Dashboards are defined in code and show tiles and ranked bars; there are no time-series
|
|
170
|
+
charts.
|
|
40
171
|
|
|
41
|
-
See [implementation status](https://github.com/adulash/adulajs/blob/main/docs/implementation-status.md)
|
|
172
|
+
See [implementation status](https://github.com/adulash/adulajs/blob/main/docs/implementation-status.md) and [gaps](https://github.com/adulash/adulajs/blob/main/GAPS.md).
|
|
@@ -6,9 +6,9 @@ A plugin is just code that has not been written yet. No abstraction before the s
|
|
|
6
6
|
|
|
7
7
|
Structure
|
|
8
8
|
|
|
9
|
-
1. One system.
|
|
10
|
-
2. Generate the resource scaffold with adula:resource and follow its typed definition. Reuse an existing project resource when available; never assume educational
|
|
11
|
-
3. New entity: `node ace adula:resource <name> --module=<module>`, then fill the fields.
|
|
9
|
+
1. One system per company. Each business area (assets, maintenance, HR …) is an application implemented as a module in app/modules/<module>, and every entity lives in one of them. Applications share users, roles, the organisation tree, notifications and the task inbox; never create a separate deployment per application.
|
|
10
|
+
2. Generate the resource scaffold with adula:resource and follow its typed definition. Reuse an existing project resource when available; never assume educational applications are installed.
|
|
11
|
+
3. New application: `node ace adula:app <name> --label-ar=<Arabic label>` (module, example resource, default roles, smoke test). New entity in an application: `node ace adula:resource <name> --module=<module>`, then fill the fields.
|
|
12
12
|
4. Before creating an entity, check the registry. Same meaning exists → belongsTo. Never duplicate a table.
|
|
13
13
|
5. A module writes only its own tables; dependency direction follows start/modules.ts, never backwards.
|
|
14
14
|
6. Modules talk through events, never by importing each other's controllers. Heavy listeners go to jobs.
|
|
@@ -20,7 +20,7 @@ Security 10. Every route passes the authorize middleware. Every transformer uses
|
|
|
20
20
|
|
|
21
21
|
UI 13. Before designing or changing any interface, read and apply `.agents/skills/adula-frontend-design/SKILL.md` (AdulaJS's bundled frontend-design skill for business applications). At project kickoff, request the company's identity before the first design: name, logo, colors, fonts and brand guidelines when available. Reuse supplied identity, ask only for missing information, and preserve it in project-owned docs/design-identity.md. Fill the resource definition before writing a page. Override only via pages/<resource>/. 14. Compose interfaces from the project-owned shadcn/ui components in inertia/components/ui/. Use Button, Input, Select, Table, Card and the other registry primitives instead of hand-styled native controls or homemade equivalents. Semantic HTML for structure, text and form submission is allowed. Add components only via `node ace adula:ui add`, never `shadcn add`. 15. All forms (including create/edit) and row/record detail views use shadcn Dialog (modal) by default. Use ResourceSurface for resource forms/details; do not choose a standalone page, Sheet or custom overlay unless the user explicitly requests that alternative. View dialogs close on outside click; edit dialogs ask before closing by default. Honor system preferences for Gregorian, Hijri or both calendars and reduced motion. RTL by default; Arabic labels; English identifiers. Installation terminal instructions are English. Preserve explicit user exceptions and project-owned customizations.
|
|
22
22
|
|
|
23
|
-
Boundaries 16. Never modify node_modules/adula or node_modules/@adula, and never use patch-package (enforced by lint). Do not re-implement an AdulaJS service under another name (checked in review). 17. A limitation is recorded in GAPS.md (template inside) and reported to the developer — never worked around. Describe the AdulaJS capability, not this project, and reproduce it on a new
|
|
23
|
+
Boundaries 16. Never modify node_modules/adula or node_modules/@adula, and never use patch-package (enforced by lint). Do not re-implement an AdulaJS service under another name (checked in review). 17. A limitation is recorded in GAPS.md (template inside) and reported to the developer — never worked around. Describe the AdulaJS capability, not this project, and reproduce it on a new system from create-adulajs. The developer submits it through the prefilled form link printed by `node ace adula:gaps report`, then records `Issue: #<number>`; never open AdulaJS issues through the API. 18. Only packages already in package.json. Ask before adding one. 19. New application (module) or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
|
|
24
24
|
<!-- adula:end -->
|
|
25
25
|
|
|
26
26
|
## Project rules
|
|
@@ -1,28 +1,36 @@
|
|
|
1
|
-
# AdulaJS capabilities (2.
|
|
1
|
+
# AdulaJS capabilities (2.3.0)
|
|
2
2
|
|
|
3
|
-
Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by AdulaJS.
|
|
3
|
+
Generated by `node ace adula:capabilities`. Read this before proposing an application (a module under app/modules); anything not listed here is not provided by AdulaJS.
|
|
4
4
|
|
|
5
5
|
## Resource definition
|
|
6
6
|
|
|
7
7
|
| Field type | Storage |
|
|
8
8
|
|---|---|
|
|
9
|
-
| string | varchar |
|
|
10
|
-
| text | text |
|
|
11
|
-
| integer | integer |
|
|
12
|
-
| money | bigint minor units, decimal string in JSON |
|
|
9
|
+
| string | varchar(255); min/max length, pattern, format email/url/phone |
|
|
10
|
+
| text | text; min/max length, pattern |
|
|
11
|
+
| integer | integer; min/max |
|
|
12
|
+
| money | bigint minor units, decimal string in JSON; min/max in minor units |
|
|
13
|
+
| decimal | numeric(precision 18, scale 2 by default); canonical decimal string ("12.50"); min/max |
|
|
14
|
+
| percent | numeric(precision 7, scale 2 by default); 12.5 means 12.5 %; min/max |
|
|
15
|
+
| email | varchar(254), trimmed and lower-cased |
|
|
16
|
+
| phone | varchar(32), stored as +?digits (7 to 15 digits) |
|
|
17
|
+
| url | varchar(2048), absolute http(s) URLs only |
|
|
18
|
+
| enum | varchar; one of options [{ value, label }] |
|
|
19
|
+
| multiSelect | jsonb array of option values in options order; min/max count; filter contains |
|
|
20
|
+
| manyToMany | join table <owner>_<key> (or table), array of target ids; targets must be viewable |
|
|
13
21
|
| boolean | boolean |
|
|
14
22
|
| date | date (YYYY-MM-DD) |
|
|
15
23
|
| datetime | timestamptz |
|
|
16
24
|
| json | jsonb |
|
|
17
|
-
| attachment | attachments row id; per-
|
|
25
|
+
| attachment | attachments row id; per-file accept/maxSize; multiple: true (max, default 10) stores an ordered jsonb array of ids; images, PDF and text preview inline |
|
|
18
26
|
| belongsTo | foreign key, preloaded, restrict on delete |
|
|
19
27
|
| user | users foreign key, restrict on delete; choices are active members of the record unit or its ancestors; related as { id, fullName } |
|
|
20
28
|
| hasMany | child resource; inline rows saved with the parent |
|
|
21
29
|
| lookup | lookups group key |
|
|
22
30
|
|
|
23
|
-
Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column.
|
|
31
|
+
Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column, default (create prefill, server default and column default), visibleWhen ({ sibling: value | values }; hidden fields are stored empty and not required), min / max (length, numeric limit or count), pattern (anchored RegExp source), format (string: email, url or phone), precision / scale (decimal, percent), options (enum, multiSelect), resource / table (manyToMany).
|
|
24
32
|
|
|
25
|
-
Resource options: scoped (required), scope.from (the unit follows a required belongsTo parent), title (fields that name the record in relations, pickers, tasks and approvals), submittable (docStatus, submit/cancel/amend-by-copy), version (optimistic locking, default with submittable),
|
|
33
|
+
Resource options: scoped (required), scope.from (the unit follows a required belongsTo parent), title (fields that name the record in relations, pickers, tasks and approvals), submittable (docStatus, submit/cancel/amend-by-copy), version (optimistic locking, default with submittable), unique (composite combinations of fields, partial over active rows), list / form / show / serialize / hidden, actions, hooks.beforeSave / hooks.afterSave, validator / model (optional: without validator a VineJS validator is derived from the fields).
|
|
26
34
|
|
|
27
35
|
Role rule conditions: $eq, $ne, $in, $lt, $gt, $like on scalar fields; unsupported conditions are refused. Organization scope is always added with AND. `$actor.id` names the signed-in user on user fields, createdBy and updatedBy ($eq, $ne, $in), bound per request.
|
|
28
36
|
|
|
@@ -32,9 +40,9 @@ Workflow steps: condition, update, notify, approval, decision, delay, http, end.
|
|
|
32
40
|
|
|
33
41
|
- **Resources and authorization:** `defineResource`, `ResourceRegistry`, `ResourceService`, `createResourceController`, `buildAbility`, `accessibleBy`, `ActorStore`, `packedResourceRules`
|
|
34
42
|
- **Records and collaboration:** `RecordCollaboration`, `followerListeners`, `Assignments`, `SavedViews`, `logActivity`
|
|
35
|
-
- **Documents and workflows:** `defineWorkflow`, `WorkflowEngine`, `workflowListeners`
|
|
43
|
+
- **Documents and workflows:** `defineWorkflow`, `WorkflowEngine`, `workflowListeners`, `WorkflowDelegations`
|
|
36
44
|
- **Notifications and messages:** `notify`, `notifyWithTemplate`, `MessageTemplates`, `deliverNotificationMail`, `listenForNotifications`, `NotificationsAdmin`
|
|
37
|
-
- **Integration:** `Webhooks`, `signWebhook`, `InboundWebhooks`, `openApiDocument`, `ImportBatches`, `renderPrintHtml`, `htmlToPdf`
|
|
45
|
+
- **Integration:** `Webhooks`, `signWebhook`, `InboundWebhooks`, `openApiDocument`, `apiClientSource`, `ImportBatches`, `xlsxImportAdapter`, `renderPrintHtml`, `htmlToPdf`
|
|
38
46
|
- **Security:** `UserInvitations`, `UsersAdmin`, `RolesAdmin`
|
|
39
47
|
- **Data and operations:** `sequence`, `Settings`, `SettingsAdmin`, `publishOutbox`, `consumeEvent`, `recordMutation`, `moveOrgUnit`, `migrateStorage`, `verifyBackup`, `runtimeHealth`
|
|
40
48
|
|
|
@@ -47,8 +55,11 @@ Workflow steps: condition, update, notify, approval, decision, delay, http, end.
|
|
|
47
55
|
- Create links with defaults: /resources/<resource>/create?defaults[field]=value
|
|
48
56
|
- Domain events <module>.<resource>.{created,updated,deleted,submitted,cancelled,amended} with idempotent listeners
|
|
49
57
|
- Module workflows (Module.workflows) with versioned definitions
|
|
58
|
+
- Approval delegation while out of office (WorkflowDelegations; never widens record access)
|
|
59
|
+
- Step SLA deadlines (sla: hours, dueSoonHours, escalate overdue | notify | reassign, to a recipient or { manager: roleKey }) evaluated by the sla:evaluate job
|
|
50
60
|
- Message templates edited per deployment
|
|
51
61
|
- Outgoing webhooks and the bearer-token /api/v1 API
|
|
62
|
+
- Typed API client of the bearer-token API: GET /api/v1/client.ts per token, or node ace adula:client into clients/<system>/
|
|
52
63
|
- Signed inbound webhooks raising inbound.<source>.<event> through the outbox
|
|
53
64
|
|
|
54
65
|
## Outside AdulaJS
|
|
@@ -57,4 +68,3 @@ Workflow steps: condition, update, notify, approval, decision, delay, http, end.
|
|
|
57
68
|
- Runtime plugins
|
|
58
69
|
- A visual workflow editor
|
|
59
70
|
- Multi-tenant SaaS in one database (one deployment per organization)
|
|
60
|
-
- XLSX import until a maintained parser passes the dependency rule (GAP-006)
|
|
@@ -25,12 +25,14 @@ Understand the user's task, the important action and the information hierarchy.
|
|
|
25
25
|
|
|
26
26
|
## Business application priorities
|
|
27
27
|
|
|
28
|
-
Optimize for repeated daily work: finding a record, understanding its status, entering accurate data and completing an authorized action. Use familiar layouts consistently across
|
|
28
|
+
Optimize for repeated daily work: finding a record, understanding its status, entering accurate data and completing an authorized action. Use familiar layouts consistently across applications. A marketing landing page, experimental typography, oversized hero section or ornamental animation is not the default for an operational screen.
|
|
29
29
|
|
|
30
30
|
- Tables: prioritize identifiers, meaningful names, status, dates and amounts. Align numeric values consistently, use tabular numerals, preserve searchable/filterable columns, and keep row actions predictable. Prefer useful density with readable spacing; do not replace comparable rows with decorative cards. Show totals or KPIs only when backed by actual data.
|
|
31
31
|
- Forms: group related fields, order them according to the business workflow, expose required fields and format hints, distinguish editable and read-only values, and place validation beside the affected field. Use sensible existing defaults, clear save/cancel actions and visible saving/success/conflict feedback. Keep inline document items within the parent transaction.
|
|
32
32
|
- Details: lead with the record identifier and current status, followed by the business facts, permitted next actions, related items and audit history when available. Do not expose hidden fields or use color as the only status indicator.
|
|
33
33
|
- Appearance: reuse the application's typography and design tokens, quiet surfaces, clear borders and a restrained accent for the primary action. Reserve warning/destructive colors for their actual meaning. Avoid gradients, decorative motion, arbitrary font changes and excess whitespace that slows scanning unless the user specifically requests them.
|
|
34
|
+
- Light and dark themes: every screen must work in both. Use theme tokens only (`bg-card`, `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, and the status tokens `text-success`, `text-warning`, `text-info`, `text-destructive` with tinted surfaces such as `bg-warning/10 border-warning/30`). Never write `bg-white`, `text-white`, palette classes (`bg-amber-50`, `text-red-700`) or hex colors in components; printed documents stay light.
|
|
35
|
+
- Navigation: keep the workspace shell. Add an administration page to `components/admin_sections.ts`, as a page of «الإعدادات» (`settings`) or of «الأشخاص والصلاحيات» (`people`): the sidebar keeps exactly these two administration entries, and a section's pages appear as one horizontal row of the registry `Tabs` (default look) under the header, each tab a link to its own address. Never add links to the shell by hand, sub-items under a sidebar entry, or a second sidebar of styled links for sub-pages. Per-user interface state belongs in `start/preferences.ts` (`definePreference`) and `usePreference`, not in localStorage.
|
|
34
36
|
- Arabic and accessibility: use RTL logical spacing and Arabic labels, keep identifiers and numeric/date inputs legible with appropriate direction, maintain keyboard order and visible focus, and keep controls usable on mobile. Long forms scroll inside their Dialog rather than switching presentation automatically.
|
|
35
37
|
- Operational states: provide specific Arabic loading, empty, no-results, permission-denied, validation and recoverable-error states. Distinguish an empty dataset from a failed request; never invent sample success data in a live screen.
|
|
36
38
|
|
|
@@ -46,11 +48,11 @@ Install missing registry components with `node ace adula:ui add <component>`. Ne
|
|
|
46
48
|
|
|
47
49
|
Every form and every row/record detail view opens in a shadcn Dialog unless the user explicitly requests another presentation. This includes create/edit forms and custom page overrides. Do not infer a page or Sheet exception from screen size, form length or personal design preference.
|
|
48
50
|
|
|
49
|
-
For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. From a list, open records with `openRecord(resource, id, 'show' | 'edit')` (exported by `resource-surface`): the dialog opens over the mounted list, and closing keeps its query, loaded rows and scroll. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
|
|
51
|
+
For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. From a list, open records with `openRecord(resource, id, 'show' | 'edit')` and the create form with `openCreate(resource)` (exported by `resource-surface`): the dialog opens at once over the mounted list, its body loads inside it, and closing keeps its query, loaded rows and scroll. Saving a new record closes the dialog and pins the new row first in the list, highlighted; saving an edit shows the record's details in the same dialog. A page other than the generic list that opens records this way renders `RecordOverlayDialog` (exported by `resource-page`). Never open a dialog by visiting a page that renders it: the page behind it would render again. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
|
|
50
52
|
|
|
51
|
-
Give every Dialog a visible DialogTitle and a useful DialogDescription. Keep long content scrollable within the viewport, Arabic RTL alignment, an accessible close control, focus containment and Escape dismissal. Use shadcn components inside the modal too. Keep validation and conflict messages inside it, preserve typed values on errors, and keep unauthorized actions absent. Do not replace server authorization with UI checks.
|
|
53
|
+
Give every Dialog a visible DialogTitle and a useful DialogDescription. Keep long content scrollable within the viewport, Arabic RTL alignment, an accessible close control, focus containment and Escape dismissal. A dialog whose content can exceed the screen height uses `LongDialogContent` (registry `long-dialog`) inside the shadcn `Dialog`: a fixed header with the title and description, a body that alone scrolls with its scrollbar always visible in both themes, and a fixed footer with the actions («إلغاء» or «إغلاق» as outline first, then the primary action). Do not hand-build this layout or let the whole dialog scroll. Record dialogs already follow it: `ResourceSurface` renders `LongDialogContent`, and a record body puts its actions in `RecordFooter` (secondary actions at the start, then «إلغاء» or `RecordFooterClose`, then the primary), with the submit button naming its form through `form`; a custom record override does the same instead of placing buttons at the end of the body. Use shadcn components inside the modal too. Keep validation and conflict messages inside it, preserve typed values on errors, and keep unauthorized actions absent. Do not replace server authorization with UI checks.
|
|
52
54
|
|
|
53
|
-
Use `mode="view"` for details and `mode="edit"` for custom forms. Details close on outside click
|
|
55
|
+
Use `mode="view"` for details and `mode="edit"` for custom forms. Details close on outside click. Editors ask for confirmation on outside click, close, «إلغاء» or Escape only when there are unsaved changes, and preserve input when the user continues editing; an untouched editor, or one whose values were changed back, closes at once. The shared Dialog decides this itself; never compute a dialog's dirty state or report `data-dirty`. A dialog whose state is plain inputs, text areas and selects declares nothing: the Dialog compares each control with the value it had before the user changed it. Any other state (a draft object, a list order, switches, a chosen file, a typed secret) is declared with the `value` prop of `Dialog`, or with `useDialogValue(value)` from a component inside it (ResourceForm does this); the Dialog captures it as it renders until the user first interacts, compares it with stable serialization on closing and treats a restored value as clean. A step saved within one opening (an uploaded file becoming a mapping), or a save that keeps the dialog open, starts afresh with `<DialogValue key={step} value={...} />` whose key changes after the save. A dialog that declares a value declares its full form state: once anything is declared its plain controls are no longer compared, and the Dialog warns on the console when a control changed while no declaration did. Respect `ui.preferences` rather than rebuilding dismissal logic. Confirm permission changes and destructive actions with distinct labels, and display server rejection/success feedback. Administrative access protection must remain enforced on the server.
|
|
54
56
|
|
|
55
57
|
Honor the system calendar preference: Gregorian, Umm al-Qura Hijri, or both. Reuse FieldControl/ResourceValue and the shared formatter; never store formatted Hijri text in a date column. Both mode shows two representations of one date and allows either input calendar. Keep transitions short, preserve the workspace shell and honor reduced motion. Installation terminal instructions are English for terminal compatibility; the application remains Arabic.
|
|
56
58
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: idea-review
|
|
3
|
-
description: Translate a new module or workflow into existing AdulaJS resources and declared extension points before writing code.
|
|
3
|
+
description: Translate a new application (a module under app/modules) or workflow into existing AdulaJS resources and declared extension points before writing code.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Use for a new
|
|
6
|
+
Use for a new application or workflow only; field changes do not need it.
|
|
7
7
|
|
|
8
8
|
1. Run `node ace adula:capabilities` and read the output: AdulaJS field types, services,
|
|
9
9
|
workflow steps, extension points, what is outside AdulaJS, and this project's
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** Applies the assistant's retention through the application's wiring in `#services/adula`. */
|
|
3
|
+
export default class AdulaAssistantPrune extends BaseCommand {
|
|
4
|
+
static commandName: string;
|
|
5
|
+
static description: string;
|
|
6
|
+
static options: {
|
|
7
|
+
startApp: boolean;
|
|
8
|
+
};
|
|
9
|
+
run(): Promise<void>;
|
|
10
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** Applies the assistant's retention through the application's wiring in `#services/adula`. */
|
|
3
|
+
export default class AdulaAssistantPrune extends BaseCommand {
|
|
4
|
+
static commandName = 'adula:assistant:prune';
|
|
5
|
+
static description = 'Delete assistant conversation metadata after 30 days, used proposals after a day and token usage after 90 days';
|
|
6
|
+
static options = { startApp: true };
|
|
7
|
+
async run() {
|
|
8
|
+
const { adula } = (await this.app.import('#services/adula'));
|
|
9
|
+
const removed = await adula().assistant.prune();
|
|
10
|
+
this.logger.info(`Removed ${removed.conversations} conversations, ${removed.proposals} proposals and ${removed.usage} usage rows`);
|
|
11
|
+
}
|
|
12
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** The application owns the outbox job mapping in `#services/events` (`publishEvents`). */
|
|
3
|
+
export default class AdulaOutbox extends BaseCommand {
|
|
4
|
+
static commandName: string;
|
|
5
|
+
static description: string;
|
|
6
|
+
static options: {
|
|
7
|
+
startApp: boolean;
|
|
8
|
+
};
|
|
9
|
+
run(): Promise<void>;
|
|
10
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** The application owns the outbox job mapping in `#services/events` (`publishEvents`). */
|
|
3
|
+
export default class AdulaOutbox extends BaseCommand {
|
|
4
|
+
static commandName = 'adula:outbox';
|
|
5
|
+
static description = 'Publish one locked batch of durable events to the queue';
|
|
6
|
+
static options = { startApp: true };
|
|
7
|
+
async run() {
|
|
8
|
+
const { publishEvents } = (await this.app.import('#services/events'));
|
|
9
|
+
this.logger.info(`Published ${await publishEvents()} events`);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
export default class AdulaRestoreReconcile extends BaseCommand {
|
|
3
|
+
static commandName: string;
|
|
4
|
+
static description: string;
|
|
5
|
+
static options: {
|
|
6
|
+
startApp: boolean;
|
|
7
|
+
};
|
|
8
|
+
force: boolean;
|
|
9
|
+
run(): Promise<void>;
|
|
10
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
2
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
3
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
4
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
5
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
6
|
+
};
|
|
7
|
+
import { BaseCommand, flags } from '@adonisjs/core/ace';
|
|
8
|
+
export default class AdulaRestoreReconcile extends BaseCommand {
|
|
9
|
+
static commandName = 'adula:restore:reconcile';
|
|
10
|
+
static description = 'After a restore, rebuild the event queue and invalidate cached authorization';
|
|
11
|
+
static options = { startApp: true };
|
|
12
|
+
async run() {
|
|
13
|
+
if (!this.force)
|
|
14
|
+
throw new Error('Stop web, worker and scheduler first; then pass --force after restoring the database');
|
|
15
|
+
// The queue and cache services are application dependencies, resolved from the application.
|
|
16
|
+
const { default: queue } = (await this.app.import('@nemoventures/adonis-jobs/services/main'));
|
|
17
|
+
const { default: cache } = (await this.app.import('@adonisjs/cache/services/main'));
|
|
18
|
+
const { default: db } = await import('@adonisjs/lucid/services/db');
|
|
19
|
+
// This queue contains only deliveries whose authoritative records live in outbox.
|
|
20
|
+
await queue.clear(['events']);
|
|
21
|
+
await db
|
|
22
|
+
.connection()
|
|
23
|
+
.getWriteClient()
|
|
24
|
+
.transaction(async (trx) => {
|
|
25
|
+
await trx('outbox').update({ published_at: null });
|
|
26
|
+
await trx('authorization_revision').where('id', 1).increment('version', 1);
|
|
27
|
+
});
|
|
28
|
+
await cache.clear();
|
|
29
|
+
this.logger.success('Durable events will replay with listener deduplication; authorization cache cleared');
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
__decorate([
|
|
33
|
+
flags.boolean()
|
|
34
|
+
], AdulaRestoreReconcile.prototype, "force", void 0);
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
export default class AdulaRuntimeHealth extends BaseCommand {
|
|
3
|
+
static commandName: string;
|
|
4
|
+
static description: string;
|
|
5
|
+
static options: {
|
|
6
|
+
startApp: boolean;
|
|
7
|
+
};
|
|
8
|
+
service: string;
|
|
9
|
+
run(): Promise<void>;
|
|
10
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
2
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
3
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
4
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
5
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
6
|
+
};
|
|
7
|
+
import { BaseCommand, flags } from '@adonisjs/core/ace';
|
|
8
|
+
export default class AdulaRuntimeHealth extends BaseCommand {
|
|
9
|
+
static commandName = 'adula:runtime:health';
|
|
10
|
+
static description = 'Check the worker or single scheduler heartbeat';
|
|
11
|
+
static options = { startApp: true };
|
|
12
|
+
async run() {
|
|
13
|
+
if (!['worker', 'scheduler'].includes(this.service))
|
|
14
|
+
throw new Error('Unknown service');
|
|
15
|
+
const { Settings } = await import('../src/services/settings.js');
|
|
16
|
+
const { default: db } = await import('@adonisjs/lucid/services/db');
|
|
17
|
+
const last = await new Settings(db.connection().getWriteClient()).get(`${this.service}.heartbeat`);
|
|
18
|
+
const age = Date.now() - Date.parse(last ?? '');
|
|
19
|
+
const healthy = Number.isFinite(age) && age >= 0 && age < 60000;
|
|
20
|
+
this.logger.log(`${this.service}: ${healthy ? 'healthy' : 'unhealthy'}`);
|
|
21
|
+
if (!healthy)
|
|
22
|
+
this.exitCode = 1;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
__decorate([
|
|
26
|
+
flags.string({ default: 'worker' })
|
|
27
|
+
], AdulaRuntimeHealth.prototype, "service", void 0);
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** The application owns the Drive-backed pruning in `#services/upload_pruning`. */
|
|
3
|
+
export default class AdulaUploadsPrune extends BaseCommand {
|
|
4
|
+
static commandName: string;
|
|
5
|
+
static description: string;
|
|
6
|
+
static options: {
|
|
7
|
+
startApp: boolean;
|
|
8
|
+
};
|
|
9
|
+
run(): Promise<void>;
|
|
10
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** The application owns the Drive-backed pruning in `#services/upload_pruning`. */
|
|
3
|
+
export default class AdulaUploadsPrune extends BaseCommand {
|
|
4
|
+
static commandName = 'adula:uploads:prune';
|
|
5
|
+
static description = 'Delete uploads older than a day that were never bound to a record';
|
|
6
|
+
static options = { startApp: true };
|
|
7
|
+
async run() {
|
|
8
|
+
const { pruneUnboundUploads } = (await this.app.import('#services/upload_pruning'));
|
|
9
|
+
const { removed, failed } = await pruneUnboundUploads();
|
|
10
|
+
this.logger.info(`Removed ${removed} unbound uploads`);
|
|
11
|
+
if (failed) {
|
|
12
|
+
this.logger.error(`${failed} unbound uploads could not be removed; they will be retried`);
|
|
13
|
+
this.exitCode = 1;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
2
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
3
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
4
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
5
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
6
|
+
};
|
|
7
|
+
import { BaseCommand, args, flags } from '@adonisjs/core/ace';
|
|
8
|
+
import { fileURLToPath } from 'node:url';
|
|
9
|
+
import { planApp, writeAppPlan } from '../src/commands/app_scaffold.js';
|
|
10
|
+
export default class App extends BaseCommand {
|
|
11
|
+
static commandName = 'adula:app';
|
|
12
|
+
static description = 'Create and register a business application: module, example resource, default roles and a smoke test';
|
|
13
|
+
async run() {
|
|
14
|
+
if (this.app.inProduction)
|
|
15
|
+
throw new Error('Generate applications in the source checkout, not in production');
|
|
16
|
+
const root = fileURLToPath(this.app.appRoot);
|
|
17
|
+
let plan;
|
|
18
|
+
try {
|
|
19
|
+
plan = await planApp(root, { name: this.name, labelAr: this.labelAr, labelEn: this.labelEn });
|
|
20
|
+
}
|
|
21
|
+
catch (error) {
|
|
22
|
+
this.logger.error(error.message);
|
|
23
|
+
this.exitCode = 1;
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
const files = Object.keys(plan.files);
|
|
27
|
+
if (this.dryRun) {
|
|
28
|
+
this.logger.info(`Dry run: adula:app ${plan.name} would create`);
|
|
29
|
+
for (const directory of plan.directories)
|
|
30
|
+
this.logger.log(` ${directory}/`);
|
|
31
|
+
for (const file of files)
|
|
32
|
+
this.logger.log(` ${file}`);
|
|
33
|
+
this.logger.log(` and register module_${plan.name} in start/modules.ts`);
|
|
34
|
+
this.logger.info('Nothing was written.');
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
37
|
+
await writeAppPlan(root, plan);
|
|
38
|
+
for (const file of files)
|
|
39
|
+
this.logger.success(file);
|
|
40
|
+
this.logger.success(`Registered module_${plan.name} in start/modules.ts`);
|
|
41
|
+
this.logger.info([
|
|
42
|
+
'Next steps:',
|
|
43
|
+
` 1. node ace migration:run, then fill app/modules/${plan.name}/resources/${plan.name}.ts with the real fields (they derive validation and forms) and update the contract fixture.`,
|
|
44
|
+
` 2. node ace adula:resource:migration ${plan.name}, then node ace migration:run again (adds the new columns)`,
|
|
45
|
+
` 3. node ace adula:install (creates the roles ${plan.name}_manager and ${plan.name}_user)`,
|
|
46
|
+
` 4. Assign the roles to people on /admin/users, then run node ace test functional --files=${plan.name} --files=${plan.name}/smoke`,
|
|
47
|
+
].join('\n'));
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
__decorate([
|
|
51
|
+
args.string({ description: 'Application name: lower-case letters, digits and underscores' })
|
|
52
|
+
], App.prototype, "name", void 0);
|
|
53
|
+
__decorate([
|
|
54
|
+
flags.string({ flagName: 'label-ar', description: 'Arabic label shown in the menu (required)' })
|
|
55
|
+
], App.prototype, "labelAr", void 0);
|
|
56
|
+
__decorate([
|
|
57
|
+
flags.string({
|
|
58
|
+
flagName: 'label-en',
|
|
59
|
+
description: 'English label (defaults to the title-cased name)',
|
|
60
|
+
})
|
|
61
|
+
], App.prototype, "labelEn", void 0);
|
|
62
|
+
__decorate([
|
|
63
|
+
flags.boolean({ flagName: 'dry-run', description: 'Print the plan without writing files' })
|
|
64
|
+
], App.prototype, "dryRun", void 0);
|