Added README for scripts.
Added WORKFLOWS for scripts.
This commit is contained in:
parent
069b38071c
commit
506aa072f6
337
scripts/README.md
Normal file
337
scripts/README.md
Normal file
@ -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.
|
||||
140
scripts/WORKFLOWS.md
Normal file
140
scripts/WORKFLOWS.md
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user