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.
Files changed (269) hide show
  1. package/README.md +149 -18
  2. package/build/agent/AGENTS.template.md +4 -4
  3. package/build/agent/capabilities.md +22 -12
  4. package/build/agent/skills/adula-frontend-design/SKILL.md +6 -4
  5. package/build/agent/skills/idea-review/SKILL.md +2 -2
  6. package/build/commands/adula_assistant_prune.d.ts +10 -0
  7. package/build/commands/adula_assistant_prune.js +12 -0
  8. package/build/commands/adula_outbox.d.ts +10 -0
  9. package/build/commands/adula_outbox.js +11 -0
  10. package/build/commands/adula_restore_reconcile.d.ts +10 -0
  11. package/build/commands/adula_restore_reconcile.js +34 -0
  12. package/build/commands/adula_runtime_health.d.ts +10 -0
  13. package/build/commands/adula_runtime_health.js +27 -0
  14. package/build/commands/adula_uploads_prune.d.ts +10 -0
  15. package/build/commands/adula_uploads_prune.js +16 -0
  16. package/build/commands/app.d.ts +10 -0
  17. package/build/commands/app.js +64 -0
  18. package/build/commands/backup_create.d.ts +11 -0
  19. package/build/commands/backup_create.js +99 -0
  20. package/build/commands/backup_open.d.ts +16 -0
  21. package/build/commands/backup_open.js +48 -0
  22. package/build/commands/backup_restore_files.d.ts +11 -0
  23. package/build/commands/backup_restore_files.js +44 -0
  24. package/build/commands/backup_restore_test.d.ts +12 -0
  25. package/build/commands/backup_restore_test.js +188 -0
  26. package/build/commands/backup_seal.d.ts +12 -0
  27. package/build/commands/backup_seal.js +36 -0
  28. package/build/commands/backup_services.d.ts +33 -0
  29. package/build/commands/backup_services.js +6 -0
  30. package/build/commands/backup_verify.d.ts +9 -0
  31. package/build/commands/backup_verify.js +59 -0
  32. package/build/commands/backup_verify_snapshot.d.ts +10 -0
  33. package/build/commands/backup_verify_snapshot.js +37 -0
  34. package/build/commands/client.d.ts +16 -0
  35. package/build/commands/client.js +71 -0
  36. package/build/commands/doctor.js +21 -1
  37. package/build/commands/install.d.ts +8 -0
  38. package/build/commands/install.js +69 -45
  39. package/build/commands/main.d.ts +3 -2
  40. package/build/commands/main.js +32 -0
  41. package/build/commands/module_add.js +4 -20
  42. package/build/commands/resource.d.ts +2 -0
  43. package/build/commands/resource.js +12 -3
  44. package/build/commands/resource_migration.d.ts +15 -0
  45. package/build/commands/resource_migration.js +81 -0
  46. package/build/commands/resource_snapshot.d.ts +2 -0
  47. package/build/commands/resource_snapshot.js +21 -4
  48. package/build/commands/sla_evaluate.d.ts +14 -0
  49. package/build/commands/sla_evaluate.js +16 -0
  50. package/build/commands/ui.js +4 -2
  51. package/build/commands/ui_css.d.ts +9 -0
  52. package/build/commands/ui_css.js +19 -0
  53. package/build/commands/upgrade.d.ts +1 -1
  54. package/build/commands/upgrade.js +1 -1
  55. package/build/configure.js +1 -1
  56. package/build/database/migrations/1770000000020_two_factor.d.ts +5 -0
  57. package/build/database/migrations/1770000000020_two_factor.js +10 -0
  58. package/build/database/migrations/1770000000041_import_modes.d.ts +5 -0
  59. package/build/database/migrations/1770000000041_import_modes.js +10 -0
  60. package/build/database/migrations/1770000000042_sync_jobs.d.ts +5 -0
  61. package/build/database/migrations/1770000000042_sync_jobs.js +10 -0
  62. package/build/database/migrations/1770000000043_notification_channels.d.ts +5 -0
  63. package/build/database/migrations/1770000000043_notification_channels.js +10 -0
  64. package/build/database/migrations/1770000000044_channel_confirmations.d.ts +5 -0
  65. package/build/database/migrations/1770000000044_channel_confirmations.js +10 -0
  66. package/build/database/migrations/1770000000045_import_leases.d.ts +5 -0
  67. package/build/database/migrations/1770000000045_import_leases.js +10 -0
  68. package/build/database/migrations/1770000000046_workflow_delegation_sla.d.ts +5 -0
  69. package/build/database/migrations/1770000000046_workflow_delegation_sla.js +10 -0
  70. package/build/database/migrations/1770000000049_print_templates.d.ts +5 -0
  71. package/build/database/migrations/1770000000049_print_templates.js +10 -0
  72. package/build/database/migrations/1770000000051_comment_notifications.d.ts +5 -0
  73. package/build/database/migrations/1770000000051_comment_notifications.js +10 -0
  74. package/build/database/migrations/1770000000054_cloud_backups.d.ts +5 -0
  75. package/build/database/migrations/1770000000054_cloud_backups.js +10 -0
  76. package/build/database/migrations/1770000000055_ai_assistant.d.ts +5 -0
  77. package/build/database/migrations/1770000000055_ai_assistant.js +10 -0
  78. package/build/database/migrations/1770000000056_appearance.d.ts +5 -0
  79. package/build/database/migrations/1770000000056_appearance.js +10 -0
  80. package/build/index.d.ts +87 -11
  81. package/build/index.js +50 -7
  82. package/build/providers/adula_provider.d.ts +2 -0
  83. package/build/providers/adula_provider.js +7 -0
  84. package/build/src/admin/contracts.js +1 -1
  85. package/build/src/admin/controller.d.ts +14 -1
  86. package/build/src/admin/controller.js +91 -13
  87. package/build/src/admin/errors.d.ts +32 -0
  88. package/build/src/admin/errors.js +63 -1
  89. package/build/src/admin/presentation.d.ts +21 -2
  90. package/build/src/admin/resource/editor.d.ts +60 -0
  91. package/build/src/admin/resource/editor.js +345 -0
  92. package/build/src/admin/resource/export.d.ts +54 -0
  93. package/build/src/admin/resource/export.js +262 -0
  94. package/build/src/admin/resource/lifecycle.d.ts +23 -0
  95. package/build/src/admin/resource/lifecycle.js +91 -0
  96. package/build/src/admin/resource/query.d.ts +111 -0
  97. package/build/src/admin/resource/query.js +595 -0
  98. package/build/src/admin/resource/read.d.ts +109 -0
  99. package/build/src/admin/resource/read.js +388 -0
  100. package/build/src/admin/resource/shared.d.ts +93 -0
  101. package/build/src/admin/resource/shared.js +265 -0
  102. package/build/src/admin/resource/trash.d.ts +10 -0
  103. package/build/src/admin/resource/trash.js +56 -0
  104. package/build/src/admin/resource/write.d.ts +57 -0
  105. package/build/src/admin/resource/write.js +603 -0
  106. package/build/src/admin/resource_service.d.ts +80 -193
  107. package/build/src/admin/resource_service.js +81 -1343
  108. package/build/src/admin/resource_tools.d.ts +111 -0
  109. package/build/src/admin/resource_tools.js +139 -0
  110. package/build/src/ai/assistant.d.ts +100 -0
  111. package/build/src/ai/assistant.js +487 -0
  112. package/build/src/ai/client.d.ts +49 -0
  113. package/build/src/ai/client.js +85 -0
  114. package/build/src/ai/prompt.d.ts +23 -0
  115. package/build/src/ai/prompt.js +83 -0
  116. package/build/src/ai/settings.d.ts +56 -0
  117. package/build/src/ai/settings.js +214 -0
  118. package/build/src/ai/usage.d.ts +16 -0
  119. package/build/src/ai/usage.js +33 -0
  120. package/build/src/appearance/appearance.d.ts +134 -0
  121. package/build/src/appearance/appearance.js +461 -0
  122. package/build/src/appearance/colors.d.ts +43 -0
  123. package/build/src/appearance/colors.js +99 -0
  124. package/build/src/appearance/logo.d.ts +32 -0
  125. package/build/src/appearance/logo.js +112 -0
  126. package/build/src/attachments/attachment_service.d.ts +46 -2
  127. package/build/src/attachments/attachment_service.js +96 -4
  128. package/build/src/auth/actor_store.d.ts +5 -1
  129. package/build/src/auth/actor_store.js +8 -4
  130. package/build/src/auth/conditions.d.ts +5 -0
  131. package/build/src/auth/conditions.js +26 -3
  132. package/build/src/auth/sql.js +17 -5
  133. package/build/src/auth/two_factor.d.ts +96 -0
  134. package/build/src/auth/two_factor.js +259 -0
  135. package/build/src/backups/archive.d.ts +52 -0
  136. package/build/src/backups/archive.js +362 -0
  137. package/build/src/backups/cloud_backups.d.ts +133 -0
  138. package/build/src/backups/cloud_backups.js +650 -0
  139. package/build/src/backups/doctor.d.ts +7 -0
  140. package/build/src/backups/doctor.js +55 -0
  141. package/build/src/backups/providers.d.ts +81 -0
  142. package/build/src/backups/providers.js +470 -0
  143. package/build/src/collaboration/assignments.d.ts +59 -2
  144. package/build/src/collaboration/assignments.js +196 -74
  145. package/build/src/collaboration/record_collaboration.d.ts +21 -4
  146. package/build/src/collaboration/record_collaboration.js +126 -51
  147. package/build/src/collaboration/shared.d.ts +24 -0
  148. package/build/src/collaboration/shared.js +34 -0
  149. package/build/src/commands/app_scaffold.d.ts +72 -0
  150. package/build/src/commands/app_scaffold.js +285 -0
  151. package/build/src/commands/capabilities.js +35 -9
  152. package/build/src/commands/doctor.d.ts +24 -2
  153. package/build/src/commands/doctor.js +81 -6
  154. package/build/src/commands/gap_report.d.ts +1 -1
  155. package/build/src/commands/gap_report.js +2 -2
  156. package/build/src/commands/generator.d.ts +37 -1
  157. package/build/src/commands/generator.js +61 -18
  158. package/build/src/commands/snapshot.d.ts +24 -13
  159. package/build/src/commands/snapshot.js +54 -14
  160. package/build/src/commands/source_markers.d.ts +10 -0
  161. package/build/src/commands/source_markers.js +29 -0
  162. package/build/src/core/activity.d.ts +2 -0
  163. package/build/src/core/activity.js +7 -1
  164. package/build/src/core/administrators.d.ts +38 -0
  165. package/build/src/core/administrators.js +145 -0
  166. package/build/src/core/avatar_image.d.ts +33 -0
  167. package/build/src/core/avatar_image.js +278 -0
  168. package/build/src/core/html_sanitizer.d.ts +20 -0
  169. package/build/src/core/html_sanitizer.js +261 -0
  170. package/build/src/core/like.d.ts +5 -0
  171. package/build/src/core/like.js +5 -0
  172. package/build/src/core/lookups.d.ts +80 -0
  173. package/build/src/core/lookups.js +319 -0
  174. package/build/src/core/mail_settings.d.ts +83 -0
  175. package/build/src/core/mail_settings.js +274 -0
  176. package/build/src/core/mail_test.d.ts +16 -0
  177. package/build/src/core/mail_test.js +81 -6
  178. package/build/src/core/message_templates.d.ts +15 -2
  179. package/build/src/core/message_templates.js +81 -11
  180. package/build/src/core/module_seed.js +2 -1
  181. package/build/src/core/notification_channels.d.ts +235 -0
  182. package/build/src/core/notification_channels.js +660 -0
  183. package/build/src/core/roles.js +26 -9
  184. package/build/src/core/saved_views.d.ts +8 -1
  185. package/build/src/core/saved_views.js +91 -26
  186. package/build/src/core/sequences.d.ts +32 -0
  187. package/build/src/core/sequences.js +97 -0
  188. package/build/src/core/settings.d.ts +5 -0
  189. package/build/src/core/settings.js +31 -3
  190. package/build/src/core/template_language.d.ts +61 -0
  191. package/build/src/core/template_language.js +141 -0
  192. package/build/src/core/ui_preferences.d.ts +10 -0
  193. package/build/src/core/ui_preferences.js +15 -1
  194. package/build/src/core/user_avatars.d.ts +79 -0
  195. package/build/src/core/user_avatars.js +186 -0
  196. package/build/src/core/user_invitations.d.ts +5 -1
  197. package/build/src/core/user_invitations.js +7 -1
  198. package/build/src/core/user_preferences.d.ts +36 -0
  199. package/build/src/core/user_preferences.js +125 -0
  200. package/build/src/core/users.d.ts +2 -0
  201. package/build/src/core/users.js +5 -3
  202. package/build/src/database/calendar_days.d.ts +19 -0
  203. package/build/src/database/calendar_days.js +36 -0
  204. package/build/src/database/schema.d.ts +201 -2
  205. package/build/src/database/schema.js +713 -59
  206. package/build/src/database/schema_diff.d.ts +70 -0
  207. package/build/src/database/schema_diff.js +190 -0
  208. package/build/src/events/record_mutation.d.ts +2 -1
  209. package/build/src/events/record_mutation.js +1 -0
  210. package/build/src/integrations/api_client.d.ts +37 -0
  211. package/build/src/integrations/api_client.js +567 -0
  212. package/build/src/integrations/import_adapters.d.ts +37 -0
  213. package/build/src/integrations/import_adapters.js +35 -0
  214. package/build/src/integrations/imports.d.ts +130 -16
  215. package/build/src/integrations/imports.js +434 -73
  216. package/build/src/integrations/openapi.d.ts +3 -1
  217. package/build/src/integrations/openapi.js +465 -31
  218. package/build/src/integrations/outbound.d.ts +94 -0
  219. package/build/src/integrations/outbound.js +276 -0
  220. package/build/src/integrations/print.d.ts +22 -1
  221. package/build/src/integrations/print.js +68 -22
  222. package/build/src/integrations/print_templates.d.ts +216 -0
  223. package/build/src/integrations/print_templates.js +1017 -0
  224. package/build/src/integrations/sync_jobs.d.ts +139 -0
  225. package/build/src/integrations/sync_jobs.js +416 -0
  226. package/build/src/integrations/webhooks.d.ts +12 -12
  227. package/build/src/integrations/webhooks.js +34 -43
  228. package/build/src/integrations/xlsx.d.ts +41 -0
  229. package/build/src/integrations/xlsx.js +519 -0
  230. package/build/src/languages/ar.d.ts +11 -0
  231. package/build/src/languages/ar.js +358 -0
  232. package/build/src/languages/ar_ui.d.ts +461 -0
  233. package/build/src/languages/ar_ui.js +464 -0
  234. package/build/src/languages/catalog.d.ts +66 -0
  235. package/build/src/languages/catalog.js +152 -0
  236. package/build/src/languages/en.d.ts +7 -0
  237. package/build/src/languages/en.js +352 -0
  238. package/build/src/languages/en_ui.d.ts +3 -0
  239. package/build/src/languages/en_ui.js +458 -0
  240. package/build/src/languages/validation.d.ts +26 -0
  241. package/build/src/languages/validation.js +60 -0
  242. package/build/src/lists/bulk_actions.d.ts +89 -0
  243. package/build/src/lists/bulk_actions.js +268 -0
  244. package/build/src/lists/dashboards.d.ts +138 -0
  245. package/build/src/lists/dashboards.js +290 -0
  246. package/build/src/mcp/tools.js +9 -104
  247. package/build/src/resource/define_resource.d.ts +18 -1
  248. package/build/src/resource/define_resource.js +212 -18
  249. package/build/src/resource/definition.d.ts +44 -0
  250. package/build/src/resource/definition.js +171 -0
  251. package/build/src/resource/registry.js +15 -4
  252. package/build/src/resource/types.d.ts +313 -16
  253. package/build/src/resource/values.d.ts +56 -1
  254. package/build/src/resource/values.js +237 -5
  255. package/build/src/services/settings.d.ts +2 -0
  256. package/build/src/services/settings.js +5 -1
  257. package/build/src/upgrade/legacy.js +2 -2
  258. package/build/src/workflows/calendar.d.ts +9 -0
  259. package/build/src/workflows/calendar.js +44 -0
  260. package/build/src/workflows/define_workflow.d.ts +48 -3
  261. package/build/src/workflows/define_workflow.js +57 -13
  262. package/build/src/workflows/delegations.d.ts +107 -0
  263. package/build/src/workflows/delegations.js +326 -0
  264. package/build/src/workflows/engine.d.ts +80 -4
  265. package/build/src/workflows/engine.js +466 -86
  266. package/build/src/workflows/sla.d.ts +15 -0
  267. package/build/src/workflows/sla.js +8 -0
  268. package/build/stubs/resource_contract.txt +12 -1
  269. package/package.json +9 -2
@@ -0,0 +1,70 @@
1
+ import type { Knex } from 'knex';
2
+ import type { Resource } from '../resource/types.js';
3
+ import { type ResourceAddition, type ResourceColumn, type ResourceJoinTable, type ResourceTableDefinition, type ResourceUniqueIndex } from './schema.js';
4
+ /** What the live database lacks or holds differently from a definition's resourceSchema. */
5
+ export type SchemaDrift = {
6
+ table: string;
7
+ /** The table itself does not exist (its create-migration has not run). */
8
+ missingTable: boolean;
9
+ missingColumns: ResourceColumn[];
10
+ /** Columns whose PostgreSQL type differs (varchar lengths are not compared). */
11
+ wrongTypes: {
12
+ column: string;
13
+ expected: string;
14
+ actual: string;
15
+ }[];
16
+ /**
17
+ * Field columns that are NOT NULL while the definition lets them be empty (for example
18
+ * a required field that gained `visibleWhen`). Only this relaxing direction is reported:
19
+ * NOT NULL is never added automatically.
20
+ */
21
+ notNullColumns: string[];
22
+ missingUnique: ResourceUniqueIndex[];
23
+ /**
24
+ * Unique indexes of a submittable table whose predicate still counts cancelled
25
+ * documents (created before cancelled documents were excluded): `index` is the live
26
+ * index name, `expected` the index the definition wants instead.
27
+ */
28
+ staleUnique: {
29
+ index: string;
30
+ expected: ResourceUniqueIndex;
31
+ }[];
32
+ missingJoinTables: ResourceJoinTable[];
33
+ };
34
+ /**
35
+ * Compares the live table (resolved through the connection's search_path) with what the
36
+ * definition expects: missing columns, different types, NOT NULL columns the definition
37
+ * lets be empty, missing unique indexes (by column set, whatever their name), unique
38
+ * indexes that still count cancelled documents and missing join tables. Nothing is changed.
39
+ */
40
+ export declare function schemaDrift(db: Knex, resource: ResourceTableDefinition): Promise<SchemaDrift>;
41
+ /** Whether a drift needs nothing. */
42
+ export declare function inSync(drift: SchemaDrift): boolean;
43
+ /** Whether adula:resource:migration has something to write for a drift. */
44
+ export declare function migratable(drift: SchemaDrift): boolean;
45
+ /** One line per difference, for adula:doctor and adula:resource:migration. */
46
+ export declare function describeDrift(drift: SchemaDrift): string[];
47
+ /**
48
+ * The migration content for a drift: snapshots of the fields whose column or join table
49
+ * is missing, the missing unique indexes not created with those fields, and the relaxing
50
+ * changes (NOT NULL dropped, unique indexes recreated without cancelled documents). Wrong
51
+ * types are never changed and NOT NULL is never added automatically; they need a
52
+ * hand-written migration.
53
+ */
54
+ export declare function resourceAddition(resource: Pick<Resource, 'fields'>, drift: SchemaDrift): ResourceAddition;
55
+ /**
56
+ * Standard columns the definition expects but the table lacks. alterResourceTable adds
57
+ * field columns only; for the `version` column of `version: true` (#138) the generated
58
+ * migration adds it with a fixed statement (existing rows start at version 1). The other
59
+ * standard columns (org_unit_id, doc_status, ...) carry meaning no default can supply,
60
+ * so they are reported for a hand-written expand migration.
61
+ */
62
+ export declare function missingStandardColumns(drift: SchemaDrift): {
63
+ statements: string[];
64
+ unsupported: string[];
65
+ };
66
+ /**
67
+ * The source of a migration that runs `statements` (from missingStandardColumns), then
68
+ * applies `addition` with alterResourceTable.
69
+ */
70
+ export declare function additionMigrationSource(name: string, addition: ResourceAddition, statements?: readonly string[]): string;
@@ -0,0 +1,190 @@
1
+ import { resourceSchema, } from './schema.js';
2
+ import { fieldSnapshot } from '../commands/snapshot.js';
3
+ /** varchar(n) lengths may be widened by hand; only the base type is compared. */
4
+ const comparable = (type) => type.replace(/^character varying\(\d+\)$/, 'character varying');
5
+ async function liveColumns(db, table) {
6
+ const result = await db.raw(`SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type,
7
+ a.attnotnull AS not_null
8
+ FROM pg_attribute a
9
+ WHERE a.attrelid = to_regclass(?) AND a.attnum > 0 AND NOT a.attisdropped`, [table]);
10
+ return new Map(result.rows.map((row) => [
11
+ row.name,
12
+ { type: row.type, notNull: row.not_null },
13
+ ]));
14
+ }
15
+ async function liveUniqueIndexes(db, table) {
16
+ const result = await db.raw(`SELECT i.relname AS name, pg_get_expr(x.indpred, x.indrelid) AS predicate,
17
+ array_agg(a.attname::text ORDER BY k.ord) AS columns
18
+ FROM pg_index x
19
+ JOIN pg_class i ON i.oid = x.indexrelid
20
+ CROSS JOIN LATERAL unnest(x.indkey) WITH ORDINALITY AS k(attnum, ord)
21
+ JOIN pg_attribute a ON a.attrelid = x.indrelid AND a.attnum = k.attnum
22
+ WHERE x.indrelid = to_regclass(?) AND x.indisunique
23
+ GROUP BY x.indexrelid, i.relname, x.indpred, x.indrelid`, [table]);
24
+ return result.rows.map((row) => ({
25
+ name: row.name,
26
+ predicate: row.predicate ?? '',
27
+ key: [...row.columns].sort().join(','),
28
+ }));
29
+ }
30
+ async function exists(db, table) {
31
+ const result = await db.raw('SELECT to_regclass(?) IS NOT NULL AS present', [table]);
32
+ return Boolean(result.rows[0]?.present);
33
+ }
34
+ /**
35
+ * Compares the live table (resolved through the connection's search_path) with what the
36
+ * definition expects: missing columns, different types, NOT NULL columns the definition
37
+ * lets be empty, missing unique indexes (by column set, whatever their name), unique
38
+ * indexes that still count cancelled documents and missing join tables. Nothing is changed.
39
+ */
40
+ export async function schemaDrift(db, resource) {
41
+ const expected = resourceSchema(resource);
42
+ const drift = {
43
+ table: expected.table,
44
+ missingTable: false,
45
+ missingColumns: [],
46
+ wrongTypes: [],
47
+ notNullColumns: [],
48
+ missingUnique: [],
49
+ staleUnique: [],
50
+ missingJoinTables: [],
51
+ };
52
+ if (!(await exists(db, expected.table)))
53
+ return { ...drift, missingTable: true };
54
+ const columns = await liveColumns(db, expected.table);
55
+ for (const column of expected.columns) {
56
+ const actual = columns.get(column.name);
57
+ if (actual === undefined) {
58
+ drift.missingColumns.push(column);
59
+ continue;
60
+ }
61
+ if (comparable(actual.type) !== comparable(column.type))
62
+ drift.wrongTypes.push({ column: column.name, expected: column.type, actual: actual.type });
63
+ if (column.field !== null && column.nullable && actual.notNull)
64
+ drift.notNullColumns.push(column.name);
65
+ }
66
+ const unique = await liveUniqueIndexes(db, expected.table);
67
+ for (const index of expected.unique) {
68
+ const key = [...index.columns].sort().join(',');
69
+ const matches = unique.filter((live) => live.key === key);
70
+ if (!matches.length)
71
+ drift.missingUnique.push(index);
72
+ else if (index.excludeCancelled)
73
+ // Only AdulaJS's own partial indexes over live rows are recreated; a hand-made
74
+ // index or constraint without that predicate is left to its author.
75
+ for (const live of matches)
76
+ if (/\bdeleted_at IS NULL\b/.test(live.predicate) && !/\bdoc_status\b/.test(live.predicate))
77
+ drift.staleUnique.push({ index: live.name, expected: index });
78
+ }
79
+ for (const join of expected.joinTables)
80
+ if (!(await exists(db, join.table)))
81
+ drift.missingJoinTables.push(join);
82
+ return drift;
83
+ }
84
+ /** Whether a drift needs nothing. */
85
+ export function inSync(drift) {
86
+ return !drift.wrongTypes.length && !migratable(drift) && !drift.missingTable;
87
+ }
88
+ /** Whether adula:resource:migration has something to write for a drift. */
89
+ export function migratable(drift) {
90
+ return (!drift.missingTable &&
91
+ Boolean(drift.missingColumns.length ||
92
+ drift.notNullColumns.length ||
93
+ drift.missingUnique.length ||
94
+ drift.staleUnique.length ||
95
+ drift.missingJoinTables.length));
96
+ }
97
+ /** One line per difference, for adula:doctor and adula:resource:migration. */
98
+ export function describeDrift(drift) {
99
+ if (drift.missingTable)
100
+ return [`${drift.table}: table is missing`];
101
+ return [
102
+ ...drift.missingColumns.map((column) => `${drift.table}.${column.name}: column is missing`),
103
+ ...drift.wrongTypes.map((entry) => `${drift.table}.${entry.column}: type is ${entry.actual}, expected ${entry.expected}`),
104
+ ...drift.notNullColumns.map((column) => `${drift.table}.${column}: column is NOT NULL, but the definition lets it be empty (optional or visibleWhen)`),
105
+ ...drift.missingUnique.map((index) => `${drift.table}: unique index on (${index.columns.join(', ')}) is missing`),
106
+ ...drift.staleUnique.map((entry) => `${drift.table}: unique index ${entry.index} on (${entry.expected.columns.join(', ')}) still counts cancelled documents`),
107
+ ...drift.missingJoinTables.map((join) => `${join.table}: join table of ${drift.table}.${join.field} is missing`),
108
+ ];
109
+ }
110
+ /**
111
+ * The migration content for a drift: snapshots of the fields whose column or join table
112
+ * is missing, the missing unique indexes not created with those fields, and the relaxing
113
+ * changes (NOT NULL dropped, unique indexes recreated without cancelled documents). Wrong
114
+ * types are never changed and NOT NULL is never added automatically; they need a
115
+ * hand-written migration.
116
+ */
117
+ export function resourceAddition(resource, drift) {
118
+ const fields = {};
119
+ for (const column of drift.missingColumns)
120
+ if (column.field)
121
+ fields[column.field] = fieldSnapshot(resource.fields[column.field]);
122
+ for (const join of drift.missingJoinTables)
123
+ fields[join.field] = fieldSnapshot(resource.fields[join.field]);
124
+ const unique = drift.missingUnique
125
+ .filter((index) => !(index.fields.length === 1 && index.fields[0] in fields))
126
+ .map((index) => index.columns);
127
+ const recreateUnique = drift.staleUnique.map((entry) => ({
128
+ index: entry.index,
129
+ columns: entry.expected.columns,
130
+ }));
131
+ return {
132
+ ...(drift.notNullColumns.length ? { dropNotNull: [...drift.notNullColumns] } : {}),
133
+ ...(Object.keys(fields).length ? { fields } : {}),
134
+ ...(unique.length ? { unique } : {}),
135
+ ...(recreateUnique.length ? { recreateUnique } : {}),
136
+ };
137
+ }
138
+ /**
139
+ * Standard columns the definition expects but the table lacks. alterResourceTable adds
140
+ * field columns only; for the `version` column of `version: true` (#138) the generated
141
+ * migration adds it with a fixed statement (existing rows start at version 1). The other
142
+ * standard columns (org_unit_id, doc_status, ...) carry meaning no default can supply,
143
+ * so they are reported for a hand-written expand migration.
144
+ */
145
+ export function missingStandardColumns(drift) {
146
+ const statements = [];
147
+ const unsupported = [];
148
+ for (const column of drift.missingColumns) {
149
+ if (column.field)
150
+ continue;
151
+ if (column.name === 'version')
152
+ statements.push(`ALTER TABLE ${drift.table} ADD COLUMN IF NOT EXISTS version integer NOT NULL DEFAULT 1`);
153
+ else
154
+ unsupported.push(column.name);
155
+ }
156
+ return { statements, unsupported };
157
+ }
158
+ /**
159
+ * The source of a migration that runs `statements` (from missingStandardColumns), then
160
+ * applies `addition` with alterResourceTable.
161
+ */
162
+ export function additionMigrationSource(name, addition, statements = []) {
163
+ const client = statements.length ? 'db' : 'this.db.getWriteClient()';
164
+ const lines = [
165
+ ...(statements.length ? [' const db = this.db.getWriteClient()'] : []),
166
+ ...statements.map((sql) => ` await db.raw(${JSON.stringify(sql)})`),
167
+ ...(Object.keys(addition).length
168
+ ? [
169
+ ` await alterResourceTable(${client}, '${name}', ${JSON.stringify(addition, null, 2)
170
+ .split('\n')
171
+ .join('\n ')})`,
172
+ ]
173
+ : []),
174
+ ];
175
+ const imports = Object.keys(addition).length ? "import { alterResourceTable } from 'adula'\n" : '';
176
+ return `import { BaseSchema } from '@adonisjs/lucid/schema'
177
+ ${imports}
178
+ // Generated by \`node ace adula:resource:migration ${name}\`: what the database lacked and
179
+ // relaxing changes only (NOT NULL dropped, unique indexes no longer counting cancelled documents).
180
+ // Immutable once it has run; later definition changes get a new migration.
181
+ export default class extends BaseSchema {
182
+ async up() {
183
+ ${lines.join('\n')}
184
+ }
185
+ async down() {
186
+ throw new Error('Use an expand/contract migration or restore a backup')
187
+ }
188
+ }
189
+ `;
190
+ }
@@ -13,7 +13,8 @@ export declare function recordMutation(trx: Knex.Transaction, mutation: {
13
13
  actorId: number;
14
14
  /** The administrator acting as actorId, when impersonating. */
15
15
  impersonatorId?: number;
16
- action: Action;
16
+ /** A resource action, or `restore` of a soft-deleted record (ADR 046). */
17
+ action: Action | 'restore';
17
18
  fields: string[];
18
19
  /** Before/after values of the changed fields; read back per viewer's field access. */
19
20
  changes?: FieldChange[];
@@ -8,6 +8,7 @@ export async function recordMutation(trx, mutation) {
8
8
  submit: 'submitted',
9
9
  cancel: 'cancelled',
10
10
  amend: 'amended',
11
+ restore: 'restored',
11
12
  };
12
13
  if (!past[mutation.action])
13
14
  throw new Error('Unsupported mutation event');
@@ -0,0 +1,37 @@
1
+ /**
2
+ * A typed API client generated from the OpenAPI document of openApiDocument(): one
3
+ * self-contained TypeScript module (no imports, no DOM or Node types) holding the
4
+ * per-resource record and input types and a small fetch-based runtime. The document
5
+ * is usually actor-filtered, so the client describes exactly what one token may use.
6
+ */
7
+ type Schema = Record<string, unknown>;
8
+ /** The parts of an OpenAPI 3.1 document the generator reads (openApiDocument's output). */
9
+ export type ApiClientDocument = {
10
+ info?: {
11
+ title?: string;
12
+ version?: string;
13
+ };
14
+ servers?: {
15
+ url: string;
16
+ }[];
17
+ paths: Record<string, Record<string, unknown>>;
18
+ components?: {
19
+ schemas?: Record<string, Schema>;
20
+ };
21
+ };
22
+ export type ApiClientOptions = {
23
+ /** Default server for createAdulaClient when no baseUrl is passed; the document's server otherwise. */
24
+ baseUrl?: string;
25
+ };
26
+ /**
27
+ * One self-contained TypeScript module for the API the document describes: record and
28
+ * input interfaces per resource, the Resources map and createAdulaClient().
29
+ */
30
+ export declare function apiClientSource(document: ApiClientDocument, options?: ApiClientOptions): string;
31
+ /** The same client as a declaration file: the types plus the runtime signatures. */
32
+ export declare function apiClientDeclarations(document: ApiClientDocument): string;
33
+ /** The clients/<name> directory of a system: its package name without scope, in kebab-case. */
34
+ export declare function apiClientName(packageName: unknown): string;
35
+ /** README.md written next to a generated client by adula:client. */
36
+ export declare function apiClientReadme(name: string, document: ApiClientDocument): string;
37
+ export {};