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:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\<script>.ps1

or in-session:

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.

. .\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:

.\scripts\dotnet-min.ps1 <dotnet args>

Examples:

.\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:

.\scripts\pip-min.ps1 <pip args>

Examples:

.\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:

.\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:

.\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:

.\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:

.\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 for copy/paste command recipes.