diff --git a/SCRIPT_WRAPPER_CONTRACT.md b/SCRIPT_WRAPPER_CONTRACT.md index 5709eca..428fc13 100644 --- a/SCRIPT_WRAPPER_CONTRACT.md +++ b/SCRIPT_WRAPPER_CONTRACT.md @@ -13,66 +13,51 @@ Current state as of 2026-05-13: - The previously stale JSON-config assumption shown in this contract is no longer current; active repos use `nwn-tool.yaml`. -## Active Scope +## Scope Status -This contract is still active, but the priority has changed. +This contract is complete for active root wrappers as of 2026-05-13. -The old priority was: +Completed: -- make `$@` / `@args` forwarding work - -The current priority is: - -- remove wrapper-side business logic that still duplicates toolkit behavior -- keep wrappers thin across shell, PowerShell, and release-entrypoint paths -- align wrapper logs and error handling with the current logging contract -- finish wrapper/tooling parity before moving deeper into wiki deployment +- root `.sh` wrappers are thin `cd` plus `scripts/run-nwn-tool.sh` launchers +- root `.ps1` wrappers are thin `scripts/run-nwn-tool.ps1` launchers +- all active root wrappers forward arbitrary arguments transparently +- shell and PowerShell wrapper regression coverage includes every active root + wrapper in `module/` and `assets/` +- stale documentation references to unsupported root wrappers were removed ## Current Findings -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: +No active root-wrapper thinning work remains. + +The scripts below are intentionally not root wrappers: - `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". + parse effective config and own release publishing orchestration. - `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: +These scripts remain acceptable under this wrapper contract because they are +release/bootstrap plumbing, not user-facing build/extract wrappers. Future +release automation cleanup should happen under release or logging contracts, not +by adding logic to root wrappers. -- a single source of truth for preflight behavior -- preserving thin root wrappers -- shared repo plumbing only where toolkit ownership is not appropriate -- no duplicated config decoding logic between `.sh` and `.ps1` +## Maintenance Rules -## Deferred Scope - -Defer unrelated wrapper-adjacent work for now: - -- model-compilation wrapper concerns -- release-announcement publication scripting -- broader asset-processing script consolidation outside wrapper ownership - -## Immediate Plan - -1. Audit every wrapper that does more than `cd` plus `exec`. -2. Classify wrapper logic into: - - toolkit-owned behavior - - shared repo plumbing - - release-only orchestration -3. Keep paired `.sh` and `.ps1` root wrappers thin; do not add new wrappers +1. 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 +2. Root wrappers must not parse config, inspect source trees, preflight build + products, or duplicate toolkit command decisions. +3. `scripts/run-nwn-tool.*` may keep tool install/update bootstrap, but must not + perform command-specific build logic. +4. Release-entrypoint orchestration belongs in release contracts; do not treat it + as a reason to thicken root wrappers. +5. If a root wrapper is added or removed, update README command lists and wrapper + contract tests in the same change. -# Problem +# Historical Problem -The current `.sh` and `.ps1` wrapper scripts do not properly forward arbitrary CLI arguments to the underlying toolkit commands. +Earlier `.sh` and `.ps1` wrapper scripts did not properly forward arbitrary CLI arguments to the underlying toolkit commands. Example: @@ -84,7 +69,7 @@ Example: - `--force` - future flags -Many wrappers only support fixed commands or partially forward arguments. +That passthrough issue is now fixed for active root wrappers. Additionally, after recent refactors — including: @@ -94,7 +79,7 @@ Additionally, after recent refactors — including: - command refactors - repository abstraction changes -— several wrapper scripts are now outdated and no longer correctly reflect the current toolkit behavior. +— several wrapper scripts became outdated and no longer correctly reflected toolkit behavior. Example of a recent error produced: @@ -121,9 +106,9 @@ Traceback (most recent call last): FileNotFoundError: [Errno 2] No such file or directory: '${HOME}/Projects/nwnee-shadowsoverwestgate/assets/nwn-tool.json' ``` -# Goal +# Completed Goal -Make all wrapper scripts: +Active root wrapper scripts are now: - consistent - argument-transparent