journal/scripts/README.md

# 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

Current repository caveat:

- This clean repo currently does **not** contain `tests/` or `Journal.Api/`.
- Running full gate without matching files will fail.

### `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

Current repository caveat:

- Script references `Journal.Api/Journal.Api.csproj`.
- If `Journal.Api` is absent, export fails unless script is adjusted.

### `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`

Current repository caveat:

- Script references `Journal.Api/Journal.Api.csproj`.
- If `Journal.Api` is absent, import validation step fails unless script is adjusted.

## 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.