From 14313b7ac9f994c0a3963925317b0c5a43494719 Mon Sep 17 00:00:00 2001 From: vickydotbat Date: Wed, 13 May 2026 20:20:15 +0200 Subject: [PATCH] Updated documentation for wrappers --- SCRIPT_WRAPPER_CONTRACT.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/SCRIPT_WRAPPER_CONTRACT.md b/SCRIPT_WRAPPER_CONTRACT.md index 3d0d213..5709eca 100644 --- a/SCRIPT_WRAPPER_CONTRACT.md +++ b/SCRIPT_WRAPPER_CONTRACT.md @@ -4,11 +4,12 @@ Refactor and harden all shell wrapper scripts across the module and assets repos 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 `scripts/run-nwn-tool.*` passthrough shims. - Wrapper regression coverage already exists in `module/tests/` and `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 longer current; active repos use `nwn-tool.yaml`. @@ -29,21 +30,20 @@ The current priority is: ## Current Findings -The main active wrapper gap is no longer argument forwarding. The bigger gaps are -wrapper thickness and duplicated orchestration: +The main active wrapper gap is no longer argument forwarding or root-wrapper +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 parse effective config themselves and still own substantial orchestration that 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: - 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 - no duplicated config decoding logic between `.sh` and `.ps1` @@ -62,10 +62,10 @@ Defer unrelated wrapper-adjacent work for now: - toolkit-owned behavior - shared repo plumbing - release-only orchestration -3. Move duplicated config reads and command decisions out of paired `.sh` and - `.ps1` wrappers where possible. -4. Keep root wrappers as thin launchers with transparent argument forwarding. -5. Expand regression coverage from passthrough correctness into: +3. Keep paired `.sh` and `.ps1` root wrappers thin; do not add new wrappers + unless a command is intentionally promoted to a user-facing entrypoint. +4. Expand regression coverage from spot checks to all active root wrappers. +5. Continue release-entrypoint review separately: - wrapper-side preflight behavior - stderr/stdout separation for JSON-producing subcommands - shell/PowerShell parity for any remaining unavoidable wrapper logic