shiyuyun/wyndham-ARR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: enable XML processing in container entry

Browse Source
This commit is contained in:
Wyndham ARR
2026-07-29 18:34:03 +08:00
parent 12881be17e
commit ad3d9878c5
13 changed files with 118 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.project-docs/20-architecture/module-map.md
View File

@@ -9,7 +9,7 @@
| `arr_ingestion/`, `arr_processing/` | Validate and persist structured processing results | Keep deterministic replay and transaction semantics. |
| `monthly_reports/` | Database-backed monthly workbook generation | Needs formula-cell output and automatic orchestration integration. |
| `database/` | Finance facts, views, guards and migrations | Database total remains useful for integrity checks. |
| `Dockerfile`, `compose.yaml` | Reproducible single-server Web/MCP runtime | Compose explicitly enables XML processing; source defaults remain fail-closed. |
| `Dockerfile`, `compose.yaml` | Reproducible single-server Web/MCP runtime | Dockerfile default Web CMD and Compose explicitly enable XML processing; direct source CLI defaults and runtime readiness remain fail-closed. |
| `deploy/` | Caddy TLS/auth boundary, production env template and operator runbook | Only Caddy publishes host ports; never commit the real production env file. |
| `tests/` | Regression and acceptance coverage | Add post-commit trigger and formula-cell assertions when implementation is authorized. |

2
.project-docs/20-architecture/system-overview.md
View File

@@ -22,7 +22,7 @@ The ARR system accepts an Opera XML upload, stores the private source artifact,
- The user-facing upload workflow does not collect monthly report year, month, or cutoff date.
- Monthly processing reads validated database facts rather than repeating Agent business logic.
- Database `total_price` may support validation, but the exported `TOTAL PRICE` cell must remain a formula.
- Public deployment enables XML processing only through the explicit Compose command and requires `processing_ready=true`; it does not change local/application defaults.
- Container deployment enables XML processing through both the Dockerfile default Web CMD and the explicit Compose command, and still requires `processing_ready=true`; direct source CLI execution remains default-closed.
## Related Decisions

5
.project-docs/30-worklog/current-state.md
View File

@@ -2,10 +2,11 @@
## Current Focus
The controlled public-deployment source snapshot is published on `main` at `https://git.nianxx.cn/shiyuyun/wyndham-ARR.git`; initial deployment commit `a701de9` contains the verified source snapshot. Its Compose Web entry explicitly enables `--enable-processing --secure-cookies`; Caddy is the only public listener and adds HTTPS plus Web Basic Auth, while MCP retains its independent bearer and exact Host allowlist. Local application defaults remain fail-closed. The snapshot passes 259 tests with 2 environment skips plus contract, checksum, candidate-file and secret scans. No public server deployment has been performed from this workspace.
The controlled public-deployment source snapshot is published on `main` at `https://git.nianxx.cn/shiyuyun/wyndham-ARR.git`; initial deployment commit `a701de9` contains the verified source snapshot. The Dockerfile default Web CMD and Compose Web command now both explicitly enable `--enable-processing`; Compose additionally uses `--secure-cookies`, while Caddy remains the documented public listener and MCP retains its independent bearer and exact Host allowlist. Direct source CLI execution remains fail-closed. The current suite passes 260 tests with 2 environment skips plus deployment-entry static assertions. No public-server runtime has been verified from this workspace.
## Recently Completed
- 2026-07-29: Fixed the direct Docker-image launch path so its default Web CMD explicitly includes `--enable-processing`, matching Compose. The controlled local launchd script was also updated and restarted: PID 50730 reports both database and processing ready, and a browser DOM check confirms the XML chooser is enabled. Added a regression test that opens only XML processing mutations; all 260 tests pass with 2 artifact-tool skips. Source CLI defaults and the runtime readiness gate remain fail-closed.
- 2026-07-29: Published the deployment-ready snapshot to the empty self-hosted repository as `main`, established upstream tracking and verified that the remote branch contains initial commit `a701de9`.
- 2026-07-29: Added a Linux Dockerfile, Compose, Caddy TLS boundary, production env example and deployment runbook. The Web health gate requires both `database_ready` and `processing_ready`; the production command opens XML processing without changing the source default.
- 2026-07-29: Added opt-in HTTPS `Secure` session cookies, made the booking fixture root portable, removed local paths/test endpoints/temporary tunnel names from the publishable snapshot, and verified 271 final candidate files (about 2.0 MiB) contain no detected secrets, symlinks or files larger than 1 MiB.
@@ -26,7 +27,7 @@ The controlled public-deployment source snapshot is published on `main` at `http
## Next Recommended Steps
1. Deploy the repository using `deploy/README.md`, inject real Secrets only on the server, and require the public Web health response to report `database_ready=true` and `processing_ready=true`.
1. Redeploy the latest repository image using `deploy/README.md`, inject real Secrets only on the server, and require the public Web health response to report `database_ready=true` and `processing_ready=true`; any platform override of Docker CMD must retain `--enable-processing`.
2. Rebind SuperAgent to `https://<MCP_PUBLIC_HOST>/mcp`, rediscover exactly `arr_submit_processing_result`, save/publish the new Agent version, and stop relying on the temporary ngrok endpoint.
3. Rerun the vertical slice with a fresh no-PII XML and require a `committed`/`already_committed` receipt plus matching Finance version, current pointer and fact rows.
4. In separately authorized implementation work, add the automatic post-commit monthly dispatch and required `TOTAL PRICE` formula behavior.

1
.project-docs/30-worklog/task-history.md
View File

@@ -4,6 +4,7 @@
| Date | Task | Outcome | Docs Updated |
|---|---|---|---|
| 2026-07-29 | Open XML processing in the Docker image and current local Web entry | Added `--enable-processing` to Dockerfile CMD so direct image launches match Compose; updated/restarted the controlled local launchd entry and verified database/processing health plus an enabled XML file chooser; kept source CLI/runtime readiness fail-closed; passed 260 tests with 2 expected skips | README/runbook, current state, architecture module map, deployment and local-runtime evidence/index, container-entry reflection, planning record |
| 2026-07-29 | Prepare and publish the project for controlled public-server deployment | Added Docker/Compose/Caddy deployment with XML processing explicitly enabled, HTTPS Secure cookies, Basic Auth/Bearer boundaries and a Chinese runbook; sanitized publishable history; 259 tests passed (2 skipped), all contracts/checksums and a 271-file secret/size/symlink scan passed; pushed `main` to the self-hosted repository and verified initial deployment commit `a701de9` | Current state, architecture, deployment evidence/index, commitments, module map |
| 2026-07-29 | Restart the controlled ARR MCP public path | Restarted loopback MCP and fixed ngrok host; corrected exact public Host allowlisting after a diagnostic 421; public unauthorized requests now return 401 and authenticated one-tool discovery returns 200. Main upload remains disabled | Current state, E2E evidence/index, commitment, active planning record |
| 2026-07-29 | Diagnose persistent SuperAgent MCP `failed` status | Confirmed the temporary MCP and ngrok processes had exited; public `/mcp` returns `ERR_NGROK_3200 endpoint offline` despite valid DNS/TLS. The stale platform config version 33 remains a second-stage issue after reachability is restored | Current state, E2E evidence/index, commitment, active planning record |

3
.project-docs/50-evidence/evidence-index.md
View File

@@ -4,7 +4,8 @@ Use this index for searchable, traceable evidence records.
| Date | Topic | Status | Source | Detail |
|---|---|---|---|---|
| 2026-07-29 | Controlled public deployment repository | Active until server E2E | [Evidence topic](topics/2026-07-29-public-deployment-repository.md) | Deployment entry explicitly enables XML processing behind Caddy HTTPS/Basic Auth; 259 tests and snapshot safety checks pass, but Docker/public runtime awaits the user's server. |
| 2026-07-29 | Local XML upload runtime re-enabled | Active until local restart/config change | [Evidence topic](topics/2026-07-29-local-xml-upload-runtime-reenabled.md) | The old launchd process omitted `--enable-processing`; its controlled launcher was corrected and restarted, health now reports database/processing ready, and the XML chooser is enabled without submitting a file. |
| 2026-07-29 | Controlled public deployment repository | Active until server E2E | [Evidence topic](topics/2026-07-29-public-deployment-repository.md) | Dockerfile default CMD and Compose explicitly enable XML processing while source CLI/runtime readiness remain fail-closed; 260 tests pass with 2 skips, but the refreshed image and public runtime still require server verification. |
| 2026-07-29 | Live synthetic XML upload vertical slice | Active blocker | [Evidence topic](topics/2026-07-29-live-synthetic-xml-vertical-slice.md) | Public MCP reachability and one-tool discovery are restored; stale SuperAgent config version 33 must now be refreshed before the next commit test. |
## When To Add Evidence

36
.project-docs/50-evidence/topics/2026-07-29-local-xml-upload-runtime-reenabled.md Normal file
View File

@@ -0,0 +1,36 @@
# Evidence Topic: Local XML upload runtime re-enabled
## Metadata
- Date: 2026-07-29
- Status: Active
- Scope: Current local Web process on port 8765
- Confidence: Fact
- Source: launchd/process inspection, health response and in-app browser DOM inspection
- Last verified: 2026-07-29
- Stale trigger: Restart or reconfiguration of `com.chillishark.opera-arr-report`, route/Keychain changes, or replacement of the 8765 Web process
## Question
Why was ARR.XML upload disabled in the currently running page, and is it actually enabled after correction?
## Evidence
- Before correction, launchd PID 70702 ran `arr_web.run` with database, Agent writeback, monthly and company-report flags but omitted `--enable-processing`.
- The pre-correction health response was HTTP 200 with `database_ready=true` and `processing_ready=false`.
- The controlled launcher `/Users/chillishark/温德姆AR/start-lan.command` already loaded the private route configuration and Keychain-backed runtime credentials; only the final processing flag was missing.
- After adding `--enable-processing` and restarting label `com.chillishark.opera-arr-report`, PID 50730 runs with that flag and health reports both `database_ready=true` and `processing_ready=true`.
- The refreshed page exposes one XML input accepting `.xml`, `text/xml` and `application/xml`; it is enabled, the dropzone is not disabled and the service hint is empty. The process button remains disabled until a file is selected, as designed.
- No XML file was selected or submitted during this verification.
## Finding
The upload was disabled because the long-running local launcher omitted the explicit processing feature flag. The corrected process has passed both the runtime readiness gate and the page-level control check.
## Impact
The user can now select ARR.XML on the current local page. A real end-to-end result still requires SuperAgent to call the published MCP tool and an MCP `committed`/`already_committed` receipt; merely selecting or dispatching the file is not a database success signal.
## Risk
The local launchd service remains bound to `0.0.0.0:8765`. Enabling upload therefore exposes a mutation surface to the reachable LAN; use only on a trusted network and move formal testing behind the operator-managed authenticated public boundary.

13
.project-docs/50-evidence/topics/2026-07-29-public-deployment-repository.md
View File

@@ -12,29 +12,30 @@
## Question
Does the publishable source snapshot open XML processing through an explicit authenticated HTTPS deployment entry without exposing local state, credentials or unfinished report claims?
Does the publishable source snapshot open XML processing through both supported container launch paths without exposing local state, credentials or unfinished report claims?
## Evidence
- Files: `Dockerfile`, `compose.yaml`, `deploy/Caddyfile`, `deploy/.env.production.example`, `deploy/README.md`, `arr_web/app.py`, `arr_web/run.py`, `tests/test_arr_web.py`.
- Git: initial deployment snapshot commit `a701de9f0eff7402fe1785c3b35de5652576152a` was pushed to `origin/main`; an independent `ls-remote` check is required after the documentation closeout commit as the final publication proof.
- Deployment command inspection: Compose Web command contains `--enable-processing` and `--secure-cookies`; only Caddy maps host ports 80/443, Web and MCP use internal `expose` ports.
- Tests: Python 3.12 full discovery ran 259 tests successfully; 2 environment-dependent tests were skipped.
- Deployment command inspection: Dockerfile default Web CMD and Compose Web command both contain `--enable-processing`; Compose also contains `--secure-cookies`. Only Caddy maps host ports 80/443 in the documented Compose topology, while Web and MCP use internal `expose` ports.
- Regression: `tests/test_deployment_entrypoints.py` parses the Dockerfile JSON CMD, requires `--enable-processing`, and rejects accidental enablement of monthly, company-report or legacy Agent-writeback mutations.
- Tests: Python 3.12 full discovery ran 260 tests successfully; 2 environment-dependent artifact-tool tests were skipped.
- Integrity: every entry in `CHECKSUMS.sha256` passed and 10 JSON contracts parsed.
- Snapshot audit: 271 final candidate files, about 2.0 MiB, zero files over 1 MiB, zero symlinks, eight ZIP/XLSX archives inspected and zero detected secret/private-endpoint hits after documented placeholder allowlisting.
- Configuration: Compose YAML parsed and assertions confirmed both required Web flags. Docker/Caddy executables are absent locally, so no image build or public TLS runtime result is claimed.
## Finding
The repository snapshot provides a fail-closed deployment profile that opens XML upload only when the database, guarded OSS and SuperAgent processing runtime initialize. Web traffic is protected by Caddy HTTPS plus Basic Auth, MCP traffic retains application bearer authentication, and application defaults remain closed outside this profile.
The repository snapshot now makes direct Docker-image launches and Compose launches consistent: both request XML processing, while the source CLI remains default-closed and the page opens upload only after the database, guarded OSS, SuperAgent and HMAC runtime initialize. The documented Compose topology protects Web traffic with Caddy HTTPS plus Basic Auth, and MCP retains application bearer authentication.
## Impact
The next test should use the stable deployed domains, not the temporary ngrok endpoint. `processing_ready=true` is a deployment prerequisite, but business completion still requires SuperAgent tool rediscovery and an MCP `committed`/`already_committed` receipt with matching database facts.
The server must rebuild/redeploy the image; a platform-level CMD override must retain `--enable-processing`. `processing_ready=true` remains the deployment prerequisite, but business completion still requires SuperAgent tool rediscovery and an MCP `committed`/`already_committed` receipt with matching database facts.
## Open Items
- Build and start the containers on the public Linux server; verify DNS, ACME, health and logs.
- Rebuild and start the latest containers on the public Linux server; verify that `/api/health` reports both `database_ready=true` and `processing_ready=true`.
- Rebind and republish the SuperAgent MCP configuration against the stable MCP domain.
- Execute one no-PII XML end-to-end commit test.
- Implement automatic post-commit monthly dispatch and the required `TOTAL PRICE` formula in separately authorized work.

23
.project-docs/60-reflection/cases/2026-07-29-verify-all-container-entrypoints.md Normal file
View File

@@ -0,0 +1,23 @@
# Verify every production container entrypoint
## Trigger
The deployment snapshot explicitly enabled XML processing in the Compose Web command,
but the Dockerfile default CMD omitted `--enable-processing`. A platform that built and
ran the image directly therefore served the page with processing disabled even when all
runtime environment values were present.
## Lesson
A deployment feature flag is not verified merely because one orchestrator profile
contains it. Every supported executable entrypoint must agree: image CMD, Compose
command and any documented platform override. Runtime readiness remains a separate
gate and must not be replaced by a static flag assertion.
## Action
- Parse the Dockerfile CMD in an automated test and require the intended processing flag.
- Assert that unrelated mutation flags remain absent.
- Keep the source CLI default closed and require `/api/health` to report
`processing_ready=true` after deployment.
- Tell operators that replacing CMD/command also replaces the feature flag.

1
.project-docs/60-reflection/reflection-index.md
View File

@@ -4,6 +4,7 @@ Use this index for second-order workflow lessons.
| Date | Reflection | Trigger | Action | Detail |
|---|---|---|---|---|
| 2026-07-29 | Verify every production container entrypoint | XML processing was enabled in Compose but omitted from Dockerfile CMD, so direct image launches stayed closed | Add a regression test for Dockerfile CMD and document platform command overrides | [Case](cases/2026-07-29-verify-all-container-entrypoints.md) |
| 2026-07-29 | Remote Agent success is not a database commit | Repeated live runs ended remotely without an MCP submission | Add a multi-signal acceptance gate and preserve failed-run cleanup evidence | [Case](cases/2026-07-29-remote-success-is-not-a-database-commit.md) |
| 2026-07-29 | Internal parameters are not user inputs | Human correction of the monthly-report workflow | Update docs and promote the boundary to ADR-001 | [Case](cases/2026-07-29-internal-parameters-are-not-user-inputs.md) |