98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# Workspace Install Docs Fixture Self-Containment — Design
|
|
|
|
**Date:** 2026-08-20
|
|
|
|
**Status:** Approved for implementation
|
|
|
|
## Purpose
|
|
|
|
Restore the documented direct invocation of `scripts/verify-workspace-install-docs.sh` so it passes
|
|
in a clean environment without inheriting `TMPDIR` or `THT_AUTH_CONFIG_ROOT` from the operator.
|
|
The verifier must prove that its generated local/server installation fixtures are complete by
|
|
themselves.
|
|
|
|
## Observed regression
|
|
|
|
Two independent gaps stop the current `--fixtures-only` path:
|
|
|
|
1. several `mktemp` calls expand `TMPDIR` under `set -u` without a default;
|
|
2. the authentication lifecycle commit made `THT_AUTH_CONFIG_ROOT` mandatory in `compose.yaml`,
|
|
while the local, server, and canonical Compose fixture environments still omit it.
|
|
|
|
The failure is unrelated to the PSD checklist commits. Supplying both values externally makes the
|
|
entire fixture suite pass, which confirms the missing-input boundary but is not an acceptable
|
|
long-term workaround.
|
|
|
|
## Scope
|
|
|
|
Modify only:
|
|
|
|
- `scripts/verify-workspace-install-docs.sh`
|
|
- `scripts/test-verify-workspace-install-docs.sh`
|
|
|
|
Do not modify Compose, authentication runtime code, documentation examples, the PSD server, Docker
|
|
resources, or the legacy stack.
|
|
|
|
## Required behavior
|
|
|
|
### Temporary directory contract
|
|
|
|
Every `mktemp` call in the production verifier must use `/tmp` when `TMPDIR` is absent. An explicitly
|
|
provided `TMPDIR` remains supported. The verifier must not mutate or export the caller's environment.
|
|
|
|
### Authentication fixture contract
|
|
|
|
Each Compose-rendering fixture owns a distinct authentication configuration directory inside its
|
|
fixture root:
|
|
|
|
- local installation example fixture;
|
|
- server installation example fixture;
|
|
- canonical local/server Compose fixture.
|
|
|
|
Each generated fixture environment sets `THT_AUTH_CONFIG_ROOT` to that directory. The directory is
|
|
created before Compose rendering and contains no real credential. Tests assert that the rendered
|
|
core service mounts the expected source at `/run/thothii-auth` read-only, so an ambient host value
|
|
cannot mask an incomplete fixture.
|
|
|
|
### Regression-test contract
|
|
|
|
The test runner invokes the production `--fixtures-only` verifier with both `TMPDIR` and
|
|
`THT_AUTH_CONFIG_ROOT` explicitly absent. This test must fail on the current source for the observed
|
|
reason and pass only after both self-containment gaps are fixed.
|
|
|
|
## TDD sequence
|
|
|
|
1. Change only the test runner so it removes both variables for the production-verifier call.
|
|
2. Run the focused test and retain the expected RED result.
|
|
3. Add the `/tmp` fallback to the production verifier; rerun and confirm the remaining RED result is
|
|
the missing auth root.
|
|
4. Add fixture-owned auth directories, environment entries, and rendered-mount assertions.
|
|
5. Run the focused test and direct clean-environment verifier to GREEN.
|
|
6. Run shell syntax checks, documentation smoke checks, and `git diff --check`.
|
|
|
|
## Failure handling
|
|
|
|
- A missing fixture auth directory or environment entry fails before a PASS is printed.
|
|
- A rendered auth mount with the wrong source, target, or read-only flag fails the fixture.
|
|
- A scanner or Compose error remains an error; it is not reclassified as an expected negative.
|
|
- Temporary fixture cleanup remains bounded to paths created by `mktemp`.
|
|
|
|
## Acceptance
|
|
|
|
All of the following must pass from the repository root:
|
|
|
|
```bash
|
|
env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
|
|
bash scripts/verify-workspace-install-docs.sh --fixtures-only
|
|
|
|
env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
|
|
bash scripts/test-verify-workspace-install-docs.sh
|
|
|
|
bash -n scripts/verify-workspace-install-docs.sh
|
|
bash -n scripts/test-verify-workspace-install-docs.sh
|
|
bash scripts/auth-docs-smoke.sh
|
|
git diff --check
|
|
```
|
|
|
|
No acceptance command starts, stops, reloads, builds, or otherwise mutates the PSD server stack.
|