spms 1.2.1__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 (174) hide show
  1. spms-1.2.1/LICENSE +14 -0
  2. spms-1.2.1/PKG-INFO +298 -0
  3. spms-1.2.1/README.md +251 -0
  4. spms-1.2.1/pyproject.toml +116 -0
  5. spms-1.2.1/setup.cfg +4 -0
  6. spms-1.2.1/src/app_core/__init__.py +1 -0
  7. spms-1.2.1/src/app_core/assistant/__init__.py +70 -0
  8. spms-1.2.1/src/app_core/assistant/action_validation.py +970 -0
  9. spms-1.2.1/src/app_core/assistant/actions.py +473 -0
  10. spms-1.2.1/src/app_core/assistant/common.py +265 -0
  11. spms-1.2.1/src/app_core/assistant/engine.py +571 -0
  12. spms-1.2.1/src/app_core/assistant/feedback.py +175 -0
  13. spms-1.2.1/src/app_core/assistant/formatting.py +1299 -0
  14. spms-1.2.1/src/app_core/assistant/nlu.py +186 -0
  15. spms-1.2.1/src/app_core/assistant/runtime.py +387 -0
  16. spms-1.2.1/src/app_core/assistant/tools.py +1154 -0
  17. spms-1.2.1/src/app_core/barcodes.py +248 -0
  18. spms-1.2.1/src/app_core/db.py +1540 -0
  19. spms-1.2.1/src/app_core/doctor.py +686 -0
  20. spms-1.2.1/src/app_core/domain/__init__.py +10 -0
  21. spms-1.2.1/src/app_core/domain/availability.py +64 -0
  22. spms-1.2.1/src/app_core/domain/dates.py +162 -0
  23. spms-1.2.1/src/app_core/domain/metrics.py +119 -0
  24. spms-1.2.1/src/app_core/domain/money.py +106 -0
  25. spms-1.2.1/src/app_core/domain/tax.py +66 -0
  26. spms-1.2.1/src/app_core/paths.py +223 -0
  27. spms-1.2.1/src/app_core/services/__init__.py +36 -0
  28. spms-1.2.1/src/app_core/services/_monolith.py +7846 -0
  29. spms-1.2.1/src/app_core/services/_seed_data.py +214 -0
  30. spms-1.2.1/src/app_core/services/billing_docs.py +245 -0
  31. spms-1.2.1/src/app_core/services/reports_metrics.py +180 -0
  32. spms-1.2.1/src/app_core/support.py +389 -0
  33. spms-1.2.1/src/app_core/updater.py +478 -0
  34. spms-1.2.1/src/spms.egg-info/PKG-INFO +298 -0
  35. spms-1.2.1/src/spms.egg-info/SOURCES.txt +172 -0
  36. spms-1.2.1/src/spms.egg-info/dependency_links.txt +1 -0
  37. spms-1.2.1/src/spms.egg-info/entry_points.txt +3 -0
  38. spms-1.2.1/src/spms.egg-info/requires.txt +25 -0
  39. spms-1.2.1/src/spms.egg-info/top_level.txt +4 -0
  40. spms-1.2.1/tests/test_assistant.py +508 -0
  41. spms-1.2.1/tests/test_assistant_actions_validation_feedback.py +262 -0
  42. spms-1.2.1/tests/test_assistant_coverage_recent.py +92 -0
  43. spms-1.2.1/tests/test_assistant_engine_runtime_coverage.py +139 -0
  44. spms-1.2.1/tests/test_assistant_runtime_coverage.py +167 -0
  45. spms-1.2.1/tests/test_assistant_tools_formatting_coverage.py +257 -0
  46. spms-1.2.1/tests/test_assistant_tools_new.py +31 -0
  47. spms-1.2.1/tests/test_attribution.py +32 -0
  48. spms-1.2.1/tests/test_audit_fixes_2026.py +112 -0
  49. spms-1.2.1/tests/test_auth.py +106 -0
  50. spms-1.2.1/tests/test_batch_fefo_traceability.py +138 -0
  51. spms-1.2.1/tests/test_business_fixes_analytics.py +88 -0
  52. spms-1.2.1/tests/test_cov95_assistant_core.py +367 -0
  53. spms-1.2.1/tests/test_cov95_assistant_formatting_tools.py +215 -0
  54. spms-1.2.1/tests/test_cov95_db.py +345 -0
  55. spms-1.2.1/tests/test_cov95_doctor_updater.py +294 -0
  56. spms-1.2.1/tests/test_cov95_monolith_services_a.py +423 -0
  57. spms-1.2.1/tests/test_cov95_monolith_services_b.py +293 -0
  58. spms-1.2.1/tests/test_cov95_monolith_services_c.py +132 -0
  59. spms-1.2.1/tests/test_cov95_support_paths_barcodes.py +248 -0
  60. spms-1.2.1/tests/test_cov95b_assistant_core.py +509 -0
  61. spms-1.2.1/tests/test_cov95b_core_platform.py +675 -0
  62. spms-1.2.1/tests/test_cov95b_monolith_extra.py +645 -0
  63. spms-1.2.1/tests/test_cov95b_monolith_more.py +193 -0
  64. spms-1.2.1/tests/test_coverage_90_action_validation_tools.py +291 -0
  65. spms-1.2.1/tests/test_coverage_90_batch2.py +368 -0
  66. spms-1.2.1/tests/test_coverage_90_batch3.py +21 -0
  67. spms-1.2.1/tests/test_coverage_90_deps.py +137 -0
  68. spms-1.2.1/tests/test_coverage_90_doctor_engine.py +280 -0
  69. spms-1.2.1/tests/test_coverage_90_formatting_tools_branches.py +344 -0
  70. spms-1.2.1/tests/test_coverage_90_monolith_batch1.py +271 -0
  71. spms-1.2.1/tests/test_coverage_90_monolith_batch2.py +215 -0
  72. spms-1.2.1/tests/test_coverage_90_quickwins.py +343 -0
  73. spms-1.2.1/tests/test_coverage_90_tools_more.py +307 -0
  74. spms-1.2.1/tests/test_coverage_gaps.py +554 -0
  75. spms-1.2.1/tests/test_dashboards.py +188 -0
  76. spms-1.2.1/tests/test_db_coverage.py +101 -0
  77. spms-1.2.1/tests/test_db_integrity_idempotency.py +68 -0
  78. spms-1.2.1/tests/test_db_migrations.py +81 -0
  79. spms-1.2.1/tests/test_demo_seed_guards.py +54 -0
  80. spms-1.2.1/tests/test_domain_primitives.py +209 -0
  81. spms-1.2.1/tests/test_expenses.py +71 -0
  82. spms-1.2.1/tests/test_extra.py +342 -0
  83. spms-1.2.1/tests/test_extra2.py +346 -0
  84. spms-1.2.1/tests/test_extra3.py +305 -0
  85. spms-1.2.1/tests/test_final.py +712 -0
  86. spms-1.2.1/tests/test_golive_invariants_migrations_contracts.py +262 -0
  87. spms-1.2.1/tests/test_guests.py +144 -0
  88. spms-1.2.1/tests/test_integration.py +88 -0
  89. spms-1.2.1/tests/test_integrity_batch_ops.py +60 -0
  90. spms-1.2.1/tests/test_integrity_batch_seed_strengthened.py +293 -0
  91. spms-1.2.1/tests/test_inventory.py +131 -0
  92. spms-1.2.1/tests/test_invoice_clean.py +50 -0
  93. spms-1.2.1/tests/test_invoices.py +93 -0
  94. spms-1.2.1/tests/test_ledger.py +122 -0
  95. spms-1.2.1/tests/test_migrate_v9_idempotency.py +52 -0
  96. spms-1.2.1/tests/test_paths.py +86 -0
  97. spms-1.2.1/tests/test_paths_updater_doctor_coverage.py +312 -0
  98. spms-1.2.1/tests/test_payments.py +101 -0
  99. spms-1.2.1/tests/test_pos.py +142 -0
  100. spms-1.2.1/tests/test_printers.py +147 -0
  101. spms-1.2.1/tests/test_quality_gate_foundations.py +405 -0
  102. spms-1.2.1/tests/test_recipes.py +230 -0
  103. spms-1.2.1/tests/test_reports.py +92 -0
  104. spms-1.2.1/tests/test_reports_metrics.py +105 -0
  105. spms-1.2.1/tests/test_reservations.py +265 -0
  106. spms-1.2.1/tests/test_rooms.py +185 -0
  107. spms-1.2.1/tests/test_round_2.py +327 -0
  108. spms-1.2.1/tests/test_round_3.py +306 -0
  109. spms-1.2.1/tests/test_seed_barcode_batch.py +107 -0
  110. spms-1.2.1/tests/test_services_catalog_vouchers_rules.py +119 -0
  111. spms-1.2.1/tests/test_services_coverage_100.py +511 -0
  112. spms-1.2.1/tests/test_services_groups_packages_approvals_shifts.py +195 -0
  113. spms-1.2.1/tests/test_services_integrity_night_audit.py +106 -0
  114. spms-1.2.1/tests/test_settings.py +94 -0
  115. spms-1.2.1/tests/test_subagent_expanded_coverage.py +618 -0
  116. spms-1.2.1/tests/test_subagent_scope_coverage.py +432 -0
  117. spms-1.2.1/tests/test_subagent_scope_nov12_expansion.py +461 -0
  118. spms-1.2.1/tests/test_support_reporting.py +125 -0
  119. spms-1.2.1/tests/test_updater.py +28 -0
  120. spms-1.2.1/ui/__init__.py +1 -0
  121. spms-1.2.1/ui/web/__init__.py +1 -0
  122. spms-1.2.1/ui/web/deps.py +614 -0
  123. spms-1.2.1/ui/web/rendering.py +81 -0
  124. spms-1.2.1/ui/web/route_utils.py +48 -0
  125. spms-1.2.1/ui/web/routes/__init__.py +1 -0
  126. spms-1.2.1/ui/web/routes/accounting.py +168 -0
  127. spms-1.2.1/ui/web/routes/assistant.py +585 -0
  128. spms-1.2.1/ui/web/routes/dashboard.py +33 -0
  129. spms-1.2.1/ui/web/routes/files.py +28 -0
  130. spms-1.2.1/ui/web/routes/guests.py +115 -0
  131. spms-1.2.1/ui/web/routes/housekeeping.py +158 -0
  132. spms-1.2.1/ui/web/routes/pos_inventory.py +492 -0
  133. spms-1.2.1/ui/web/routes/reports_analytics.py +80 -0
  134. spms-1.2.1/ui/web/routes/reservations.py +628 -0
  135. spms-1.2.1/ui/web/routes/settings_branding.py +910 -0
  136. spms-1.2.1/ui/web/routes/support.py +55 -0
  137. spms-1.2.1/ui/web/server.py +273 -0
  138. spms-1.2.1/ui/web/static/app.css +142 -0
  139. spms-1.2.1/ui/web/static/app.js +80 -0
  140. spms-1.2.1/ui/web/static/assistant_widget.js +284 -0
  141. spms-1.2.1/ui/web/static/icons/apple-touch-icon.png +0 -0
  142. spms-1.2.1/ui/web/static/icons/icon-192.png +0 -0
  143. spms-1.2.1/ui/web/static/icons/icon-512.png +0 -0
  144. spms-1.2.1/ui/web/static/manifest.webmanifest +25 -0
  145. spms-1.2.1/ui/web/static/sw.js +63 -0
  146. spms-1.2.1/ui/web/templates/accounting/index.html +163 -0
  147. spms-1.2.1/ui/web/templates/assistant/_messages.html +102 -0
  148. spms-1.2.1/ui/web/templates/assistant/index.html +80 -0
  149. spms-1.2.1/ui/web/templates/base.html +94 -0
  150. spms-1.2.1/ui/web/templates/dashboard.html +95 -0
  151. spms-1.2.1/ui/web/templates/errors/500.html +29 -0
  152. spms-1.2.1/ui/web/templates/guests/detail.html +132 -0
  153. spms-1.2.1/ui/web/templates/guests/list.html +23 -0
  154. spms-1.2.1/ui/web/templates/housekeeping/index.html +94 -0
  155. spms-1.2.1/ui/web/templates/partials/forms.html +7 -0
  156. spms-1.2.1/ui/web/templates/partials/ui.html +24 -0
  157. spms-1.2.1/ui/web/templates/pos/index.html +378 -0
  158. spms-1.2.1/ui/web/templates/reports/index.html +51 -0
  159. spms-1.2.1/ui/web/templates/reports/view.html +7 -0
  160. spms-1.2.1/ui/web/templates/reservations/detail.html +249 -0
  161. spms-1.2.1/ui/web/templates/reservations/groups.html +89 -0
  162. spms-1.2.1/ui/web/templates/reservations/list.html +71 -0
  163. spms-1.2.1/ui/web/templates/settings/approvals.html +70 -0
  164. spms-1.2.1/ui/web/templates/settings/health.html +25 -0
  165. spms-1.2.1/ui/web/templates/settings/index.html +230 -0
  166. spms-1.2.1/ui/web/templates/settings/packages.html +69 -0
  167. spms-1.2.1/ui/web/templates/settings/rate_plans.html +89 -0
  168. spms-1.2.1/ui/web/templates/settings/service_catalog.html +56 -0
  169. spms-1.2.1/ui/web/templates/settings/users.html +55 -0
  170. spms-1.2.1/ui/web/templates/settings/vouchers.html +56 -0
  171. spms-1.2.1/ui/web/templates/setup_wizard.html +41 -0
  172. spms-1.2.1/ui/web/templates/support/report.html +322 -0
  173. spms-1.2.1/ui/web/templates/unlock.html +14 -0
  174. spms-1.2.1/ui/web/templates/unlock_recovery.html +17 -0
spms-1.2.1/LICENSE ADDED
@@ -0,0 +1,14 @@
1
+ Copyright (c) 2026 Michael Helmy. All rights reserved.
2
+
3
+ This software and associated documentation files (the "Software") are proprietary.
4
+ No license is granted to use, copy, modify, merge, publish, distribute,
5
+ sublicense, and/or sell copies of the Software, in whole or in part, except
6
+ with prior written permission from the copyright holder.
7
+
8
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
9
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
10
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
11
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
12
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
13
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
14
+ SOFTWARE.
spms-1.2.1/PKG-INFO ADDED
@@ -0,0 +1,298 @@
1
+ Metadata-Version: 2.4
2
+ Name: spms
3
+ Version: 1.2.1
4
+ Summary: SPMS (Super Property Management System) — local-first property management with FastAPI/HTMX web UI (shared core, SQLite-safe single-worker web).
5
+ Author: Michael Helmy
6
+ License: Proprietary
7
+ Project-URL: Homepage, https://github.com/Michaelhehelmy/spms
8
+ Project-URL: Repository, https://github.com/Michaelhehelmy/spms
9
+ Project-URL: Issues, https://github.com/Michaelhehelmy/spms/issues
10
+ Keywords: property,hotel,pms,pos,inventory,fastapi,htmx,sqlite,web
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Environment :: Web Environment
19
+ Classifier: Framework :: FastAPI
20
+ Classifier: Intended Audience :: End Users/Desktop
21
+ Classifier: Topic :: Office/Business
22
+ Classifier: Topic :: Office/Business :: Financial
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: fastapi>=0.110
27
+ Requires-Dist: uvicorn[standard]>=0.27
28
+ Requires-Dist: jinja2>=3.1
29
+ Requires-Dist: python-multipart>=0.0.9
30
+ Requires-Dist: itsdangerous>=2.1
31
+ Provides-Extra: assistant-ml
32
+ Requires-Dist: scikit-learn>=1.3; extra == "assistant-ml"
33
+ Requires-Dist: joblib>=1.3; extra == "assistant-ml"
34
+ Requires-Dist: setfit>=1.0; extra == "assistant-ml"
35
+ Requires-Dist: sentence-transformers>=2.2; extra == "assistant-ml"
36
+ Provides-Extra: assistant-llm
37
+ Requires-Dist: llama-cpp-python>=0.2; extra == "assistant-llm"
38
+ Provides-Extra: dev
39
+ Requires-Dist: pytest>=7.0; extra == "dev"
40
+ Requires-Dist: httpx>=0.24; extra == "dev"
41
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
42
+ Requires-Dist: ruff>=0.8.0; extra == "dev"
43
+ Provides-Extra: labels
44
+ Provides-Extra: all
45
+ Requires-Dist: spms[dev]; extra == "all"
46
+ Dynamic: license-file
47
+
48
+ # SPMS (Super Property Management System)
49
+
50
+ SPMS (Super Property Management System) — local-first property management with a shared backend and a web frontend:
51
+
52
+ - **Web UI:** FastAPI + HTMX server (`ui.web.server:app`, `launcher.py`, `main.py`) for browser access on desktop/mobile, LAN, or behind a reverse proxy.
53
+
54
+ **Architecture:** all business logic lives in `src/app_core/` (DB, services, paths, assistant, integrity/doctor, updater, barcode/batch logic, support/reporting) and is used by `ui/web/`. SQLite is the datastore.
55
+
56
+ ## Current capabilities
57
+
58
+ - **Front desk & reservations:** guests (including 360° portfolio views), rooms/rate plans, availability, create/check-in/checkout flows, folio/balances, payments/refunds where applicable, invoices/receipts.
59
+ - **POS & inventory:** catalog, walk-in and reservation-linked sales, recipes/meals/ingredients with auto-deduction, expenses, and **traceable barcodes/SKUs/lots**.
60
+ - **Batch/lot traceability & FEFO:** inventory supports batch/lot tracking with received date/time, expiry date, remaining/received quantity, unit cost, supplier/reference/notes, status/expiry state, and movements. Supports **FEFO-aware** (First Expired, First Out) workflows, expiring/expired batch review, batch/lot lists, and barcode/SKU/lot trace (resolved item or lot with received/expiry/remaining and recent movements when available).
61
+ - **Activities/trips:** register/book activities/excursions, track bookings/stats, and post charges to folios/invoices.
62
+ - **Accounting, reports & analytics:** ledger, operational/financial reports and analytics/exports (as available in the app).
63
+ - **Grounded assistant (read-only):** Web assistant answers from real app data/tools (ops, reports, guests/portfolios, reservations/balances, inventory including expiring batches, batch lists, barcode/lot trace, activities/bookings, integrity/health, and app version/update status). Assistant follows configured unlock/allowlist policy and remains read-only.
64
+ - **Integrity & health:** read-only ledger/data integrity checks in-app, CLI **doctor** (`python -m app_core.doctor`), safe backup/verify helpers, and web liveness/readiness probes `GET /health`, `GET /healthz`, `GET /readyz`.
65
+ - **Issue reporting (privacy-first):** Web **Report issue** (`/support/report`) and CLI **`python -m app_core.support`** generate sanitized diagnostics (no passwords/secrets/tokens/CSRF/session/recovery codes or DB/guest/payment records), let you review/edit details, download/copy Markdown or JSON reports (including device/OS info and recent in-app steps), open a prefilled GitHub issue, or upload the downloaded JSON report via the landing page (if configured) so it can be delivered to maintainers. Unhandled web errors show a friendly “Report this issue” page with prefilled context.
66
+ - **In-app updates (git installs):** **Settings → App updates** supports **Check for updates**, changelog/commit details, and **Apply/Update** via **git fast-forward**. Local source changes must be committed/stashed/discarded before apply.
67
+ - **Backups & data safety:** create verified DB backups from Settings (**Backup now**, subject to unlock/CSRF as applicable) or CLI/scripts. Runtime data is preserved across source updates; **restore is manual and offline**.
68
+
69
+ ## Operational requirements (important)
70
+
71
+ - **SQLite / single worker:** always run the web server with **`--workers 1`**. Do not increase worker count.
72
+ - **Web secret key:** set **`PM_WEB_SECRET_KEY`** to a strong random value for any non-local/shared/LAN/remote deployment.
73
+ - **HTTPS / transport security:** bind to `127.0.0.1` for local-only use. For LAN/remote/browser access, use **HTTPS** (reverse proxy that terminates TLS) or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
74
+ - **Data directory & permissions:** runtime data lives in `PM_DATA_DIR` or app defaults/legacy locations (DB, exports, invoices). Ensure the process user can read/write the data directory and keep a single writer.
75
+ - **Data preserved across updates:** source/app updates (in-app fast-forward or `git pull --ff-only`) do **not** modify runtime data (DB, exports, invoices, configured data dir). DB migrations run on startup and are additive where applicable.
76
+ - **Restart after apply:** after applying an in-app update, **restart the app/server** to load the new version.
77
+ - **Local source changes:** in-app apply requires a clean working tree for fast-forward; commit, stash, or discard local changes first.
78
+ - **Backups before risky operations:** take and verify backups before upgrades/migrations, restores, or major operational changes.
79
+ - **No destructive one-click restore:** restore is deliberate/manual/offline (stop app, verify backup, replace files, start, verify integrity).
80
+ - **Security model:** web state-changing requests are CSRF-protected; sensitive/destructive/admin mutations require **super-password unlock** (and CSRF) per policy, while some routine operational/front-desk flows remain usable with CSRF only. See `docs/web_authz_matrix.md`.
81
+
82
+ ## Repository layout
83
+
84
+ ```text
85
+ launcher.py # unified web launcher/menu
86
+ main.py # web entry point (compatibility)
87
+ pyproject.toml # packaging metadata, dependencies, extras
88
+ requirements.txt # runtime dependencies (web-only app)
89
+ requirements-dev.txt # dev/test dependencies
90
+ scripts/ # install/setup/update/backup/coverage helpers
91
+ src/app_core/ # shared backend (db, services, paths, assistant, doctor, updater, ...)
92
+ ui/web/ # FastAPI + HTMX web UI
93
+ docs/ # operations, security, deployment, runbooks
94
+ assistant.md # assistant capabilities/evolution/plan
95
+ tests/ # pytest suite
96
+ ```
97
+
98
+ ## Quick decision: how to run
99
+
100
+ | Goal | Recommended mode |
101
+ |---|---|
102
+ | Local use on a PC/server | Web UI on `127.0.0.1` (`python launcher.py` / `python main.py`) |
103
+ | Access from phone/tablet browser on same LAN | **Web** bound to `0.0.0.0` behind trusted LAN/VPN and with `PM_WEB_SECRET_KEY`; prefer HTTPS reverse proxy if feasible |
104
+ | Remote access over internet | **Web** behind **HTTPS** reverse proxy / VPN / Tailscale (never plain HTTP public exposure) |
105
+ | iSH (iOS/Alpine, constrained) | Run the Web UI on a supported host when web dependencies/toolchains are unavailable on-device |
106
+ | Android (Termux) | **Web** (`--workers 1`) |
107
+ | Windows desktop/server | `scripts/install_windows.ps1` / `scripts/setup_windows.ps1` or manual venv |
108
+
109
+ ## One-line install / update (all supported OS families)
110
+
111
+ These commands are intended for **first-time install and later re-runs** on git-based installs: they bootstrap prerequisites where possible, clone/update (fast-forward), refresh dependencies, preserve runtime data, and launch/run per selected mode. **Always keep web on `--workers 1`**. For shared/non-local/LAN/remote web access, set a strong `PM_WEB_SECRET_KEY` and use **HTTPS** via reverse proxy/VPN/private networking (do not expose plain HTTP publicly). **Built-in recovery:** if an install/update gets stuck due to dirty tree, stale `.git/index.lock`, stuck merge/rebase, or ff-only/checkout errors (e.g. `Reset branch 'main'`), rerun with `REPAIR=1` (Unix/Termux) or `-Repair` / `$env:REPAIR='1'` (Windows) to auto-recover by resetting local source to the target branch (runtime data in `PM_DATA_DIR`/external data dirs is not removed by git).
112
+
113
+ | OS / Environment | One-line command | Notes |
114
+ |---|---|---|
115
+ | **Linux / macOS / WSL / generic Unix** (curl) | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Detects environment/package manager, installs/updates, and launches the web app. Re-run anytime. |
116
+ | **Linux / macOS / WSL** (wget) | `wget -qO- https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Fallback if `curl` is unavailable. |
117
+ | **Web server for LAN (trusted network)** | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY="$(openssl rand -hex 32)" sh` | `--workers 1` required (SQLite). Use HTTPS reverse proxy/VPN for shared/remote access. |
118
+ | **Android (Termux)** | `pkg update -y && pkg install -y curl && curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Installs/updates and launches web app. For LAN web add `MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY=...` (use HTTPS/proxy for shared access). |
119
+ | **Windows (PowerShell, bootstrap)** | `irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 \| iex` | Uses winget when available to install Python/Git if missing, then clones/updates and runs setup/deploy. Customize via `$env:ACTION/$env:MODE/$env:HOST/$env:PORT/$env:PM_WEB_SECRET_KEY`. |
120
+ | **Windows (CMD bootstrap)** | `curl -fsSL -o install_windows.cmd https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.cmd && install_windows.cmd -Action deploy -Mode auto` | Downloads/runs bootstrap wrapper (uses PowerShell script). |
121
+
122
+ **Common env vars / parameters (Unix installer/setup):** `INSTALL_DIR`, `REPO_URL`, `BRANCH`, `GIT_REF`/`TAG`/`COMMIT` (pinned ref), `MODE` (`web`; legacy values map to web), `ACTION` (`auto|setup|run|deploy`), `SKIP_WEB` (`auto|0|1`), `HOST`, `PORT`, `PYTHON`, `INSTALL_DEV`, `RUN_TESTS`, `PM_DATA_DIR`, `PM_WEB_SECRET_KEY`. **Windows:** pass `-GitRef`/`-Action`/`-Mode`/`-BindHost`/`-Port` or set corresponding env vars (`GIT_REF`/`TAG`/`COMMIT`, etc.).
123
+
124
+ - `ACTION=auto` (default): full install+launch if missing, else update deps/code and launch.
125
+ - `ACTION=setup`: install/update/prepare only. `ACTION=run`: run existing install. `ACTION=deploy`: setup + run.
126
+ - Runtime data (DB/exports/invoices/`PM_DATA_DIR`) is preserved by scripts/updates.
127
+
128
+ ### Pinned/reproducible installs
129
+
130
+ - Install/update to a specific tag/commit/branch: `GIT_REF=<tag-or-commit-or-branch> sh` (Unix) or `-GitRef <...>` / `$env:GIT_REF=<...>` (Windows). Aliases: `TAG`, `COMMIT`.
131
+ - **Pinned bootstrap script URL:** use the raw script at the same ref to ensure installer logic is reproducible, e.g. `https://raw.githubusercontent.com/Michaelhehelmy/spms/<tag-or-commit>/scripts/install.sh` (Unix) or `.../<tag-or-commit>/scripts/install_windows.ps1` (Windows).
132
+ - Existing checkouts: `GIT_REF=<tag> ACTION=setup sh scripts/setup.sh` (or Windows setup script) checks out the requested ref; when on a branch, scripts may fast-forward as applicable. Runtime data is preserved.
133
+ - For immutable production-like deployments, prefer pinning to a release tag/commit and recording the resolved commit (`git -C <install-dir> rev-parse HEAD`) alongside backups/change records.
134
+
135
+ ### Dependency/install robustness (constrained environments)
136
+
137
+ - **Web dependency/toolchain issues:** if web dependency installation/build fails (e.g. `pydantic-core`/Rust wheel issues on constrained environments), install/upgrade Python/build tools or a compatible prebuilt wheel, or run the web app on a fuller host.
138
+ - **`pydantic-core` / Rust wheel issues:** on iSH/Termux/older CPU architectures or limited toolchains, some web deps may require Rust/cargo/build tools or a prebuilt wheel matching your Python version/architecture. If unavailable, upgrade Python/toolchain, install build deps, or run the Web UI on a supported host.
139
+ - **SQLite web safety:** always run the web server with `--workers 1`. Use `PM_WEB_SECRET_KEY` and HTTPS reverse proxy/VPN for non-local/shared access. Runtime data (`PM_DATA_DIR`, DB, exports, invoices) is preserved across setup/update runs.
140
+
141
+ ## Platform-specific setup
142
+
143
+ ### Linux / macOS / WSL / Unix-like
144
+ - Use `scripts/install.sh` (bootstrap) or `scripts/setup.sh` from a checkout.
145
+ - Examples: `sh scripts/setup.sh` (setup), `MODE=web ACTION=deploy sh scripts/setup.sh`, `MODE=web HOST=127.0.0.1 PORT=8000 ACTION=deploy sh scripts/setup.sh`.
146
+ - WSL: treat as Linux; bind carefully for LAN access and account for Windows firewall/port forwarding.
147
+
148
+ ### Android (Termux)
149
+ ```sh
150
+ pkg update && pkg install -y git python curl
151
+ curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | sh
152
+ # or web on LAN (trusted network): add MODE=web HOST=0.0.0.0 PORT=8000 and PM_WEB_SECRET_KEY
153
+ ```
154
+
155
+ ### iOS (iSH / Alpine)
156
+ ```sh
157
+ apk add --no-cache curl
158
+ curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | MODE=web sh
159
+ ```
160
+ If web dependencies cannot be built on-device, run the Web UI on a supported host and access it from the browser.
161
+
162
+ ### iOS/iPadOS as web client
163
+ Run the server on a capable host (Mac/Linux/Windows/Termux/RPi/VPS) and open from Safari (`http://<host>:8000` on LAN or `https://...` via reverse proxy/Tailscale/VPN). Add to Home Screen for app-like use.
164
+
165
+ ### Windows (10/11, Server)
166
+ - **Bootstrap (recommended):** PowerShell (Admin recommended for winget):
167
+ ```powershell
168
+ irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 | iex
169
+ ```
170
+ Customize: `$env:ACTION='deploy'; $env:MODE='web'; $env:HOST='127.0.0.1'; $env:PORT='8000'; $env:PM_WEB_SECRET_KEY='...'; irm ... | iex`
171
+ - **From existing checkout:**
172
+ ```powershell
173
+ powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1 -Action deploy -Mode web
174
+ powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1 -Action deploy -Mode web -BindHost 127.0.0.1 -Port 8000
175
+ scripts\install_windows.cmd -Action deploy -Mode auto
176
+ ```
177
+ - If winget is unavailable, install Python 3.10+ (PATH) and Git, then re-run. Scripts attempt to refresh PATH/bootstrap prerequisites.
178
+
179
+ ### Manual install (any OS with Python)
180
+
181
+ ```bash
182
+ git clone https://github.com/Michaelhehelmy/spms.git
183
+ cd spms
184
+ python3 -m venv .venv
185
+ # activate: Unix `. .venv/bin/activate` | PowerShell `.\\.venv\\Scripts\\Activate.ps1` | cmd `.venv\\Scripts\\activate.bat`
186
+ pip install -r requirements.txt # runtime dependencies (web-only app)
187
+ # optional dev/test deps: pip install -r requirements-dev.txt
188
+ python launcher.py # menu
189
+ python launcher.py --web --host 127.0.0.1 --port 8000
190
+ # direct web server (always --workers 1):
191
+ PYTHONPATH=src python -m uvicorn ui.web.server:app --host 127.0.0.1 --port 8000 --workers 1
192
+ ```
193
+
194
+ `pyproject.toml` also defines extras/scripts (`.[web]`, `.[dev]`, `property-manager`, `pm`, etc.) for packaging workflows.
195
+
196
+ ## Web deployment essentials
197
+
198
+ - **Workers:** `--workers 1` only (SQLite/shared state). Never increase workers.
199
+ - **Bind:** `127.0.0.1` local-only; `0.0.0.0` reachable on interfaces (LAN). Manage firewall exposure explicitly.
200
+ - **Secret:** set `PM_WEB_SECRET_KEY` to a strong random value for any non-local/shared deployment (required for non-loopback use unless an explicit local/dev insecure override is set).
201
+ - **TLS/remote access:** use reverse proxy with HTTPS or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
202
+ - **Data directory & permissions:** set `PM_DATA_DIR` if needed; ensure the service user can read/write the data directory and run with a single writer.
203
+ - **Health probes:** `GET /health` and `GET /healthz` (liveness/basic health with readiness summary), `GET /readyz` (readiness/runtime checks including data-dir writability). Keep probes and app on `--workers 1`.
204
+ - **Service/autostart:** use systemd/launchd/NSSM/Task Scheduler/supervisor/Docker restart policy to run venv Python/uvicorn with `--workers 1`.
205
+ - **Reverse proxy:** proxy to `127.0.0.1:8000`, terminate TLS, and forward standard proxy headers as needed.
206
+ - **Backups, restore, updates:** take and verify backups before upgrades/migrations; restore is manual/offline (with restore drill validation recommended); restart the app/server after applying updates.
207
+ - **App icon / launcher:** no native installer icons are bundled. For browser/mobile install use "Add to Home Screen" (add PWA assets like `manifest.webmanifest` and icons under `ui/web/static/` and link from `ui/web/templates/base.html` if needed); for Windows/Linux create OS shortcuts (`.lnk`/`.desktop`) pointing to the venv launcher with a custom icon.
208
+ - See `docs/DEPLOYMENT.md` and `docs/SECURITY.md` for examples and hardening.
209
+
210
+ ## Security model (Web) — summary
211
+
212
+ - **CSRF:** all state-changing web requests (POST/PUT/PATCH/DELETE) are CSRF-protected (form tokens and/or header/middleware enforcement per request type).
213
+ - **Super-password unlock:** sensitive/destructive/admin mutations require active unlock (super password) in addition to CSRF (financial/accounting operations, inventory/stock/batch/recipe/meal/activity changes, voids/refunds/cancels/deletes/modifications, exports/backups/seed/demo/settings changes, labels, protected downloads where applicable, etc.).
214
+ - **Routine operational flows:** some front-desk/POS operations may remain usable with CSRF where appropriate, but policy-sensitive overrides/destructive actions remain gated by unlock.
215
+ - **Assistant:** follows configured unlock/allowlist policy while remaining read-only and grounded.
216
+ - **Secrets & transport:** strong `PM_WEB_SECRET_KEY`, HTTPS/private networking for shared/remote access.
217
+ - **Reference:** `docs/web_authz_matrix.md` is the authoritative route-group matrix for `ui/web`. See `docs/SECURITY.md` for hardening checklist.
218
+
219
+ ## Updates
220
+
221
+ **In-app (recommended for git installs):** **Settings → Updates & Health → App updates** → **Check for updates** → **Update now / Apply** appears **only when an update is available** (git fast-forward for clean checkouts).
222
+
223
+ - **Automated:** check/fetch metadata, show changelog/commits, apply ff-only when eligible.
224
+ - **Requirements/limits:** clean working tree required; non-fast-forward/diverged histories need manual git resolution.
225
+ - **Data preserved:** DB, exports, invoices, and configured data directory (`PM_DATA_DIR`/defaults) are not modified by source updates.
226
+ - **After apply:** **restart the app/server** to load the new version. If dependencies changed, refresh the venv via setup scripts.
227
+ - **Update notifications (auto-check):** built-in polling-based checks run when online (cached/rate-limited, configurable via `auto_check_updates` / `auto_update_check_interval_hours`) and notify in the web UI when updates/releases are available. Git installs can be applied in-app (ff-only) then restarted; native/packaged installs require downloading/installing the new release artifact. No push infrastructure; auto-apply is not enabled by default.
228
+ - **First-time update / platform guides:** Windows: rerun `scripts/install_windows.ps1` (or `git pull --ff-only` + `scripts\setup_windows.ps1 -Action setup`) then restart. Termux: rerun `scripts/install.sh` with `MODE=web ... --workers 1` (or manual ff-only + setup) then restart. Details in `docs/UPDATES.md`.
229
+ - **Manual CLI:** `git pull --ff-only` then re-run setup to refresh deps if needed (Unix/Termux: `MODE=<...> ACTION=setup sh scripts/setup.sh`, Windows: `scripts\setup_windows.ps1 -Action setup`).
230
+
231
+ See `docs/UPDATES.md` for release/update/rollback guidance.
232
+
233
+ ## Integrity, health checks & doctor
234
+
235
+ - **In-app (read-only):** ledger/data integrity checks available in Web UI and via grounded assistant queries.
236
+ - **CLI doctor:** `PYTHONPATH=src python -m app_core.doctor` (or `scripts/backup_runtime.* --doctor`) for operational health checks. Supports `--json`, `--check-updates`, `--strict`, and safe backup/verify helpers: `--backup [--backup-to <path>]`, `--verify-backup <path>` / `--verify`.
237
+ - **Web probes:** `GET /health`, `GET /healthz`, `GET /readyz` for liveness/readiness (and detailed readiness checks).
238
+
239
+ ## Backups & restore
240
+
241
+ - **Create backups (automated/helpers):**
242
+ - Web UI: **Settings → Backup now** (subject to unlock/CSRF as applicable).
243
+ - CLI: `python3 scripts/backup_runtime.py --backup [--to <path>]`, `python3 scripts/backup_runtime.py --verify <backup.db>`, `python3 scripts/backup_runtime.py --doctor [--json] [--check-updates]`, or `PYTHONPATH=src python -m app_core.doctor --backup/--verify-backup`.
244
+ - Wrappers: `scripts/backup_runtime.sh`, `scripts/backup_runtime.cmd`, `scripts/backup_runtime.ps1`.
245
+ - **Preserve:** DB, exports, invoices, and data dir (`PM_DATA_DIR` or defaults). Take backups regularly and before upgrades/migrations.
246
+ - **Restore (manual, offline):** no destructive one-click in-app restore.
247
+ 1. Stop app/server.
248
+ 2. Verify candidate backup (`--verify` / `--verify-backup`).
249
+ 3. Copy current DB/files as safety backup.
250
+ 4. Replace active DB (and related exports/invoices if needed) with verified backup in the correct data directory.
251
+ 5. Start app/server (`--workers 1` for web); migrations run on startup.
252
+ 6. Verify with doctor/integrity checks and app smoke tests.
253
+
254
+ See `docs/BACKUP_RESTORE.md` for DR guidance.
255
+
256
+ ## Tests & checks
257
+
258
+ ```bash
259
+ python -m py_compile src/app_core/*.py ui/web/*.py main.py launcher.py
260
+ PYTHONPATH=src pytest -q
261
+ pytest --cov=src/app_core --cov=ui --cov-report=term-missing --cov-report=xml:coverage.xml
262
+ python -m pip install -r requirements.txt -r requirements-dev.txt && python -m pytest -q
263
+ ```
264
+
265
+ ## Troubleshooting (quick)
266
+
267
+ - **Web deps/build issues (iSH/limited toolchains):** use `SKIP_WEB=0 MODE=web`.
268
+ - **`venv` missing:** install distro Python venv package (e.g. `python3-venv`) or re-run setup scripts.
269
+ - **Port in use / unreachable:** change `PORT`, bind correct `HOST`, allow firewall, verify LAN IP/proxy.
270
+ - **DB/permission issues:** ensure writable data dir (`PM_DATA_DIR`/defaults), single writer, `--workers 1` for web.
271
+ - **Update apply blocked:** commit/stash/discard local changes or resolve non-fast-forward state manually.
272
+
273
+ See `docs/TROUBLESHOOTING.md`.
274
+
275
+ ## Packaging & install formats
276
+
277
+ - **Python package (wheel/sdist):** `pyproject.toml` builds distributable packages including web UI assets (`ui/web/templates`, `ui/web/static`, PWA manifest/icons/service worker). CI workflow: `.github/workflows/release-python-package.yml` (artifacts on tags/dispatch; optional PyPI publish via `PYPI_API_TOKEN`).
278
+ - **Container image (GHCR):** multi-arch image published by `.github/workflows/release-container.yml` to `ghcr.io/michaelhehelmy/spms` (run with `--workers 1`, persistent `PM_DATA_DIR`).
279
+ - **Native binaries:** Nuitka builds via `.github/workflows/release-native.yml` (Windows `.exe`, Linux binary/AppImage path, macOS `.dmg`). See `docs/NATIVE_BUILDS.md`.
280
+ - **PWA / installable web app:** manifest, icons, and a minimal service worker are served from `ui/web/static/` for “Add to Home Screen / Install app” (best over HTTPS for non-localhost).
281
+ - **Kubernetes/Helm:** chart skeleton in `deploy/helm/spms` (single-replica, SQLite-safe `--workers 1`, persistent data volume, probes).
282
+ - **Linux packages scaffolds:** Debian/Ubuntu `.deb` (`deploy/packaging/deb/build-deb.sh`) and RPM (`deploy/packaging/rpm/build-rpm.sh`, `SPECS/spms.spec`) with `spms-web` systemd service and `/etc/spms/spms.env`.
283
+ - **Android WebView wrapper scaffold:** `deploy/mobile/android-webview/` (configurable SPMS URL; reuse web UI/PWA).
284
+ - **Planned/optional (external/signing/hardening):** Windows/macOS installers (signed/notarized), TWA/store packaging. Details and roadmap: `docs/PACKAGING.md`.
285
+
286
+ ## More documentation
287
+
288
+ - `assistant.md` — assistant capabilities, grounded/read-only behavior, evolution and plan.
289
+ - `docs/PACKAGING.md` — packaging/distribution formats, modularization boundaries, and implementation roadmap/status.
290
+ - `docs/NATIVE_BUILDS.md` — Nuitka/native standalone build and release packaging guidance (GitHub Releases assets auto-detected by landing page). Landing page can also accept uploaded JSON issue reports via Cloudflare Pages Function (`functions/api/report.js`) when configured with secrets (e.g. `REPORT_GITHUB_TOKEN`, optional `REPORT_GITHUB_REPO`/`REPORT_GITHUB_LABELS`) to create GitHub issues for maintainers.
291
+ - `docs/PRODUCTION_ROADMAP.md` — phased P0–P3 production hardening/operations roadmap and checklist.
292
+ - `docs/DEPLOYMENT.md` — local/LAN/remote deployment, reverse proxy + HTTPS, systemd/Docker guidance.
293
+ - `docs/SECURITY.md` — hardening checklist, secrets/cookies, authz/unlock/CSRF, printer/file/data handling.
294
+ - `docs/BACKUP_RESTORE.md` — backup, verify, restore, DR, data preservation.
295
+ - `docs/UPDATES.md` — release/update/rollback guidance.
296
+ - `docs/TROUBLESHOOTING.md` — common issues and diagnostics.
297
+ - `docs/GO_LIVE_CHECKLIST.md` — operational go-live steps (monitoring, domain/TLS, backups, pilot, etc.).
298
+ - `docs/web_authz_matrix.md` — web route-group authz/CSRF/unlock reference (authoritative for `ui/web`).
spms-1.2.1/README.md ADDED
@@ -0,0 +1,251 @@
1
+ # SPMS (Super Property Management System)
2
+
3
+ SPMS (Super Property Management System) — local-first property management with a shared backend and a web frontend:
4
+
5
+ - **Web UI:** FastAPI + HTMX server (`ui.web.server:app`, `launcher.py`, `main.py`) for browser access on desktop/mobile, LAN, or behind a reverse proxy.
6
+
7
+ **Architecture:** all business logic lives in `src/app_core/` (DB, services, paths, assistant, integrity/doctor, updater, barcode/batch logic, support/reporting) and is used by `ui/web/`. SQLite is the datastore.
8
+
9
+ ## Current capabilities
10
+
11
+ - **Front desk & reservations:** guests (including 360° portfolio views), rooms/rate plans, availability, create/check-in/checkout flows, folio/balances, payments/refunds where applicable, invoices/receipts.
12
+ - **POS & inventory:** catalog, walk-in and reservation-linked sales, recipes/meals/ingredients with auto-deduction, expenses, and **traceable barcodes/SKUs/lots**.
13
+ - **Batch/lot traceability & FEFO:** inventory supports batch/lot tracking with received date/time, expiry date, remaining/received quantity, unit cost, supplier/reference/notes, status/expiry state, and movements. Supports **FEFO-aware** (First Expired, First Out) workflows, expiring/expired batch review, batch/lot lists, and barcode/SKU/lot trace (resolved item or lot with received/expiry/remaining and recent movements when available).
14
+ - **Activities/trips:** register/book activities/excursions, track bookings/stats, and post charges to folios/invoices.
15
+ - **Accounting, reports & analytics:** ledger, operational/financial reports and analytics/exports (as available in the app).
16
+ - **Grounded assistant (read-only):** Web assistant answers from real app data/tools (ops, reports, guests/portfolios, reservations/balances, inventory including expiring batches, batch lists, barcode/lot trace, activities/bookings, integrity/health, and app version/update status). Assistant follows configured unlock/allowlist policy and remains read-only.
17
+ - **Integrity & health:** read-only ledger/data integrity checks in-app, CLI **doctor** (`python -m app_core.doctor`), safe backup/verify helpers, and web liveness/readiness probes `GET /health`, `GET /healthz`, `GET /readyz`.
18
+ - **Issue reporting (privacy-first):** Web **Report issue** (`/support/report`) and CLI **`python -m app_core.support`** generate sanitized diagnostics (no passwords/secrets/tokens/CSRF/session/recovery codes or DB/guest/payment records), let you review/edit details, download/copy Markdown or JSON reports (including device/OS info and recent in-app steps), open a prefilled GitHub issue, or upload the downloaded JSON report via the landing page (if configured) so it can be delivered to maintainers. Unhandled web errors show a friendly “Report this issue” page with prefilled context.
19
+ - **In-app updates (git installs):** **Settings → App updates** supports **Check for updates**, changelog/commit details, and **Apply/Update** via **git fast-forward**. Local source changes must be committed/stashed/discarded before apply.
20
+ - **Backups & data safety:** create verified DB backups from Settings (**Backup now**, subject to unlock/CSRF as applicable) or CLI/scripts. Runtime data is preserved across source updates; **restore is manual and offline**.
21
+
22
+ ## Operational requirements (important)
23
+
24
+ - **SQLite / single worker:** always run the web server with **`--workers 1`**. Do not increase worker count.
25
+ - **Web secret key:** set **`PM_WEB_SECRET_KEY`** to a strong random value for any non-local/shared/LAN/remote deployment.
26
+ - **HTTPS / transport security:** bind to `127.0.0.1` for local-only use. For LAN/remote/browser access, use **HTTPS** (reverse proxy that terminates TLS) or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
27
+ - **Data directory & permissions:** runtime data lives in `PM_DATA_DIR` or app defaults/legacy locations (DB, exports, invoices). Ensure the process user can read/write the data directory and keep a single writer.
28
+ - **Data preserved across updates:** source/app updates (in-app fast-forward or `git pull --ff-only`) do **not** modify runtime data (DB, exports, invoices, configured data dir). DB migrations run on startup and are additive where applicable.
29
+ - **Restart after apply:** after applying an in-app update, **restart the app/server** to load the new version.
30
+ - **Local source changes:** in-app apply requires a clean working tree for fast-forward; commit, stash, or discard local changes first.
31
+ - **Backups before risky operations:** take and verify backups before upgrades/migrations, restores, or major operational changes.
32
+ - **No destructive one-click restore:** restore is deliberate/manual/offline (stop app, verify backup, replace files, start, verify integrity).
33
+ - **Security model:** web state-changing requests are CSRF-protected; sensitive/destructive/admin mutations require **super-password unlock** (and CSRF) per policy, while some routine operational/front-desk flows remain usable with CSRF only. See `docs/web_authz_matrix.md`.
34
+
35
+ ## Repository layout
36
+
37
+ ```text
38
+ launcher.py # unified web launcher/menu
39
+ main.py # web entry point (compatibility)
40
+ pyproject.toml # packaging metadata, dependencies, extras
41
+ requirements.txt # runtime dependencies (web-only app)
42
+ requirements-dev.txt # dev/test dependencies
43
+ scripts/ # install/setup/update/backup/coverage helpers
44
+ src/app_core/ # shared backend (db, services, paths, assistant, doctor, updater, ...)
45
+ ui/web/ # FastAPI + HTMX web UI
46
+ docs/ # operations, security, deployment, runbooks
47
+ assistant.md # assistant capabilities/evolution/plan
48
+ tests/ # pytest suite
49
+ ```
50
+
51
+ ## Quick decision: how to run
52
+
53
+ | Goal | Recommended mode |
54
+ |---|---|
55
+ | Local use on a PC/server | Web UI on `127.0.0.1` (`python launcher.py` / `python main.py`) |
56
+ | Access from phone/tablet browser on same LAN | **Web** bound to `0.0.0.0` behind trusted LAN/VPN and with `PM_WEB_SECRET_KEY`; prefer HTTPS reverse proxy if feasible |
57
+ | Remote access over internet | **Web** behind **HTTPS** reverse proxy / VPN / Tailscale (never plain HTTP public exposure) |
58
+ | iSH (iOS/Alpine, constrained) | Run the Web UI on a supported host when web dependencies/toolchains are unavailable on-device |
59
+ | Android (Termux) | **Web** (`--workers 1`) |
60
+ | Windows desktop/server | `scripts/install_windows.ps1` / `scripts/setup_windows.ps1` or manual venv |
61
+
62
+ ## One-line install / update (all supported OS families)
63
+
64
+ These commands are intended for **first-time install and later re-runs** on git-based installs: they bootstrap prerequisites where possible, clone/update (fast-forward), refresh dependencies, preserve runtime data, and launch/run per selected mode. **Always keep web on `--workers 1`**. For shared/non-local/LAN/remote web access, set a strong `PM_WEB_SECRET_KEY` and use **HTTPS** via reverse proxy/VPN/private networking (do not expose plain HTTP publicly). **Built-in recovery:** if an install/update gets stuck due to dirty tree, stale `.git/index.lock`, stuck merge/rebase, or ff-only/checkout errors (e.g. `Reset branch 'main'`), rerun with `REPAIR=1` (Unix/Termux) or `-Repair` / `$env:REPAIR='1'` (Windows) to auto-recover by resetting local source to the target branch (runtime data in `PM_DATA_DIR`/external data dirs is not removed by git).
65
+
66
+ | OS / Environment | One-line command | Notes |
67
+ |---|---|---|
68
+ | **Linux / macOS / WSL / generic Unix** (curl) | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Detects environment/package manager, installs/updates, and launches the web app. Re-run anytime. |
69
+ | **Linux / macOS / WSL** (wget) | `wget -qO- https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Fallback if `curl` is unavailable. |
70
+ | **Web server for LAN (trusted network)** | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY="$(openssl rand -hex 32)" sh` | `--workers 1` required (SQLite). Use HTTPS reverse proxy/VPN for shared/remote access. |
71
+ | **Android (Termux)** | `pkg update -y && pkg install -y curl && curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Installs/updates and launches web app. For LAN web add `MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY=...` (use HTTPS/proxy for shared access). |
72
+ | **Windows (PowerShell, bootstrap)** | `irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 \| iex` | Uses winget when available to install Python/Git if missing, then clones/updates and runs setup/deploy. Customize via `$env:ACTION/$env:MODE/$env:HOST/$env:PORT/$env:PM_WEB_SECRET_KEY`. |
73
+ | **Windows (CMD bootstrap)** | `curl -fsSL -o install_windows.cmd https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.cmd && install_windows.cmd -Action deploy -Mode auto` | Downloads/runs bootstrap wrapper (uses PowerShell script). |
74
+
75
+ **Common env vars / parameters (Unix installer/setup):** `INSTALL_DIR`, `REPO_URL`, `BRANCH`, `GIT_REF`/`TAG`/`COMMIT` (pinned ref), `MODE` (`web`; legacy values map to web), `ACTION` (`auto|setup|run|deploy`), `SKIP_WEB` (`auto|0|1`), `HOST`, `PORT`, `PYTHON`, `INSTALL_DEV`, `RUN_TESTS`, `PM_DATA_DIR`, `PM_WEB_SECRET_KEY`. **Windows:** pass `-GitRef`/`-Action`/`-Mode`/`-BindHost`/`-Port` or set corresponding env vars (`GIT_REF`/`TAG`/`COMMIT`, etc.).
76
+
77
+ - `ACTION=auto` (default): full install+launch if missing, else update deps/code and launch.
78
+ - `ACTION=setup`: install/update/prepare only. `ACTION=run`: run existing install. `ACTION=deploy`: setup + run.
79
+ - Runtime data (DB/exports/invoices/`PM_DATA_DIR`) is preserved by scripts/updates.
80
+
81
+ ### Pinned/reproducible installs
82
+
83
+ - Install/update to a specific tag/commit/branch: `GIT_REF=<tag-or-commit-or-branch> sh` (Unix) or `-GitRef <...>` / `$env:GIT_REF=<...>` (Windows). Aliases: `TAG`, `COMMIT`.
84
+ - **Pinned bootstrap script URL:** use the raw script at the same ref to ensure installer logic is reproducible, e.g. `https://raw.githubusercontent.com/Michaelhehelmy/spms/<tag-or-commit>/scripts/install.sh` (Unix) or `.../<tag-or-commit>/scripts/install_windows.ps1` (Windows).
85
+ - Existing checkouts: `GIT_REF=<tag> ACTION=setup sh scripts/setup.sh` (or Windows setup script) checks out the requested ref; when on a branch, scripts may fast-forward as applicable. Runtime data is preserved.
86
+ - For immutable production-like deployments, prefer pinning to a release tag/commit and recording the resolved commit (`git -C <install-dir> rev-parse HEAD`) alongside backups/change records.
87
+
88
+ ### Dependency/install robustness (constrained environments)
89
+
90
+ - **Web dependency/toolchain issues:** if web dependency installation/build fails (e.g. `pydantic-core`/Rust wheel issues on constrained environments), install/upgrade Python/build tools or a compatible prebuilt wheel, or run the web app on a fuller host.
91
+ - **`pydantic-core` / Rust wheel issues:** on iSH/Termux/older CPU architectures or limited toolchains, some web deps may require Rust/cargo/build tools or a prebuilt wheel matching your Python version/architecture. If unavailable, upgrade Python/toolchain, install build deps, or run the Web UI on a supported host.
92
+ - **SQLite web safety:** always run the web server with `--workers 1`. Use `PM_WEB_SECRET_KEY` and HTTPS reverse proxy/VPN for non-local/shared access. Runtime data (`PM_DATA_DIR`, DB, exports, invoices) is preserved across setup/update runs.
93
+
94
+ ## Platform-specific setup
95
+
96
+ ### Linux / macOS / WSL / Unix-like
97
+ - Use `scripts/install.sh` (bootstrap) or `scripts/setup.sh` from a checkout.
98
+ - Examples: `sh scripts/setup.sh` (setup), `MODE=web ACTION=deploy sh scripts/setup.sh`, `MODE=web HOST=127.0.0.1 PORT=8000 ACTION=deploy sh scripts/setup.sh`.
99
+ - WSL: treat as Linux; bind carefully for LAN access and account for Windows firewall/port forwarding.
100
+
101
+ ### Android (Termux)
102
+ ```sh
103
+ pkg update && pkg install -y git python curl
104
+ curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | sh
105
+ # or web on LAN (trusted network): add MODE=web HOST=0.0.0.0 PORT=8000 and PM_WEB_SECRET_KEY
106
+ ```
107
+
108
+ ### iOS (iSH / Alpine)
109
+ ```sh
110
+ apk add --no-cache curl
111
+ curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | MODE=web sh
112
+ ```
113
+ If web dependencies cannot be built on-device, run the Web UI on a supported host and access it from the browser.
114
+
115
+ ### iOS/iPadOS as web client
116
+ Run the server on a capable host (Mac/Linux/Windows/Termux/RPi/VPS) and open from Safari (`http://<host>:8000` on LAN or `https://...` via reverse proxy/Tailscale/VPN). Add to Home Screen for app-like use.
117
+
118
+ ### Windows (10/11, Server)
119
+ - **Bootstrap (recommended):** PowerShell (Admin recommended for winget):
120
+ ```powershell
121
+ irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 | iex
122
+ ```
123
+ Customize: `$env:ACTION='deploy'; $env:MODE='web'; $env:HOST='127.0.0.1'; $env:PORT='8000'; $env:PM_WEB_SECRET_KEY='...'; irm ... | iex`
124
+ - **From existing checkout:**
125
+ ```powershell
126
+ powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1 -Action deploy -Mode web
127
+ powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1 -Action deploy -Mode web -BindHost 127.0.0.1 -Port 8000
128
+ scripts\install_windows.cmd -Action deploy -Mode auto
129
+ ```
130
+ - If winget is unavailable, install Python 3.10+ (PATH) and Git, then re-run. Scripts attempt to refresh PATH/bootstrap prerequisites.
131
+
132
+ ### Manual install (any OS with Python)
133
+
134
+ ```bash
135
+ git clone https://github.com/Michaelhehelmy/spms.git
136
+ cd spms
137
+ python3 -m venv .venv
138
+ # activate: Unix `. .venv/bin/activate` | PowerShell `.\\.venv\\Scripts\\Activate.ps1` | cmd `.venv\\Scripts\\activate.bat`
139
+ pip install -r requirements.txt # runtime dependencies (web-only app)
140
+ # optional dev/test deps: pip install -r requirements-dev.txt
141
+ python launcher.py # menu
142
+ python launcher.py --web --host 127.0.0.1 --port 8000
143
+ # direct web server (always --workers 1):
144
+ PYTHONPATH=src python -m uvicorn ui.web.server:app --host 127.0.0.1 --port 8000 --workers 1
145
+ ```
146
+
147
+ `pyproject.toml` also defines extras/scripts (`.[web]`, `.[dev]`, `property-manager`, `pm`, etc.) for packaging workflows.
148
+
149
+ ## Web deployment essentials
150
+
151
+ - **Workers:** `--workers 1` only (SQLite/shared state). Never increase workers.
152
+ - **Bind:** `127.0.0.1` local-only; `0.0.0.0` reachable on interfaces (LAN). Manage firewall exposure explicitly.
153
+ - **Secret:** set `PM_WEB_SECRET_KEY` to a strong random value for any non-local/shared deployment (required for non-loopback use unless an explicit local/dev insecure override is set).
154
+ - **TLS/remote access:** use reverse proxy with HTTPS or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
155
+ - **Data directory & permissions:** set `PM_DATA_DIR` if needed; ensure the service user can read/write the data directory and run with a single writer.
156
+ - **Health probes:** `GET /health` and `GET /healthz` (liveness/basic health with readiness summary), `GET /readyz` (readiness/runtime checks including data-dir writability). Keep probes and app on `--workers 1`.
157
+ - **Service/autostart:** use systemd/launchd/NSSM/Task Scheduler/supervisor/Docker restart policy to run venv Python/uvicorn with `--workers 1`.
158
+ - **Reverse proxy:** proxy to `127.0.0.1:8000`, terminate TLS, and forward standard proxy headers as needed.
159
+ - **Backups, restore, updates:** take and verify backups before upgrades/migrations; restore is manual/offline (with restore drill validation recommended); restart the app/server after applying updates.
160
+ - **App icon / launcher:** no native installer icons are bundled. For browser/mobile install use "Add to Home Screen" (add PWA assets like `manifest.webmanifest` and icons under `ui/web/static/` and link from `ui/web/templates/base.html` if needed); for Windows/Linux create OS shortcuts (`.lnk`/`.desktop`) pointing to the venv launcher with a custom icon.
161
+ - See `docs/DEPLOYMENT.md` and `docs/SECURITY.md` for examples and hardening.
162
+
163
+ ## Security model (Web) — summary
164
+
165
+ - **CSRF:** all state-changing web requests (POST/PUT/PATCH/DELETE) are CSRF-protected (form tokens and/or header/middleware enforcement per request type).
166
+ - **Super-password unlock:** sensitive/destructive/admin mutations require active unlock (super password) in addition to CSRF (financial/accounting operations, inventory/stock/batch/recipe/meal/activity changes, voids/refunds/cancels/deletes/modifications, exports/backups/seed/demo/settings changes, labels, protected downloads where applicable, etc.).
167
+ - **Routine operational flows:** some front-desk/POS operations may remain usable with CSRF where appropriate, but policy-sensitive overrides/destructive actions remain gated by unlock.
168
+ - **Assistant:** follows configured unlock/allowlist policy while remaining read-only and grounded.
169
+ - **Secrets & transport:** strong `PM_WEB_SECRET_KEY`, HTTPS/private networking for shared/remote access.
170
+ - **Reference:** `docs/web_authz_matrix.md` is the authoritative route-group matrix for `ui/web`. See `docs/SECURITY.md` for hardening checklist.
171
+
172
+ ## Updates
173
+
174
+ **In-app (recommended for git installs):** **Settings → Updates & Health → App updates** → **Check for updates** → **Update now / Apply** appears **only when an update is available** (git fast-forward for clean checkouts).
175
+
176
+ - **Automated:** check/fetch metadata, show changelog/commits, apply ff-only when eligible.
177
+ - **Requirements/limits:** clean working tree required; non-fast-forward/diverged histories need manual git resolution.
178
+ - **Data preserved:** DB, exports, invoices, and configured data directory (`PM_DATA_DIR`/defaults) are not modified by source updates.
179
+ - **After apply:** **restart the app/server** to load the new version. If dependencies changed, refresh the venv via setup scripts.
180
+ - **Update notifications (auto-check):** built-in polling-based checks run when online (cached/rate-limited, configurable via `auto_check_updates` / `auto_update_check_interval_hours`) and notify in the web UI when updates/releases are available. Git installs can be applied in-app (ff-only) then restarted; native/packaged installs require downloading/installing the new release artifact. No push infrastructure; auto-apply is not enabled by default.
181
+ - **First-time update / platform guides:** Windows: rerun `scripts/install_windows.ps1` (or `git pull --ff-only` + `scripts\setup_windows.ps1 -Action setup`) then restart. Termux: rerun `scripts/install.sh` with `MODE=web ... --workers 1` (or manual ff-only + setup) then restart. Details in `docs/UPDATES.md`.
182
+ - **Manual CLI:** `git pull --ff-only` then re-run setup to refresh deps if needed (Unix/Termux: `MODE=<...> ACTION=setup sh scripts/setup.sh`, Windows: `scripts\setup_windows.ps1 -Action setup`).
183
+
184
+ See `docs/UPDATES.md` for release/update/rollback guidance.
185
+
186
+ ## Integrity, health checks & doctor
187
+
188
+ - **In-app (read-only):** ledger/data integrity checks available in Web UI and via grounded assistant queries.
189
+ - **CLI doctor:** `PYTHONPATH=src python -m app_core.doctor` (or `scripts/backup_runtime.* --doctor`) for operational health checks. Supports `--json`, `--check-updates`, `--strict`, and safe backup/verify helpers: `--backup [--backup-to <path>]`, `--verify-backup <path>` / `--verify`.
190
+ - **Web probes:** `GET /health`, `GET /healthz`, `GET /readyz` for liveness/readiness (and detailed readiness checks).
191
+
192
+ ## Backups & restore
193
+
194
+ - **Create backups (automated/helpers):**
195
+ - Web UI: **Settings → Backup now** (subject to unlock/CSRF as applicable).
196
+ - CLI: `python3 scripts/backup_runtime.py --backup [--to <path>]`, `python3 scripts/backup_runtime.py --verify <backup.db>`, `python3 scripts/backup_runtime.py --doctor [--json] [--check-updates]`, or `PYTHONPATH=src python -m app_core.doctor --backup/--verify-backup`.
197
+ - Wrappers: `scripts/backup_runtime.sh`, `scripts/backup_runtime.cmd`, `scripts/backup_runtime.ps1`.
198
+ - **Preserve:** DB, exports, invoices, and data dir (`PM_DATA_DIR` or defaults). Take backups regularly and before upgrades/migrations.
199
+ - **Restore (manual, offline):** no destructive one-click in-app restore.
200
+ 1. Stop app/server.
201
+ 2. Verify candidate backup (`--verify` / `--verify-backup`).
202
+ 3. Copy current DB/files as safety backup.
203
+ 4. Replace active DB (and related exports/invoices if needed) with verified backup in the correct data directory.
204
+ 5. Start app/server (`--workers 1` for web); migrations run on startup.
205
+ 6. Verify with doctor/integrity checks and app smoke tests.
206
+
207
+ See `docs/BACKUP_RESTORE.md` for DR guidance.
208
+
209
+ ## Tests & checks
210
+
211
+ ```bash
212
+ python -m py_compile src/app_core/*.py ui/web/*.py main.py launcher.py
213
+ PYTHONPATH=src pytest -q
214
+ pytest --cov=src/app_core --cov=ui --cov-report=term-missing --cov-report=xml:coverage.xml
215
+ python -m pip install -r requirements.txt -r requirements-dev.txt && python -m pytest -q
216
+ ```
217
+
218
+ ## Troubleshooting (quick)
219
+
220
+ - **Web deps/build issues (iSH/limited toolchains):** use `SKIP_WEB=0 MODE=web`.
221
+ - **`venv` missing:** install distro Python venv package (e.g. `python3-venv`) or re-run setup scripts.
222
+ - **Port in use / unreachable:** change `PORT`, bind correct `HOST`, allow firewall, verify LAN IP/proxy.
223
+ - **DB/permission issues:** ensure writable data dir (`PM_DATA_DIR`/defaults), single writer, `--workers 1` for web.
224
+ - **Update apply blocked:** commit/stash/discard local changes or resolve non-fast-forward state manually.
225
+
226
+ See `docs/TROUBLESHOOTING.md`.
227
+
228
+ ## Packaging & install formats
229
+
230
+ - **Python package (wheel/sdist):** `pyproject.toml` builds distributable packages including web UI assets (`ui/web/templates`, `ui/web/static`, PWA manifest/icons/service worker). CI workflow: `.github/workflows/release-python-package.yml` (artifacts on tags/dispatch; optional PyPI publish via `PYPI_API_TOKEN`).
231
+ - **Container image (GHCR):** multi-arch image published by `.github/workflows/release-container.yml` to `ghcr.io/michaelhehelmy/spms` (run with `--workers 1`, persistent `PM_DATA_DIR`).
232
+ - **Native binaries:** Nuitka builds via `.github/workflows/release-native.yml` (Windows `.exe`, Linux binary/AppImage path, macOS `.dmg`). See `docs/NATIVE_BUILDS.md`.
233
+ - **PWA / installable web app:** manifest, icons, and a minimal service worker are served from `ui/web/static/` for “Add to Home Screen / Install app” (best over HTTPS for non-localhost).
234
+ - **Kubernetes/Helm:** chart skeleton in `deploy/helm/spms` (single-replica, SQLite-safe `--workers 1`, persistent data volume, probes).
235
+ - **Linux packages scaffolds:** Debian/Ubuntu `.deb` (`deploy/packaging/deb/build-deb.sh`) and RPM (`deploy/packaging/rpm/build-rpm.sh`, `SPECS/spms.spec`) with `spms-web` systemd service and `/etc/spms/spms.env`.
236
+ - **Android WebView wrapper scaffold:** `deploy/mobile/android-webview/` (configurable SPMS URL; reuse web UI/PWA).
237
+ - **Planned/optional (external/signing/hardening):** Windows/macOS installers (signed/notarized), TWA/store packaging. Details and roadmap: `docs/PACKAGING.md`.
238
+
239
+ ## More documentation
240
+
241
+ - `assistant.md` — assistant capabilities, grounded/read-only behavior, evolution and plan.
242
+ - `docs/PACKAGING.md` — packaging/distribution formats, modularization boundaries, and implementation roadmap/status.
243
+ - `docs/NATIVE_BUILDS.md` — Nuitka/native standalone build and release packaging guidance (GitHub Releases assets auto-detected by landing page). Landing page can also accept uploaded JSON issue reports via Cloudflare Pages Function (`functions/api/report.js`) when configured with secrets (e.g. `REPORT_GITHUB_TOKEN`, optional `REPORT_GITHUB_REPO`/`REPORT_GITHUB_LABELS`) to create GitHub issues for maintainers.
244
+ - `docs/PRODUCTION_ROADMAP.md` — phased P0–P3 production hardening/operations roadmap and checklist.
245
+ - `docs/DEPLOYMENT.md` — local/LAN/remote deployment, reverse proxy + HTTPS, systemd/Docker guidance.
246
+ - `docs/SECURITY.md` — hardening checklist, secrets/cookies, authz/unlock/CSRF, printer/file/data handling.
247
+ - `docs/BACKUP_RESTORE.md` — backup, verify, restore, DR, data preservation.
248
+ - `docs/UPDATES.md` — release/update/rollback guidance.
249
+ - `docs/TROUBLESHOOTING.md` — common issues and diagnostics.
250
+ - `docs/GO_LIVE_CHECKLIST.md` — operational go-live steps (monitoring, domain/TLS, backups, pilot, etc.).
251
+ - `docs/web_authz_matrix.md` — web route-group authz/CSRF/unlock reference (authoritative for `ui/web`).