Extensions declare settings once and resolve typed values from Pi flags, environment variables, trusted project settings, user settings, and defaults without shared runtime imports.
This plan covers the settings helper, not the wider package migration in the spec.
Plan dependencies: none.
Delivery
flowchart LR
pilot["1. Nushell setting resolves across sources"] --> reuse["2. Second extension uses same generated helper"] --> guard["3. Generated output stays reproducible"]
declaration["Extension-owned declarations"] --> generated["Generated local helper"]
generated --> pilot
generated --> reuse
Make extensions/nushell/index.ts declare its startup setting and consume an extension-local helper generated from scripts/codegen/templates/pi-ext-settings.ts via scripts/codegen/targets.json and scripts/codegen.mjs.
Register the CLI flag before reading it; resolve per key in order: specified flag, namespaced environment variable, trusted project .pi/settings.json, user settings.json, declared default.
Pass ctx.isProjectTrusted() into SettingsManager.create and test CLI omission, valid overrides, explicit false where expressible, untrusted projects, and invalid values using extensions/nushell/__tests__/.
Migrate extensions/fast/index.ts to the same generated helper and extension-owned declaration, preserving its existing default and project-over-user behavior.
Test that generation produces no sibling runtime imports and that each extension still runs when installed independently.
Add deterministic regeneration and drift checks to the existing codegen task and tests; verify focused extension tests and checks through Mise.
Missing inputs remain distinct from false, 0, and empty strings; invalid values yield source-specific diagnostics without silently selecting a lower-priority source or printing to machine-readable stdout.
Interface contract
Each declaration specifies a settings key, value parser, default, optional CLI flag name, and optional environment variable name.
The generated helper registers supported Pi flags and resolves values at lifecycle points where both flags and project trust are available.
Pi supports only boolean and string extension flags; numeric or structured values require parsing strings.
A flag registration default must not erase the distinction between an omitted flag and a configured value.
Document precedence and invalid-value behavior at the extension boundary; do not change unrelated extension settings implicitly.
Verification
scripts/codegen/targets.json selects only participating extensions; generated helpers stay inside their owning extension.
Tests cover precedence, absence versus falsy values, invalid inputs, project trust, independent installation, and regeneration drift.
Focused Mise verification passes for migrated extensions; codegen output is reproducible.
---
id: PX-PLAN-YWSH8M_H
type: plan
title: Generated Extension-Local Settings Helper
spec: PX-SPEC-DZLVGRW4
status: approved
---
## Outcome
Extensions declare settings once and resolve typed values from Pi flags, environment variables, trusted project settings, user settings, and defaults without shared runtime imports.
This plan covers the settings helper, not the wider package migration in the spec.
Plan dependencies: none.
## Delivery
```mermaid
flowchart LR
pilot["1. Nushell setting resolves across sources"] --> reuse["2. Second extension uses same generated helper"] --> guard["3. Generated output stays reproducible"]
declaration["Extension-owned declarations"] --> generated["Generated local helper"]
generated --> pilot
generated --> reuse
```
1. Make `extensions/nushell/index.ts` declare its startup setting and consume an extension-local helper generated from `scripts/codegen/templates/pi-ext-settings.ts` via `scripts/codegen/targets.json` and `scripts/codegen.mjs`.
Register the CLI flag before reading it; resolve per key in order: specified flag, namespaced environment variable, trusted project `.pi/settings.json`, user `settings.json`, declared default.
Pass `ctx.isProjectTrusted()` into `SettingsManager.create` and test CLI omission, valid overrides, explicit false where expressible, untrusted projects, and invalid values using `extensions/nushell/__tests__/`.
2. Migrate `extensions/fast/index.ts` to the same generated helper and extension-owned declaration, preserving its existing default and project-over-user behavior.
Test that generation produces no sibling runtime imports and that each extension still runs when installed independently.
3. Add deterministic regeneration and drift checks to the existing codegen task and tests; verify focused extension tests and checks through Mise.
Missing inputs remain distinct from `false`, `0`, and empty strings; invalid values yield source-specific diagnostics without silently selecting a lower-priority source or printing to machine-readable stdout.
## Interface contract
Each declaration specifies a settings key, value parser, default, optional CLI flag name, and optional environment variable name.
The generated helper registers supported Pi flags and resolves values at lifecycle points where both flags and project trust are available.
Pi supports only boolean and string extension flags; numeric or structured values require parsing strings.
A flag registration default must not erase the distinction between an omitted flag and a configured value.
Document precedence and invalid-value behavior at the extension boundary; do not change unrelated extension settings implicitly.
## Verification
- `scripts/codegen/targets.json` selects only participating extensions; generated helpers stay inside their owning extension.
- Tests cover precedence, absence versus falsy values, invalid inputs, project trust, independent installation, and regeneration drift.
- Focused Mise verification passes for migrated extensions; codegen output is reproducible.