329 lines
8.1 KiB
Markdown
329 lines
8.1 KiB
Markdown
# Scripts Reference
|
|
|
|
This folder contains PowerShell wrappers for repeatable local development, build, publish, and cache operations.
|
|
|
|
## Scope
|
|
|
|
These scripts target the repository rooted at `E:\stansshit\csharp\journal-master\journal`.
|
|
|
|
## Requirements
|
|
|
|
- PowerShell 7+ (`pwsh` recommended)
|
|
- .NET SDK (current repo uses `net10.0` targets)
|
|
- Python (for `pip-min.ps1`, `migration-gate.ps1`)
|
|
- Node.js + npm (for `publish-app.ps1`)
|
|
|
|
## Execution Policy
|
|
|
|
If script execution is blocked on Windows, run commands with one of:
|
|
|
|
```powershell
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\<script>.ps1
|
|
```
|
|
|
|
or in-session:
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process Bypass
|
|
```
|
|
|
|
## Script Overview
|
|
|
|
| Script | Purpose |
|
|
|---|---|
|
|
| `dev-shell.ps1` | Initializes current shell with repo-local .NET/pip/HuggingFace cache env vars. |
|
|
| `script-common.ps1` | Shared helper functions used by most scripts. |
|
|
| `dotnet-min.ps1` | Minimal `dotnet` wrapper with local NuGet cache and safe defaults. |
|
|
| `pip-min.ps1` | Minimal `pip` wrapper with repo-local target/cache and Windows compatibility mapping. |
|
|
| `pip_safe.py` | Python wrapper used by `pip-min.ps1` to patch temporary-directory behavior. |
|
|
| `publish-app.ps1` | Builds frontend web bundle or Tauri desktop app. |
|
|
| `publish-sidecar.ps1` | Publishes `Journal.Sidecar` single-file executable to `output/`. |
|
|
| `publish-webgateway.ps1` | Publishes `Journal.WebGateway` and optionally copies web assets into `wwwroot`. |
|
|
| `run-webgateway.ps1` | Runs `Journal.WebGateway` with configurable URLs and project root. |
|
|
| `migration-gate.ps1` | End-to-end migration/parity gate (build + smoke/parity/API checks). |
|
|
| `nuget-export-cache.ps1` | Primes and exports `.nuget` cache to zip for transfer. |
|
|
| `nuget-import-cache.ps1` | Imports exported cache zip and validates restore. |
|
|
|
|
## Common Patterns Used Across Scripts
|
|
|
|
- Proxy cleanup: `Clear-JournalProxyEnv`
|
|
- Repo root detection: `Resolve-JournalRepoRoot`
|
|
- Repo-local caches:
|
|
- `.dotnet_home`
|
|
- `.nuget\packages`
|
|
- `.nuget\http-cache`
|
|
- `.pip\cache`
|
|
- `.tmp\*`
|
|
- `.npm\cache`
|
|
|
|
## Detailed Reference
|
|
|
|
### `dev-shell.ps1`
|
|
|
|
Dot-source this script to configure your *current shell*.
|
|
|
|
```powershell
|
|
. .\scripts\dev-shell.ps1
|
|
```
|
|
|
|
What it does:
|
|
|
|
- loads `script-common.ps1`
|
|
- resolves repo root
|
|
- clears proxy env vars
|
|
- initializes repo-local .NET, pip, and HuggingFace env vars
|
|
|
|
Use this once per shell session before running development commands manually.
|
|
|
|
### `script-common.ps1`
|
|
|
|
Shared helper functions:
|
|
|
|
- `Clear-JournalProxyEnv`
|
|
- `Resolve-JournalRepoRoot`
|
|
- `Initialize-JournalDotnetEnv`
|
|
- `Initialize-JournalPipEnv`
|
|
- `Initialize-JournalHuggingFaceEnv`
|
|
- `Resolve-JournalSidecarProjectPath`
|
|
- `Resolve-JournalAppRoot`
|
|
- `Resolve-JournalWebGatewayProjectPath`
|
|
|
|
Also supports optional override:
|
|
|
|
- `JOURNAL_REPO_ROOT`
|
|
|
|
### `dotnet-min.ps1`
|
|
|
|
Wrapper around `dotnet` with resilient restore/build defaults.
|
|
|
|
Usage:
|
|
|
|
```powershell
|
|
.\scripts\dotnet-min.ps1 <dotnet args>
|
|
```
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
.\scripts\dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj
|
|
.\scripts\dotnet-min.ps1 restore Journal.WebGateway/Journal.WebGateway.csproj
|
|
.\scripts\dotnet-min.ps1 run --project Journal.Sidecar/Journal.Sidecar.csproj
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- sets repo-local `DOTNET_CLI_HOME` and NuGet cache paths
|
|
- clears proxy env vars
|
|
- adds for common commands (`restore`, `build`, `run`, `test`, `publish`, `pack`):
|
|
- `-p:RestoreIgnoreFailedSources=true`
|
|
- `-p:NuGetAudit=false`
|
|
- for `restore`, also adds `--ignore-failed-sources`
|
|
|
|
### `pip-min.ps1`
|
|
|
|
Wrapper around `python -m pip` focused on constrained hosts.
|
|
|
|
Usage:
|
|
|
|
```powershell
|
|
.\scripts\pip-min.ps1 <pip args>
|
|
```
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
.\scripts\pip-min.ps1 install requests
|
|
.\scripts\pip-min.ps1 install --index-url https://pypi.org/simple faster-whisper
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- initializes repo-local pip cache/temp paths
|
|
- clears proxy env vars
|
|
- for `install` without target/prefix:
|
|
- strips `--user`
|
|
- installs into `.pydeps\py314`
|
|
- on Windows, maps `pyaudio` to `pyaudiowpatch`
|
|
- uses `pip_safe.py` if present
|
|
|
|
### `pip_safe.py`
|
|
|
|
Compatibility wrapper for pip on some Windows + Python 3.14 setups.
|
|
|
|
Behavior:
|
|
|
|
- monkey-patches `tempfile.mkdtemp` to create writable temp directories (`0o777`)
|
|
- then forwards to pip internal CLI
|
|
|
|
### `publish-app.ps1`
|
|
|
|
Builds the frontend (`web`) or Tauri desktop app (`tauri`).
|
|
|
|
Parameters:
|
|
|
|
- `-Target web|tauri` (default `web`)
|
|
- `-Configuration Release|Debug` (default `Release`)
|
|
- `-TauriBundles none|nsis|msi` (default `none`)
|
|
- `-InstallDeps`
|
|
- `-SkipInstall`
|
|
- `-DryRun`
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
.\scripts\publish-app.ps1 -Target web
|
|
.\scripts\publish-app.ps1 -Target tauri -TauriBundles none
|
|
.\scripts\publish-app.ps1 -Target tauri -TauriBundles nsis
|
|
```
|
|
|
|
Notes:
|
|
|
|
- uses repo-local npm cache/temp paths
|
|
- `-TauriBundles none` maps to `tauri build --no-bundle` (raw exe build)
|
|
- expected web output: `Journal.App\build`
|
|
- expected tauri exe location: `Journal.App\src-tauri\target\release\journalapp.exe` (Release)
|
|
|
|
### `publish-sidecar.ps1`
|
|
|
|
Publishes `Journal.Sidecar` as a self-contained single-file executable.
|
|
|
|
Parameters:
|
|
|
|
- `-Configuration` (default `Release`)
|
|
- `-Runtime` (default `win-x64`)
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
.\scripts\publish-sidecar.ps1 -Configuration Release -Runtime win-x64
|
|
```
|
|
|
|
Output:
|
|
|
|
- `output\Journal.Sidecar.exe` (for Windows runtime)
|
|
|
|
### `publish-webgateway.ps1`
|
|
|
|
Publishes `Journal.WebGateway` and optionally embeds built web assets.
|
|
|
|
Parameters:
|
|
|
|
- `-Configuration Release|Debug` (default `Release`)
|
|
- `-Runtime` (default `win-x64`)
|
|
- `-SelfContained` (switch)
|
|
- `-SkipWebAssets` (switch)
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
.\scripts\publish-app.ps1 -Target web
|
|
.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64
|
|
```
|
|
|
|
Output:
|
|
|
|
- `output\webgateway\`
|
|
- optional `output\webgateway\wwwroot\` from `Journal.App\build`
|
|
|
|
### `run-webgateway.ps1`
|
|
|
|
Runs `Journal.WebGateway` directly with controlled environment.
|
|
|
|
Parameters:
|
|
|
|
- `-Configuration Release|Debug` (default `Release`)
|
|
- `-Urls` (default `http://0.0.0.0:5180`)
|
|
- `-ProjectRoot` (optional; if omitted, repo root)
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
.\scripts\run-webgateway.ps1
|
|
.\scripts\run-webgateway.ps1 -Urls http://127.0.0.1:5180
|
|
.\scripts\run-webgateway.ps1 -ProjectRoot E:\stansshit\csharp\journal-master\journal
|
|
```
|
|
|
|
Notes:
|
|
|
|
- sets `JOURNAL_PROJECT_ROOT` for the gateway process
|
|
- useful when multiple repo clones exist and you need deterministic data/vault paths
|
|
|
|
### `migration-gate.ps1`
|
|
|
|
Runs migration quality gate.
|
|
|
|
Parameters:
|
|
|
|
- `-SkipSmoke`
|
|
- `-SkipApi`
|
|
|
|
Current behavior:
|
|
|
|
1. builds `Journal.Sidecar`
|
|
2. optionally runs `Journal.SmokeTests`
|
|
3. runs Python parity harness test discovery
|
|
4. optionally runs API contract test discovery
|
|
|
|
If `tests/` is absent, Python parity and API contract steps are skipped automatically with a clear message — the sidecar build and smoke tests still run.
|
|
|
|
### `nuget-export-cache.ps1`
|
|
|
|
Primes and exports NuGet cache to zip.
|
|
|
|
Parameters:
|
|
|
|
- `-OutputZip` (default `nuget-cache-export.zip`)
|
|
- `-IncludeDotnetHome`
|
|
|
|
Behavior:
|
|
|
|
- runs restore for selected projects via `dotnet-min.ps1`
|
|
- copies `.nuget` (and optional `.dotnet_home`) to staging
|
|
- writes `nuget-cache-manifest.txt`
|
|
- outputs zip
|
|
|
|
Primes restore for `Journal.Sidecar`, `Journal.WebGateway`, and `Journal.SmokeTests`.
|
|
|
|
### `nuget-import-cache.ps1`
|
|
|
|
Imports exported cache zip and validates by restore.
|
|
|
|
Parameters:
|
|
|
|
- `-InputZip` (default `nuget-cache-export.zip`)
|
|
|
|
Behavior:
|
|
|
|
- extracts zip into repo root
|
|
- runs restore for selected projects via `dotnet-min.ps1`
|
|
|
|
Validates restore for `Journal.Sidecar`, `Journal.WebGateway`, and `Journal.SmokeTests`.
|
|
|
|
## Environment Variables Used
|
|
|
|
- `JOURNAL_REPO_ROOT` (optional override for repo detection)
|
|
- `JOURNAL_PROJECT_ROOT` (runtime project root for gateway/sidecar config)
|
|
- `DOTNET_CLI_HOME`
|
|
- `NUGET_PACKAGES`
|
|
- `NUGET_HTTP_CACHE_PATH`
|
|
- `NUGET_CERT_REVOCATION_MODE`
|
|
- `PIP_CACHE_DIR`
|
|
- `HF_HOME`
|
|
- `HUGGINGFACE_HUB_CACHE`
|
|
|
|
## Output and Cache Directories
|
|
|
|
- `output/`
|
|
- `output/webgateway/`
|
|
- `.dotnet_home/`
|
|
- `.nuget/packages/`
|
|
- `.nuget/http-cache/`
|
|
- `.npm/cache/`
|
|
- `.pip/cache/`
|
|
- `.tmp/`
|
|
- `.pydeps/`
|
|
|
|
## See Also
|
|
|
|
- [`WORKFLOWS.md`](./WORKFLOWS.md) for copy/paste command recipes.
|