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
package/CHANGELOG.md CHANGED
@@ -7,7 +7,404 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ---
9
9
 
10
- ## [3.6.9] - 2025-10-30
10
+ ## [3.7.0] - 2025-11-05
11
+
12
+ ### Added - Runtime Database Reconnection
13
+
14
+ **Automatic connection recovery with exponential backoff retry logic**
15
+
16
+ #### Features
17
+ - **ConnectionManager** - Singleton wrapper for all database operations
18
+ - **Exponential Backoff** - Retry delays: 1s → 2s → 4s → 8s → 16s (31 seconds total)
19
+ - **Smart Error Detection** - Recognizes connection errors across SQLite, MySQL, PostgreSQL
20
+ - **Process.exit on Exhaustion** - Exits cleanly after 5 failed retries
21
+ - **27 Operations Wrapped** - All transactional operations protected:
22
+ - context.ts: 5 operations
23
+ - tasks.ts: 9 operations
24
+ - files.ts: 3 operations
25
+ - constraints.ts: 3 operations
26
+ - config.ts: 2 operations
27
+ - utils.ts: 5 operations
28
+
29
+ #### Connection Error Patterns Detected
30
+ - **Network Errors**: ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET, EPIPE
31
+ - **SQLite**: "database is locked", "unable to open database"
32
+ - **MySQL/MariaDB**: "server has gone away", "lost connection to mysql server"
33
+ - **PostgreSQL**: "connection to server was lost", "could not connect to server"
34
+ - **Knex-specific**: "timeout acquiring a connection", "pool is destroyed"
35
+
36
+ #### Test Coverage
37
+ - **41 tests passing** (22 unit + 19 integration)
38
+ - Retry behavior verification
39
+ - Production scenario simulation (server restart, network failures)
40
+ - Tool integration testing
41
+
42
+ #### Impact
43
+ - ✅ **Resilient operations** - Automatic recovery from transient connection failures
44
+ - ✅ **Production ready** - Handles server restarts, network issues
45
+ - ✅ **Zero regressions** - All existing tests pass
46
+ - ✅ **Token efficient** - No manual retry logic needed in agent code
47
+
48
+ ---
49
+
50
+ ### Changed - Validation Error Messages
51
+
52
+ **70-85% token reduction in error message size**
53
+
54
+ #### Token Efficiency
55
+ - **Before**: ~1000+ characters (~300+ tokens) with full examples embedded
56
+ - **After**: ~200 characters (~50 tokens) with reference IDs
57
+ - **Reduction**: 70-85% token savings
58
+
59
+ #### New Error Format
60
+ ```json
61
+ {
62
+ "error": "Missing: key, value",
63
+ "action": "set",
64
+ "reference": "decision.set",
65
+ "missing": ["key", "value"],
66
+ "hint": "Use 'quick_set' for simpler usage..."
67
+ }
68
+ ```
69
+
70
+ #### Features
71
+ - **Reference IDs** - Compact `{tool}.{action}` format (e.g., "decision.set")
72
+ - **Concise Messages** - Essential information only
73
+ - **Conditional Fields** - Only include fields when present
74
+ - **Self-Documenting** - AI can query `action: "help"` for full docs if needed
75
+
76
+ #### Error Types
77
+ - Missing params: `"Missing: key, value"`
78
+ - Typos: `"Invalid params: val → value"`
79
+ - Unknown action: `"Unknown action 'sett'. Did you mean: set?"`
80
+
81
+ #### Impact
82
+ - ✅ **Token efficiency** - 70-85% reduction in error size
83
+ - ✅ **Cost reduction** - Lower API costs for AI agents
84
+ - ✅ **Better UX** - Quick, scannable errors
85
+ - ✅ **Backward compatible** - Error structure unchanged
86
+
87
+ ---
88
+
89
+ ### Changed - Debug Log Format
90
+
91
+ **Single-line log entries for easier parsing**
92
+
93
+ #### Problem
94
+ Multi-line log messages broke standard text processing tools (grep, awk, log rotation).
95
+
96
+ #### Solution
97
+ - **Sanitization Function** - Replaces newlines with spaces, collapses whitespace
98
+ - **Applied To**: All log messages, data values, JSON output
99
+ - **Result**: Every log entry is exactly one line
100
+
101
+ #### Benefits
102
+ - ✅ **Easier parsing** - Line-based tools work correctly
103
+ - ✅ **Better grep** - Search across entire messages
104
+ - ✅ **Simpler analysis** - Standard text processing
105
+ - ✅ **Cleaner output** - No unexpected line breaks
106
+
107
+ #### Example
108
+ **Before:**
109
+ ```
110
+ [2025-11-05T02:00:00.000Z] [ERROR] Error details:
111
+ Stack trace line 1
112
+ Stack trace line 2
113
+ ```
114
+
115
+ **After:**
116
+ ```
117
+ [2025-11-05T02:00:00.000Z] [ERROR] Error details: Stack trace line 1 Stack trace line 2
118
+ ```
119
+
120
+ ---
121
+
122
+ ### Fixed - Multi-Project Migration (Critical)
123
+
124
+ **Fixed migration for ALL users upgrading from v3.6.10 to v3.7.0**
125
+
126
+ #### Problem
127
+ - SQLite's `ALTER TABLE` silently failed for 4 tables with complex foreign keys
128
+ - Migration reported success but columns weren't added
129
+ - Task creation would fail: `"table t_task_details has no column named project_id"`
130
+
131
+ #### Root Cause
132
+ SQLite cannot modify tables with `ON DELETE CASCADE` constraints using ALTER TABLE.
133
+
134
+ #### Solution
135
+ - **Table Recreation Strategy** - Backup → Drop → Recreate → Restore
136
+ - **4 Tables Fixed**:
137
+ - `t_task_details` (STEP 4.7)
138
+ - `t_task_file_links` (STEP 4.8)
139
+ - `t_task_decision_links` (STEP 4.9)
140
+ - `t_task_tags` (composite PRIMARY KEY)
141
+
142
+ #### Idempotency
143
+ All recreation steps check if `project_id` exists before executing:
144
+ ```typescript
145
+ const hasProjectId = await knex.schema.hasColumn('table_name', 'project_id');
146
+ if (!hasProjectId) {
147
+ // Recreation logic
148
+ }
149
+ ```
150
+
151
+ #### Data Preservation Verified
152
+ - ✅ 223 task detail rows preserved
153
+ - ✅ 632 task tag rows preserved
154
+ - ✅ All task links preserved
155
+ - ✅ 100% data integrity maintained
156
+
157
+ #### Testing
158
+ - ✅ Fresh installation works
159
+ - ✅ v3.6.10 → v3.7.0 upgrade works
160
+ - ✅ Migration can be re-run safely (idempotent)
161
+ - ✅ TypeScript compiles without errors
162
+
163
+ #### Impact
164
+ - ✅ **Production ready** - Safe for all v3.6.10 users to upgrade
165
+ - ✅ **No data loss** - All existing data preserved
166
+ - ✅ **Idempotent** - Can re-run without errors
167
+
168
+ ---
169
+
170
+ ## [3.6.10] - 2025-10-30
171
+
172
+ ### Added - Environment Variable Support for Project Root
173
+
174
+ **New `SQLEW_PROJECT_ROOT` environment variable for project-relative databases**
175
+
176
+ #### Problem
177
+ - Junie AI and other MCP clients require absolute paths in configuration
178
+ - Users had to hardcode project-specific paths in MCP server config
179
+ - No easy way to use project-relative database paths
180
+
181
+ #### Solution
182
+ - Added `SQLEW_PROJECT_ROOT` environment variable support (inspired by serena-mcp pattern)
183
+ - MCP clients can now pass project directory via environment variable
184
+ - Database automatically created at `$SQLEW_PROJECT_ROOT/.sqlew/sqlew.db`
185
+
186
+ #### Priority Order
187
+ 1. `SQLEW_PROJECT_ROOT` environment variable (NEW - highest priority)
188
+ 2. `--db-path` CLI argument (absolute path)
189
+ 3. `--config-path` CLI argument (absolute path)
190
+ 4. `database.path` in config file (absolute path)
191
+ 5. `process.cwd()` fallback
192
+
193
+ #### Junie AI Configuration Example
194
+ ```json
195
+ {
196
+ "mcpServers": {
197
+ "sqlew": {
198
+ "command": "npx",
199
+ "args": ["sqlew"],
200
+ "env": {
201
+ "SQLEW_PROJECT_ROOT": "{projectDir}"
202
+ }
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ **Note:** Junie AI uses `{projectDir}` variable which expands to the current project's absolute path. This ensures each project gets its own isolated database without hardcoded paths. Other MCP clients may use different variable names like `${workspaceFolder}` (VS Code/Cline) - check your client's documentation.
209
+
210
+ #### Impact
211
+ - ✅ **Project-relative databases** without hardcoded absolute paths
212
+ - ✅ **Cleaner MCP configuration** (no per-project path updates needed)
213
+ - ✅ **Compatible with Junie AI, Claude Desktop, and other MCP clients**
214
+ - ✅ **No breaking changes** (environment variable is optional)
215
+
216
+ ---
217
+
218
+ ### Fixed - MCP Protocol Compliance (EPIPE Fix)
219
+
220
+ **Eliminated console output for strict JSON-RPC protocol compliance**
221
+
222
+ #### Problem
223
+ - EPIPE (broken pipe) errors when running with Junie AI on Windows
224
+ - Console output to stdout/stderr violated MCP JSON-RPC protocol requirements
225
+ - Strict MCP clients (like Junie AI) expect pure JSON-RPC on stdio streams
226
+
227
+ #### Changes
228
+ - **Redirected all diagnostic output to debug log file** - stdout/stderr reserved exclusively for JSON-RPC
229
+ - Modified `safeConsoleError()` to write to debug log instead of stderr
230
+ - Replaced 50+ console.log/console.error calls across codebase:
231
+ - `src/database.ts` - Database initialization messages
232
+ - `src/watcher/file-watcher.ts` - File watcher status and events
233
+ - `src/watcher/gitignore-parser.ts` - .gitignore loading warnings
234
+ - `src/tools/tasks.ts` - Task file registration warnings
235
+ - `src/config/example-generator.ts` - First launch messages
236
+
237
+ #### Technical Details
238
+ - **MCP Protocol Requirement**: stdin/stdout/stderr must carry only JSON-RPC messages
239
+ - **Debug Logging**: All diagnostic messages now use `debugLog()` with appropriate levels (INFO, WARN, ERROR)
240
+ - **Zero stdout pollution**: Server starts silently, waits for JSON-RPC requests
241
+ - **Tested with Junie AI**: Confirmed no EPIPE errors on Windows
242
+
243
+ #### Impact
244
+ - ✅ **Works with strict MCP clients** (Junie AI, etc.)
245
+ - ✅ **Maintains full diagnostics** via debug log file
246
+ - ✅ **Pure JSON-RPC protocol** compliance
247
+ - ✅ **No breaking changes** to MCP tool functionality
248
+
249
+ ---
250
+
251
+ ### Added - Environment Variable Support for Project Root
252
+
253
+ **New `SQLEW_PROJECT_ROOT` environment variable for project-relative databases**
254
+
255
+ #### Problem
256
+ - Junie AI and other MCP clients require absolute paths in configuration
257
+ - Users had to hardcode project-specific paths in MCP server config
258
+ - No easy way to use project-relative database paths
259
+
260
+ #### Solution
261
+ - Added `SQLEW_PROJECT_ROOT` environment variable support (inspired by serena-mcp pattern)
262
+ - MCP clients can now pass project directory via environment variable
263
+ - Database automatically created at `$SQLEW_PROJECT_ROOT/.sqlew/sqlew.db`
264
+
265
+ #### Priority Order
266
+ 1. `SQLEW_PROJECT_ROOT` environment variable (NEW - highest priority)
267
+ 2. `--db-path` CLI argument (absolute path)
268
+ 3. `--config-path` CLI argument (absolute path)
269
+ 4. `database.path` in config file (absolute path)
270
+ 5. `process.cwd()` fallback
271
+
272
+ #### Junie AI Configuration Example
273
+ ```json
274
+ {
275
+ "mcpServers": {
276
+ "sqlew": {
277
+ "command": "npx",
278
+ "args": ["sqlew"],
279
+ "env": {
280
+ "SQLEW_PROJECT_ROOT": "{projectDir}"
281
+ }
282
+ }
283
+ }
284
+ }
285
+ ```
286
+
287
+ **Note:** Junie AI uses `{projectDir}` variable which expands to the current project's absolute path. This ensures each project gets its own isolated database without hardcoded paths. Other MCP clients may use different variable names like `${workspaceFolder}` (VS Code/Cline) - check your client's documentation.
288
+
289
+ #### Impact
290
+ - ✅ **Project-relative databases** without hardcoded absolute paths
291
+ - ✅ **Cleaner MCP configuration** (no per-project path updates needed)
292
+ - ✅ **Compatible with Junie AI, Claude Desktop, and other MCP clients**
293
+ - ✅ **No breaking changes** (environment variable is optional)
294
+
295
+ ---
296
+
297
+ ### Fixed - MCP Protocol Compliance (EPIPE Fix)
298
+
299
+ **Eliminated console output for strict JSON-RPC protocol compliance**
300
+
301
+ #### Problem
302
+ - EPIPE (broken pipe) errors when running with Junie AI on Windows
303
+ - Console output to stdout/stderr violated MCP JSON-RPC protocol requirements
304
+ - Strict MCP clients (like Junie AI) expect pure JSON-RPC on stdio streams
305
+
306
+ #### Changes
307
+ - **Redirected all diagnostic output to debug log file** - stdout/stderr reserved exclusively for JSON-RPC
308
+ - Modified `safeConsoleError()` to write to debug log instead of stderr
309
+ - Replaced 50+ console.log/console.error calls across codebase:
310
+ - `src/database.ts` - Database initialization messages
311
+ - `src/watcher/file-watcher.ts` - File watcher status and events
312
+ - `src/watcher/gitignore-parser.ts` - .gitignore loading warnings
313
+ - `src/tools/tasks.ts` - Task file registration warnings
314
+ - `src/config/example-generator.ts` - First launch messages
315
+
316
+ #### Technical Details
317
+ - **MCP Protocol Requirement**: stdin/stdout/stderr must carry only JSON-RPC messages
318
+ - **Debug Logging**: All diagnostic messages now use `debugLog()` with appropriate levels (INFO, WARN, ERROR)
319
+ - **Zero stdout pollution**: Server starts silently, waits for JSON-RPC requests
320
+ - **Tested with Junie AI**: Confirmed no EPIPE errors on Windows
321
+
322
+ #### Impact
323
+ - ✅ **Works with strict MCP clients** (Junie AI, etc.)
324
+ - ✅ **Maintains full diagnostics** via debug log file
325
+ - ✅ **Pure JSON-RPC protocol** compliance
326
+ - ✅ **No breaking changes** to MCP tool functionality
327
+
328
+ ---
329
+
330
+ ### Added - Environment Variable Support for Project Root
331
+
332
+ **New `SQLEW_PROJECT_ROOT` environment variable for project-relative databases**
333
+
334
+ #### Problem
335
+ - Junie AI and other MCP clients require absolute paths in configuration
336
+ - Users had to hardcode project-specific paths in MCP server config
337
+ - No easy way to use project-relative database paths
338
+
339
+ #### Solution
340
+ - Added `SQLEW_PROJECT_ROOT` environment variable support (inspired by serena-mcp pattern)
341
+ - MCP clients can now pass project directory via environment variable
342
+ - Database automatically created at `$SQLEW_PROJECT_ROOT/.sqlew/sqlew.db`
343
+
344
+ #### Priority Order
345
+ 1. `SQLEW_PROJECT_ROOT` environment variable (NEW - highest priority)
346
+ 2. `--db-path` CLI argument (absolute path)
347
+ 3. `--config-path` CLI argument (absolute path)
348
+ 4. `database.path` in config file (absolute path)
349
+ 5. `process.cwd()` fallback
350
+
351
+ #### Junie AI Configuration Example
352
+ ```json
353
+ {
354
+ "mcpServers": {
355
+ "sqlew": {
356
+ "command": "npx",
357
+ "args": ["sqlew"],
358
+ "env": {
359
+ "SQLEW_PROJECT_ROOT": "{projectDir}"
360
+ }
361
+ }
362
+ }
363
+ }
364
+ ```
365
+
366
+ **Note:** Junie AI uses `{projectDir}` variable which expands to the current project's absolute path. This ensures each project gets its own isolated database without hardcoded paths. Other MCP clients may use different variable names like `${workspaceFolder}` (VS Code/Cline) - check your client's documentation.
367
+
368
+ #### Impact
369
+ - ✅ **Project-relative databases** without hardcoded absolute paths
370
+ - ✅ **Cleaner MCP configuration** (no per-project path updates needed)
371
+ - ✅ **Compatible with Junie AI, Claude Desktop, and other MCP clients**
372
+ - ✅ **No breaking changes** (environment variable is optional)
373
+
374
+ ---
375
+
376
+ ### Fixed - MCP Protocol Compliance (EPIPE Fix)
377
+
378
+ **Eliminated console output for strict JSON-RPC protocol compliance**
379
+
380
+ #### Problem
381
+ - EPIPE (broken pipe) errors when running with Junie AI on Windows
382
+ - Console output to stdout/stderr violated MCP JSON-RPC protocol requirements
383
+ - Strict MCP clients (like Junie AI) expect pure JSON-RPC on stdio streams
384
+
385
+ #### Changes
386
+ - **Redirected all diagnostic output to debug log file** - stdout/stderr reserved exclusively for JSON-RPC
387
+ - Modified `safeConsoleError()` to write to debug log instead of stderr
388
+ - Replaced 50+ console.log/console.error calls across codebase:
389
+ - `src/database.ts` - Database initialization messages
390
+ - `src/watcher/file-watcher.ts` - File watcher status and events
391
+ - `src/watcher/gitignore-parser.ts` - .gitignore loading warnings
392
+ - `src/tools/tasks.ts` - Task file registration warnings
393
+ - `src/config/example-generator.ts` - First launch messages
394
+
395
+ #### Technical Details
396
+ - **MCP Protocol Requirement**: stdin/stdout/stderr must carry only JSON-RPC messages
397
+ - **Debug Logging**: All diagnostic messages now use `debugLog()` with appropriate levels (INFO, WARN, ERROR)
398
+ - **Zero stdout pollution**: Server starts silently, waits for JSON-RPC requests
399
+ - **Tested with Junie AI**: Confirmed no EPIPE errors on Windows
400
+
401
+ #### Impact
402
+ - ✅ **Works with strict MCP clients** (Junie AI, etc.)
403
+ - ✅ **Maintains full diagnostics** via debug log file
404
+ - ✅ **Pure JSON-RPC protocol** compliance
405
+ - ✅ **No breaking changes** to MCP tool functionality
406
+
407
+ ---
11
408
 
12
409
  ### Fixed - Windows Absolute Path Handling
13
410
 
package/README.md CHANGED
@@ -10,25 +10,39 @@
10
10
 
11
11
  **sqlew** is a Model Context Protocol (MCP) server that gives AI agents organizational memory across sessions.
12
12
 
13
- **The Problem:** Without sqlew, every Claude session starts with zero context. You must re-explain decisions, agents can reintroduce bugs, and there's no way to track WHY decisions were made.
13
+ ### The Problem
14
+ Without sqlew, every Claude session starts with zero context. You must re-explain decisions, agents can reintroduce bugs, and there's no way to track WHY decisions were made.
14
15
 
15
- **The Solution:** sqlew lets agents remember decisions, query past context, prevent regressions with constraints, and coordinate via messaging and tasks.
16
+ It has been possible to keep records using Markdown files. However, large-scale projects or long-term maintenance records tend to generate massive amounts of documentation. This has become a problem, as it causes context rot in AI systems, leading to declining performance.
16
17
 
17
- **Example:** Session 1 records "API v1 deprecated". Session 2 (days later) queries and automatically uses v2.
18
+ ### The Solution
19
+ sqlew builds efficient external memory for AI by using relational databases.
20
+ - Records the reasoning behind decisions
21
+ - Enables querying past context
22
+ - Prevents anti-patterns through constraints
23
+ - Eliminates duplicate work via task management
24
+
25
+ **Example:**
26
+ - Session 1 records "API v1 deprecated".
27
+ - Session 2 (days later) queries and automatically uses v2.
28
+
29
+ > *This software does not send any data to external networks. We NEVER collect any data or usage statistics. Please use it with complete security.*
18
30
 
19
31
  ## Why Use sqlew?
20
32
 
21
33
  ### 🧠 Organizational Memory
22
- Traditional code tells you **WHAT** and **HOW**. sqlew adds **WHY**:
34
+ Traditional code analysis like git tells you **WHAT** is done, sqlew adds **WHY** and **HOW** on it:
23
35
  - **Decisions** → WHY it was changed
24
- - **Constraints** → WHY it must work this way
36
+ - **Constraints** → HOW should it be written
37
+ - **Tasks** → WHAT needs to be done
25
38
 
26
39
  ### ⚡ Token Efficiency
27
40
  **60-75% token reduction** in multi-session projects through structured data storage and selective querying.
28
41
 
29
42
  ### 🎯 Key Features
30
- - **5 Specialized Tools**: decisions, tasks, files, constraints, stats (config tool removed in dev)
31
- - **Parameter Validation**: Typo detection, required/optional markers, helpful error messages (NEW in dev)
43
+ - **5 Specialized Tools**: decisions, tasks, files, constraints, stats
44
+ - **Runtime Reconnection**: Automatic database connection recovery with exponential backoff
45
+ - **Parameter Validation**: Typo detection, required/optional markers, 70-85% more concise error messages
32
46
  - **Metadata-Driven**: Tag, layer, scope, and version everything
33
47
  - **Decision Context**: Document WHY with rationale, alternatives, and trade-offs
34
48
  - **Task Dependencies**: Blocking relationships with circular detection
@@ -41,7 +55,7 @@ Traditional code tells you **WHAT** and **HOW**. sqlew adds **WHY**:
41
55
  See [docs/TASK_OVERVIEW.md](docs/TASK_OVERVIEW.md) and [docs/DECISION_CONTEXT.md](docs/DECISION_CONTEXT.md) for details.
42
56
 
43
57
  ### 🔖Kanban-style AI Scrum
44
- ![kanban-style task management](assets/kanban-style.png)
58
+ ![kanban-style task management](assets/kanban-visualizer.png)
45
59
 
46
60
  ## Installation
47
61
 
@@ -51,21 +65,7 @@ See [docs/TASK_OVERVIEW.md](docs/TASK_OVERVIEW.md) and [docs/DECISION_CONTEXT.md
51
65
 
52
66
  ### Quick Install
53
67
 
54
- **Recommended (npx):**
55
- ```bash
56
- npx sqlew
57
- ```
58
-
59
- **Or install per project:**
60
- ```bash
61
- npm install sqlew
62
- ```
63
-
64
- **Note**: Global install (`npm install -g`) is **not recommended** because sqlew requires an independent database per project. Each project should maintain its own context database in `.sqlew/sqlew.db`.
65
-
66
- ### Add to Claude Desktop
67
-
68
- Edit `claude_desktop_config.json`:
68
+ on `.mcp.json` in your project's root, add these lines:
69
69
 
70
70
  ```json
71
71
  {
@@ -77,17 +77,26 @@ Edit `claude_desktop_config.json`:
77
77
  }
78
78
  }
79
79
  ```
80
+ **Recommend to restart claude after initialize**
81
+
82
+ The first time, sqlew install custom agents and initialize database. Custom agents are not loaded in this time. Please exit claude once, and restart claude again.
80
83
 
81
- Restart Claude Desktop. Done!
84
+ It's Ready!
85
+
86
+ **⚠️Note**: Global install (`npm install -g`) is **not recommended** because sqlew requires an independent settings per project. Each project should maintain its own context database in `.sqlew/sqlew.db`.
82
87
 
83
88
  **Custom database path:** Add path as argument: `"args": ["sqlew", "/path/to/db.db"]`
84
89
  **Default location:** `.sqlew/sqlew.db`
85
90
 
91
+ ### Jetbrains Junie AI
92
+
93
+ **⚠️ Not Supported:** Junie AI cannot use relative paths in MCP server configurations, which makes it incompatible with sqlew's project-based database model. Each project requires its own isolated database at `.sqlew/sqlew.db`, but Junie AI's global MCP configuration cannot handle per-project database paths.
94
+
86
95
  ## Configuration
87
96
 
88
97
  ### Optional Config File
89
98
 
90
- Create `.sqlew/config.toml` for persistent settings:
99
+ On first run, `.sqlew/config.toml` will be created for persistent settings:
91
100
 
92
101
  ```toml
93
102
  [database]
@@ -98,25 +107,31 @@ ignore_weekend = true
98
107
  message_hours = 48
99
108
  ```
100
109
 
101
- **Priority:** CLI args > config.toml > database defaults
110
+ Also `.sqlew/config.example.toml` is created for reference.
111
+
112
+ **Settings Priority:** CLI args > config.toml > database defaults
102
113
 
103
114
  See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options and validation rules.
104
115
 
105
116
  ## Quick Start
106
117
 
118
+ install it, launch claude, exit claude and launch Claude again.
119
+
107
120
  ### Basic Usage
108
121
 
109
- All tools require an `action` parameter. Example:
122
+ You'll never need to call it manually, I recommend to call this tool via prompt.
123
+
124
+ ```
125
+ read sqlew usecases, and plan implementation of feature X using sqlew.
126
+ ```
110
127
 
111
- ```javascript
112
- // Store a decision
113
- {action: "set", key: "auth_method", value: "JWT", layer: "business", tags: ["security"]}
128
+ or invoke Specialized Agent
114
129
 
115
- // Query later
116
- {action: "get", key: "auth_method"}
130
+ ```
131
+ plan implementation of feature X with @agent-scrum-master.
117
132
  ```
118
133
 
119
- For detailed examples, see [docs/TOOL_REFERENCE.md](docs/TOOL_REFERENCE.md).
134
+ Specialized Agents use sqlew more efficiently.
120
135
 
121
136
  ## Specialized Agents
122
137
 
@@ -128,7 +143,7 @@ sqlew provides three specialized agents for efficient multi-agent coordination i
128
143
  | **Researcher** | Query decisions, analyze patterns, investigate context | 14KB/conversation | Understanding past decisions, onboarding new members, sprint retrospectives |
129
144
  | **Architect** | Document decisions, enforce constraints, maintain standards | 20KB/conversation | Making architectural choices, establishing rules, validating compliance |
130
145
 
131
- ### Installation
146
+ ### Detailed Installation
132
147
 
133
148
  **By default, all three specialized agents are automatically installed** to your project's `.claude/agents/` directory on first run.
134
149
 
@@ -156,22 +171,25 @@ Savings: Scrum + Architect = 32KB (30%) | Scrum only = 12KB (74%)
156
171
 
157
172
  | Tool | Purpose | Example Use |
158
173
  |------|---------|------------|
159
- | **decision** | Record choices | "We chose PostgreSQL" |
174
+ | **decision** | Record choices and reasons | "We chose PostgreSQL" |
175
+ | **constraint** | Define rules | "DO NOT use raw SQL, use ORM" |
160
176
  | **task** | Track work | "Implement feature X" |
161
177
  | **file** | Track changes | "Modified auth.ts" |
162
- | **constraint** | Define rules | "API must be <100ms" |
163
178
  | **stats** | Database metrics | Get layer summary |
164
- | **config** | Retention settings | Auto-cleanup config |
165
179
 
166
- Each tool supports `action: "help"` for full documentation and `action: "example"` for comprehensive usage examples.
167
180
 
168
181
  ## Documentation
169
182
 
183
+ Each tool supports `action: "help"` for full documentation and `action: "example"` for comprehensive usage examples.
184
+
185
+ And `action: "use_case"` shows how to use the tool in a real-world scenario.
186
+
170
187
  ### On-Demand Documentation
171
188
 
172
189
  All tools support:
173
190
  - `action: "help"` - Parameter reference and descriptions
174
191
  - `action: "example"` - Usage scenarios and examples
192
+ - `action: "use_case"` - Real-world usage examples
175
193
 
176
194
  ### For AI Agents
177
195
 
@@ -201,6 +219,7 @@ All tools support:
201
219
  ### For Developers
202
220
 
203
221
  - [Configuration Guide](docs/CONFIGURATION.md) - TOML config file setup
222
+ - [Database Migration](docs/DATABASE_MIGRATION.md) - SQLite → MySQL/PostgreSQL migration
204
223
  - [Building from Source](docs/ARCHITECTURE.md#development) - Setup instructions
205
224
  - [Migration Guides](docs/MIGRATION_v2.md) - Version upgrade guides
206
225
 
@@ -226,7 +245,7 @@ Support development via [GitHub Sponsors](https://github.com/sponsors/sin5ddd) -
226
245
 
227
246
  ## Version
228
247
 
229
- Current version: **3.6.6**
248
+ Current version: **3.7.0**
230
249
  See [CHANGELOG.md](CHANGELOG.md) for release history.
231
250
 
232
251
  ## License