From 506aa072f61c728b3e87b3799fdcf1ed77f1c246 Mon Sep 17 00:00:00 2001
From: stan44 <stanton.e@gmail.com>
Date: Fri, 27 Feb 2026 11:11:53 -0600
Subject: [PATCH] Added README for scripts. Added WORKFLOWS for scripts.

---
 scripts/README.md    | 337 +++++++++++++++++++++++++++++++++++++++++++
 scripts/WORKFLOWS.md | 140 ++++++++++++++++++
 2 files changed, 477 insertions(+)
 create mode 100644 scripts/README.md
 create mode 100644 scripts/WORKFLOWS.md

diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..c941759
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,337 @@
+# 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.
diff --git a/scripts/WORKFLOWS.md b/scripts/WORKFLOWS.md
new file mode 100644
index 0000000..14f43c1
--- /dev/null
+++ b/scripts/WORKFLOWS.md
@@ -0,0 +1,140 @@
+# Script Workflows
+
+Practical command recipes for common tasks.
+
+## 1) Start a Clean Dev Shell
+
+```powershell
+cd E:\stansshit\csharp\journal-master\journal
+. .\scripts\dev-shell.ps1
+```
+
+Use this when you want the current shell configured with repo-local cache paths.
+
+## 2) Build .NET Projects With Safe Defaults
+
+```powershell
+.\scripts\dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj
+.\scripts\dotnet-min.ps1 build Journal.WebGateway/Journal.WebGateway.csproj
+```
+
+## 3) Build Frontend or Desktop App
+
+Web build:
+
+```powershell
+.\scripts\publish-app.ps1 -Target web
+```
+
+Tauri raw exe (no installer):
+
+```powershell
+.\scripts\publish-app.ps1 -Target tauri -TauriBundles none
+```
+
+Tauri installer bundles:
+
+```powershell
+.\scripts\publish-app.ps1 -Target tauri -TauriBundles nsis
+.\scripts\publish-app.ps1 -Target tauri -TauriBundles msi
+```
+
+## 4) Publish Sidecar
+
+```powershell
+.\scripts\publish-sidecar.ps1 -Configuration Release -Runtime win-x64
+```
+
+Expected output under `output/`.
+
+## 5) Publish WebGateway Package
+
+```powershell
+.\scripts\publish-app.ps1 -Target web
+.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64
+```
+
+If you only want gateway binary refresh:
+
+```powershell
+.\scripts\publish-webgateway.ps1 -SkipWebAssets
+```
+
+## 6) Run WebGateway Against Explicit Root
+
+When multiple clones exist, always pin project root:
+
+```powershell
+.\scripts\run-webgateway.ps1 -ProjectRoot E:\stansshit\csharp\journal-master\journal -Urls http://0.0.0.0:5180
+```
+
+Quick health check:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:5180/api/health
+```
+
+Inspect active backend config:
+
+```powershell
+$body = @{ action = 'config.get' } | ConvertTo-Json
+Invoke-RestMethod -Uri http://127.0.0.1:5180/api/command -Method Post -ContentType 'application/json' -Body $body
+```
+
+## 7) Python Package Installs in Repo-Local Target
+
+```powershell
+.\scripts\pip-min.ps1 install requests
+```
+
+Packages go to `.pydeps\py314` unless you pass your own `--target`/`--prefix`.
+
+## 8) Migration Gate (When Full Test Assets Exist)
+
+```powershell
+.\scripts\migration-gate.ps1
+```
+
+Partial run:
+
+```powershell
+.\scripts\migration-gate.ps1 -SkipSmoke -SkipApi
+```
+
+Current clean repo caveat: `tests/` and `Journal.Api/` are not present, so full gate will fail until those assets are available.
+
+## 9) NuGet Cache Export/Import (Offline-ish Restore)
+
+Export:
+
+```powershell
+.\scripts\nuget-export-cache.ps1 -OutputZip .\nuget-cache-export.zip
+```
+
+Import:
+
+```powershell
+.\scripts\nuget-import-cache.ps1 -InputZip .\nuget-cache-export.zip
+```
+
+Current clean repo caveat: both scripts reference `Journal.Api/Journal.Api.csproj`.
+
+## 10) Quick Troubleshooting
+
+Script blocked by execution policy:
+
+```powershell
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\publish-app.ps1 -Target web
+```
+
+Unexpected data/vault mismatch in WebGateway:
+
+1. Run with explicit `-ProjectRoot`.
+2. Verify with `config.get` via `/api/command`.
+3. Verify sidecar root via `/api/sidecar/root`.
+
+NuGet restore flakiness:
+
+1. Use `dotnet-min.ps1` wrappers.
+2. Confirm proxy vars are cleared (`HTTP_PROXY`, `HTTPS_PROXY`, etc.).
+3. Ensure `.nuget` directories are writable.