sqlew 3.6.9 → 3.7.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 (383) hide show
  1. package/CHANGELOG.md +398 -1
  2. package/README.md +58 -39
  3. package/assets/config.example.toml +93 -0
  4. package/assets/kanban-visualizer.png +0 -0
  5. package/assets/sample-agents/sqlew-architect.md +32 -13
  6. package/assets/sample-agents/sqlew-researcher.md +70 -17
  7. package/assets/sample-agents/sqlew-scrum-master.md +60 -25
  8. package/assets/schema.sql +2 -2
  9. package/dist/adapters/auth/auth-factory.d.ts +86 -0
  10. package/dist/adapters/auth/auth-factory.d.ts.map +1 -0
  11. package/dist/adapters/auth/auth-factory.js +103 -0
  12. package/dist/adapters/auth/auth-factory.js.map +1 -0
  13. package/dist/adapters/auth/auth-types.d.ts +30 -0
  14. package/dist/adapters/auth/auth-types.d.ts.map +1 -0
  15. package/dist/adapters/auth/auth-types.js +30 -0
  16. package/dist/adapters/auth/auth-types.js.map +1 -0
  17. package/dist/adapters/auth/base-auth-provider.d.ts +327 -0
  18. package/dist/adapters/auth/base-auth-provider.d.ts.map +1 -0
  19. package/dist/adapters/auth/base-auth-provider.js +111 -0
  20. package/dist/adapters/auth/base-auth-provider.js.map +1 -0
  21. package/dist/adapters/auth/direct-auth-provider.d.ts +356 -0
  22. package/dist/adapters/auth/direct-auth-provider.d.ts.map +1 -0
  23. package/dist/adapters/auth/direct-auth-provider.js +406 -0
  24. package/dist/adapters/auth/direct-auth-provider.js.map +1 -0
  25. package/dist/adapters/base-adapter.d.ts +638 -0
  26. package/dist/adapters/base-adapter.d.ts.map +1 -0
  27. package/dist/adapters/base-adapter.js +557 -0
  28. package/dist/adapters/base-adapter.js.map +1 -0
  29. package/dist/adapters/index.d.ts +13 -2
  30. package/dist/adapters/index.d.ts.map +1 -1
  31. package/dist/adapters/index.js +27 -5
  32. package/dist/adapters/index.js.map +1 -1
  33. package/dist/adapters/mysql-adapter.d.ts +547 -6
  34. package/dist/adapters/mysql-adapter.d.ts.map +1 -1
  35. package/dist/adapters/mysql-adapter.js +651 -32
  36. package/dist/adapters/mysql-adapter.js.map +1 -1
  37. package/dist/adapters/postgresql-adapter.d.ts +15 -4
  38. package/dist/adapters/postgresql-adapter.d.ts.map +1 -1
  39. package/dist/adapters/postgresql-adapter.js +19 -2
  40. package/dist/adapters/postgresql-adapter.js.map +1 -1
  41. package/dist/adapters/sqlite-adapter.d.ts +35 -5
  42. package/dist/adapters/sqlite-adapter.d.ts.map +1 -1
  43. package/dist/adapters/sqlite-adapter.js +57 -18
  44. package/dist/adapters/sqlite-adapter.js.map +1 -1
  45. package/dist/cli/db-dump.d.ts +32 -0
  46. package/dist/cli/db-dump.d.ts.map +1 -0
  47. package/dist/cli/db-dump.js +409 -0
  48. package/dist/cli/db-dump.js.map +1 -0
  49. package/dist/cli.js +24 -14
  50. package/dist/cli.js.map +1 -1
  51. package/dist/config/example-generator.d.ts.map +1 -1
  52. package/dist/config/example-generator.js +4 -3
  53. package/dist/config/example-generator.js.map +1 -1
  54. package/dist/config/knex/bootstrap/20251025020452_create_master_tables.d.ts.map +1 -0
  55. package/dist/{migrations → config}/knex/bootstrap/20251025020452_create_master_tables.js +7 -2
  56. package/dist/config/knex/bootstrap/20251025020452_create_master_tables.js.map +1 -0
  57. package/dist/config/knex/bootstrap/20251025021152_create_transaction_tables.d.ts.map +1 -0
  58. package/dist/{migrations → config}/knex/bootstrap/20251025021152_create_transaction_tables.js +49 -50
  59. package/dist/config/knex/bootstrap/20251025021152_create_transaction_tables.js.map +1 -0
  60. package/dist/config/knex/bootstrap/20251025021351_create_indexes.d.ts.map +1 -0
  61. package/dist/config/knex/bootstrap/20251025021351_create_indexes.js.map +1 -0
  62. package/dist/config/knex/bootstrap/20251025021416_seed_master_data.d.ts.map +1 -0
  63. package/dist/{migrations → config}/knex/bootstrap/20251025021416_seed_master_data.js +11 -6
  64. package/dist/config/knex/bootstrap/20251025021416_seed_master_data.js.map +1 -0
  65. package/dist/config/knex/bootstrap/20251025070349_create_views.d.ts.map +1 -0
  66. package/dist/{migrations → config}/knex/bootstrap/20251025070349_create_views.js +66 -14
  67. package/dist/config/knex/bootstrap/20251025070349_create_views.js.map +1 -0
  68. package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts.map +1 -0
  69. package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js +22 -0
  70. package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js.map +1 -0
  71. package/dist/config/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts.map +1 -0
  72. package/dist/config/knex/enhancements/20251025082220_fix_task_dependencies_columns.js.map +1 -0
  73. package/dist/config/knex/enhancements/20251025090000_create_help_system_tables.d.ts.map +1 -0
  74. package/dist/{migrations → config}/knex/enhancements/20251025090000_create_help_system_tables.js +6 -0
  75. package/dist/config/knex/enhancements/20251025090000_create_help_system_tables.js.map +1 -0
  76. package/dist/config/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts.map +1 -0
  77. package/dist/{migrations → config}/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js +6 -0
  78. package/dist/config/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js.map +1 -0
  79. package/dist/config/knex/enhancements/20251025100000_seed_help_metadata.d.ts.map +1 -0
  80. package/dist/{migrations → config}/knex/enhancements/20251025100000_seed_help_metadata.js +6 -0
  81. package/dist/config/knex/enhancements/20251025100000_seed_help_metadata.js.map +1 -0
  82. package/dist/config/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts.map +1 -0
  83. package/dist/config/knex/enhancements/20251025100100_seed_remaining_use_cases.js.map +1 -0
  84. package/dist/config/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts.map +1 -0
  85. package/dist/{migrations → config}/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js +7 -0
  86. package/dist/config/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js.map +1 -0
  87. package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts.map +1 -0
  88. package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.js +62 -0
  89. package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.js.map +1 -0
  90. package/dist/config/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts.map +1 -0
  91. package/dist/config/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js.map +1 -0
  92. package/dist/config/knex/enhancements/20251027020000_update_agent_reusability.d.ts.map +1 -0
  93. package/dist/{migrations → config}/knex/enhancements/20251027020000_update_agent_reusability.js +6 -0
  94. package/dist/config/knex/enhancements/20251027020000_update_agent_reusability.js.map +1 -0
  95. package/dist/config/knex/enhancements/20251028000000_simplify_agent_system.d.ts.map +1 -0
  96. package/dist/{migrations → config}/knex/enhancements/20251028000000_simplify_agent_system.js +6 -0
  97. package/dist/config/knex/enhancements/20251028000000_simplify_agent_system.js.map +1 -0
  98. package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.d.ts +13 -0
  99. package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.d.ts.map +1 -0
  100. package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.js +48 -0
  101. package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.js.map +1 -0
  102. package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.d.ts +24 -0
  103. package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.d.ts.map +1 -0
  104. package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.js +189 -0
  105. package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.js.map +1 -0
  106. package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.d.ts +16 -0
  107. package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.d.ts.map +1 -0
  108. package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.js +65 -0
  109. package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.js.map +1 -0
  110. package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.d.ts +23 -0
  111. package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.d.ts.map +1 -0
  112. package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.js +118 -0
  113. package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.js.map +1 -0
  114. package/dist/config/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts.map +1 -0
  115. package/dist/config/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js.map +1 -0
  116. package/dist/config/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts.map +1 -0
  117. package/dist/config/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js.map +1 -0
  118. package/dist/config/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts.map +1 -0
  119. package/dist/config/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js.map +1 -0
  120. package/dist/config/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts.map +1 -0
  121. package/dist/config/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js.map +1 -0
  122. package/dist/config/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts.map +1 -0
  123. package/dist/config/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js.map +1 -0
  124. package/dist/config/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts.map +1 -0
  125. package/dist/config/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js.map +1 -0
  126. package/dist/config/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts.map +1 -0
  127. package/dist/config/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js.map +1 -0
  128. package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.d.ts +49 -0
  129. package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.d.ts.map +1 -0
  130. package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.js +864 -0
  131. package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.js.map +1 -0
  132. package/dist/config/loader.d.ts +23 -3
  133. package/dist/config/loader.d.ts.map +1 -1
  134. package/dist/config/loader.js +155 -8
  135. package/dist/config/loader.js.map +1 -1
  136. package/dist/config/types.d.ts +261 -2
  137. package/dist/config/types.d.ts.map +1 -1
  138. package/dist/config/types.js.map +1 -1
  139. package/dist/config/writer.d.ts +65 -0
  140. package/dist/config/writer.d.ts.map +1 -0
  141. package/dist/config/writer.js +139 -0
  142. package/dist/config/writer.js.map +1 -0
  143. package/dist/database.d.ts +11 -2
  144. package/dist/database.d.ts.map +1 -1
  145. package/dist/database.js +65 -8
  146. package/dist/database.js.map +1 -1
  147. package/dist/index.js +186 -32
  148. package/dist/index.js.map +1 -1
  149. package/dist/knexfile.d.ts.map +1 -1
  150. package/dist/knexfile.js +88 -12
  151. package/dist/knexfile.js.map +1 -1
  152. package/dist/tests/all-features.test.js +15 -3
  153. package/dist/tests/all-features.test.js.map +1 -1
  154. package/dist/tests/config-loader.test.d.ts +6 -0
  155. package/dist/tests/config-loader.test.d.ts.map +1 -0
  156. package/dist/tests/config-loader.test.js +201 -0
  157. package/dist/tests/config-loader.test.js.map +1 -0
  158. package/dist/tests/connection-manager-integration.test.d.ts +2 -0
  159. package/dist/tests/connection-manager-integration.test.d.ts.map +1 -0
  160. package/dist/tests/connection-manager-integration.test.js +431 -0
  161. package/dist/tests/connection-manager-integration.test.js.map +1 -0
  162. package/dist/tests/connection-manager.test.d.ts +2 -0
  163. package/dist/tests/connection-manager.test.d.ts.map +1 -0
  164. package/dist/tests/connection-manager.test.js +361 -0
  165. package/dist/tests/connection-manager.test.js.map +1 -0
  166. package/dist/tests/dump-import.test.d.ts +15 -0
  167. package/dist/tests/dump-import.test.d.ts.map +1 -0
  168. package/dist/tests/dump-import.test.js +430 -0
  169. package/dist/tests/dump-import.test.js.map +1 -0
  170. package/dist/tests/migration-idempotency.test.d.ts +2 -0
  171. package/dist/tests/migration-idempotency.test.d.ts.map +1 -0
  172. package/dist/tests/migration-idempotency.test.js +330 -0
  173. package/dist/tests/migration-idempotency.test.js.map +1 -0
  174. package/dist/tests/migration-upgrade-paths.test.d.ts +2 -0
  175. package/dist/tests/migration-upgrade-paths.test.d.ts.map +1 -0
  176. package/dist/tests/migration-upgrade-paths.test.js +248 -0
  177. package/dist/tests/migration-upgrade-paths.test.js.map +1 -0
  178. package/dist/tests/multi-project-migration.test.d.ts +17 -0
  179. package/dist/tests/multi-project-migration.test.d.ts.map +1 -0
  180. package/dist/tests/multi-project-migration.test.js +399 -0
  181. package/dist/tests/multi-project-migration.test.js.map +1 -0
  182. package/dist/tests/multi-project.test.d.ts +5 -0
  183. package/dist/tests/multi-project.test.d.ts.map +1 -0
  184. package/dist/tests/multi-project.test.js +238 -0
  185. package/dist/tests/multi-project.test.js.map +1 -0
  186. package/dist/tests/schema-migration.test.d.ts +8 -0
  187. package/dist/tests/schema-migration.test.d.ts.map +1 -0
  188. package/dist/tests/schema-migration.test.js +108 -0
  189. package/dist/tests/schema-migration.test.js.map +1 -0
  190. package/dist/tests/sql-dump-converters.test.d.ts +7 -0
  191. package/dist/tests/sql-dump-converters.test.d.ts.map +1 -0
  192. package/dist/tests/sql-dump-converters.test.js +314 -0
  193. package/dist/tests/sql-dump-converters.test.js.map +1 -0
  194. package/dist/tests/sql-dump-cross-database.test.d.ts +21 -0
  195. package/dist/tests/sql-dump-cross-database.test.d.ts.map +1 -0
  196. package/dist/tests/sql-dump-cross-database.test.js +314 -0
  197. package/dist/tests/sql-dump-cross-database.test.js.map +1 -0
  198. package/dist/tests/sql-dump-default-conversions.test.d.ts +8 -0
  199. package/dist/tests/sql-dump-default-conversions.test.d.ts.map +1 -0
  200. package/dist/tests/sql-dump-default-conversions.test.js +141 -0
  201. package/dist/tests/sql-dump-default-conversions.test.js.map +1 -0
  202. package/dist/tests/sql-dump-fk-constraints.test.d.ts +13 -0
  203. package/dist/tests/sql-dump-fk-constraints.test.d.ts.map +1 -0
  204. package/dist/tests/sql-dump-fk-constraints.test.js +381 -0
  205. package/dist/tests/sql-dump-fk-constraints.test.js.map +1 -0
  206. package/dist/tests/sql-dump-indexes.test.d.ts +12 -0
  207. package/dist/tests/sql-dump-indexes.test.d.ts.map +1 -0
  208. package/dist/tests/sql-dump-indexes.test.js +269 -0
  209. package/dist/tests/sql-dump-indexes.test.js.map +1 -0
  210. package/dist/tests/sql-dump-integration.test.d.ts +16 -0
  211. package/dist/tests/sql-dump-integration.test.d.ts.map +1 -0
  212. package/dist/tests/sql-dump-integration.test.js +342 -0
  213. package/dist/tests/sql-dump-integration.test.js.map +1 -0
  214. package/dist/tests/sql-dump-table-ordering.test.d.ts +8 -0
  215. package/dist/tests/sql-dump-table-ordering.test.d.ts.map +1 -0
  216. package/dist/tests/sql-dump-table-ordering.test.js +253 -0
  217. package/dist/tests/sql-dump-table-ordering.test.js.map +1 -0
  218. package/dist/tests/tasks.link-file-backward-compat.test.js +11 -1
  219. package/dist/tests/tasks.link-file-backward-compat.test.js.map +1 -1
  220. package/dist/tests/tasks.watch-files-action.test.js +11 -1
  221. package/dist/tests/tasks.watch-files-action.test.js.map +1 -1
  222. package/dist/tests/type-conversion.test.d.ts +8 -0
  223. package/dist/tests/type-conversion.test.d.ts.map +1 -0
  224. package/dist/tests/type-conversion.test.js +312 -0
  225. package/dist/tests/type-conversion.test.js.map +1 -0
  226. package/dist/tests/utils/test-helpers.d.ts +93 -0
  227. package/dist/tests/utils/test-helpers.d.ts.map +1 -0
  228. package/dist/tests/utils/test-helpers.js +407 -0
  229. package/dist/tests/utils/test-helpers.js.map +1 -0
  230. package/dist/tools/config.d.ts +58 -0
  231. package/dist/tools/config.d.ts.map +1 -0
  232. package/dist/tools/config.js +281 -0
  233. package/dist/tools/config.js.map +1 -0
  234. package/dist/tools/constraints.d.ts.map +1 -1
  235. package/dist/tools/constraints.js +138 -122
  236. package/dist/tools/constraints.js.map +1 -1
  237. package/dist/tools/context.d.ts.map +1 -1
  238. package/dist/tools/context.js +216 -109
  239. package/dist/tools/context.js.map +1 -1
  240. package/dist/tools/files.d.ts.map +1 -1
  241. package/dist/tools/files.js +123 -102
  242. package/dist/tools/files.js.map +1 -1
  243. package/dist/tools/tasks.d.ts.map +1 -1
  244. package/dist/tools/tasks.js +583 -521
  245. package/dist/tools/tasks.js.map +1 -1
  246. package/dist/tools/utils.d.ts +5 -0
  247. package/dist/tools/utils.d.ts.map +1 -1
  248. package/dist/tools/utils.js +176 -122
  249. package/dist/tools/utils.js.map +1 -1
  250. package/dist/types.d.ts +9 -26
  251. package/dist/types.d.ts.map +1 -1
  252. package/dist/utils/cleanup.d.ts +3 -0
  253. package/dist/utils/cleanup.d.ts.map +1 -1
  254. package/dist/utils/cleanup.js +14 -2
  255. package/dist/utils/cleanup.js.map +1 -1
  256. package/dist/utils/connection-manager.d.ts +59 -0
  257. package/dist/utils/connection-manager.d.ts.map +1 -0
  258. package/dist/utils/connection-manager.js +178 -0
  259. package/dist/utils/connection-manager.js.map +1 -0
  260. package/dist/utils/debug-logger.d.ts +8 -4
  261. package/dist/utils/debug-logger.d.ts.map +1 -1
  262. package/dist/utils/debug-logger.js +27 -7
  263. package/dist/utils/debug-logger.js.map +1 -1
  264. package/dist/utils/error-handler.d.ts +12 -2
  265. package/dist/utils/error-handler.d.ts.map +1 -1
  266. package/dist/utils/error-handler.js +22 -21
  267. package/dist/utils/error-handler.js.map +1 -1
  268. package/dist/utils/parameter-validator.d.ts.map +1 -1
  269. package/dist/utils/parameter-validator.js +36 -15
  270. package/dist/utils/parameter-validator.js.map +1 -1
  271. package/dist/utils/project-context.d.ts +111 -0
  272. package/dist/utils/project-context.d.ts.map +1 -0
  273. package/dist/utils/project-context.js +187 -0
  274. package/dist/utils/project-context.js.map +1 -0
  275. package/dist/utils/project-root.d.ts +79 -0
  276. package/dist/utils/project-root.d.ts.map +1 -0
  277. package/dist/utils/project-root.js +108 -0
  278. package/dist/utils/project-root.js.map +1 -0
  279. package/dist/utils/sql-dump-converters.d.ts +188 -0
  280. package/dist/utils/sql-dump-converters.d.ts.map +1 -0
  281. package/dist/utils/sql-dump-converters.js +311 -0
  282. package/dist/utils/sql-dump-converters.js.map +1 -0
  283. package/dist/utils/sql-dump.d.ts +102 -0
  284. package/dist/utils/sql-dump.d.ts.map +1 -0
  285. package/dist/utils/sql-dump.js +1550 -0
  286. package/dist/utils/sql-dump.js.map +1 -0
  287. package/dist/utils/vcs-adapter.d.ts +42 -0
  288. package/dist/utils/vcs-adapter.d.ts.map +1 -1
  289. package/dist/utils/vcs-adapter.js +154 -0
  290. package/dist/utils/vcs-adapter.js.map +1 -1
  291. package/dist/watcher/file-watcher.d.ts.map +1 -1
  292. package/dist/watcher/file-watcher.js +48 -49
  293. package/dist/watcher/file-watcher.js.map +1 -1
  294. package/dist/watcher/gitignore-parser.d.ts.map +1 -1
  295. package/dist/watcher/gitignore-parser.js +2 -1
  296. package/dist/watcher/gitignore-parser.js.map +1 -1
  297. package/docs/BASEADAPTER_IMPLEMENTATION.md +399 -0
  298. package/docs/DATABASE_AUTH.md +445 -0
  299. package/docs/DATABASE_MIGRATION.md +247 -0
  300. package/docs/MULTI_PROJECT_ARCHITECTURE.md +497 -0
  301. package/package.json +12 -4
  302. package/dist/migrations/knex/bootstrap/20251025020452_create_master_tables.d.ts.map +0 -1
  303. package/dist/migrations/knex/bootstrap/20251025020452_create_master_tables.js.map +0 -1
  304. package/dist/migrations/knex/bootstrap/20251025021152_create_transaction_tables.d.ts.map +0 -1
  305. package/dist/migrations/knex/bootstrap/20251025021152_create_transaction_tables.js.map +0 -1
  306. package/dist/migrations/knex/bootstrap/20251025021351_create_indexes.d.ts.map +0 -1
  307. package/dist/migrations/knex/bootstrap/20251025021351_create_indexes.js.map +0 -1
  308. package/dist/migrations/knex/bootstrap/20251025021416_seed_master_data.d.ts.map +0 -1
  309. package/dist/migrations/knex/bootstrap/20251025021416_seed_master_data.js.map +0 -1
  310. package/dist/migrations/knex/bootstrap/20251025070349_create_views.d.ts.map +0 -1
  311. package/dist/migrations/knex/bootstrap/20251025070349_create_views.js.map +0 -1
  312. package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts.map +0 -1
  313. package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js +0 -15
  314. package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js.map +0 -1
  315. package/dist/migrations/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts.map +0 -1
  316. package/dist/migrations/knex/enhancements/20251025082220_fix_task_dependencies_columns.js.map +0 -1
  317. package/dist/migrations/knex/enhancements/20251025090000_create_help_system_tables.d.ts.map +0 -1
  318. package/dist/migrations/knex/enhancements/20251025090000_create_help_system_tables.js.map +0 -1
  319. package/dist/migrations/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts.map +0 -1
  320. package/dist/migrations/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js.map +0 -1
  321. package/dist/migrations/knex/enhancements/20251025100000_seed_help_metadata.d.ts.map +0 -1
  322. package/dist/migrations/knex/enhancements/20251025100000_seed_help_metadata.js.map +0 -1
  323. package/dist/migrations/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts.map +0 -1
  324. package/dist/migrations/knex/enhancements/20251025100100_seed_remaining_use_cases.js.map +0 -1
  325. package/dist/migrations/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts.map +0 -1
  326. package/dist/migrations/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js.map +0 -1
  327. package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts.map +0 -1
  328. package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.js +0 -34
  329. package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.js.map +0 -1
  330. package/dist/migrations/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts.map +0 -1
  331. package/dist/migrations/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js.map +0 -1
  332. package/dist/migrations/knex/enhancements/20251027020000_update_agent_reusability.d.ts.map +0 -1
  333. package/dist/migrations/knex/enhancements/20251027020000_update_agent_reusability.js.map +0 -1
  334. package/dist/migrations/knex/enhancements/20251028000000_simplify_agent_system.d.ts.map +0 -1
  335. package/dist/migrations/knex/enhancements/20251028000000_simplify_agent_system.js.map +0 -1
  336. package/dist/migrations/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts.map +0 -1
  337. package/dist/migrations/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js.map +0 -1
  338. package/dist/migrations/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts.map +0 -1
  339. package/dist/migrations/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js.map +0 -1
  340. package/dist/migrations/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts.map +0 -1
  341. package/dist/migrations/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js.map +0 -1
  342. package/dist/migrations/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts.map +0 -1
  343. package/dist/migrations/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js.map +0 -1
  344. package/dist/migrations/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts.map +0 -1
  345. package/dist/migrations/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js.map +0 -1
  346. package/dist/migrations/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts.map +0 -1
  347. package/dist/migrations/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js.map +0 -1
  348. package/dist/migrations/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts.map +0 -1
  349. package/dist/migrations/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js.map +0 -1
  350. /package/dist/{migrations → config}/knex/bootstrap/20251025020452_create_master_tables.d.ts +0 -0
  351. /package/dist/{migrations → config}/knex/bootstrap/20251025021152_create_transaction_tables.d.ts +0 -0
  352. /package/dist/{migrations → config}/knex/bootstrap/20251025021351_create_indexes.d.ts +0 -0
  353. /package/dist/{migrations → config}/knex/bootstrap/20251025021351_create_indexes.js +0 -0
  354. /package/dist/{migrations → config}/knex/bootstrap/20251025021416_seed_master_data.d.ts +0 -0
  355. /package/dist/{migrations → config}/knex/bootstrap/20251025070349_create_views.d.ts +0 -0
  356. /package/dist/{migrations → config}/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts +0 -0
  357. /package/dist/{migrations → config}/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts +0 -0
  358. /package/dist/{migrations → config}/knex/enhancements/20251025082220_fix_task_dependencies_columns.js +0 -0
  359. /package/dist/{migrations → config}/knex/enhancements/20251025090000_create_help_system_tables.d.ts +0 -0
  360. /package/dist/{migrations → config}/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts +0 -0
  361. /package/dist/{migrations → config}/knex/enhancements/20251025100000_seed_help_metadata.d.ts +0 -0
  362. /package/dist/{migrations → config}/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts +0 -0
  363. /package/dist/{migrations → config}/knex/enhancements/20251025100100_seed_remaining_use_cases.js +0 -0
  364. /package/dist/{migrations → config}/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts +0 -0
  365. /package/dist/{migrations → config}/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts +0 -0
  366. /package/dist/{migrations → config}/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts +0 -0
  367. /package/dist/{migrations → config}/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js +0 -0
  368. /package/dist/{migrations → config}/knex/enhancements/20251027020000_update_agent_reusability.d.ts +0 -0
  369. /package/dist/{migrations → config}/knex/enhancements/20251028000000_simplify_agent_system.d.ts +0 -0
  370. /package/dist/{migrations → config}/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts +0 -0
  371. /package/dist/{migrations → config}/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js +0 -0
  372. /package/dist/{migrations → config}/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts +0 -0
  373. /package/dist/{migrations → config}/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js +0 -0
  374. /package/dist/{migrations → config}/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts +0 -0
  375. /package/dist/{migrations → config}/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js +0 -0
  376. /package/dist/{migrations → config}/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts +0 -0
  377. /package/dist/{migrations → config}/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js +0 -0
  378. /package/dist/{migrations → config}/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts +0 -0
  379. /package/dist/{migrations → config}/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js +0 -0
  380. /package/dist/{migrations → config}/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts +0 -0
  381. /package/dist/{migrations → config}/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js +0 -0
  382. /package/dist/{migrations → config}/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts +0 -0
  383. /package/dist/{migrations → config}/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js +0 -0
@@ -0,0 +1,638 @@
1
+ /**
2
+ * @fileoverview Base adapter for database connections with authentication integration.
3
+ *
4
+ * This module provides the foundation for all database adapters in the multi-RDBMS system.
5
+ * It integrates authentication providers (SSH tunneling, direct connections, cloud IAM) with
6
+ * Knex.js-based database connections, managing the complete connection lifecycle.
7
+ *
8
+ * **Key Responsibilities:**
9
+ * - Authentication provider integration via factory
10
+ * - Connection lifecycle management (connect → authenticate → establish → cleanup)
11
+ * - Knex.js instance management and access control
12
+ * - Transaction support delegation
13
+ * - Abstract methods for adapter-specific initialization
14
+ *
15
+ * **Connection Flow:**
16
+ * 1. Constructor: Initialize with DatabaseConfig
17
+ * 2. connect(): Authenticate via provider, establish Knex connection
18
+ * 3. initialize(): Adapter-specific setup (pragmas, schemas, etc.)
19
+ * 4. getKnex(): Access Knex instance for queries
20
+ * 5. disconnect(): Close Knex connection
21
+ * 6. cleanup(): Release authentication resources (tunnels, tokens)
22
+ *
23
+ * **Architecture:**
24
+ * ```
25
+ * BaseAdapter (abstract)
26
+ * ├── Authentication Layer: BaseAuthProvider integration
27
+ * ├── Connection Layer: Knex.js management
28
+ * └── Adapter-Specific: Abstract methods for subclasses
29
+ *
30
+ * Concrete Adapters:
31
+ * ├── SQLiteAdapter (no auth required)
32
+ * ├── PostgreSQLAdapter (with auth integration)
33
+ * └── MySQLAdapter (with auth integration)
34
+ * ```
35
+ *
36
+ * @module adapters/base-adapter
37
+ * @since v3.7.0
38
+ */
39
+ import type { Knex } from 'knex';
40
+ import type { DatabaseAdapter } from './types.js';
41
+ import type { DatabaseConfig } from '../config/types.js';
42
+ import type { BaseAuthProvider, ConnectionParams } from './auth/base-auth-provider.js';
43
+ /**
44
+ * Abstract base class for database adapters with authentication integration.
45
+ *
46
+ * This class provides common functionality for all database adapters, integrating
47
+ * authentication providers with Knex.js connections. Subclasses implement
48
+ * database-specific features (SQLite pragmas, PostgreSQL settings, MySQL config).
49
+ *
50
+ * **Design Principles:**
51
+ * - Separation of concerns: Auth provider handles authentication, adapter handles DB operations
52
+ * - Lazy initialization: Knex instance created only after successful authentication
53
+ * - Resource safety: Explicit cleanup for both auth providers and DB connections
54
+ * - Fail-fast validation: Auth provider validates config before connection attempt
55
+ * - Backward compatibility: Maintains DatabaseAdapter interface contract
56
+ *
57
+ * **Authentication Integration:**
58
+ * - SQLite: No authentication provider (null), direct file connection
59
+ * - PostgreSQL/MySQL: Auth provider handles tunneling/IAM/direct auth
60
+ * - SSH tunneling: Provider establishes tunnel, returns localhost connection params
61
+ * - Cloud IAM: Provider generates temporary tokens, returns params with SSL config
62
+ *
63
+ * **Error Handling:**
64
+ * - Constructor: Config validation (throws if invalid)
65
+ * - connect(): Authentication failures, connection failures
66
+ * - getKnex(): Throws if called before connect()
67
+ * - cleanup(): Swallows errors to prevent cascading failures
68
+ *
69
+ * @abstract
70
+ * @implements {DatabaseAdapter}
71
+ *
72
+ * @example
73
+ * // Implementing a PostgreSQL adapter
74
+ * class PostgreSQLAdapter extends BaseAdapter {
75
+ * readonly supportsReturning = true;
76
+ * readonly supportsJSON = true;
77
+ * readonly databaseName = 'postgresql' as const;
78
+ *
79
+ * async initialize(): Promise<void> {
80
+ * const knex = this.getKnex();
81
+ * // PostgreSQL-specific initialization
82
+ * await knex.raw('SET statement_timeout = 30000');
83
+ * await knex.raw('SET timezone = "UTC"');
84
+ * }
85
+ *
86
+ * getDialect(): string {
87
+ * return 'pg';
88
+ * }
89
+ *
90
+ * // Implement other DatabaseAdapter methods...
91
+ * }
92
+ *
93
+ * @example
94
+ * // Using the adapter with authentication
95
+ * const config: DatabaseConfig = {
96
+ * type: 'postgres',
97
+ * connection: {
98
+ * host: 'db.internal',
99
+ * port: 5432,
100
+ * database: 'production'
101
+ * },
102
+ * auth: {
103
+ * type: 'ssh',
104
+ * user: 'postgres',
105
+ * password: 'secret',
106
+ * ssh: {
107
+ * host: 'bastion.example.com',
108
+ * username: 'deploy',
109
+ * privateKeyPath: '/path/to/key.pem'
110
+ * }
111
+ * }
112
+ * };
113
+ *
114
+ * const adapter = new PostgreSQLAdapter(config);
115
+ * try {
116
+ * await adapter.connect();
117
+ * const knex = adapter.getKnex();
118
+ * const users = await knex('users').select('*');
119
+ * console.log(users);
120
+ * } finally {
121
+ * await adapter.disconnect();
122
+ * await adapter.cleanup();
123
+ * }
124
+ *
125
+ * @example
126
+ * // Transaction support
127
+ * const adapter = new PostgreSQLAdapter(config);
128
+ * await adapter.connect();
129
+ *
130
+ * try {
131
+ * await adapter.transaction(async (trx) => {
132
+ * await trx('accounts').where({ id: 1 }).update({ balance: 100 });
133
+ * await trx('accounts').where({ id: 2 }).update({ balance: 200 });
134
+ * });
135
+ * } finally {
136
+ * await adapter.disconnect();
137
+ * await adapter.cleanup();
138
+ * }
139
+ *
140
+ * @example
141
+ * // SQLite adapter (no authentication)
142
+ * class SQLiteAdapter extends BaseAdapter {
143
+ * async connect(): Promise<Knex> {
144
+ * // SQLite doesn't need authentication provider
145
+ * // Override connect to bypass auth flow
146
+ * const config: Knex.Config = {
147
+ * client: 'better-sqlite3',
148
+ * connection: {
149
+ * filename: this.config.connection.database
150
+ * },
151
+ * useNullAsDefault: true
152
+ * };
153
+ *
154
+ * this.knex = knex(config);
155
+ * await this.initialize();
156
+ * return this.knex;
157
+ * }
158
+ *
159
+ * getDialect(): string {
160
+ * return 'sqlite3';
161
+ * }
162
+ * }
163
+ */
164
+ export declare abstract class BaseAdapter implements DatabaseAdapter {
165
+ /**
166
+ * Database configuration containing connection and authentication settings.
167
+ * @protected
168
+ * @readonly
169
+ */
170
+ protected readonly config: DatabaseConfig;
171
+ /**
172
+ * Authentication provider instance for handling credentials, tunnels, and tokens.
173
+ * Null for databases that don't require authentication (e.g., SQLite).
174
+ * @protected
175
+ */
176
+ protected authProvider: BaseAuthProvider | null;
177
+ /**
178
+ * Knex.js instance for database operations.
179
+ * Null until connect() is called successfully.
180
+ * @protected
181
+ */
182
+ protected knexInstance: Knex | null;
183
+ /**
184
+ * Creates a new database adapter instance.
185
+ *
186
+ * @param {DatabaseConfig} config - Database configuration object
187
+ *
188
+ * @throws {Error} If database type is unsupported
189
+ *
190
+ * @example
191
+ * const adapter = new PostgreSQLAdapter({
192
+ * type: 'postgres',
193
+ * connection: { host: 'localhost', port: 5432, database: 'mydb' },
194
+ * auth: { type: 'direct', user: 'postgres', password: 'postgres' }
195
+ * });
196
+ */
197
+ constructor(config: DatabaseConfig);
198
+ /**
199
+ * Performs adapter-specific initialization after connection is established.
200
+ *
201
+ * This method is called automatically after Knex connection is created.
202
+ * Subclasses implement database-specific setup:
203
+ *
204
+ * **SQLite:**
205
+ * - PRAGMA settings (journal_mode, foreign_keys, synchronous)
206
+ * - Query performance optimizations
207
+ *
208
+ * **PostgreSQL:**
209
+ * - Session settings (statement_timeout, timezone)
210
+ * - Search path configuration
211
+ * - Connection pool settings
212
+ *
213
+ * **MySQL:**
214
+ * - Session variables (sql_mode, time_zone)
215
+ * - Character set configuration
216
+ * - Transaction isolation level
217
+ *
218
+ * @abstract
219
+ * @returns {Promise<void>}
220
+ *
221
+ * @throws {Error} If initialization fails
222
+ *
223
+ * @example
224
+ * // SQLite implementation
225
+ * async initialize(): Promise<void> {
226
+ * const knex = this.getKnex();
227
+ * await knex.raw('PRAGMA journal_mode = WAL');
228
+ * await knex.raw('PRAGMA foreign_keys = ON');
229
+ * await knex.raw('PRAGMA synchronous = NORMAL');
230
+ * }
231
+ *
232
+ * @example
233
+ * // PostgreSQL implementation
234
+ * async initialize(): Promise<void> {
235
+ * const knex = this.getKnex();
236
+ * await knex.raw('SET statement_timeout = 30000');
237
+ * await knex.raw('SET timezone = "UTC"');
238
+ * await knex.raw('SET search_path = public');
239
+ * }
240
+ */
241
+ abstract initialize(): Promise<void>;
242
+ /**
243
+ * Returns the Knex dialect identifier for this database.
244
+ *
245
+ * Used for Knex configuration and feature detection.
246
+ *
247
+ * **Valid Dialect Values:**
248
+ * - 'sqlite3' - SQLite
249
+ * - 'pg' - PostgreSQL
250
+ * - 'mysql' - MySQL
251
+ * - 'mysql2' - MySQL with mysql2 driver
252
+ * - 'mssql' - Microsoft SQL Server
253
+ * - 'oracledb' - Oracle Database
254
+ *
255
+ * @abstract
256
+ * @returns {string} Knex dialect identifier
257
+ *
258
+ * @example
259
+ * // SQLite adapter
260
+ * getDialect(): string {
261
+ * return 'sqlite3';
262
+ * }
263
+ *
264
+ * @example
265
+ * // PostgreSQL adapter
266
+ * getDialect(): string {
267
+ * return 'pg';
268
+ * }
269
+ */
270
+ abstract getDialect(): string;
271
+ /**
272
+ * Whether this database supports RETURNING clause in INSERT/UPDATE/DELETE.
273
+ * @abstract
274
+ */
275
+ abstract readonly supportsReturning: boolean;
276
+ /**
277
+ * Whether this database has native JSON support.
278
+ * @abstract
279
+ */
280
+ abstract readonly supportsJSON: boolean;
281
+ /**
282
+ * Whether this database supports UPSERT operations (INSERT ... ON CONFLICT).
283
+ * @abstract
284
+ */
285
+ abstract readonly supportsUpsert: boolean;
286
+ /**
287
+ * Whether this database supports Common Table Expressions (WITH clause).
288
+ * @abstract
289
+ */
290
+ abstract readonly supportsCTE: boolean;
291
+ /**
292
+ * Whether this database supports window functions.
293
+ * @abstract
294
+ */
295
+ abstract readonly supportsWindowFunctions: boolean;
296
+ /**
297
+ * Whether this database supports savepoints within transactions.
298
+ * @abstract
299
+ */
300
+ abstract readonly supportsSavepoints: boolean;
301
+ /**
302
+ * Database name identifier.
303
+ * @abstract
304
+ */
305
+ abstract readonly databaseName: 'sqlite' | 'postgresql' | 'mysql';
306
+ /**
307
+ * Establishes database connection with authentication.
308
+ *
309
+ * This method orchestrates the complete connection flow:
310
+ * 1. Create authentication provider (if required)
311
+ * 2. Validate authentication configuration
312
+ * 3. Authenticate and obtain connection parameters
313
+ * 4. Create Knex instance with authenticated params
314
+ * 5. Call initialize() for adapter-specific setup
315
+ *
316
+ * **Authentication Flow:**
317
+ * - Direct: Use credentials as-is
318
+ * - SSH: Establish tunnel, connect to localhost
319
+ * - AWS/GCP IAM: Generate token, connect with SSL
320
+ *
321
+ * **Important Notes:**
322
+ * - This method is idempotent: calling twice reuses existing connection
323
+ * - Auth provider resources remain allocated until cleanup() is called
324
+ * - Knex instance is accessible via getKnex() after successful connection
325
+ * - Subclasses can override for special handling (e.g., SQLite)
326
+ *
327
+ * @returns {Promise<Knex>} Knex instance for database operations
328
+ *
329
+ * @throws {Error} 'Database already connected' - if connection exists
330
+ * @throws {Error} Auth provider validation errors
331
+ * @throws {Error} Authentication failures (invalid credentials, network issues)
332
+ * @throws {Error} Knex connection failures (database unreachable, invalid database name)
333
+ * @throws {Error} Initialization failures (adapter-specific setup errors)
334
+ *
335
+ * @example
336
+ * // Standard usage
337
+ * const adapter = new PostgreSQLAdapter(config);
338
+ * try {
339
+ * const knex = await adapter.connect();
340
+ * console.log('Connected successfully');
341
+ * } catch (error) {
342
+ * console.error('Connection failed:', error.message);
343
+ * await adapter.cleanup();
344
+ * throw error;
345
+ * }
346
+ *
347
+ * @example
348
+ * // Idempotent connection
349
+ * const adapter = new PostgreSQLAdapter(config);
350
+ * const knex1 = await adapter.connect(); // Establishes connection
351
+ * const knex2 = await adapter.connect(); // Returns same instance
352
+ * console.log(knex1 === knex2); // true
353
+ */
354
+ connect(): Promise<Knex>;
355
+ /**
356
+ * Closes the database connection.
357
+ *
358
+ * This method closes the Knex connection pool, releasing all database connections.
359
+ * It does NOT release authentication provider resources (SSH tunnels, tokens) -
360
+ * call cleanup() to release those.
361
+ *
362
+ * **Resource Lifecycle:**
363
+ * - disconnect() → Closes Knex connection pool
364
+ * - cleanup() → Releases auth provider resources (tunnels, tokens)
365
+ * - Both must be called for complete cleanup
366
+ *
367
+ * **Important Notes:**
368
+ * - This method is idempotent: safe to call multiple times
369
+ * - Pending queries are allowed to complete before closing
370
+ * - After disconnect(), getKnex() will throw an error
371
+ * - Auth provider resources remain allocated until cleanup()
372
+ *
373
+ * @returns {Promise<void>}
374
+ *
375
+ * @example
376
+ * // Complete cleanup flow
377
+ * const adapter = new PostgreSQLAdapter(config);
378
+ * try {
379
+ * await adapter.connect();
380
+ * // ... use database ...
381
+ * } finally {
382
+ * await adapter.disconnect(); // Close DB connection
383
+ * await adapter.cleanup(); // Release auth resources
384
+ * }
385
+ *
386
+ * @example
387
+ * // Idempotent disconnect
388
+ * await adapter.disconnect(); // Closes connection
389
+ * await adapter.disconnect(); // Safe - no-op
390
+ */
391
+ disconnect(): Promise<void>;
392
+ /**
393
+ * Releases authentication provider resources.
394
+ *
395
+ * This method releases resources allocated during authentication:
396
+ * - SSH tunnels: Closes SSH connection and releases local port
397
+ * - Cloud IAM: Invalidates cached tokens
398
+ * - Direct connections: No-op (no resources to release)
399
+ *
400
+ * **Important Notes:**
401
+ * - This method MUST be called after disconnect() to prevent resource leaks
402
+ * - Errors during cleanup are caught and logged, not thrown
403
+ * - This method is idempotent: safe to call multiple times
404
+ * - Auth provider is set to null after cleanup
405
+ *
406
+ * **Resource Leak Prevention:**
407
+ * Always call cleanup() in a finally block to ensure resources are released
408
+ * even if database operations fail.
409
+ *
410
+ * @returns {Promise<void>}
411
+ *
412
+ * @example
413
+ * // Proper cleanup flow
414
+ * const adapter = new PostgreSQLAdapter(config);
415
+ * try {
416
+ * await adapter.connect();
417
+ * // ... database operations ...
418
+ * } finally {
419
+ * await adapter.disconnect();
420
+ * await adapter.cleanup();
421
+ * }
422
+ *
423
+ * @example
424
+ * // Error handling during cleanup
425
+ * try {
426
+ * await adapter.cleanup();
427
+ * } catch (error) {
428
+ * // Cleanup errors are logged but not thrown to prevent cascading failures
429
+ * console.error('Cleanup failed:', error);
430
+ * }
431
+ */
432
+ cleanup(): Promise<void>;
433
+ /**
434
+ * Returns the Knex.js instance for database operations.
435
+ *
436
+ * This method provides access to the underlying Knex instance for executing
437
+ * queries, building query chains, and accessing raw connections.
438
+ *
439
+ * **Important Notes:**
440
+ * - Must call connect() before calling this method
441
+ * - Throws error if connection not established
442
+ * - Returns same instance across multiple calls
443
+ *
444
+ * @returns {Knex} Knex instance for database operations
445
+ *
446
+ * @throws {Error} 'Database not connected. Call connect() first.' - if not connected
447
+ *
448
+ * @example
449
+ * // Standard usage
450
+ * const adapter = new PostgreSQLAdapter(config);
451
+ * await adapter.connect();
452
+ * const knex = adapter.getKnex();
453
+ * const users = await knex('users').select('*');
454
+ *
455
+ * @example
456
+ * // Query builder
457
+ * const knex = adapter.getKnex();
458
+ * const query = knex('orders')
459
+ * .where('status', 'pending')
460
+ * .andWhere('created_at', '>', '2024-01-01')
461
+ * .orderBy('created_at', 'desc');
462
+ *
463
+ * @example
464
+ * // Raw queries
465
+ * const knex = adapter.getKnex();
466
+ * const result = await knex.raw('SELECT * FROM users WHERE id = ?', [userId]);
467
+ */
468
+ getKnex(): Knex;
469
+ /**
470
+ * Executes a callback within a database transaction.
471
+ *
472
+ * This method delegates to Knex's transaction management, providing:
473
+ * - Automatic commit on success
474
+ * - Automatic rollback on error
475
+ * - Optional isolation level configuration
476
+ *
477
+ * **Transaction Isolation Levels:**
478
+ * - 'serializable': Strongest isolation, prevents all anomalies
479
+ * - 'repeatable read': Prevents non-repeatable reads and phantom reads
480
+ * - 'read committed': Prevents dirty reads (default for most databases)
481
+ *
482
+ * **Important Notes:**
483
+ * - All database operations within callback must use the trx parameter
484
+ * - Do not mix transaction queries with non-transaction queries
485
+ * - Nested transactions use savepoints (if supported by database)
486
+ *
487
+ * @param {Function} callback - Async function receiving transaction object
488
+ * @param {Object} [options] - Transaction options
489
+ * @param {string} [options.isolationLevel] - Transaction isolation level
490
+ * @returns {Promise<T>} Result from callback function
491
+ *
492
+ * @throws {Error} If callback throws (transaction is rolled back)
493
+ *
494
+ * @example
495
+ * // Bank transfer transaction
496
+ * await adapter.transaction(async (trx) => {
497
+ * await trx('accounts')
498
+ * .where({ id: fromAccount })
499
+ * .decrement('balance', amount);
500
+ *
501
+ * await trx('accounts')
502
+ * .where({ id: toAccount })
503
+ * .increment('balance', amount);
504
+ *
505
+ * await trx('transfers').insert({
506
+ * from_account: fromAccount,
507
+ * to_account: toAccount,
508
+ * amount
509
+ * });
510
+ * });
511
+ *
512
+ * @example
513
+ * // Transaction with isolation level
514
+ * await adapter.transaction(async (trx) => {
515
+ * const balance = await trx('accounts')
516
+ * .where({ id: accountId })
517
+ * .first('balance');
518
+ *
519
+ * if (balance.balance >= amount) {
520
+ * await trx('accounts')
521
+ * .where({ id: accountId })
522
+ * .decrement('balance', amount);
523
+ * }
524
+ * }, { isolationLevel: 'serializable' });
525
+ *
526
+ * @example
527
+ * // Error handling (automatic rollback)
528
+ * try {
529
+ * await adapter.transaction(async (trx) => {
530
+ * await trx('users').insert({ name: 'Alice' });
531
+ * throw new Error('Something went wrong');
532
+ * await trx('logs').insert({ message: 'Never executed' });
533
+ * });
534
+ * } catch (error) {
535
+ * console.log('Transaction rolled back:', error.message);
536
+ * }
537
+ */
538
+ transaction<T>(callback: (trx: Knex.Transaction) => Promise<T>, options?: {
539
+ isolationLevel?: 'serializable' | 'read committed' | 'repeatable read';
540
+ }): Promise<T>;
541
+ /**
542
+ * Builds Knex configuration from connection parameters.
543
+ *
544
+ * This method converts ConnectionParams (returned by auth provider) into
545
+ * Knex.Config format. Subclasses can override to customize configuration.
546
+ *
547
+ * **Default Behavior:**
548
+ * - Uses dialect from getDialect()
549
+ * - Passes connection params to Knex
550
+ * - Configures SSL if present
551
+ * - Merges additional params
552
+ *
553
+ * @protected
554
+ * @param {ConnectionParams | null} connParams - Connection parameters from auth provider
555
+ * @returns {Knex.Config} Knex configuration object
556
+ *
557
+ * @example
558
+ * // Custom configuration in subclass
559
+ * protected buildKnexConfig(connParams: ConnectionParams | null): Knex.Config {
560
+ * const baseConfig = super.buildKnexConfig(connParams);
561
+ * return {
562
+ * ...baseConfig,
563
+ * pool: {
564
+ * min: 2,
565
+ * max: 10,
566
+ * afterCreate: (conn, done) => {
567
+ * // Custom connection setup
568
+ * done(null, conn);
569
+ * }
570
+ * }
571
+ * };
572
+ * }
573
+ */
574
+ protected buildKnexConfig(connParams: ConnectionParams | null): Knex.Config;
575
+ /**
576
+ * Inserts a row and returns the inserted record.
577
+ * Adapts to databases that don't support RETURNING clause.
578
+ * @abstract
579
+ */
580
+ abstract insertReturning<T extends Record<string, any>>(table: string, data: Partial<T>): Promise<T>;
581
+ /**
582
+ * Upserts a row (INSERT ... ON CONFLICT UPDATE).
583
+ * Adapts to different upsert syntaxes across databases.
584
+ * @abstract
585
+ */
586
+ abstract upsert<T extends Record<string, any>>(table: string, data: Partial<T>, conflictColumns: string[], updateColumns?: string[]): Promise<number>;
587
+ /**
588
+ * Extracts a value from a JSON column.
589
+ * @abstract
590
+ */
591
+ abstract jsonExtract(column: string, path: string): Knex.Raw;
592
+ /**
593
+ * Builds a JSON object from field values.
594
+ * @abstract
595
+ */
596
+ abstract jsonBuildObject(fields: Record<string, any>): Knex.Raw;
597
+ /**
598
+ * Returns current timestamp expression.
599
+ * @abstract
600
+ */
601
+ abstract currentTimestamp(): Knex.Raw;
602
+ /**
603
+ * Converts Unix epoch to datetime.
604
+ * @abstract
605
+ */
606
+ abstract fromUnixEpoch(epochColumn: string): Knex.Raw;
607
+ /**
608
+ * Converts datetime to Unix epoch.
609
+ * @abstract
610
+ */
611
+ abstract toUnixEpoch(timestampColumn: string): Knex.Raw;
612
+ /**
613
+ * Concatenates string values.
614
+ * @abstract
615
+ */
616
+ abstract concat(...values: Array<string | Knex.Raw>): Knex.Raw;
617
+ /**
618
+ * Aggregates strings with separator.
619
+ * @abstract
620
+ */
621
+ abstract stringAgg(column: string, separator?: string): Knex.Raw;
622
+ /**
623
+ * Creates a savepoint within a transaction.
624
+ * @abstract
625
+ */
626
+ abstract savepoint<T>(trx: Knex.Transaction, callback: (sp: Knex.Transaction) => Promise<T>): Promise<T>;
627
+ /**
628
+ * Checks if a table exists in the database.
629
+ * @abstract
630
+ */
631
+ abstract tableExists(tableName: string): Promise<boolean>;
632
+ /**
633
+ * Adds an auto-increment column to a table builder.
634
+ * @abstract
635
+ */
636
+ abstract autoIncrementColumn(table: Knex.CreateTableBuilder, columnName?: string): void;
637
+ }
638
+ //# sourceMappingURL=base-adapter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"base-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/base-adapter.ts"],"names":[],"mappings":"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"}