# Scripts (Python-first, cross-platform)

This folder now uses Python as the default runtime for orchestration and diagnostics.

## Preferred scripts

- `diag.py`: tool probing and install-plan generation (`dotnet`, `python`, `node`, `npm`, `cargo`, `tauri`)
- `build.py`: normalized build actions used by SDT workflows
- `dev_shell.py`: cross-platform shell bootstrap export/doctor helper
- `dotnet-min.py`: resilient `dotnet` wrapper with local cache env
- `pip-min.py`: resilient `pip` wrapper with local cache env and repo-local target default
- `npm-clean.py`: remove `node_modules` cross-platform
- `migration-gate.py`: build/test quality gate
- `nuget-export-cache.py`: archive `.nuget` cache
- `nuget-import-cache.py`: restore `.nuget` cache from archive
- `publish-app.py`: build web or tauri app (cross-platform)
- `publish-sidecar.py`: publish sidecar .NET service
- `publish-webgateway.py`: publish gateway .NET service and optional web assets
- `run-webgateway.py`: run gateway in dev or published-output mode
- `publish-output.py`: orchestrate sidecar/web/gateway/desktop publish steps
- `sync-output.py`: sweep newest build artifacts into `output/`
- `script_common.py`: shared helpers (repo root resolution, env shaping, command runner)
  - `project.rootHints` supports glob markers (for example `*.sln`) and directory/file markers (`.git`, `package.json`)
  - Windows PATH token expansion (`%NVM_HOME%`, `%NVM_SYMLINK%`, etc.) is applied during command resolution

## Shell bootstrap wrappers

- `dev-shell.ps1`: PowerShell wrapper over `dev_shell.py`
- `dev-shell.sh`: bash/zsh wrapper over `dev_shell.py`
- `dev-shell.cmd`: cmd wrapper over `dev_shell.py`

## Legacy scripts

Existing `.ps1` entrypoints are now compatibility wrappers that forward to Python scripts.
`script-common.ps1` is legacy-only compatibility and not used by active SDT workflows.

Original PowerShell implementations are archived under `scripts/legacy/` as `*.legacy.ps1` for reference during transition.

## Root Hint Semantics

`project.rootHints` is evaluated in this order:
1. Exact marker exists at candidate root (file or directory)
2. Root-level glob match (`glob`)
3. Recursive glob match (`rglob`)

Examples:
- `"*.sln"`
- `".git"`
- `"package.json"`
- `"src-tauri/tauri.conf.json"`

## Quick usage

```powershell
python scripts/diag.py probe --tool dotnet --json
python scripts/dotnet-min.py build
python scripts/migration-gate.py
python scripts/nuget-export-cache.py --output-zip nuget-cache-export.zip
python scripts/nuget-import-cache.py --input-zip nuget-cache-export.zip
python scripts/npm-clean.py --working-dir .
python scripts/dev_shell.py export --shell pwsh --json
python scripts/dev_shell.py doctor
```