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.
- projectbudget-0.1.0/.gitignore +38 -0
- projectbudget-0.1.0/LICENSE +201 -0
- projectbudget-0.1.0/NOTICE +5 -0
- projectbudget-0.1.0/PKG-INFO +125 -0
- projectbudget-0.1.0/README.md +87 -0
- projectbudget-0.1.0/docs/adr/000-template.md +17 -0
- projectbudget-0.1.0/docs/adr/001-database-sqlite-default-postgresql-supported.md +23 -0
- projectbudget-0.1.0/docs/adr/002-ui-jinja2-htmx-with-json-api-parity.md +23 -0
- projectbudget-0.1.0/docs/adr/003-money-integer-minor-units-one-currency.md +21 -0
- projectbudget-0.1.0/docs/adr/004-item-kind-and-consolidation.md +27 -0
- projectbudget-0.1.0/docs/adr/005-auth-single-owner-principal-chokepoint.md +24 -0
- projectbudget-0.1.0/docs/adr/006-forecast-v1-semantics.md +26 -0
- projectbudget-0.1.0/docs/adr/007-sync-contract.md +25 -0
- projectbudget-0.1.0/docs/adr/008-canonical-export-format.md +21 -0
- projectbudget-0.1.0/docs/adr/009-license-apache-2-no-cla.md +18 -0
- projectbudget-0.1.0/docs/adr/010-distribution.md +23 -0
- projectbudget-0.1.0/docs/adr/011-deferred-list-is-binding.md +20 -0
- projectbudget-0.1.0/docs/adr/012-per-project-lists-one-budget.md +42 -0
- projectbudget-0.1.0/docs/adr/013-agent-access-manifest-first-mcp-over-api.md +41 -0
- projectbudget-0.1.0/docs/adr/README.md +21 -0
- projectbudget-0.1.0/docs/agents/AGENTS-section.md +49 -0
- projectbudget-0.1.0/docs/agents/README.md +16 -0
- projectbudget-0.1.0/docs/agents/skills/shopping-list/SKILL.md +60 -0
- projectbudget-0.1.0/docs/manifest.md +74 -0
- projectbudget-0.1.0/docs/manifest.schema.json +209 -0
- projectbudget-0.1.0/docs/operations.md +169 -0
- projectbudget-0.1.0/docs/release.md +38 -0
- projectbudget-0.1.0/docs/rfc/ProjectBudget-RFC-v2.md +334 -0
- projectbudget-0.1.0/docs/rfc/ProjectBudget-RFC-v3.md +346 -0
- projectbudget-0.1.0/docs/threat-model.md +50 -0
- projectbudget-0.1.0/pyproject.toml +173 -0
- projectbudget-0.1.0/src/projectbudget/__init__.py +10 -0
- projectbudget-0.1.0/src/projectbudget/adapters/__init__.py +5 -0
- projectbudget-0.1.0/src/projectbudget/adapters/export_format.py +220 -0
- projectbudget-0.1.0/src/projectbudget/adapters/manifest.py +341 -0
- projectbudget-0.1.0/src/projectbudget/adapters/sources.py +232 -0
- projectbudget-0.1.0/src/projectbudget/api/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/api/backlog.py +20 -0
- projectbudget-0.1.0/src/projectbudget/api/budget.py +56 -0
- projectbudget-0.1.0/src/projectbudget/api/catalog.py +129 -0
- projectbudget-0.1.0/src/projectbudget/api/forecast.py +20 -0
- projectbudget-0.1.0/src/projectbudget/api/projects.py +57 -0
- projectbudget-0.1.0/src/projectbudget/api/purchases.py +154 -0
- projectbudget-0.1.0/src/projectbudget/api/requirements.py +92 -0
- projectbudget-0.1.0/src/projectbudget/api/router.py +115 -0
- projectbudget-0.1.0/src/projectbudget/api/schemas.py +997 -0
- projectbudget-0.1.0/src/projectbudget/api/sync.py +135 -0
- projectbudget-0.1.0/src/projectbudget/api/transfer.py +36 -0
- projectbudget-0.1.0/src/projectbudget/cli/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/cli/demo.py +51 -0
- projectbudget-0.1.0/src/projectbudget/cli/main.py +554 -0
- projectbudget-0.1.0/src/projectbudget/domain/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/domain/catalog.py +173 -0
- projectbudget-0.1.0/src/projectbudget/domain/consolidation.py +264 -0
- projectbudget-0.1.0/src/projectbudget/domain/forecast.py +381 -0
- projectbudget-0.1.0/src/projectbudget/domain/manifest.py +80 -0
- projectbudget-0.1.0/src/projectbudget/domain/money.py +191 -0
- projectbudget-0.1.0/src/projectbudget/domain/principal.py +23 -0
- projectbudget-0.1.0/src/projectbudget/domain/sync.py +506 -0
- projectbudget-0.1.0/src/projectbudget/fixtures/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/fixtures/canonical.py +178 -0
- projectbudget-0.1.0/src/projectbudget/localtime.py +90 -0
- projectbudget-0.1.0/src/projectbudget/mcp_server.py +351 -0
- projectbudget-0.1.0/src/projectbudget/persistence/__init__.py +5 -0
- projectbudget-0.1.0/src/projectbudget/persistence/backup.py +63 -0
- projectbudget-0.1.0/src/projectbudget/persistence/base.py +23 -0
- projectbudget-0.1.0/src/projectbudget/persistence/engine.py +96 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrate.py +100 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/env.py +55 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/script.py.mako +24 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0001_initial.py +24 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0002_owner_auth.py +87 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0003_domain_core.py +141 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0004_inventory_and_backlog_order.py +74 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0005_budget_plan_and_purchases.py +151 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0006_catalog_merge_redirect.py +39 -0
- projectbudget-0.1.0/src/projectbudget/persistence/migrations/versions/0007_sync_sources_and_source_refs.py +129 -0
- projectbudget-0.1.0/src/projectbudget/persistence/models.py +371 -0
- projectbudget-0.1.0/src/projectbudget/persistence/session.py +11 -0
- projectbudget-0.1.0/src/projectbudget/py.typed +0 -0
- projectbudget-0.1.0/src/projectbudget/services/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/services/auth.py +367 -0
- projectbudget-0.1.0/src/projectbudget/services/backlog.py +150 -0
- projectbudget-0.1.0/src/projectbudget/services/budget.py +237 -0
- projectbudget-0.1.0/src/projectbudget/services/catalog.py +518 -0
- projectbudget-0.1.0/src/projectbudget/services/clock.py +15 -0
- projectbudget-0.1.0/src/projectbudget/services/errors.py +95 -0
- projectbudget-0.1.0/src/projectbudget/services/forecast.py +27 -0
- projectbudget-0.1.0/src/projectbudget/services/guards.py +30 -0
- projectbudget-0.1.0/src/projectbudget/services/inventory.py +314 -0
- projectbudget-0.1.0/src/projectbudget/services/passwords.py +55 -0
- projectbudget-0.1.0/src/projectbudget/services/projects.py +128 -0
- projectbudget-0.1.0/src/projectbudget/services/purchases.py +588 -0
- projectbudget-0.1.0/src/projectbudget/services/requirements.py +318 -0
- projectbudget-0.1.0/src/projectbudget/services/sync.py +966 -0
- projectbudget-0.1.0/src/projectbudget/services/tokens.py +147 -0
- projectbudget-0.1.0/src/projectbudget/services/transfer.py +536 -0
- projectbudget-0.1.0/src/projectbudget/services/workspace.py +57 -0
- projectbudget-0.1.0/src/projectbudget/settings.py +119 -0
- projectbudget-0.1.0/src/projectbudget/web/__init__.py +4 -0
- projectbudget-0.1.0/src/projectbudget/web/app.py +79 -0
- projectbudget-0.1.0/src/projectbudget/web/auth.py +146 -0
- projectbudget-0.1.0/src/projectbudget/web/errors.py +94 -0
- projectbudget-0.1.0/src/projectbudget/web/health.py +56 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/__init__.py +1 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/account.py +90 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/backlog.py +59 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/budget.py +112 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/catalog.py +220 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/data.py +67 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/login.py +137 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/projects.py +313 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/purchases.py +231 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/sync.py +242 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/timeline.py +97 -0
- projectbudget-0.1.0/src/projectbudget/web/pages/tokens.py +78 -0
- projectbudget-0.1.0/src/projectbudget/web/security.py +109 -0
- projectbudget-0.1.0/src/projectbudget/web/static/app.css +164 -0
- projectbudget-0.1.0/src/projectbudget/web/static/confirm.js +29 -0
- projectbudget-0.1.0/src/projectbudget/web/static/favicon.svg +1 -0
- projectbudget-0.1.0/src/projectbudget/web/static/timeline.js +112 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/LICENSE.md +9 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/README.md +10 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/chartjs/chart.umd.js +14 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/LICENSE +13 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/README.md +9 -0
- projectbudget-0.1.0/src/projectbudget/web/static/vendor/htmx/htmx.min.js +1 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/account.html +28 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/backlog.html +41 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/base.html +42 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/budget.html +83 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/catalog.html +57 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/catalog_item.html +110 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/data.html +37 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/error.html +9 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/login.html +23 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/partials/backlog_table.html +77 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/partials/requirement_row.html +73 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/partials/token_row.html +18 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/project.html +112 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/projects.html +32 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/purchase.html +101 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/purchases.html +50 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/setup_required.html +12 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/sync.html +56 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/sync_source.html +166 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/timeline.html +136 -0
- projectbudget-0.1.0/src/projectbudget/web/templates/tokens.html +39 -0
- projectbudget-0.1.0/src/projectbudget/web/templates.py +54 -0
- projectbudget-0.1.0/tests/conftest.py +155 -0
- projectbudget-0.1.0/tests/e2e/__init__.py +0 -0
- projectbudget-0.1.0/tests/e2e/conftest.py +117 -0
- projectbudget-0.1.0/tests/e2e/test_smoke.py +390 -0
- projectbudget-0.1.0/tests/fixtures/workspace.json +243 -0
- projectbudget-0.1.0/tests/test_acceptance.py +276 -0
- projectbudget-0.1.0/tests/test_acceptance_sync.py +176 -0
- projectbudget-0.1.0/tests/test_accessibility.py +55 -0
- projectbudget-0.1.0/tests/test_agent_kit.py +139 -0
- projectbudget-0.1.0/tests/test_api_and_tokens.py +125 -0
- projectbudget-0.1.0/tests/test_api_domain.py +200 -0
- projectbudget-0.1.0/tests/test_api_forecast.py +172 -0
- projectbudget-0.1.0/tests/test_api_purchases.py +164 -0
- projectbudget-0.1.0/tests/test_api_sync.py +230 -0
- projectbudget-0.1.0/tests/test_auth_service.py +325 -0
- projectbudget-0.1.0/tests/test_backlog_service.py +223 -0
- projectbudget-0.1.0/tests/test_backup.py +119 -0
- projectbudget-0.1.0/tests/test_budget_service.py +153 -0
- projectbudget-0.1.0/tests/test_catalog_merge.py +219 -0
- projectbudget-0.1.0/tests/test_catalog_service.py +332 -0
- projectbudget-0.1.0/tests/test_cli.py +393 -0
- projectbudget-0.1.0/tests/test_cli_sync.py +83 -0
- projectbudget-0.1.0/tests/test_collection.py +40 -0
- projectbudget-0.1.0/tests/test_consolidation.py +360 -0
- projectbudget-0.1.0/tests/test_demo.py +69 -0
- projectbudget-0.1.0/tests/test_domain_catalog.py +99 -0
- projectbudget-0.1.0/tests/test_engine.py +112 -0
- projectbudget-0.1.0/tests/test_fixture_file.py +36 -0
- projectbudget-0.1.0/tests/test_forecast.py +339 -0
- projectbudget-0.1.0/tests/test_health.py +54 -0
- projectbudget-0.1.0/tests/test_invariants.py +343 -0
- projectbudget-0.1.0/tests/test_inventory_concurrency.py +193 -0
- projectbudget-0.1.0/tests/test_inventory_service.py +155 -0
- projectbudget-0.1.0/tests/test_localtime.py +107 -0
- projectbudget-0.1.0/tests/test_manifest_parsing.py +174 -0
- projectbudget-0.1.0/tests/test_mcp_server.py +312 -0
- projectbudget-0.1.0/tests/test_migrations.py +34 -0
- projectbudget-0.1.0/tests/test_money.py +184 -0
- projectbudget-0.1.0/tests/test_package.py +22 -0
- projectbudget-0.1.0/tests/test_pages.py +528 -0
- projectbudget-0.1.0/tests/test_pages_purchases.py +237 -0
- projectbudget-0.1.0/tests/test_pages_sync.py +370 -0
- projectbudget-0.1.0/tests/test_pages_timeline.py +225 -0
- projectbudget-0.1.0/tests/test_passwords.py +27 -0
- projectbudget-0.1.0/tests/test_pr_helpers.py +391 -0
- projectbudget-0.1.0/tests/test_projects_service.py +92 -0
- projectbudget-0.1.0/tests/test_purchases_concurrency.py +133 -0
- projectbudget-0.1.0/tests/test_purchases_lifecycle.py +225 -0
- projectbudget-0.1.0/tests/test_purchases_service.py +233 -0
- projectbudget-0.1.0/tests/test_requirements_service.py +324 -0
- projectbudget-0.1.0/tests/test_routes_require_owner.py +89 -0
- projectbudget-0.1.0/tests/test_security_headers.py +40 -0
- projectbudget-0.1.0/tests/test_settings.py +72 -0
- projectbudget-0.1.0/tests/test_sources.py +189 -0
- projectbudget-0.1.0/tests/test_sync_plan.py +669 -0
- projectbudget-0.1.0/tests/test_sync_service.py +1011 -0
- projectbudget-0.1.0/tests/test_templates_safe.py +67 -0
- projectbudget-0.1.0/tests/test_tokens_service.py +86 -0
- projectbudget-0.1.0/tests/test_transfer.py +251 -0
- projectbudget-0.1.0/tests/test_web_auth.py +275 -0
- 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,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).
|