diff --git a/.claude/skills/clean-env/SKILL.md b/.claude/skills/clean-env/SKILL.md index 498d3fdeb..ffa33b49c 100644 --- a/.claude/skills/clean-env/SKILL.md +++ b/.claude/skills/clean-env/SKILL.md @@ -5,14 +5,18 @@ description: Reset the OpenRegister development environment (stop, remove volume # Clean Environment -Run the `clean-env.sh` script to fully reset the OpenRegister development environment. +Reset the Conduction dev instance and bring it back up healthy. -This will: -1. Stop all containers from the OpenRegister docker-compose -2. Remove all containers and volumes (full data reset) -3. Start containers fresh -4. Wait for Nextcloud to become ready -5. Install core apps: openregister, opencatalogi, softwarecatalog, nldesign, mydash +> **This skill used to name a script that does not exist.** It said to run +> `bash .claude/scripts/clean-env.sh`; there is no such file in this repo or in +> any app checkout, and there never was one to find. Its documented app list was +> five entries long (`openregister opencatalogi softwarecatalog nldesign +> launchpad`) at a time when the fleet was twenty-one and three of those five +> names were app *directories* rather than app ids. Anyone following it got a +> "command not found" if they were lucky and a half-configured instance if they +> improvised past it. The real, maintained entry point is +> `.github/dev-up.sh` — it is the one place that knows about the mounts, the +> vendored PHP dependencies and the frontend bundles. **Model check — only apply when this skill is run standalone. Skip this section entirely if this skill was called from within another skill — the calling skill is responsible for model selection.** @@ -27,22 +31,70 @@ This will: ## Instructions -Run the clean-env script: +Work from the workspace root (the directory holding `.github/` and the app +checkouts as siblings). + +### Restart and heal — the common case + +Most "my environment is broken" reports need only this. It re-establishes +partial mounts, clears maintenance mode, runs pending migrations, installs any +missing `vendor/`, enables every mounted Conduction app and reports any app +whose frontend bundle would render blank: + +```bash +bash .github/dev-up.sh +``` + +### Full reset — destructive + +**This deletes the database and every volume.** Only run it when a full reset is +actually intended; `dev-up.sh` alone fixes most breakage. ```bash -bash .claude/scripts/clean-env.sh +docker compose -p openregister -f .github/docker-compose.yml down -v +bash .github/dev-up.sh ``` -**Important:** This is a destructive operation — it removes all database data and volumes. Only run when a full reset is intended. +## Verifying -After the script completes, verify the environment: -1. Check that Nextcloud is accessible at http://nextcloud.local -2. Log in with admin/admin -3. Confirm apps are listed and enabled +`dev-up.sh` ends in a status block — read it rather than assuming success: + +- `needsDbUpgrade: false` — an instance stuck at `true` serves a 503 the moment + anything trips maintenance mode. +- `apps visible: N/N` — a shortfall is named per app, and it says whether the + cause is an empty checkout (clone it) or a mount that did not attach. +- `apps enabled:` plus any `⚠` lines. **A `⚠ … need a frontend rebuild` line + means those apps are enabled and still render a blank page** — `occ` reports + them as perfectly healthy. Run the `npm ci && npm run build` command the + script prints for each one. + +Then open http://localhost:8080 (admin/admin) and confirm the apps appear in the +app menu. + +## If an app still fails to enable + +`dev-up.sh` prints the actual `occ` error per app; act on that rather than +retrying. The two failures that recur: + +- **`Class "…" not found`** — the app's `vendor/` is missing or half-installed. + `(cd && composer install --no-dev --ignore-platform-reqs)`. If + composer dies on `Could not delete …/vendor/…`, the tree contains root-owned + files from a container-side composer run; `dev-up.sh` heals that on its next + run. +- **`SKIP — empty checkout`** — the directory is mounted but empty. Clone + the repo into it, or drop its mount from `.github/docker-compose.yml`. + +To enable one by hand (note `-u www-data` — without it `occ` runs as root and +refuses): -If any app fails to enable, try running manually: ```bash -docker exec nextcloud php occ app-enable +docker exec -u www-data nextcloud php occ app:enable ``` +Use the app **id** (`integriq`, `filinq`, `dossiq`, `stackiq`, `keepiq`, +`larpinq`, `learniq`, `decidiq`, `buildiq`, `humaniq`), not the checkout +directory name (`openconnector`, `docudesk`, `procest`, …). The id is the `` +in `appinfo/info.xml`; a wrong name is not an error you will notice, because +`occ app:enable` on an unknown app just does nothing useful. + > 💡 If you switched models to run this command, don't forget to switch back to your preferred model with `/model ` (e.g. `/model default` or `/model sonnet`). diff --git a/.claude/skills/clean-env/examples/expected-output.md b/.claude/skills/clean-env/examples/expected-output.md index a7bd55386..28b59aae7 100644 --- a/.claude/skills/clean-env/examples/expected-output.md +++ b/.claude/skills/clean-env/examples/expected-output.md @@ -1,64 +1,85 @@ - + # Expected Output: clean-env +Captured from a real run on 2026-08-27, not written from memory. The previous +version of this file showed a script that does not exist writing "✓ All apps +installed" against five app names, at a URL (`http://nextcloud.local`) the +instance does not serve — an example nobody could ever have produced. + ## Successful run ``` -$ bash .claude/scripts/clean-env.sh - -[clean-env] Stopping containers... -Stopping nextcloud ... done -Stopping nextcloud_db ... done -✓ Containers stopped +$ bash .github/dev-up.sh -[clean-env] Removing containers and volumes... -Removing nextcloud ... done -Removing nextcloud_db ... done -Removing volume nextcloud_nextcloud_data ... done -Removing volume nextcloud_db_data ... done -✓ Containers and volumes removed +==> Starting stack (project=openregister) +==> Waiting for the DB +==> Waiting for all 36 app mounts inside the container + only 34/36 app dirs visible + collectives: EMPTY CHECKOUT at openregister/custom_apps/collectives -- clone it or drop its mount; restarting cannot help + zaakafhandelapp: EMPTY CHECKOUT at zaakafhandelapp -- clone it or drop its mount; restarting cannot help + every missing dir is an empty checkout, not a mount failure -- not restarting +==> Ensuring un-busted assets are not cached for 6 months + ok +==> Ensuring custom_apps is writable by www-data + ok +==> Clearing maintenance mode +==> Reconciling pending app upgrades (only if needed) + no upgrade needed +==> Healing PHP dependencies (vendor/) + stackiq: no vendor/autoload.php -- installing + ok +==> Ensuring Conduction apps are enabled + enabling keepiq (disabled) + ok + enabling integriq (disabled) + ok + enabling stackiq (disabled) + ok + SKIP zaakafhandelapp -- empty checkout at ../zaakafhandelapp (nothing to enable) +==> Re-reconciling upgrades (enabling an app can register a migration) + no upgrade needed +==> Checking frontend bundles match the app id + ok +==> Done. Status: + - installed: true + - version: 34.0.0.12 + - maintenance: false + - needsDbUpgrade: false + apps visible: 34/36 + apps enabled: 71 + UI: http://localhost:8080 (admin/admin) +``` -[clean-env] Starting fresh containers... -Creating network "openregister_default" with the default driver -Creating volume "nextcloud_db_data" ... done -Creating volume "nextcloud_nextcloud_data" ... done -Creating nextcloud_db ... done -Creating nextcloud ... done -✓ Containers started +## What a problem looks like -[clean-env] Waiting for Nextcloud to become ready... -.......... -✓ Nextcloud is ready at http://nextcloud.local +The script does not hide these; read to the end of the output. -[clean-env] Installing apps... -openregister installed and enabled. -opencatalogi installed and enabled. -softwarecatalog installed and enabled. -nldesign installed and enabled. -mydash installed and enabled. -✓ All apps installed +An app that is enabled and would still render a blank page — `occ` calls this +app perfectly healthy, so this section is the only thing that reports it: -[clean-env] Done! Environment is clean and ready. +``` +==> Checking frontend bundles match the app id + integriq: js/integriq-main.js missing (found openconnector-main.js -- stale, pre-rename) + fix: (cd ../openconnector && npm ci && npm run build) +... + ⚠ 5 app(s) need a frontend rebuild before their page renders ``` -## Post-script verification +An app that refused to enable, with the reason rather than a shrug: ``` -✅ Nextcloud accessible at http://nextcloud.local -✅ Logged in with admin/admin -✅ Apps enabled and active: - - openregister ✓ - - opencatalogi ✓ - - softwarecatalog ✓ - - nldesign ✓ - - mydash ✓ + enabling keepiq (disabled) + FAILED: An unhandled exception has been thrown: Error: Class "Ramsey\Uuid\Uuid" not found in …/keepiq/lib/Repair/SeedSecretTypes.php:115 + 1 app(s) could not be enabled -- see the errors above ``` -## If an app fails to enable +The stack failing to start at all — note that a **public** image answers +`denied: denied` when the local ghcr.io credential has expired, so the script +logs out and retries once before believing it: -```bash -# Re-enable manually: -docker exec nextcloud php occ app:enable openregister -docker exec nextcloud php occ app:enable opencatalogi +``` +==> Starting stack (project=openregister) + Error response from daemon: Head "https://ghcr.io/v2/conductionnl/n8n-nextcloud/manifests/latest": denied: denied + ghcr.io denied a pull -- logging out (credentials may be stale) and retrying once ```