ShadowsOverWestgate/sow-tools
7
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 38 Activity

Updated documentation for wrappers

Browse Source
This commit is contained in:
archvillainette
2026-05-13 20:20:15 +02:00
parent 4fd0375608
commit 14313b7ac9
1 changed files with 12 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SCRIPT_WRAPPER_CONTRACT.md
+12 -12
View File
@@ -4,11 +4,12 @@ Refactor and harden all shell wrapper scripts across the module and assets repos
Current state as of 2026-05-13: Current state as of 2026-05-13:
- Argument passthrough is largely solved for the active root wrappers. - Argument passthrough is solved for the active root wrappers.
- `module/` and `assets/` now use repo-root launchers plus - `module/` and `assets/` now use repo-root launchers plus
`scripts/run-nwn-tool.*` passthrough shims. `scripts/run-nwn-tool.*` passthrough shims.
- Wrapper regression coverage already exists in `module/tests/` and - Wrapper regression coverage already exists in `module/tests/` and
`assets/tests/`. `assets/tests/`.
- Active repo-root `.sh` and `.ps1` wrappers are intentionally thin launchers.
- The previously stale JSON-config assumption shown in this contract is no - The previously stale JSON-config assumption shown in this contract is no
longer current; active repos use `nwn-tool.yaml`. longer current; active repos use `nwn-tool.yaml`.
@@ -29,21 +30,20 @@ The current priority is:
## Current Findings ## Current Findings
The main active wrapper gap is no longer argument forwarding. The bigger gaps are The main active wrapper gap is no longer argument forwarding or root-wrapper
wrapper thickness and duplicated orchestration: thickness. The root wrappers are already thin `cd` plus `run-nwn-tool` launchers.
The remaining wrapper-adjacent thickness is release orchestration:
- `module/build-module.sh` still shells out to `config effective --json`, parses
config locally, probes script sources, resolves manifest paths, and performs
pre-build manifest refresh.
- `module/build-module.ps1` mirrors the same logic in a second implementation.
- `module/scripts/release-all.sh` and `assets/scripts/release-haks.sh` both - `module/scripts/release-all.sh` and `assets/scripts/release-haks.sh` both
parse effective config themselves and still own substantial orchestration that parse effective config themselves and still own substantial orchestration that
is not just "launch the toolkit". is not just "launch the toolkit".
- `scripts/run-nwn-tool.*` still own tool installation/update bootstrap. This is
shared repo plumbing, not build business logic.
That means the wrapper contract should now optimize for: That means the wrapper contract should now optimize for:
- a single source of truth for preflight behavior - a single source of truth for preflight behavior
- thinner root wrappers - preserving thin root wrappers
- shared repo plumbing only where toolkit ownership is not appropriate - shared repo plumbing only where toolkit ownership is not appropriate
- no duplicated config decoding logic between `.sh` and `.ps1` - no duplicated config decoding logic between `.sh` and `.ps1`
@@ -62,10 +62,10 @@ Defer unrelated wrapper-adjacent work for now:
- toolkit-owned behavior - toolkit-owned behavior
- shared repo plumbing - shared repo plumbing
- release-only orchestration - release-only orchestration
3. Move duplicated config reads and command decisions out of paired `.sh` and 3. Keep paired `.sh` and `.ps1` root wrappers thin; do not add new wrappers
`.ps1` wrappers where possible. unless a command is intentionally promoted to a user-facing entrypoint.
4. Keep root wrappers as thin launchers with transparent argument forwarding. 4. Expand regression coverage from spot checks to all active root wrappers.
5. Expand regression coverage from passthrough correctness into: 5. Continue release-entrypoint review separately:
- wrapper-side preflight behavior - wrapper-side preflight behavior
- stderr/stdout separation for JSON-producing subcommands - stderr/stdout separation for JSON-producing subcommands
- shell/PowerShell parity for any remaining unavoidable wrapper logic - shell/PowerShell parity for any remaining unavoidable wrapper logic