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.
- package/LICENSE.md +10 -0
- package/README.md +40 -2
- package/build/agent/AGENTS.template.md +28 -0
- package/build/agent/capabilities.md +60 -0
- package/build/agent/skills/adula-frontend-design/SKILL.md +59 -0
- package/build/agent/skills/idea-review/SKILL.md +31 -0
- package/build/agent/skills/module-review/SKILL.md +22 -0
- package/build/agent/skills/perf-review/SKILL.md +24 -0
- package/build/agent/skills/schema-review/SKILL.md +22 -0
- package/build/agent/skills/security-review/SKILL.md +24 -0
- package/build/agent/skills/ui-review/SKILL.md +22 -0
- package/build/commands/capabilities.d.ts +10 -0
- package/build/commands/capabilities.js +40 -0
- package/build/commands/doctor.d.ts +9 -0
- package/build/commands/doctor.js +72 -0
- package/build/commands/gaps.d.ts +12 -0
- package/build/commands/gaps.js +62 -0
- package/build/commands/install.d.ts +9 -0
- package/build/commands/install.js +105 -0
- package/build/commands/main.d.ts +8 -0
- package/build/commands/main.js +33 -0
- package/build/commands/module_add.d.ts +8 -0
- package/build/commands/module_add.js +57 -0
- package/build/commands/module_remove.d.ts +10 -0
- package/build/commands/module_remove.js +94 -0
- package/build/commands/resource.d.ts +8 -0
- package/build/commands/resource.js +29 -0
- package/build/commands/resource_snapshot.d.ts +15 -0
- package/build/commands/resource_snapshot.js +61 -0
- package/build/commands/storage_migrate.d.ts +12 -0
- package/build/commands/storage_migrate.js +39 -0
- package/build/commands/ui.d.ts +11 -0
- package/build/commands/ui.js +210 -0
- package/build/commands/upgrade.d.ts +15 -0
- package/build/commands/upgrade.js +34 -0
- package/build/configure.d.ts +2 -0
- package/build/configure.js +79 -0
- package/build/database/migrations/1770000000000_core.d.ts +5 -0
- package/build/database/migrations/1770000000000_core.js +10 -0
- package/build/database/migrations/1770000000001_attachments.d.ts +5 -0
- package/build/database/migrations/1770000000001_attachments.js +10 -0
- package/build/database/migrations/1770000000002_saved_views.d.ts +5 -0
- package/build/database/migrations/1770000000002_saved_views.js +10 -0
- package/build/database/migrations/1770000000003_user_invitations.d.ts +5 -0
- package/build/database/migrations/1770000000003_user_invitations.js +18 -0
- package/build/database/migrations/1770000000004_collaboration.d.ts +5 -0
- package/build/database/migrations/1770000000004_collaboration.js +10 -0
- package/build/database/migrations/1770000000005_assignments.d.ts +5 -0
- package/build/database/migrations/1770000000005_assignments.js +10 -0
- package/build/database/migrations/1770000000006_messaging.d.ts +5 -0
- package/build/database/migrations/1770000000006_messaging.js +10 -0
- package/build/database/migrations/1770000000007_webhooks.d.ts +5 -0
- package/build/database/migrations/1770000000007_webhooks.js +10 -0
- package/build/database/migrations/1770000000008_imports.d.ts +5 -0
- package/build/database/migrations/1770000000008_imports.js +10 -0
- package/build/database/migrations/1770000000010_workflows.d.ts +5 -0
- package/build/database/migrations/1770000000010_workflows.js +10 -0
- package/build/database/migrations/1770000000011_managed_assignments.d.ts +5 -0
- package/build/database/migrations/1770000000011_managed_assignments.js +10 -0
- package/build/database/migrations/1770000000012_role_keys.d.ts +5 -0
- package/build/database/migrations/1770000000012_role_keys.js +10 -0
- package/build/database/migrations/1770000000013_notification_targets.d.ts +5 -0
- package/build/database/migrations/1770000000013_notification_targets.js +10 -0
- package/build/database/migrations/1770000000014_upload_grants.d.ts +5 -0
- package/build/database/migrations/1770000000014_upload_grants.js +10 -0
- package/build/database/migrations/1770000000015_inbound_webhooks.d.ts +5 -0
- package/build/database/migrations/1770000000015_inbound_webhooks.js +10 -0
- package/build/database/migrations/1770000000016_adulajs_names.d.ts +6 -0
- package/build/database/migrations/1770000000016_adulajs_names.js +11 -0
- package/build/index.d.ts +80 -0
- package/build/index.js +49 -0
- package/build/providers/adula_provider.d.ts +6 -0
- package/build/providers/adula_provider.js +10 -0
- package/build/src/admin/contracts.d.ts +19 -0
- package/build/src/admin/contracts.js +115 -0
- package/build/src/admin/controller.d.ts +32 -0
- package/build/src/admin/controller.js +167 -0
- package/build/src/admin/errors.d.ts +5 -0
- package/build/src/admin/errors.js +9 -0
- package/build/src/admin/presentation.d.ts +28 -0
- package/build/src/admin/presentation.js +1 -0
- package/build/src/admin/record_title.d.ts +14 -0
- package/build/src/admin/record_title.js +50 -0
- package/build/src/admin/resource_service.d.ts +376 -0
- package/build/src/admin/resource_service.js +1448 -0
- package/build/src/attachments/attachment_service.d.ts +100 -0
- package/build/src/attachments/attachment_service.js +270 -0
- package/build/src/attachments/doctor.d.ts +4 -0
- package/build/src/attachments/doctor.js +28 -0
- package/build/src/attachments/storage_migrate.d.ts +39 -0
- package/build/src/attachments/storage_migrate.js +64 -0
- package/build/src/attachments/upload_grants.d.ts +44 -0
- package/build/src/attachments/upload_grants.js +105 -0
- package/build/src/auth/ability.d.ts +24 -0
- package/build/src/auth/ability.js +34 -0
- package/build/src/auth/actor_store.d.ts +14 -0
- package/build/src/auth/actor_store.js +70 -0
- package/build/src/auth/conditions.d.ts +26 -0
- package/build/src/auth/conditions.js +117 -0
- package/build/src/auth/packed_rules.d.ts +4 -0
- package/build/src/auth/packed_rules.js +13 -0
- package/build/src/auth/sql.d.ts +11 -0
- package/build/src/auth/sql.js +118 -0
- package/build/src/collaboration/assignments.d.ts +129 -0
- package/build/src/collaboration/assignments.js +333 -0
- package/build/src/collaboration/record_collaboration.d.ts +86 -0
- package/build/src/collaboration/record_collaboration.js +348 -0
- package/build/src/commands/agent_assets.d.ts +7 -0
- package/build/src/commands/agent_assets.js +66 -0
- package/build/src/commands/capabilities.d.ts +19 -0
- package/build/src/commands/capabilities.js +179 -0
- package/build/src/commands/doctor.d.ts +42 -0
- package/build/src/commands/doctor.js +375 -0
- package/build/src/commands/gap_report.d.ts +56 -0
- package/build/src/commands/gap_report.js +110 -0
- package/build/src/commands/generator.d.ts +1 -0
- package/build/src/commands/generator.js +70 -0
- package/build/src/commands/snapshot.d.ts +28 -0
- package/build/src/commands/snapshot.js +48 -0
- package/build/src/commands/source_markers.d.ts +11 -0
- package/build/src/commands/source_markers.js +41 -0
- package/build/src/core/activity.d.ts +43 -0
- package/build/src/core/activity.js +77 -0
- package/build/src/core/administration_guard.d.ts +3 -0
- package/build/src/core/administration_guard.js +39 -0
- package/build/src/core/health.d.ts +42 -0
- package/build/src/core/health.js +44 -0
- package/build/src/core/mail_test.d.ts +18 -0
- package/build/src/core/mail_test.js +88 -0
- package/build/src/core/message_templates.d.ts +83 -0
- package/build/src/core/message_templates.js +293 -0
- package/build/src/core/module_seed.d.ts +15 -0
- package/build/src/core/module_seed.js +31 -0
- package/build/src/core/notifications.d.ts +42 -0
- package/build/src/core/notifications.js +91 -0
- package/build/src/core/org_units.d.ts +30 -0
- package/build/src/core/org_units.js +123 -0
- package/build/src/core/roles.d.ts +98 -0
- package/build/src/core/roles.js +447 -0
- package/build/src/core/saved_views.d.ts +37 -0
- package/build/src/core/saved_views.js +164 -0
- package/build/src/core/settings.d.ts +29 -0
- package/build/src/core/settings.js +113 -0
- package/build/src/core/setup.d.ts +14 -0
- package/build/src/core/setup.js +89 -0
- package/build/src/core/ui_preferences.d.ts +12 -0
- package/build/src/core/ui_preferences.js +30 -0
- package/build/src/core/user_invitations.d.ts +23 -0
- package/build/src/core/user_invitations.js +144 -0
- package/build/src/core/users.d.ts +44 -0
- package/build/src/core/users.js +182 -0
- package/build/src/database/configure.d.ts +3 -0
- package/build/src/database/configure.js +41 -0
- package/build/src/database/schema.d.ts +52 -0
- package/build/src/database/schema.js +538 -0
- package/build/src/eslint/index.d.ts +3 -0
- package/build/src/eslint/index.js +90 -0
- package/build/src/events/adonis_jobs.d.ts +9 -0
- package/build/src/events/adonis_jobs.js +13 -0
- package/build/src/events/outbox.d.ts +19 -0
- package/build/src/events/outbox.js +33 -0
- package/build/src/events/record_mutation.d.ts +24 -0
- package/build/src/events/record_mutation.js +62 -0
- package/build/src/integrations/imports.d.ts +74 -0
- package/build/src/integrations/imports.js +333 -0
- package/build/src/integrations/inbound_webhooks.d.ts +94 -0
- package/build/src/integrations/inbound_webhooks.js +276 -0
- package/build/src/integrations/openapi.d.ts +39 -0
- package/build/src/integrations/openapi.js +323 -0
- package/build/src/integrations/print.d.ts +37 -0
- package/build/src/integrations/print.js +124 -0
- package/build/src/integrations/webhooks.d.ts +98 -0
- package/build/src/integrations/webhooks.js +298 -0
- package/build/src/mcp/tools.d.ts +8 -0
- package/build/src/mcp/tools.js +156 -0
- package/build/src/org/org_service.d.ts +2 -0
- package/build/src/org/org_service.js +16 -0
- package/build/src/resource/define_resource.d.ts +5 -0
- package/build/src/resource/define_resource.js +68 -0
- package/build/src/resource/registry.d.ts +12 -0
- package/build/src/resource/registry.js +101 -0
- package/build/src/resource/types.d.ts +155 -0
- package/build/src/resource/types.js +1 -0
- package/build/src/resource/values.d.ts +5 -0
- package/build/src/resource/values.js +88 -0
- package/build/src/services/backup.d.ts +14 -0
- package/build/src/services/backup.js +59 -0
- package/build/src/services/settings.d.ts +21 -0
- package/build/src/services/settings.js +30 -0
- package/build/src/upgrade/legacy.d.ts +27 -0
- package/build/src/upgrade/legacy.js +58 -0
- package/build/src/upgrade/rename.d.ts +17 -0
- package/build/src/upgrade/rename.js +94 -0
- package/build/src/version.d.ts +1 -0
- package/build/src/version.js +2 -0
- package/build/src/workflows/define_workflow.d.ts +124 -0
- package/build/src/workflows/define_workflow.js +123 -0
- package/build/src/workflows/engine.d.ts +141 -0
- package/build/src/workflows/engine.js +752 -0
- package/build/stubs/README.md +6 -0
- package/build/stubs/controller.stub +8 -0
- package/build/stubs/main.d.ts +5 -0
- package/build/stubs/main.js +5 -0
- package/build/stubs/main.ts +5 -0
- package/build/stubs/modules.stub +6 -0
- package/build/stubs/resource_contract.stub +1 -0
- package/build/stubs/resource_contract.txt +452 -0
- package/build/stubs/routes.stub +16 -0
- package/build/stubs/service.stub +9 -0
- package/package.json +95 -3
package/LICENSE.md
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# The MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023
|
|
4
|
+
Copyright (c) 2026 adula contributors
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
7
|
+
|
|
8
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
9
|
+
|
|
10
|
+
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,41 @@
|
|
|
1
|
-
#
|
|
1
|
+
# adula
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Resource framework for AdonisJS 7 and PostgreSQL 17, version 2.0.0 (the AdulaJS rename, ADR 039; 1.0 scope accepted by the owner, ADR 028). Node 24 or later is required. MIT licensed. The public API in `api/adula-api.json` follows semantic versioning.
|
|
4
|
+
|
|
5
|
+
## Install into a consumer
|
|
6
|
+
|
|
7
|
+
Follow the canonical [installation guide](https://github.com/adulash/adulajs/blob/main/docs/installation.md). For a new application, the separate `create-adula-app` initializer installs the AdonisJS host and application 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
|
+
|
|
9
|
+
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
|
+
|
|
11
|
+
## Contracts
|
|
12
|
+
|
|
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.
|
|
14
|
+
|
|
15
|
+
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
|
+
|
|
17
|
+
Other exports include `ActorStore`, schema helpers, organizational moves, settings, sequences, notifications, jobs/outbox interfaces, packed rules and the generic controller factory. Commands include `adula:resource`, `adula:install`, `adula:doctor`, `adula:module:add`, `adula:module:remove`, `adula:ui add` and `adula:capabilities`.
|
|
18
|
+
|
|
19
|
+
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
|
+
|
|
21
|
+
## Generated HTTP contracts
|
|
22
|
+
|
|
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.
|
|
24
|
+
|
|
25
|
+
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
|
+
|
|
27
|
+
Doctor measures the deployment's `storage/uploads` directory and warns above 5 decimal GB. When copied UI hashes or AdulaJS compatibility change, it inventories project pages for review. This conservative check does not prove import compatibility, completed page review or attachment restoration.
|
|
28
|
+
|
|
29
|
+
## Current limitations
|
|
30
|
+
|
|
31
|
+
Phases 3 and 4 (collaboration, assignments, templates and realtime notifications,
|
|
32
|
+
CSV import, printing, webhooks, API tokens/OpenAPI, amend-by-copy and versioned
|
|
33
|
+
XState workflows) are implemented with PostgreSQL tests; see the
|
|
34
|
+
[business features guide](https://github.com/adulash/adulajs/blob/main/docs/business-features.md).
|
|
35
|
+
|
|
36
|
+
- Two-factor authentication is not included; it is planned for 2.0 (ADR 027).
|
|
37
|
+
- Impersonation was reviewed by automated adversarial and black-box tests only; its
|
|
38
|
+
human security review is deferred to 2.0 (ADR 027).
|
|
39
|
+
- XLSX import is not available (GAP-006); CSV is.
|
|
40
|
+
|
|
41
|
+
See [implementation status](https://github.com/adulash/adulajs/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adulajs/blob/main/GAPS.md) and [1.0 acceptance](https://github.com/adulash/adulajs/blob/main/docs/acceptance-1.0.md).
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
<!-- adula:start (managed by adula:doctor — do not edit) -->
|
|
2
|
+
|
|
3
|
+
# AdulaJS rules
|
|
4
|
+
|
|
5
|
+
A plugin is just code that has not been written yet. No abstraction before the second need.
|
|
6
|
+
|
|
7
|
+
Structure
|
|
8
|
+
|
|
9
|
+
1. One system. Every entity lives in app/modules/<module>. No separate "apps".
|
|
10
|
+
2. Generate the resource scaffold with adula:resource and follow its typed definition. Reuse an existing project resource when available; never assume educational modules are installed.
|
|
11
|
+
3. New entity: `node ace adula:resource <name> --module=<module>`, then fill the fields.
|
|
12
|
+
4. Before creating an entity, check the registry. Same meaning exists → belongsTo. Never duplicate a table.
|
|
13
|
+
5. A module writes only its own tables; dependency direction follows start/modules.ts, never backwards.
|
|
14
|
+
6. Modules talk through events, never by importing each other's controllers. Heavy listeners go to jobs.
|
|
15
|
+
7. Every resource declares `scoped` explicitly. Standard columns are generated; never edit them. Migrations follow expand/contract: never drop or rename a column in the same release that stops using it.
|
|
16
|
+
8. Deletes are soft. Changeable lists come from lookups. Approvable documents use `submittable: true`.
|
|
17
|
+
9. Notify via notify(), number via sequence, configure via settings. Nothing else.
|
|
18
|
+
|
|
19
|
+
Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). `systemSave` and `rehome` skip role rules: use them only in listeners and module services after an explicit authorization, never in a controller or route (enforced by lint). 11. Never write crypto, sessions, or auth flows; use AdulaJS. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
|
|
20
|
+
|
|
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
|
+
|
|
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 application from create-app. 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 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
|
+
<!-- adula:end -->
|
|
25
|
+
|
|
26
|
+
## Project rules
|
|
27
|
+
|
|
28
|
+
This is a reference consumer. Additions approved by the implementation plan are authorized.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# AdulaJS capabilities (2.0.0)
|
|
2
|
+
|
|
3
|
+
Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by AdulaJS.
|
|
4
|
+
|
|
5
|
+
## Resource definition
|
|
6
|
+
|
|
7
|
+
| Field type | Storage |
|
|
8
|
+
|---|---|
|
|
9
|
+
| string | varchar |
|
|
10
|
+
| text | text |
|
|
11
|
+
| integer | integer |
|
|
12
|
+
| money | bigint minor units, decimal string in JSON |
|
|
13
|
+
| boolean | boolean |
|
|
14
|
+
| date | date (YYYY-MM-DD) |
|
|
15
|
+
| datetime | timestamptz |
|
|
16
|
+
| json | jsonb |
|
|
17
|
+
| attachment | attachments row id; per-field accept/maxSize |
|
|
18
|
+
| belongsTo | foreign key, preloaded, restrict on delete |
|
|
19
|
+
| user | users foreign key, restrict on delete; choices are active members of the record unit or its ancestors; related as { id, fullName } |
|
|
20
|
+
| hasMany | child resource; inline rows saved with the parent |
|
|
21
|
+
| lookup | lookups group key |
|
|
22
|
+
|
|
23
|
+
Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column.
|
|
24
|
+
|
|
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), customFields, list / form / show / serialize / hidden, actions, hooks.beforeSave / hooks.afterSave.
|
|
26
|
+
|
|
27
|
+
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
|
+
|
|
29
|
+
Workflow steps: condition, update, notify, approval, decision, delay, http, end. Workflow and step names: use lower-case letters, digits and underscores, starting with a letter (for example release_approval, notify_approved).
|
|
30
|
+
|
|
31
|
+
## Services
|
|
32
|
+
|
|
33
|
+
- **Resources and authorization:** `defineResource`, `ResourceRegistry`, `ResourceService`, `createResourceController`, `buildAbility`, `accessibleBy`, `ActorStore`, `packedResourceRules`
|
|
34
|
+
- **Records and collaboration:** `RecordCollaboration`, `followerListeners`, `Assignments`, `SavedViews`, `logActivity`
|
|
35
|
+
- **Documents and workflows:** `defineWorkflow`, `WorkflowEngine`, `workflowListeners`
|
|
36
|
+
- **Notifications and messages:** `notify`, `notifyWithTemplate`, `MessageTemplates`, `deliverNotificationMail`, `listenForNotifications`, `NotificationsAdmin`
|
|
37
|
+
- **Integration:** `Webhooks`, `signWebhook`, `InboundWebhooks`, `openApiDocument`, `ImportBatches`, `renderPrintHtml`, `htmlToPdf`
|
|
38
|
+
- **Security:** `UserInvitations`, `UsersAdmin`, `RolesAdmin`
|
|
39
|
+
- **Data and operations:** `sequence`, `Settings`, `SettingsAdmin`, `publishOutbox`, `consumeEvent`, `recordMutation`, `moveOrgUnit`, `migrateStorage`, `verifyBackup`, `runtimeHealth`
|
|
40
|
+
|
|
41
|
+
## Extension points
|
|
42
|
+
|
|
43
|
+
- Resource hooks (beforeSave, afterSave) inside the save transaction
|
|
44
|
+
- ResourceService.systemSave for module-decided writes (validator, hooks and audit, no role rules); ResourceService.rehome after a parent moves
|
|
45
|
+
- Assignment closing notes (Assignments closeNote: optional or required); managed assignments (managed: true) closed by module code with Assignments.close
|
|
46
|
+
- Page override: inertia/pages/<resource>/{index,form,show}.tsx replaces the generated page
|
|
47
|
+
- Create links with defaults: /resources/<resource>/create?defaults[field]=value
|
|
48
|
+
- Domain events <module>.<resource>.{created,updated,deleted,submitted,cancelled,amended} with idempotent listeners
|
|
49
|
+
- Module workflows (Module.workflows) with versioned definitions
|
|
50
|
+
- Message templates edited per deployment
|
|
51
|
+
- Outgoing webhooks and the bearer-token /api/v1 API
|
|
52
|
+
- Signed inbound webhooks raising inbound.<source>.<event> through the outbox
|
|
53
|
+
|
|
54
|
+
## Outside AdulaJS
|
|
55
|
+
|
|
56
|
+
- Dynamic fields or a field editor screen
|
|
57
|
+
- Runtime plugins
|
|
58
|
+
- A visual workflow editor
|
|
59
|
+
- Multi-tenant SaaS in one database (one deployment per organization)
|
|
60
|
+
- XLSX import until a maintained parser passes the dependency rule (GAP-006)
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: adula-frontend-design
|
|
3
|
+
description: Design business application interfaces for AdulaJS using project-owned shadcn/ui components, Arabic RTL layouts, practical data density, and modal forms and record details. Apply whenever creating or changing an operational page, form, table, dialog, or dashboard in an AdulaJS application.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Frontend design for AdulaJS
|
|
7
|
+
|
|
8
|
+
This is AdulaJS's self-contained frontend-design skill. Read it before UI work; it does not require a globally installed skill or a particular agent vendor.
|
|
9
|
+
|
|
10
|
+
## Request company identity on day one
|
|
11
|
+
|
|
12
|
+
At project kickoff, before the first visual design, inspect the user's brief, existing assets, theme and `docs/design-identity.md`. If the company identity has not been supplied, ask for it early in one concise Arabic request. For example:
|
|
13
|
+
|
|
14
|
+
> لتطبيق هوية شركتكم من أول واجهة، زوّدني باسم الشركة وشعارها وألوانها وخطوطها المعتمدة ودليل الهوية إن وُجد. وإن لم تكن لديكم هوية جاهزة، أخبرني بذلك لنحدد اتجاهًا مناسبًا لنظام الأعمال.
|
|
15
|
+
|
|
16
|
+
Use the normal conversation when requesting logo files or a brand guide; a text-only input tool cannot receive attachments. Ask only for missing items when some identity is already known. Do not request information or approval already supplied. If the user explicitly delegates brand creation or says there is no identity, propose a restrained business direction within that authorization.
|
|
17
|
+
|
|
18
|
+
Record supplied identity in project-owned `docs/design-identity.md`: company/product names, local asset paths or supplied source links, color tokens, Arabic and Latin fonts if specified, logo usage, source of each decision and unresolved items. This is application content, not an AdulaJS-managed file; installation and upgrades must preserve it. Do not claim that a proposed or inferred choice came from the company's official guidelines.
|
|
19
|
+
|
|
20
|
+
Apply known identity from the first interface through theme tokens, typography, logo placement and naming. Adapt inaccessible color combinations through readable pairings while retaining the brand's role and noting the decision. Do not distort logos or fetch unrelated branding. If a reply or assets are pending, continue independent work; use the existing theme or a clearly provisional neutral theme for unavoidable previews. Elapsed time is not brand approval. Incorporate supplied identity once it arrives.
|
|
21
|
+
|
|
22
|
+
## Design within the application
|
|
23
|
+
|
|
24
|
+
Understand the user's task, the important action and the information hierarchy. Inspect the existing theme and nearby screens before choosing typography, density, spacing and emphasis. Build a deliberate, cohesive interface using the application's tokens and Arabic typography. Prefer a restrained business interface with clear states and useful whitespace; avoid generic dashboard decoration and invented metrics. Honor a supplied design direction.
|
|
25
|
+
|
|
26
|
+
## Business application priorities
|
|
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 modules. A marketing landing page, experimental typography, oversized hero section or ornamental animation is not the default for an operational screen.
|
|
29
|
+
|
|
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
|
+
- 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
|
+
- 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
|
+
- 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
|
+
- 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
|
+
- 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
|
+
|
|
37
|
+
If a general frontend-design skill is also available, apply its craft within these business constraints. Do not follow its more experimental visual suggestions when they conflict with consistency, usability or the user's workflow.
|
|
38
|
+
|
|
39
|
+
## Compose shadcn components
|
|
40
|
+
|
|
41
|
+
Use the copied shadcn/ui primitives in `inertia/components/ui/`: Button, Input, Textarea, Select, Checkbox, Switch, Table, Card, Dialog, Alert and related components. Compose them; do not recreate controls with styled native HTML, a custom modal overlay or an unrelated component library. Semantic elements such as main, section, headings, dl and form remain appropriate for structure and submission. Hidden inputs remain appropriate for metadata.
|
|
42
|
+
|
|
43
|
+
Install missing registry components with `node ace adula:ui add <component>`. Never run `shadcn add` directly or modify installed AdulaJS internals. Preserve application-owned component customizations; preview updates and merge deliberate changes.
|
|
44
|
+
|
|
45
|
+
## Modal is the default
|
|
46
|
+
|
|
47
|
+
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
|
+
|
|
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.
|
|
50
|
+
|
|
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.
|
|
52
|
+
|
|
53
|
+
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 by default and preserve input when the user continues editing. 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
|
+
|
|
55
|
+
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
|
+
|
|
57
|
+
## Verify the experience
|
|
58
|
+
|
|
59
|
+
Exercise opening, filling, validation, saving, viewing details and closing. Check direct links, nested selects/popovers, keyboard focus and Escape, and a narrow mobile viewport. Test the explicit page exception when adding one. Use realistic Arabic content, inspect the rendered result, and run the project's required checks. Report which behavior was actually verified without claiming the broader visual or release acceptance gate is complete.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: idea-review
|
|
3
|
+
description: Translate a new module or workflow into existing AdulaJS resources and declared extension points before writing code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use for a new module or workflow only; field changes do not need it.
|
|
7
|
+
|
|
8
|
+
1. Run `node ace adula:capabilities` and read the output: AdulaJS field types, services,
|
|
9
|
+
workflow steps, extension points, what is outside AdulaJS, and this project's
|
|
10
|
+
registered modules, resources and workflows. Read docs/decisions and GAPS.md.
|
|
11
|
+
2. Find existing entities with the same meaning; reference them with belongsTo.
|
|
12
|
+
Never duplicate a table owned by another module.
|
|
13
|
+
3. Produce a compact blueprint:
|
|
14
|
+
- module name, `dependsOn`, owned resources with `scoped` stated explicitly;
|
|
15
|
+
- fields with AdulaJS types, required/unique/searchable/filterable, permission levels,
|
|
16
|
+
hidden fields, lookups (groups and keys) and sequences;
|
|
17
|
+
- submittable documents and their workflow as steps (condition, update, notify,
|
|
18
|
+
approval, delay, http, end) with approvers by role;
|
|
19
|
+
- events consumed and emitted, listeners (idempotent) and any webhooks;
|
|
20
|
+
- role rules per action, including conditions from the six operators;
|
|
21
|
+
- acceptance tests: 403/404/uniqueness/scope from the generator plus the
|
|
22
|
+
business rules.
|
|
23
|
+
4. Classify each requirement: **now** (AdulaJS capability), **extension** (hooks, page
|
|
24
|
+
override, listener, workflow), or **outside AdulaJS** (record it in GAPS.md
|
|
25
|
+
with Needed by, Tried, Blocked because, Proposed AdulaJS change, Workaround).
|
|
26
|
+
5. Never design a dynamic field editor, runtime plugin loader, visual workflow editor
|
|
27
|
+
or a second tenant model. An already-approved plan authorizes its modules; do not
|
|
28
|
+
ask to approve them again.
|
|
29
|
+
|
|
30
|
+
After implementation, run the reviewers: module-review, security-review,
|
|
31
|
+
schema-review, ui-review and perf-review.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: module-review
|
|
3
|
+
description: Review a module's boundaries, dependencies, events and scope before merging.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Check, citing file and line for every finding:
|
|
7
|
+
|
|
8
|
+
- The module lives in `app/modules/<name>` and is registered in `start/modules.ts`
|
|
9
|
+
after every module it depends on; `dependsOn` lists each module whose resources
|
|
10
|
+
it references. `ResourceRegistry.register` must accept the order.
|
|
11
|
+
- It writes only its own tables. Cross-module effects happen in idempotent
|
|
12
|
+
listeners (`consumeEvent` + processed_events), never by importing another
|
|
13
|
+
module's controllers or services. Heavy listeners dispatch jobs.
|
|
14
|
+
- Every resource declares `scoped`. Central (`scoped: false`) resources are
|
|
15
|
+
justified; scoped ones rely on AdulaJS's organization scope, not custom filters.
|
|
16
|
+
- Documents that need approval use `submittable: true` and a module workflow; the
|
|
17
|
+
operational status is a lookup separate from `docStatus`.
|
|
18
|
+
- No AdulaJS service is re-implemented under another name (notify, sequence, settings,
|
|
19
|
+
assignments, comments, imports, webhooks, workflows).
|
|
20
|
+
- Educational fixtures are not imported by the application.
|
|
21
|
+
|
|
22
|
+
Verdict: accept, or a numbered list of blocking findings.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: perf-review
|
|
3
|
+
description: Review queries, pagination and background work against the performance budget.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Budget (plan section 13): list with two relations p95 < 300 ms, form save < 200 ms,
|
|
7
|
+
cached Ability build < 5 ms, on 100,000 seeded rows and 50 concurrent users.
|
|
8
|
+
|
|
9
|
+
Check, citing file and line:
|
|
10
|
+
|
|
11
|
+
- Lists go through `ResourceService.list`: keyset pagination, limit ≤ 100, selected
|
|
12
|
+
columns only, belongsTo preloaded in one query per relation; no query in a loop.
|
|
13
|
+
- Custom queries have supporting indexes (foreign keys, `(org_unit_id, deleted_at)`,
|
|
14
|
+
sort columns used by saved views); `EXPLAIN` shows no sequential scan on large
|
|
15
|
+
tables for the common filters.
|
|
16
|
+
- Save paths keep one transaction: record, lines, activity, field changes and outbox.
|
|
17
|
+
Anything slow (mail, HTTP, PDF, imports) runs in the worker, never inline.
|
|
18
|
+
- Listeners are idempotent and cheap or dispatch jobs; workflows do not poll.
|
|
19
|
+
- Caches (Ability, lookups, settings) are invalidated by AdulaJS's revision rules,
|
|
20
|
+
not by time alone.
|
|
21
|
+
- Run `pnpm test:medical` with `K6_BINARY` on staging-like hardware before release
|
|
22
|
+
and record the measured p95 values; never relax the thresholds.
|
|
23
|
+
|
|
24
|
+
Verdict: accept, or findings with the measurement or query plan.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: schema-review
|
|
3
|
+
description: Review migrations and resource definitions for integrity and evolution.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Check, citing file and line:
|
|
7
|
+
|
|
8
|
+
- Migrations are additive (expand/contract): no drop or rename of a column still
|
|
9
|
+
read by the previous release; AdulaJS migrations are never edited after release.
|
|
10
|
+
- Standard columns come from the generator (`id`, `org_unit_id` when scoped,
|
|
11
|
+
`created_by`, `updated_by`, timestamps, `deleted_at`, `version`, `doc_status`,
|
|
12
|
+
`amended_from_id`); they are not hand-edited.
|
|
13
|
+
- Every foreign key is indexed and `restrict` on delete (cascade only inside the
|
|
14
|
+
same module); `(org_unit_id, deleted_at)` exists for scoped tables.
|
|
15
|
+
- Unique rules are partial (`WHERE deleted_at IS NULL`); searchable fields produce
|
|
16
|
+
the generated tsvector with a GIN index.
|
|
17
|
+
- Money is bigint minor units; dates use `date`, instants `timestamptz`; changeable
|
|
18
|
+
lists are lookups, numbering uses sequences.
|
|
19
|
+
- The definition's `form`, `list`, `show` and `serialize` match the columns, and
|
|
20
|
+
generated contract tests cover 403/404/uniqueness/scope.
|
|
21
|
+
|
|
22
|
+
Verdict: accept, or blocking findings with the corrected migration.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: security-review
|
|
3
|
+
description: Review authorization, serialization and sensitive flows of a change.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Check, citing file and line:
|
|
7
|
+
|
|
8
|
+
- Every route passes authentication and the resource goes through ResourceService
|
|
9
|
+
(or `resources.access` for record features). Custom queries use `accessibleBy`;
|
|
10
|
+
nothing reads records by id without the scope and Ability checks.
|
|
11
|
+
- Responses use AdulaJS serializers; hidden and `permissionLevel` fields never leave
|
|
12
|
+
the server, including through search, sort, filters, exports, prints, history,
|
|
13
|
+
notifications, webhooks and OpenAPI.
|
|
14
|
+
- Role rules use only the six operators; nothing widens scope with an allow rule.
|
|
15
|
+
- No hand-written crypto, sessions, password or token handling. Secrets are sealed
|
|
16
|
+
with the application encryption; tokens and recovery codes are stored hashed.
|
|
17
|
+
- Outgoing HTTP (webhooks, workflow steps) targets HTTPS and cannot reach private
|
|
18
|
+
addresses in production; payloads carry identifiers, not record fields.
|
|
19
|
+
- Uploads and imports are size-limited and parsed by AdulaJS; errors never echo
|
|
20
|
+
secrets. Rate limits cover authentication, second factor and token creation.
|
|
21
|
+
- 2FA, impersonation and authentication changes are flagged for human review
|
|
22
|
+
(AGENTS rule 11); map the change to ASVS 4.0.3 V2/V3/V4 items.
|
|
23
|
+
|
|
24
|
+
Verdict: accept, or blocking findings with the exploit scenario for each.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ui-review
|
|
3
|
+
description: Review pages and components for RTL, the component system and data access.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Check, citing file and line:
|
|
7
|
+
|
|
8
|
+
- Components come from `inertia/components/ui` (installed by `node ace adula:ui add`);
|
|
9
|
+
no `shadcn add` in modules, no hand-styled native controls or homemade dialogs.
|
|
10
|
+
- Forms and record details use the shadcn Dialog (ResourceSurface) unless the user
|
|
11
|
+
asked otherwise; destructive actions confirm; edits guard against closing.
|
|
12
|
+
- RTL: `dir="rtl"`, logical properties (`ms-`, `ps-`, `text-start`), arrows follow
|
|
13
|
+
the reading direction, Latin digits in amounts per the UI preference, Arabic
|
|
14
|
+
labels and English identifiers. Dates honor the calendar preference.
|
|
15
|
+
- Generated pages are overridden only through `pages/<resource>/<mode>.tsx`.
|
|
16
|
+
- Heavy sections are deferred props or fetched after render; lists paginate with
|
|
17
|
+
the scroll prop; no page renders data the server did not serialize for the user.
|
|
18
|
+
- Accessible names exist for icon buttons, dialogs and regions; errors use
|
|
19
|
+
`role="alert"`; focus stays inside dialogs.
|
|
20
|
+
- Company identity from docs/design-identity.md is applied, not invented.
|
|
21
|
+
|
|
22
|
+
Verdict: accept, or findings with screenshots or selectors.
|
|
@@ -0,0 +1,40 @@
|
|
|
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
|
+
import { writeFile } from 'node:fs/promises';
|
|
9
|
+
import { capabilityCatalog } from '../src/commands/capabilities.js';
|
|
10
|
+
export default class Capabilities extends BaseCommand {
|
|
11
|
+
static commandName = 'adula:capabilities';
|
|
12
|
+
static description = 'Generate the capability catalog (AdulaJS features plus this project registry)';
|
|
13
|
+
static options = { startApp: true };
|
|
14
|
+
async run() {
|
|
15
|
+
let registry;
|
|
16
|
+
try {
|
|
17
|
+
;
|
|
18
|
+
({ registry } = await this.app.import('#start/modules'));
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
this.logger.warning('start/modules could not be loaded; printing AdulaJS capabilities only');
|
|
22
|
+
}
|
|
23
|
+
// Imported lazily: main.ts lists this command itself.
|
|
24
|
+
const { getMetaData } = await import('./main.js');
|
|
25
|
+
const metadata = await getMetaData();
|
|
26
|
+
const catalog = capabilityCatalog({
|
|
27
|
+
registry,
|
|
28
|
+
commands: metadata.map((command) => `${command.commandName} — ${command.description}`),
|
|
29
|
+
});
|
|
30
|
+
if (this.write) {
|
|
31
|
+
await writeFile(this.app.makePath('capabilities.md'), catalog);
|
|
32
|
+
this.logger.success('capabilities.md');
|
|
33
|
+
}
|
|
34
|
+
else
|
|
35
|
+
this.logger.log(catalog);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
__decorate([
|
|
39
|
+
flags.boolean({ description: 'Write capabilities.md at the project root' })
|
|
40
|
+
], Capabilities.prototype, "write", void 0);
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
import { fileURLToPath } from 'node:url';
|
|
3
|
+
import { diagnose, diagnoseResourceSnapshots, diagnoseOutbox, diagnoseWorkflowRoles, } from '../src/commands/doctor.js';
|
|
4
|
+
import { runtimeHealth } from '../src/core/health.js';
|
|
5
|
+
import { diagnoseAttachments } from '../src/attachments/doctor.js';
|
|
6
|
+
import { Settings } from '../src/services/settings.js';
|
|
7
|
+
import { MigrationRunner } from '@adonisjs/lucid/migration';
|
|
8
|
+
import { readFile } from 'node:fs/promises';
|
|
9
|
+
import { renamedMigration } from '../src/upgrade/legacy.js';
|
|
10
|
+
export default class Doctor extends BaseCommand {
|
|
11
|
+
static commandName = 'adula:doctor';
|
|
12
|
+
static description = 'Check AdulaJS ownership, installation and backup readiness';
|
|
13
|
+
static options = { startApp: true };
|
|
14
|
+
async run() {
|
|
15
|
+
const { default: db } = await import('@adonisjs/lucid/services/db');
|
|
16
|
+
const findings = await diagnose(fileURLToPath(this.app.appRoot), new Settings(db.connection().getWriteClient()), this.app.inProduction, process.env);
|
|
17
|
+
findings.push(await diagnoseAttachments(db.connection().getWriteClient()));
|
|
18
|
+
findings.push(diagnoseOutbox(await runtimeHealth(db.connection().getWriteClient())));
|
|
19
|
+
const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
|
|
20
|
+
const missing = migrations.filter((entry) => entry.status === 'corrupt');
|
|
21
|
+
const pending = migrations.filter((entry) => entry.status === 'pending');
|
|
22
|
+
const legacy = missing.some((entry) => renamedMigration(entry.name));
|
|
23
|
+
findings.push({
|
|
24
|
+
check: 'database.migrations',
|
|
25
|
+
status: missing.length ? 'fail' : pending.length ? 'warn' : 'pass',
|
|
26
|
+
message: legacy
|
|
27
|
+
? 'The migration history still names the 1.x package; run node ace adula:upgrade before migration:run'
|
|
28
|
+
: missing.length
|
|
29
|
+
? `Applied migration files are missing: ${missing.map((entry) => entry.name).join(', ')}`
|
|
30
|
+
: pending.length
|
|
31
|
+
? `${pending.length} pending migrations; run migration:run after the deployment backup`
|
|
32
|
+
: 'Migration files and database history agree',
|
|
33
|
+
});
|
|
34
|
+
const sources = [];
|
|
35
|
+
for (const entry of pending)
|
|
36
|
+
for (const extension of ['.ts', '.js'])
|
|
37
|
+
try {
|
|
38
|
+
const file = `${entry.name}${extension}`;
|
|
39
|
+
sources.push({ file, source: await readFile(this.app.makePath(file), 'utf8') });
|
|
40
|
+
break;
|
|
41
|
+
}
|
|
42
|
+
catch { }
|
|
43
|
+
let registry;
|
|
44
|
+
try {
|
|
45
|
+
;
|
|
46
|
+
({ registry } = await this.app.import('#start/modules'));
|
|
47
|
+
}
|
|
48
|
+
catch { }
|
|
49
|
+
if (registry) {
|
|
50
|
+
// Before the 1.1 migrations run, roles have no key column yet (an unfinished upgrade).
|
|
51
|
+
const keyed = await db.connection().getWriteClient().schema.hasColumn('roles', 'key');
|
|
52
|
+
const roles = await db.from('roles').select(keyed ? ['key', 'name'] : ['name']);
|
|
53
|
+
findings.push(diagnoseWorkflowRoles(registry.workflows(), roles.map((role) => ({
|
|
54
|
+
key: role.key ? String(role.key) : null,
|
|
55
|
+
name: String(role.name),
|
|
56
|
+
}))));
|
|
57
|
+
}
|
|
58
|
+
if (registry)
|
|
59
|
+
findings.push(diagnoseResourceSnapshots(sources, (name) => {
|
|
60
|
+
try {
|
|
61
|
+
return registry.get(name);
|
|
62
|
+
}
|
|
63
|
+
catch {
|
|
64
|
+
return undefined;
|
|
65
|
+
}
|
|
66
|
+
}));
|
|
67
|
+
for (const finding of findings)
|
|
68
|
+
this.logger.log(`${finding.status.toUpperCase()} ${finding.check}: ${finding.message}`);
|
|
69
|
+
if (findings.some((finding) => finding.status === 'fail'))
|
|
70
|
+
this.exitCode = 1;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { BaseCommand } from '@adonisjs/core/ace';
|
|
2
|
+
/** Collects GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
|
|
3
|
+
export default class Gaps extends BaseCommand {
|
|
4
|
+
static commandName: string;
|
|
5
|
+
static description: string;
|
|
6
|
+
static options: {
|
|
7
|
+
startApp: boolean;
|
|
8
|
+
};
|
|
9
|
+
action: string;
|
|
10
|
+
yes: boolean;
|
|
11
|
+
run(): Promise<void>;
|
|
12
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
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 { readFile } from 'node:fs/promises';
|
|
9
|
+
import { gapReport } from '../src/commands/gap_report.js';
|
|
10
|
+
import { LEGACY_FILES } from '../src/upgrade/legacy.js';
|
|
11
|
+
/** Collects GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
|
|
12
|
+
export default class Gaps extends BaseCommand {
|
|
13
|
+
static commandName = 'adula:gaps';
|
|
14
|
+
static description = 'Show the project gap report with private names masked, and links that open the AdulaJS gap form prefilled';
|
|
15
|
+
static options = { startApp: false };
|
|
16
|
+
async run() {
|
|
17
|
+
if (this.action !== 'report')
|
|
18
|
+
throw new Error('Usage: adula:gaps report [--yes]');
|
|
19
|
+
const path = this.app.makePath('GAPS.md');
|
|
20
|
+
let content;
|
|
21
|
+
try {
|
|
22
|
+
content = await readFile(path, 'utf8');
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
// Until adula:upgrade renames it, a 1.x application keeps its gap log under the old name.
|
|
26
|
+
const [legacy] = LEGACY_FILES.gaps;
|
|
27
|
+
try {
|
|
28
|
+
content = await readFile(this.app.makePath(legacy), 'utf8');
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
throw new Error('GAPS.md does not exist; adula:install creates it');
|
|
32
|
+
}
|
|
33
|
+
this.logger.warning(`Reading ${legacy}; run adula:upgrade to rename it to GAPS.md`);
|
|
34
|
+
}
|
|
35
|
+
const { masked, gaps } = gapReport(content);
|
|
36
|
+
this.logger.info(`${gaps.length} gap(s) recorded in GAPS.md`);
|
|
37
|
+
for (const gap of gaps)
|
|
38
|
+
this.logger.log(` ${gap.title}${gap.issue ? ` (reported: ${gap.issue})` : ''}`);
|
|
39
|
+
if (!this.yes) {
|
|
40
|
+
const confirmed = await this.prompt.confirm('Show the full masked report and the issue links? Nothing is sent anywhere by this command.');
|
|
41
|
+
if (!confirmed)
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
this.logger.log(masked);
|
|
45
|
+
const pending = gaps.filter((gap) => gap.url);
|
|
46
|
+
if (!pending.length)
|
|
47
|
+
return;
|
|
48
|
+
this.logger.info('Review each link in a browser, submit the form, then write the issue number in the entry as "Issue: #<number>".');
|
|
49
|
+
for (const gap of pending) {
|
|
50
|
+
this.logger.log(`\n${gap.title}`);
|
|
51
|
+
if (gap.missing.length)
|
|
52
|
+
this.logger.warning(`Complete before submitting: ${gap.missing.join(', ')}`);
|
|
53
|
+
this.logger.log(gap.url);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
__decorate([
|
|
58
|
+
args.string({ description: 'report' })
|
|
59
|
+
], Gaps.prototype, "action", void 0);
|
|
60
|
+
__decorate([
|
|
61
|
+
flags.boolean({ description: 'Print without asking for confirmation' })
|
|
62
|
+
], Gaps.prototype, "yes", void 0);
|