From bbf1681ff69ce4982f199c115c526a9b8ce013d8 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 7 Jul 2026 13:04:20 +0200 Subject: [PATCH] Sync wiki from project files --- Repo-docs-MODULE-ARCHITECTURE.md | 25 +++++++++++++++++++++---- Repo-docs-RELEASE-DEPENDENCIES.md | 22 ++++++++++++++++++---- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index cc516be..4ba9181 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -403,14 +403,20 @@ The package install-plan API records operator intent only: - `GET /api/v1/admin/system/modules/install-runs/{run_id}` returns the raw run record for diagnosis. - `GET /api/v1/admin/system/modules/install-requests` returns daemon handoff - requests queued from the admin UI or CLI. + requests queued from the admin UI or CLI plus the current daemon heartbeat. - `POST /api/v1/admin/system/modules/install-requests` queues a supervised installer request. It requires maintenance mode and maintenance access. The FastAPI request writes only the request record; it does not run package commands. +- `POST /api/v1/admin/system/modules/install-requests/{request_id}/cancel` + cancels a queued request. Running requests are not interrupted by the API; + they remain owned by the installer daemon. +- `POST /api/v1/admin/system/modules/install-requests/{request_id}/retry` + queues a new request using the options from a failed or cancelled request. - `GET /api/v1/admin/system/modules/package-catalog` reads approved package references from `GOVOPLAN_MODULE_PACKAGE_CATALOG` so operators can add known - module refs to the install plan without typing them manually. + module refs to the install plan without typing them manually. The endpoint + also reports catalog validity and the configured path. - `PUT /api/v1/admin/system/modules/install-plan` saves planned install or uninstall rows. Install rows must use tagged package or git references, not local `file:`/workspace paths. Python install rows must also include the @@ -435,9 +441,16 @@ The package install-plan API records operator intent only: runtime request queue, claims one request at a time, and executes the same supervised installer flow. `--daemon-once` processes at most one queued request and exits, which is useful for tests or process-manager one-shot - units. + units. The daemon writes `daemon.status.json` under the installer runtime + directory so the admin UI and CLI can report heartbeat/status. - `govoplan-module-installer --enqueue-supervised` creates the same request record from a shell instead of from the admin UI. +- `govoplan-module-installer --daemon-status --format json` reports the daemon + heartbeat. `--cancel-request ` and `--retry-request ` + provide shell equivalents for the admin UI request controls. +- `govoplan-module-installer --validate-package-catalog [path] --format json` + validates a catalog file or the catalog configured through + `GOVOPLAN_MODULE_PACKAGE_CATALOG`. - `govoplan-module-installer --rollback ` restores the saved package snapshots, restores the captured SQLite or external database snapshot when present, and reruns package installation from the previous freeze file. @@ -468,6 +481,10 @@ The installer preflight is intentionally conservative: - uninstalling a module with active/desired dependents is blocked; - uninstalling a module that owns migrations is blocked until that module explicitly supports migration retirement; +- modules that declare migration retirement support should also register a + retirement provider. Without a provider, preflight emits a manual-review + warning. Providers may return blockers, warnings, and an explanatory summary, + but core does not drop schema or data on behalf of modules. - module-owned uninstall guard providers can veto data/migration/worker unsafe removals; - install refs must be exact versions or tagged git refs; diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index e3a1252..ae2af1a 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`. > Origin: `repository`. @@ -95,7 +95,12 @@ govoplan-module-installer \ Admin > System > Modules can then queue the saved install plan as a supervised request. The daemon claims one queued request at a time and writes request/run records below `runtime/module-installer`. For process-manager one-shot usage or -tests, use `--daemon-once`. +tests, use `--daemon-once`. The daemon also writes +`runtime/module-installer/daemon.status.json`; check it with: + +```bash +govoplan-module-installer --daemon-status --format json +``` The installer uses a runtime lock, snapshots `pip freeze` plus WebUI `package.json`/`package-lock.json`, writes a run record below @@ -159,13 +164,19 @@ govoplan-module-installer --show-run --format json govoplan-module-installer --lock-status --format json govoplan-module-installer --list-requests --format json govoplan-module-installer --show-request --format json +govoplan-module-installer --cancel-request --format json +govoplan-module-installer --retry-request --format json ``` Package catalogs are file-backed. Set `GOVOPLAN_MODULE_PACKAGE_CATALOG` to a JSON file matching `docs/module-package-catalog.example.json`; the admin UI will show those entries and can add them to the install plan. This keeps the release approval decision outside the running server while avoiding hand-typed package -refs. +refs. Validate the catalog before handing it to operators: + +```bash +govoplan-module-installer --validate-package-catalog docs/module-package-catalog.example.json --format json +``` Install rows must use tagged package/git refs or registry packages, not local `file:` or workspace links. WebUI package changes still require `npm install` @@ -179,7 +190,10 @@ providers. Preflight blocks incompatible manifest contracts/core versions and lets module-owned guards veto package removal when data, migrations, workers, or schedulers would make uninstall unsafe. Modules that own migrations are treated as non-retirable by default, so package uninstall is blocked unless the manifest -explicitly declares migration retirement support. +explicitly declares migration retirement support. A migration-owning module that +does declare retirement support should register a retirement provider; otherwise +preflight emits a manual-review warning instead of pretending schema/data +retirement is automated. ## WebUI