projectbudget 0.1.0__tar.gz

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 (210) hide show
  1. projectbudget-0.1.0/.gitignore +38 -0
  2. projectbudget-0.1.0/LICENSE +201 -0
  3. projectbudget-0.1.0/NOTICE +5 -0
  4. projectbudget-0.1.0/PKG-INFO +125 -0
  5. projectbudget-0.1.0/README.md +87 -0
  6. projectbudget-0.1.0/docs/adr/000-template.md +17 -0
  7. projectbudget-0.1.0/docs/adr/001-database-sqlite-default-postgresql-supported.md +23 -0
  8. projectbudget-0.1.0/docs/adr/002-ui-jinja2-htmx-with-json-api-parity.md +23 -0
  9. projectbudget-0.1.0/docs/adr/003-money-integer-minor-units-one-currency.md +21 -0
  10. projectbudget-0.1.0/docs/adr/004-item-kind-and-consolidation.md +27 -0
  11. projectbudget-0.1.0/docs/adr/005-auth-single-owner-principal-chokepoint.md +24 -0
  12. projectbudget-0.1.0/docs/adr/006-forecast-v1-semantics.md +26 -0
  13. projectbudget-0.1.0/docs/adr/007-sync-contract.md +25 -0
  14. projectbudget-0.1.0/docs/adr/008-canonical-export-format.md +21 -0
  15. projectbudget-0.1.0/docs/adr/009-license-apache-2-no-cla.md +18 -0
  16. projectbudget-0.1.0/docs/adr/010-distribution.md +23 -0
  17. projectbudget-0.1.0/docs/adr/011-deferred-list-is-binding.md +20 -0
  18. projectbudget-0.1.0/docs/adr/012-per-project-lists-one-budget.md +42 -0
  19. projectbudget-0.1.0/docs/adr/013-agent-access-manifest-first-mcp-over-api.md +41 -0
  20. projectbudget-0.1.0/docs/adr/README.md +21 -0
  21. projectbudget-0.1.0/docs/agents/AGENTS-section.md +49 -0
  22. projectbudget-0.1.0/docs/agents/README.md +16 -0
  23. projectbudget-0.1.0/docs/agents/skills/shopping-list/SKILL.md +60 -0
  24. projectbudget-0.1.0/docs/manifest.md +74 -0
  25. projectbudget-0.1.0/docs/manifest.schema.json +209 -0
  26. projectbudget-0.1.0/docs/operations.md +169 -0
  27. projectbudget-0.1.0/docs/release.md +38 -0
  28. projectbudget-0.1.0/docs/rfc/ProjectBudget-RFC-v2.md +334 -0
  29. projectbudget-0.1.0/docs/rfc/ProjectBudget-RFC-v3.md +346 -0
  30. projectbudget-0.1.0/docs/threat-model.md +50 -0
  31. projectbudget-0.1.0/pyproject.toml +173 -0
  32. projectbudget-0.1.0/src/projectbudget/__init__.py +10 -0
  33. projectbudget-0.1.0/src/projectbudget/adapters/__init__.py +5 -0
  34. projectbudget-0.1.0/src/projectbudget/adapters/export_format.py +220 -0
  35. projectbudget-0.1.0/src/projectbudget/adapters/manifest.py +341 -0
  36. projectbudget-0.1.0/src/projectbudget/adapters/sources.py +232 -0
  37. projectbudget-0.1.0/src/projectbudget/api/__init__.py +1 -0
  38. projectbudget-0.1.0/src/projectbudget/api/backlog.py +20 -0
  39. projectbudget-0.1.0/src/projectbudget/api/budget.py +56 -0
  40. projectbudget-0.1.0/src/projectbudget/api/catalog.py +129 -0
  41. projectbudget-0.1.0/src/projectbudget/api/forecast.py +20 -0
  42. projectbudget-0.1.0/src/projectbudget/api/projects.py +57 -0
  43. projectbudget-0.1.0/src/projectbudget/api/purchases.py +154 -0
  44. projectbudget-0.1.0/src/projectbudget/api/requirements.py +92 -0
  45. projectbudget-0.1.0/src/projectbudget/api/router.py +115 -0
  46. projectbudget-0.1.0/src/projectbudget/api/schemas.py +997 -0
  47. projectbudget-0.1.0/src/projectbudget/api/sync.py +135 -0
  48. projectbudget-0.1.0/src/projectbudget/api/transfer.py +36 -0
  49. projectbudget-0.1.0/src/projectbudget/cli/__init__.py +1 -0
  50. projectbudget-0.1.0/src/projectbudget/cli/demo.py +51 -0
  51. projectbudget-0.1.0/src/projectbudget/cli/main.py +554 -0
  52. projectbudget-0.1.0/src/projectbudget/domain/__init__.py +1 -0
  53. projectbudget-0.1.0/src/projectbudget/domain/catalog.py +173 -0
  54. projectbudget-0.1.0/src/projectbudget/domain/consolidation.py +264 -0
  55. projectbudget-0.1.0/src/projectbudget/domain/forecast.py +381 -0
  56. projectbudget-0.1.0/src/projectbudget/domain/manifest.py +80 -0
  57. projectbudget-0.1.0/src/projectbudget/domain/money.py +191 -0
  58. projectbudget-0.1.0/src/projectbudget/domain/principal.py +23 -0
  59. projectbudget-0.1.0/src/projectbudget/domain/sync.py +506 -0
  60. projectbudget-0.1.0/src/projectbudget/fixtures/__init__.py +1 -0
  61. projectbudget-0.1.0/src/projectbudget/fixtures/canonical.py +178 -0
  62. projectbudget-0.1.0/src/projectbudget/localtime.py +90 -0
  63. projectbudget-0.1.0/src/projectbudget/mcp_server.py +351 -0
  64. projectbudget-0.1.0/src/projectbudget/persistence/__init__.py +5 -0
  65. projectbudget-0.1.0/src/projectbudget/persistence/backup.py +63 -0
  66. projectbudget-0.1.0/src/projectbudget/persistence/base.py +23 -0
  67. projectbudget-0.1.0/src/projectbudget/persistence/engine.py +96 -0
  68. projectbudget-0.1.0/src/projectbudget/persistence/migrate.py +100 -0
  69. projectbudget-0.1.0/src/projectbudget/persistence/migrations/env.py +55 -0
  70. projectbudget-0.1.0/src/projectbudget/persistence/migrations/script.py.mako +24 -0
  71. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0001_initial.py +24 -0
  72. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0002_owner_auth.py +87 -0
  73. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0003_domain_core.py +141 -0
  74. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0004_inventory_and_backlog_order.py +74 -0
  75. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0005_budget_plan_and_purchases.py +151 -0
  76. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0006_catalog_merge_redirect.py +39 -0
  77. projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0007_sync_sources_and_source_refs.py +129 -0
  78. projectbudget-0.1.0/src/projectbudget/persistence/models.py +371 -0
  79. projectbudget-0.1.0/src/projectbudget/persistence/session.py +11 -0
  80. projectbudget-0.1.0/src/projectbudget/py.typed +0 -0
  81. projectbudget-0.1.0/src/projectbudget/services/__init__.py +1 -0
  82. projectbudget-0.1.0/src/projectbudget/services/auth.py +367 -0
  83. projectbudget-0.1.0/src/projectbudget/services/backlog.py +150 -0
  84. projectbudget-0.1.0/src/projectbudget/services/budget.py +237 -0
  85. projectbudget-0.1.0/src/projectbudget/services/catalog.py +518 -0
  86. projectbudget-0.1.0/src/projectbudget/services/clock.py +15 -0
  87. projectbudget-0.1.0/src/projectbudget/services/errors.py +95 -0
  88. projectbudget-0.1.0/src/projectbudget/services/forecast.py +27 -0
  89. projectbudget-0.1.0/src/projectbudget/services/guards.py +30 -0
  90. projectbudget-0.1.0/src/projectbudget/services/inventory.py +314 -0
  91. projectbudget-0.1.0/src/projectbudget/services/passwords.py +55 -0
  92. projectbudget-0.1.0/src/projectbudget/services/projects.py +128 -0
  93. projectbudget-0.1.0/src/projectbudget/services/purchases.py +588 -0
  94. projectbudget-0.1.0/src/projectbudget/services/requirements.py +318 -0
  95. projectbudget-0.1.0/src/projectbudget/services/sync.py +966 -0
  96. projectbudget-0.1.0/src/projectbudget/services/tokens.py +147 -0
  97. projectbudget-0.1.0/src/projectbudget/services/transfer.py +536 -0
  98. projectbudget-0.1.0/src/projectbudget/services/workspace.py +57 -0
  99. projectbudget-0.1.0/src/projectbudget/settings.py +119 -0
  100. projectbudget-0.1.0/src/projectbudget/web/__init__.py +4 -0
  101. projectbudget-0.1.0/src/projectbudget/web/app.py +79 -0
  102. projectbudget-0.1.0/src/projectbudget/web/auth.py +146 -0
  103. projectbudget-0.1.0/src/projectbudget/web/errors.py +94 -0
  104. projectbudget-0.1.0/src/projectbudget/web/health.py +56 -0
  105. projectbudget-0.1.0/src/projectbudget/web/pages/__init__.py +1 -0
  106. projectbudget-0.1.0/src/projectbudget/web/pages/account.py +90 -0
  107. projectbudget-0.1.0/src/projectbudget/web/pages/backlog.py +59 -0
  108. projectbudget-0.1.0/src/projectbudget/web/pages/budget.py +112 -0
  109. projectbudget-0.1.0/src/projectbudget/web/pages/catalog.py +220 -0
  110. projectbudget-0.1.0/src/projectbudget/web/pages/data.py +67 -0
  111. projectbudget-0.1.0/src/projectbudget/web/pages/login.py +137 -0
  112. projectbudget-0.1.0/src/projectbudget/web/pages/projects.py +313 -0
  113. projectbudget-0.1.0/src/projectbudget/web/pages/purchases.py +231 -0
  114. projectbudget-0.1.0/src/projectbudget/web/pages/sync.py +242 -0
  115. projectbudget-0.1.0/src/projectbudget/web/pages/timeline.py +97 -0
  116. projectbudget-0.1.0/src/projectbudget/web/pages/tokens.py +78 -0
  117. projectbudget-0.1.0/src/projectbudget/web/security.py +109 -0
  118. projectbudget-0.1.0/src/projectbudget/web/static/app.css +164 -0
  119. projectbudget-0.1.0/src/projectbudget/web/static/confirm.js +29 -0
  120. projectbudget-0.1.0/src/projectbudget/web/static/favicon.svg +1 -0
  121. projectbudget-0.1.0/src/projectbudget/web/static/timeline.js +112 -0
  122. projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/LICENSE.md +9 -0
  123. projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/README.md +10 -0
  124. projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/chart.umd.js +14 -0
  125. projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/LICENSE +13 -0
  126. projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/README.md +9 -0
  127. projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/htmx.min.js +1 -0
  128. projectbudget-0.1.0/src/projectbudget/web/templates/account.html +28 -0
  129. projectbudget-0.1.0/src/projectbudget/web/templates/backlog.html +41 -0
  130. projectbudget-0.1.0/src/projectbudget/web/templates/base.html +42 -0
  131. projectbudget-0.1.0/src/projectbudget/web/templates/budget.html +83 -0
  132. projectbudget-0.1.0/src/projectbudget/web/templates/catalog.html +57 -0
  133. projectbudget-0.1.0/src/projectbudget/web/templates/catalog_item.html +110 -0
  134. projectbudget-0.1.0/src/projectbudget/web/templates/data.html +37 -0
  135. projectbudget-0.1.0/src/projectbudget/web/templates/error.html +9 -0
  136. projectbudget-0.1.0/src/projectbudget/web/templates/login.html +23 -0
  137. projectbudget-0.1.0/src/projectbudget/web/templates/partials/backlog_table.html +77 -0
  138. projectbudget-0.1.0/src/projectbudget/web/templates/partials/requirement_row.html +73 -0
  139. projectbudget-0.1.0/src/projectbudget/web/templates/partials/token_row.html +18 -0
  140. projectbudget-0.1.0/src/projectbudget/web/templates/project.html +112 -0
  141. projectbudget-0.1.0/src/projectbudget/web/templates/projects.html +32 -0
  142. projectbudget-0.1.0/src/projectbudget/web/templates/purchase.html +101 -0
  143. projectbudget-0.1.0/src/projectbudget/web/templates/purchases.html +50 -0
  144. projectbudget-0.1.0/src/projectbudget/web/templates/setup_required.html +12 -0
  145. projectbudget-0.1.0/src/projectbudget/web/templates/sync.html +56 -0
  146. projectbudget-0.1.0/src/projectbudget/web/templates/sync_source.html +166 -0
  147. projectbudget-0.1.0/src/projectbudget/web/templates/timeline.html +136 -0
  148. projectbudget-0.1.0/src/projectbudget/web/templates/tokens.html +39 -0
  149. projectbudget-0.1.0/src/projectbudget/web/templates.py +54 -0
  150. projectbudget-0.1.0/tests/conftest.py +155 -0
  151. projectbudget-0.1.0/tests/e2e/__init__.py +0 -0
  152. projectbudget-0.1.0/tests/e2e/conftest.py +117 -0
  153. projectbudget-0.1.0/tests/e2e/test_smoke.py +390 -0
  154. projectbudget-0.1.0/tests/fixtures/workspace.json +243 -0
  155. projectbudget-0.1.0/tests/test_acceptance.py +276 -0
  156. projectbudget-0.1.0/tests/test_acceptance_sync.py +176 -0
  157. projectbudget-0.1.0/tests/test_accessibility.py +55 -0
  158. projectbudget-0.1.0/tests/test_agent_kit.py +139 -0
  159. projectbudget-0.1.0/tests/test_api_and_tokens.py +125 -0
  160. projectbudget-0.1.0/tests/test_api_domain.py +200 -0
  161. projectbudget-0.1.0/tests/test_api_forecast.py +172 -0
  162. projectbudget-0.1.0/tests/test_api_purchases.py +164 -0
  163. projectbudget-0.1.0/tests/test_api_sync.py +230 -0
  164. projectbudget-0.1.0/tests/test_auth_service.py +325 -0
  165. projectbudget-0.1.0/tests/test_backlog_service.py +223 -0
  166. projectbudget-0.1.0/tests/test_backup.py +119 -0
  167. projectbudget-0.1.0/tests/test_budget_service.py +153 -0
  168. projectbudget-0.1.0/tests/test_catalog_merge.py +219 -0
  169. projectbudget-0.1.0/tests/test_catalog_service.py +332 -0
  170. projectbudget-0.1.0/tests/test_cli.py +393 -0
  171. projectbudget-0.1.0/tests/test_cli_sync.py +83 -0
  172. projectbudget-0.1.0/tests/test_collection.py +40 -0
  173. projectbudget-0.1.0/tests/test_consolidation.py +360 -0
  174. projectbudget-0.1.0/tests/test_demo.py +69 -0
  175. projectbudget-0.1.0/tests/test_domain_catalog.py +99 -0
  176. projectbudget-0.1.0/tests/test_engine.py +112 -0
  177. projectbudget-0.1.0/tests/test_fixture_file.py +36 -0
  178. projectbudget-0.1.0/tests/test_forecast.py +339 -0
  179. projectbudget-0.1.0/tests/test_health.py +54 -0
  180. projectbudget-0.1.0/tests/test_invariants.py +343 -0
  181. projectbudget-0.1.0/tests/test_inventory_concurrency.py +193 -0
  182. projectbudget-0.1.0/tests/test_inventory_service.py +155 -0
  183. projectbudget-0.1.0/tests/test_localtime.py +107 -0
  184. projectbudget-0.1.0/tests/test_manifest_parsing.py +174 -0
  185. projectbudget-0.1.0/tests/test_mcp_server.py +312 -0
  186. projectbudget-0.1.0/tests/test_migrations.py +34 -0
  187. projectbudget-0.1.0/tests/test_money.py +184 -0
  188. projectbudget-0.1.0/tests/test_package.py +22 -0
  189. projectbudget-0.1.0/tests/test_pages.py +528 -0
  190. projectbudget-0.1.0/tests/test_pages_purchases.py +237 -0
  191. projectbudget-0.1.0/tests/test_pages_sync.py +370 -0
  192. projectbudget-0.1.0/tests/test_pages_timeline.py +225 -0
  193. projectbudget-0.1.0/tests/test_passwords.py +27 -0
  194. projectbudget-0.1.0/tests/test_pr_helpers.py +391 -0
  195. projectbudget-0.1.0/tests/test_projects_service.py +92 -0
  196. projectbudget-0.1.0/tests/test_purchases_concurrency.py +133 -0
  197. projectbudget-0.1.0/tests/test_purchases_lifecycle.py +225 -0
  198. projectbudget-0.1.0/tests/test_purchases_service.py +233 -0
  199. projectbudget-0.1.0/tests/test_requirements_service.py +324 -0
  200. projectbudget-0.1.0/tests/test_routes_require_owner.py +89 -0
  201. projectbudget-0.1.0/tests/test_security_headers.py +40 -0
  202. projectbudget-0.1.0/tests/test_settings.py +72 -0
  203. projectbudget-0.1.0/tests/test_sources.py +189 -0
  204. projectbudget-0.1.0/tests/test_sync_plan.py +669 -0
  205. projectbudget-0.1.0/tests/test_sync_service.py +1011 -0
  206. projectbudget-0.1.0/tests/test_templates_safe.py +67 -0
  207. projectbudget-0.1.0/tests/test_tokens_service.py +86 -0
  208. projectbudget-0.1.0/tests/test_transfer.py +251 -0
  209. projectbudget-0.1.0/tests/test_web_auth.py +275 -0
  210. projectbudget-0.1.0/tests/test_workspace_service.py +37 -0
@@ -0,0 +1,38 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ .python-version.local
9
+
10
+ # Tooling caches
11
+ .ruff_cache/
12
+ .mypy_cache/
13
+ .pytest_cache/
14
+ .hypothesis/
15
+ .coverage
16
+ coverage.xml
17
+ htmlcov/
18
+
19
+ # Secrets and local config (ADR-005: secrets never live in the repo)
20
+ .env
21
+ .env.*
22
+ !.env.example
23
+
24
+ # Local data
25
+ *.sqlite
26
+ *.sqlite3
27
+ *.db
28
+ *.db-wal
29
+ *.db-shm
30
+
31
+ # Editors and OS
32
+ .idea/
33
+ .vscode/
34
+ *.swp
35
+ .DS_Store
36
+ Thumbs.db
37
+ .playwright-mcp/
38
+ .claude/settings.local.json
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,5 @@
1
+ ProjectBudget
2
+ Copyright 2026 Sean Deery
3
+
4
+ This product is licensed under the Apache License, Version 2.0.
5
+ See the LICENSE file for the full text.
@@ -0,0 +1,125 @@
1
+ Metadata-Version: 2.5
2
+ Name: projectbudget
3
+ Version: 0.1.0
4
+ Summary: One honest shopping backlog across all your projects, scheduled against your budget.
5
+ Project-URL: Homepage, https://github.com/sdeery14/project-budget
6
+ Project-URL: Documentation, https://github.com/sdeery14/project-budget/tree/main/docs
7
+ Project-URL: Issues, https://github.com/sdeery14/project-budget/issues
8
+ Project-URL: Changelog, https://github.com/sdeery14/project-budget/releases
9
+ Author: Sean Deery
10
+ License-Expression: Apache-2.0
11
+ License-File: LICENSE
12
+ License-File: NOTICE
13
+ Keywords: backlog,budget,forecast,maker,projects,self-hosted
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Intended Audience :: End Users/Desktop
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Office/Business :: Financial
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: alembic>=1.14
25
+ Requires-Dist: argon2-cffi>=23.1
26
+ Requires-Dist: fastapi>=0.115
27
+ Requires-Dist: jinja2>=3.1
28
+ Requires-Dist: mcp>=2.3
29
+ Requires-Dist: psycopg[binary]>=3.2
30
+ Requires-Dist: pydantic-settings>=2.6
31
+ Requires-Dist: python-multipart>=0.0.18
32
+ Requires-Dist: pyyaml>=6.0.3
33
+ Requires-Dist: sqlalchemy>=2.0.36
34
+ Requires-Dist: typer>=0.15
35
+ Requires-Dist: tzdata>=2024.1
36
+ Requires-Dist: uvicorn[standard]>=0.32
37
+ Description-Content-Type: text/markdown
38
+
39
+ # ProjectBudget
40
+
41
+ **Given everything my projects still need, what can I buy next, and when?**
42
+
43
+ ProjectBudget keeps several projects' shopping lists honest against one budget. Each project says what it still needs, as a manifest in its repository or a list you type in; the backlog puts all of it in one priority queue; the timeline schedules the purchases month by month against a discretionary budget you enter yourself. It is for makers, cyclists, homelabbers and DIYers running two or more projects at once, self-hosted as one process on a laptop, NAS or small VPS. SQLite by default, PostgreSQL supported, no telemetry, your data exports to one JSON file.
44
+
45
+ ## Quickstart
46
+
47
+ ```sh
48
+ # Try it on fictional data first (throwaway database, login printed on start)
49
+ uvx projectbudget run --demo
50
+
51
+ # Zero-infrastructure install: SQLite in ~/.projectbudget/
52
+ uvx projectbudget init --username you # creates the owner; prompts for a password; --currency EUR to change the default USD
53
+ uvx projectbudget run # then sign in at http://127.0.0.1:8000/login
54
+
55
+ # Or a single container with SQLite on a volume
56
+ docker run -d --name projectbudget -p 8000:8000 -v projectbudget-data:/data ghcr.io/sdeery14/projectbudget
57
+ docker exec -it projectbudget projectbudget init --username you
58
+ ```
59
+
60
+ PostgreSQL users: `cp .env.example .env`, set `POSTGRES_PASSWORD`, `docker compose up -d`, then `docker compose exec app projectbudget init --username you`. The [operations guide](docs/operations.md) covers configuration, running behind a reverse proxy, backups, the restore drill and upgrades.
61
+
62
+ There are no default credentials: the app serves only `/health` until `init` has run. The session cookie is `Secure` by default; browsers treat `localhost` as secure, so that only matters for plain HTTP on another host (`PROJECTBUDGET_SECURE_COOKIES=false` relaxes it on a trusted network).
63
+
64
+ ## How it works
65
+
66
+ One loop. Projects say what they need, the budget says what there is, and the two read-only pages in the middle answer the question at the top of this file.
67
+
68
+ ```text
69
+ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
70
+ │ 1 Projects │──►│ 2 Budget │──►│ 3 Backlog │──►│ 4 Timeline │──►│ 5 Purchase │
71
+ │ what each │ │ what you │ │ what to │ │ when the │ │ order, │
72
+ │ one needs │ │ have │ │ buy next │ │ money is │ │ receive, │
73
+ │ │ │ │ │ │ │ there │ │ consume │
74
+ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └─────┬──────┘
75
+ ▲ │
76
+ └──── manifests re-sync as projects change; stock lowers the need ◄─┘
77
+ ```
78
+
79
+ 1. **Add projects.** On the Projects page, type what a project needs: a name, a quantity, a priority. Or keep a `project-budget.yaml` next to the project, in a folder under the import directory or in a GitHub repository, add it as a sync source, preview the plan and apply it ([manifest guide](docs/manifest.md)). A synced project follows its manifest; a hand-made one is yours to edit.
80
+ 2. **Set the budget.** On the Budget page, enter the balance set aside for projects, the date it was true, a protected reserve the timeline never spends below, and the monthly contribution.
81
+ 3. **Read the backlog.** One queue across every project, priority first, with stock and open orders already subtracted and unpriced items flagged rather than summed. Price an item from its catalog page when the backlog says it needs one.
82
+ 4. **Read the timeline.** The same queue laid against the budget month by month: for each item, the month it becomes affordable, and for each month, opening balance, contribution, purchases and closing balance.
83
+ 5. **Buy.** Click "Mark purchased" on the timeline, or record the order on the Purchases page. Receive it when it arrives, which puts it in stock and records the price you paid, then consume it against the project when you use it. The backlog and timeline update on their own.
84
+
85
+ Then repeat: edit the manifest or the project as plans change, sync again, and the queue moves with it. Nothing is deleted by a sync; items that leave a manifest are archived and keep their purchase history.
86
+
87
+ Planning with a coding agent? [docs/agents/](docs/agents/) holds an `AGENTS.md` section and a Claude Code skill to copy into a project repository, so Claude Code, Codex or ChatGPT write the manifest for you and check it with `projectbudget manifest validate` before you sync it. `projectbudget mcp` gives an agent on the same machine live access through the JSON API, with a token you can make read-only and revoke; the setup is in the [operations guide](docs/operations.md#mcp-server).
88
+
89
+ ## What it does
90
+
91
+ - **One backlog across projects.** Every project's active requirements in one queue: priority first, then project, then the project's own order, which for a synced project is the manifest's file order. A part that several projects need shows once: consumables add up, reusable tools count once for the largest single demand or per project when marked exclusive. Stock and on-order quantities are shown, so you see the shortfall and what is already coming.
92
+ - **Honest totals.** An item without a price is counted, flagged and never summed as zero. Totals are labelled lower bounds whenever anything is unpriced.
93
+ - **Explainable timeline.** Enter the balance you have set aside, the date it was true, a protected reserve and a monthly contribution. Every month shows opening balance, contribution, purchases and closing balance, in strict priority order with no clever reordering, with an optimistic and a conservative date per item. Guards tell you when something is not fundable, beyond the horizon, blocked because the balance stays below the reserve, or priced from a stale estimate.
94
+ - **Purchases and inventory.** Record what you ordered or bought line by line, receive it in parts, consume it against a project, or mark a timeline item purchased in one click. Spending visibly leaves the budget.
95
+ - **Catalog.** Items with stable slugs, kinds and units; price history per item; duplicates merged in one step with redirects so old links keep working.
96
+ - **Sync.** Keep a `project-budget.yaml` next to a project, in a folder under the import directory or in a GitHub repository, and pull it in: a dry-run plan first, then one-transaction apply. Items that leave the manifest are archived, never deleted; purchases, stock and the budget are never touched. See the [manifest guide](docs/manifest.md) and the [schema](docs/manifest.schema.json).
97
+ - **Export and import.** The whole workspace as one versioned JSON document, id for id, for backup, moving between SQLite and PostgreSQL, or seeding a demo. Plus `projectbudget backup` for a consistent SQLite copy.
98
+ - **JSON API.** Everything the pages do is available under `/api/v1` with bearer tokens you create on the API tokens page (read-only or read-write); the OpenAPI document is at `/api/v1/openapi.json` once signed in.
99
+
100
+ ## Command line
101
+
102
+ | Command | Does |
103
+ | --- | --- |
104
+ | `projectbudget init --username NAME [--currency USD]` | apply migrations, create the owner, fix the currency |
105
+ | `projectbudget passwd --username NAME` | set a new password without the old one (forgotten password); signs every session out |
106
+ | `projectbudget run [--host] [--port] [--demo]` | start the single-worker server |
107
+ | `projectbudget export [--output PATH]` / `import PATH [--replace]` | the JSON workspace document |
108
+ | `projectbudget backup [--output PATH]` | consistent SQLite copy (`VACUUM INTO`) |
109
+ | `projectbudget reset [--yes]` | empty the workspace, keeping the owner, sessions, tokens and currency |
110
+ | `projectbudget sync SOURCE_ID [--dry-run] [--force]` | pull a manifest and apply its plan |
111
+ | `projectbudget manifest validate PATH [--project-id ID] [--format json]` | check a `project-budget.yaml` (or a CSV) with the sync parser, no server needed; exit 1 lists every problem with its line |
112
+ | `projectbudget mcp [--url URL]` | serve the Model Context Protocol on stdio for a coding agent, as a client of the JSON API with the token in `PROJECTBUDGET_API_TOKEN` |
113
+ | `projectbudget db upgrade\|downgrade\|current` | migrations |
114
+
115
+ ## Design and security
116
+
117
+ The design is settled in the [RFC v3](docs/rfc/ProjectBudget-RFC-v3.md) and recorded as [ADRs](docs/adr/). The [threat model](docs/threat-model.md) says what V1 protects and what it leaves out. Security reports go through [SECURITY.md](SECURITY.md), never public issues.
118
+
119
+ ## Contributing
120
+
121
+ See [CONTRIBUTING.md](CONTRIBUTING.md). One command sets up a dev environment: `uv sync --group dev && uv run pre-commit install`. Releases follow [docs/release.md](docs/release.md); changes are listed in [CHANGELOG.md](CHANGELOG.md).
122
+
123
+ ## License
124
+
125
+ Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
@@ -0,0 +1,87 @@
1
+ # ProjectBudget
2
+
3
+ **Given everything my projects still need, what can I buy next, and when?**
4
+
5
+ ProjectBudget keeps several projects' shopping lists honest against one budget. Each project says what it still needs, as a manifest in its repository or a list you type in; the backlog puts all of it in one priority queue; the timeline schedules the purchases month by month against a discretionary budget you enter yourself. It is for makers, cyclists, homelabbers and DIYers running two or more projects at once, self-hosted as one process on a laptop, NAS or small VPS. SQLite by default, PostgreSQL supported, no telemetry, your data exports to one JSON file.
6
+
7
+ ## Quickstart
8
+
9
+ ```sh
10
+ # Try it on fictional data first (throwaway database, login printed on start)
11
+ uvx projectbudget run --demo
12
+
13
+ # Zero-infrastructure install: SQLite in ~/.projectbudget/
14
+ uvx projectbudget init --username you # creates the owner; prompts for a password; --currency EUR to change the default USD
15
+ uvx projectbudget run # then sign in at http://127.0.0.1:8000/login
16
+
17
+ # Or a single container with SQLite on a volume
18
+ docker run -d --name projectbudget -p 8000:8000 -v projectbudget-data:/data ghcr.io/sdeery14/projectbudget
19
+ docker exec -it projectbudget projectbudget init --username you
20
+ ```
21
+
22
+ PostgreSQL users: `cp .env.example .env`, set `POSTGRES_PASSWORD`, `docker compose up -d`, then `docker compose exec app projectbudget init --username you`. The [operations guide](docs/operations.md) covers configuration, running behind a reverse proxy, backups, the restore drill and upgrades.
23
+
24
+ There are no default credentials: the app serves only `/health` until `init` has run. The session cookie is `Secure` by default; browsers treat `localhost` as secure, so that only matters for plain HTTP on another host (`PROJECTBUDGET_SECURE_COOKIES=false` relaxes it on a trusted network).
25
+
26
+ ## How it works
27
+
28
+ One loop. Projects say what they need, the budget says what there is, and the two read-only pages in the middle answer the question at the top of this file.
29
+
30
+ ```text
31
+ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
32
+ │ 1 Projects │──►│ 2 Budget │──►│ 3 Backlog │──►│ 4 Timeline │──►│ 5 Purchase │
33
+ │ what each │ │ what you │ │ what to │ │ when the │ │ order, │
34
+ │ one needs │ │ have │ │ buy next │ │ money is │ │ receive, │
35
+ │ │ │ │ │ │ │ there │ │ consume │
36
+ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └─────┬──────┘
37
+ ▲ │
38
+ └──── manifests re-sync as projects change; stock lowers the need ◄─┘
39
+ ```
40
+
41
+ 1. **Add projects.** On the Projects page, type what a project needs: a name, a quantity, a priority. Or keep a `project-budget.yaml` next to the project, in a folder under the import directory or in a GitHub repository, add it as a sync source, preview the plan and apply it ([manifest guide](docs/manifest.md)). A synced project follows its manifest; a hand-made one is yours to edit.
42
+ 2. **Set the budget.** On the Budget page, enter the balance set aside for projects, the date it was true, a protected reserve the timeline never spends below, and the monthly contribution.
43
+ 3. **Read the backlog.** One queue across every project, priority first, with stock and open orders already subtracted and unpriced items flagged rather than summed. Price an item from its catalog page when the backlog says it needs one.
44
+ 4. **Read the timeline.** The same queue laid against the budget month by month: for each item, the month it becomes affordable, and for each month, opening balance, contribution, purchases and closing balance.
45
+ 5. **Buy.** Click "Mark purchased" on the timeline, or record the order on the Purchases page. Receive it when it arrives, which puts it in stock and records the price you paid, then consume it against the project when you use it. The backlog and timeline update on their own.
46
+
47
+ Then repeat: edit the manifest or the project as plans change, sync again, and the queue moves with it. Nothing is deleted by a sync; items that leave a manifest are archived and keep their purchase history.
48
+
49
+ Planning with a coding agent? [docs/agents/](docs/agents/) holds an `AGENTS.md` section and a Claude Code skill to copy into a project repository, so Claude Code, Codex or ChatGPT write the manifest for you and check it with `projectbudget manifest validate` before you sync it. `projectbudget mcp` gives an agent on the same machine live access through the JSON API, with a token you can make read-only and revoke; the setup is in the [operations guide](docs/operations.md#mcp-server).
50
+
51
+ ## What it does
52
+
53
+ - **One backlog across projects.** Every project's active requirements in one queue: priority first, then project, then the project's own order, which for a synced project is the manifest's file order. A part that several projects need shows once: consumables add up, reusable tools count once for the largest single demand or per project when marked exclusive. Stock and on-order quantities are shown, so you see the shortfall and what is already coming.
54
+ - **Honest totals.** An item without a price is counted, flagged and never summed as zero. Totals are labelled lower bounds whenever anything is unpriced.
55
+ - **Explainable timeline.** Enter the balance you have set aside, the date it was true, a protected reserve and a monthly contribution. Every month shows opening balance, contribution, purchases and closing balance, in strict priority order with no clever reordering, with an optimistic and a conservative date per item. Guards tell you when something is not fundable, beyond the horizon, blocked because the balance stays below the reserve, or priced from a stale estimate.
56
+ - **Purchases and inventory.** Record what you ordered or bought line by line, receive it in parts, consume it against a project, or mark a timeline item purchased in one click. Spending visibly leaves the budget.
57
+ - **Catalog.** Items with stable slugs, kinds and units; price history per item; duplicates merged in one step with redirects so old links keep working.
58
+ - **Sync.** Keep a `project-budget.yaml` next to a project, in a folder under the import directory or in a GitHub repository, and pull it in: a dry-run plan first, then one-transaction apply. Items that leave the manifest are archived, never deleted; purchases, stock and the budget are never touched. See the [manifest guide](docs/manifest.md) and the [schema](docs/manifest.schema.json).
59
+ - **Export and import.** The whole workspace as one versioned JSON document, id for id, for backup, moving between SQLite and PostgreSQL, or seeding a demo. Plus `projectbudget backup` for a consistent SQLite copy.
60
+ - **JSON API.** Everything the pages do is available under `/api/v1` with bearer tokens you create on the API tokens page (read-only or read-write); the OpenAPI document is at `/api/v1/openapi.json` once signed in.
61
+
62
+ ## Command line
63
+
64
+ | Command | Does |
65
+ | --- | --- |
66
+ | `projectbudget init --username NAME [--currency USD]` | apply migrations, create the owner, fix the currency |
67
+ | `projectbudget passwd --username NAME` | set a new password without the old one (forgotten password); signs every session out |
68
+ | `projectbudget run [--host] [--port] [--demo]` | start the single-worker server |
69
+ | `projectbudget export [--output PATH]` / `import PATH [--replace]` | the JSON workspace document |
70
+ | `projectbudget backup [--output PATH]` | consistent SQLite copy (`VACUUM INTO`) |
71
+ | `projectbudget reset [--yes]` | empty the workspace, keeping the owner, sessions, tokens and currency |
72
+ | `projectbudget sync SOURCE_ID [--dry-run] [--force]` | pull a manifest and apply its plan |
73
+ | `projectbudget manifest validate PATH [--project-id ID] [--format json]` | check a `project-budget.yaml` (or a CSV) with the sync parser, no server needed; exit 1 lists every problem with its line |
74
+ | `projectbudget mcp [--url URL]` | serve the Model Context Protocol on stdio for a coding agent, as a client of the JSON API with the token in `PROJECTBUDGET_API_TOKEN` |
75
+ | `projectbudget db upgrade\|downgrade\|current` | migrations |
76
+
77
+ ## Design and security
78
+
79
+ The design is settled in the [RFC v3](docs/rfc/ProjectBudget-RFC-v3.md) and recorded as [ADRs](docs/adr/). The [threat model](docs/threat-model.md) says what V1 protects and what it leaves out. Security reports go through [SECURITY.md](SECURITY.md), never public issues.
80
+
81
+ ## Contributing
82
+
83
+ See [CONTRIBUTING.md](CONTRIBUTING.md). One command sets up a dev environment: `uv sync --group dev && uv run pre-commit install`. Releases follow [docs/release.md](docs/release.md); changes are listed in [CHANGELOG.md](CHANGELOG.md).
84
+
85
+ ## License
86
+
87
+ Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
@@ -0,0 +1,17 @@
1
+ # ADR-0NN: Title
2
+
3
+ **Status:** Proposed | Accepted | Superseded by ADR-0MM
4
+ **Date:** YYYY-MM-DD
5
+ **Implements:** RFC section or roadmap row this decision serves
6
+
7
+ ## Context
8
+
9
+ What situation forces a decision, and what constraints apply. Facts, not preferences.
10
+
11
+ ## Decision
12
+
13
+ What we will do, stated so a reviewer can check a PR against it.
14
+
15
+ ## Consequences
16
+
17
+ What becomes easier, what becomes harder, and what is now explicitly out of scope. If this moves something off the "Not in V1" list, say what it displaces (ADR-011).
@@ -0,0 +1,23 @@
1
+ # ADR-001: Database: SQLite default, PostgreSQL supported
2
+
3
+ **Status:** Accepted
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §3 (Architecture, Distribution), §8 (Testing)
6
+
7
+ ## Context
8
+
9
+ Self-hosters are hobbyists running one process on a laptop, NAS or small VPS. They should not need Docker Compose or a database server to try the product, and a backup should be something they can understand. A hosted maintainer instance may come later and would want PostgreSQL. Money is stored as integer minor units (ADR-003), so DECIMAL columns are not a reason to require PostgreSQL.
10
+
11
+ ## Decision
12
+
13
+ - SQLite is the default database. PostgreSQL is fully supported. Both run in CI for every PR.
14
+ - SQLAlchemy 2.0 against the **dialect-neutral subset**: no JSONB, no arrays, no partial indexes, no PostgreSQL enums. UUIDs are stored as text. Money is an integer. Enumerations are short text columns with a check constraint.
15
+ - Alembic migrations use batch mode so they apply on SQLite.
16
+ - The SQLite connect hook sets `PRAGMA foreign_keys=ON`, `journal_mode=WAL` and a busy timeout of 5 seconds on every connection. The test engine uses the same hook, so foreign-key violations fail on both backends.
17
+ - Backups: `projectbudget backup` runs `VACUUM INTO` for SQLite; `pg_dump` for PostgreSQL; `projectbudget export` (ADR-008) works for both. A plain copy of the SQLite file is documented as unsafe under WAL.
18
+
19
+ ## Consequences
20
+
21
+ - Trivially simple self-host: one file, zero infrastructure.
22
+ - A small feature tax on PostgreSQL: no PostgreSQL-only types or indexes until a hosted offering justifies a new ADR.
23
+ - There is no SQLite-only mode either; anything that works on one backend and not the other is a bug.
@@ -0,0 +1,23 @@
1
+ # ADR-002: UI: Jinja2 + HTMX with JSON API parity
2
+
3
+ **Status:** Accepted
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §3 (Routers), §7 (Security headers)
6
+
7
+ ## Context
8
+
9
+ The UI is forms, tables and one timeline chart. It must run on cheap hosts, be testable without a browser, and be maintainable by one person. It must also be usable on a phone in a store. A client-side framework would add a build step and a second codebase to keep in sync with the API.
10
+
11
+ ## Decision
12
+
13
+ - Server-rendered pages with Jinja2 and HTMX fragments. One vendored, no-build JavaScript chart library for the timeline.
14
+ - Every state-changing UI action has a JSON twin under `/api/v1`. Both route families call the same service functions with the same request models. Neither contains business logic. A test asserts parity.
15
+ - **No in-process state.** Login sessions and login rate-limit buckets are rows in the database. The app runs one worker by default; more are safe because nothing lives in process memory.
16
+ - HTMX 2 is pinned. Templates never use `hx-on` attributes or `js:`-prefixed values, so a Content Security Policy with no inline scripts and no `unsafe-eval` holds. A test greps the templates for both.
17
+ - Exit path: a single-page application can replace the templates without touching the service layer.
18
+
19
+ ## Consequences
20
+
21
+ - No WebSockets. Testable end to end with an HTTP client; a browser smoke test runs nightly, not per PR.
22
+ - Slightly less fluid grid editing than a client-side framework would give.
23
+ - Sessions survive restarts and multiple workers at the cost of one small table and one query per request.
@@ -0,0 +1,21 @@
1
+ # ADR-003: Money: integer minor units, one workspace currency
2
+
3
+ **Status:** Accepted
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §4 (Invariants), §6 (Money in the manifest)
6
+
7
+ ## Context
8
+
9
+ Budget software that drifts by a cent loses trust. Floats drift; DECIMAL columns are not available in the same form on SQLite and PostgreSQL (ADR-001). The target user has one currency.
10
+
11
+ ## Decision
12
+
13
+ - `Money(amount: int, currency: str)`: the amount is an integer in the currency's minor unit (cents for USD); the currency is an ISO 4217 code.
14
+ - The workspace currency is set at `projectbudget init`. Writes in any other currency are rejected. The fixture and documentation use USD.
15
+ - At every text boundary (manifest, CSV, API, export) money is a decimal string or an integer minor-unit field, never a float. The manifest JSON Schema rejects YAML numbers for `amount`; the parser uses `Decimal` and rejects more fractional digits than the currency allows.
16
+ - Arithmetic lives in the domain layer and is property-tested with Hypothesis.
17
+
18
+ ## Consequences
19
+
20
+ - No foreign exchange, no rounding drift, works identically on both databases.
21
+ - Multi-currency is on the "Not in V1" list and needs a new ADR (ADR-011).
@@ -0,0 +1,27 @@
1
+ # ADR-004: Item kind and consolidation
2
+
3
+ **Status:** Accepted, amended by ADR-012 (default order within a priority tier; money figures net of on-order)
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §4 (Domain model, Consolidation rules, Invariants)
6
+
7
+ ## Context
8
+
9
+ The product thesis is one honest backlog across projects. Parts are consumed; tools are reused. "3 clamps for project A and 2 for project B" must not become 5 clamps if one set moves between projects, and must become 5 if each project keeps its own. A consolidated row merges several requirements, so it needs a single priority and a single place in the queue.
10
+
11
+ ## Decision
12
+
13
+ - `CatalogItem.kind` is `consumable` or `reusable`. Reusable requirements carry `sharing` = `shared` (default) or `exclusive`.
14
+ - For each catalog item, over requirements with intent `active`:
15
+ - Consumable: gross shortfall = Σ qty − Σ consumed against those requirements − on-hand.
16
+ - Reusable: needed = max(shared qty) + Σ (exclusive qty − consumed against that requirement); gross shortfall = needed − on-hand.
17
+ - Gross shortfall floors at zero.
18
+ - **Shared reusable requirements are never consumed against.** The service layer rejects such a movement.
19
+ - **On-order** (unreceived quantity on purchases in `ordered` status) is a separate backlog column. The backlog shows gross shortfall; only the forecast (ADR-006) nets on-order out. An ordered item stays visible until received. *(ADR-012: money figures, the line totals and the "still to buy" total, now use net shortfall, the quantity the forecast buys; a second tile shows what is already committed on open orders. Quantities are unchanged.)*
20
+ - **Row priority** is the most urgent priority among the active contributing requirements. **Backlog order** is a workspace-level list on the budget plan; per-requirement `sort_order` orders only that project's view.
21
+ - The UI shows the sharing assumptions beside any shared reusable item: time overlap between projects is not modeled; shared is the default and a requirement can override to exclusive; permanently installed parts are better modeled as consumable; on-hand counts every unit regardless of which project last used it.
22
+
23
+ ## Consequences
24
+
25
+ - Correct backlog for tools and parts alike. Installing an exclusive item (consuming it) does not raise the shortfall.
26
+ - Time overlap between projects is explicitly not modeled.
27
+ - Each rule above is a named test; the worked example in the RFC (A needs 3 shared, B needs 2 shared, C needs 1 exclusive, 1 owned, shortfall 3) is a golden case.
@@ -0,0 +1,24 @@
1
+ # ADR-005: Auth: single owner now, principal chokepoint for later
2
+
3
+ **Status:** Accepted
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §3 (Services), §7 (Security requirements)
6
+
7
+ ## Context
8
+
9
+ V1 protects one owner's private budget data on an instance that may be reachable from the internet. Multi-user and multi-workspace are deferred, but the design must not make them expensive later.
10
+
11
+ ## Decision
12
+
13
+ - One owner, created by `projectbudget init`. No default credentials; the app refuses to serve until an owner exists.
14
+ - Passwords hashed with Argon2id. Session cookies with a random id and a session row in the database: HttpOnly, Secure (configurable off for localhost), SameSite=Lax, idle timeout, rotated on login.
15
+ - CSRF: Origin/Referer check on every state-changing request plus a per-session token in HTMX forms. Login rate limit with database-backed buckets and constant-time comparison.
16
+ - API tokens: random, shown once, stored as SHA-256 hashes, revocable, flagged read-only or read-write. No finer scopes in V1.
17
+ - A `require_owner` dependency on every router except `/health`, `/login` and static assets. A test walks the route table to prove it.
18
+ - Every service function receives a `Principal`. In V1 it is always the owner. There is no Workspace entity.
19
+ - Migration to multi-user: add `workspace_id` to root tables with a single backfilled value and enforce filtering in the service layer, which is already the only path to the database.
20
+
21
+ ## Consequences
22
+
23
+ - No premature tenancy. Authorization has exactly one place to live.
24
+ - Security headers, import limits, secret handling and backup drills are release blockers listed in RFC v3 §7 and tracked by named tests.
@@ -0,0 +1,26 @@
1
+ # ADR-006: Forecast V1 semantics
2
+
3
+ **Status:** Accepted
4
+ **Date:** 2026-11-07
5
+ **Implements:** RFC v3 §5 (Forecast semantics), Milestone 2
6
+
7
+ ## Context
8
+
9
+ The forecast is the product thesis: what can I buy next, and when. It must be explainable by eye, deterministic, and honest about what it does not know. It must also move when the user spends money, or the timeline becomes fiction after the first purchase.
10
+
11
+ ## Decision
12
+
13
+ - The forecast is a pure, deterministic function: `(BudgetPlan, backlog, purchases_since_as_of, today) → Schedule`. It touches no database. Every rule is a golden test.
14
+ - `BudgetPlan` carries `balance_as_of`; `earmarked_funds` is the balance on that date. Editing the balance resets `balance_as_of` to today.
15
+ - Month 1 opening balance = earmarked funds − protected reserve − Σ totals of purchases in `ordered` or `received` status dated on or after `balance_as_of`. Later months open with the previous closing.
16
+ - Each month: add the monthly contribution (month 1 receives the full contribution regardless of the day), apply labeled signed overrides, then buy from the head of the queue while it fits. Record opening, contribution, overrides, purchases and closing; that record is the explanation shown in the UI.
17
+ - Purchase unit: one backlog row is one indivisible purchase of net shortfall (gross shortfall − on-order, floored at zero) × latest unit estimate × (1 + contingency %). Rows with net shortfall 0 do not appear in the timeline.
18
+ - Queue order: row priority ascending, then the workspace backlog order. Strict; an item is never skipped because a cheaper one behind it would fit.
19
+ - Unpriced items go to a "needs a price" bucket, counted and never summed. Totals are labeled lower bounds. Shared reusable items are scheduled once; per-project views never sum to a grand total.
20
+ - Guards: "Not fundable at current inputs", "Beyond horizon" (default 36 months), stale-estimate flag at 90 days, blocked timeline while the balance is negative, "Balance may be stale" at 60 days, unpriced banner. *(#21: "blocked" is read as "the first month's balance after its contribution is still below zero"; a negative opening that the month's own contribution covers is not blocked, and the UI shows the opening floored at zero as "spendable" with the uncovered part of the reserve stated separately. The arithmetic is unchanged. A balance that already includes this month's contribution is offset with a negative current-month override; the budget page says so.)*
21
+ - Contingency % yields two schedules, optimistic and conservative; both dates are shown per item. The page carries: "Planning projection from your inputs; not financial advice."
22
+
23
+ ## Consequences
24
+
25
+ - Explainable by construction. Spending visibly reduces the plan.
26
+ - No optimization, reordering or partial buys. A "fill gaps" toggle and scenario comparison are deferred (ADR-011).