journal/Journal.DevTool/README.md

# SDT (Stan's Dev Tools)

Cross-platform terminal orchestrator for project workflows, toolchain checks, and prerequisite gating.

## Current State

- Standalone `.NET` TUI app (`net10.0`)
- Domain-separated source projects under `src/`:
  - `DevTool.Engine` (workflow/config/orchestration services)
  - `DevTool.Runtime` (process/command execution primitives)
  - `DevTool.Host.Tui` (terminal UI host surface)
- Workflow-first config model in `devtool.json`
- Strict-by-default legacy migration (`targets`-only configs fail unless compat mode is enabled)
- Python-first diagnostics/build script layer under `scripts/`
- Fail-fast execution with install prompt gating for missing prerequisites
- Debug profiles with attach metadata and diagnostics bundle generation
- Workspace-first project switching with support for external project paths
- Workspace-level defaults layering via `sdt-defaults.json` (ancestor defaults merged, project config wins)
- Project status tracking is maintained in `ROADMAP.md`
- Core run-event stream (`RunEvent`) shared by workflow + debug execution (TUI consumes it; GUI-ready)
- Run events are persisted to JSONL at `.sdt/events/` for external tooling/GUI consumers
- Run events now include versioned contract fields: `run_event_version`, `run_id`, `project_root`, `env_profile`, `timestamp_utc`, `event_type`
- TUI includes `SYSTEM -> View run events` to inspect persisted JSONL event logs
- `SYSTEM -> Run config doctor` can apply common autofixes (missing working dirs, legacy migration)
- `SYSTEM -> Keybinding help` provides normalized cross-platform shortcut guidance
- `SYSTEM -> Run history` supports rerun from prior execution context
- First-run projects are prompted to run a setup wizard (doctor + autofix + optional toolchain setup)
- Toolchain management now includes toolchain doctor + auto-fix flow with installer prompts and post-install verification
- Env profiles (`envProfiles`) support deterministic inheritance (`dev`/`ci`/`release`) and runtime profile selection from `SYSTEM -> Select env profile`
- Diagnostics bundles include managed secret redaction policy (env-key pattern redaction + output token redaction)
- Workspace quick actions/favorites can run workflows across projects (auto switch-and-run)
- Quick-action pinning is supported from workflow run results and events viewer
- Bootstrap detects additional project stacks (`go`, `maven`, `gradle`) and sets `project.type` (`dotnet`, `node`, `python`, `rust`, `go`, `java`, `tauri`, `polyglot`, `generic`)
- Headless execution mode is available for workflow/debug automation with JSON output
- Terminal capability fallback modes supported via `NO_COLOR`/`SDT_NO_COLOR` and `SDT_NO_UNICODE`

## Run

```powershell
dotnet run --project DevTool.csproj
```

Run from any subdirectory inside a project; SDT walks up to find `devtool.json`.

If `devtool.json` is missing, SDT now offers to scan the repo and generate a default config.

Explicit bootstrap command:

```powershell
dotnet run --project DevTool.csproj -- init
```

Headless workflow/debug commands:

```powershell
sdt run <workflowId> --json [--project-root <path>] [--env-profile <id>] [--non-interactive]
sdt debug <profileId> --json [--project-root <path>] [--env-profile <id>] [--non-interactive]
```

GUI bridge read/manage command:

```powershell
sdt bridge --stdio [--project-root <path>]
```

Workspace inventory scan (GUI/TUI shared discovery contract):

```powershell
sdt workspace scan --json [--project-root <path>]
```

`SDT_NONINTERACTIVE=1` globally enables non-interactive behavior for install prompts.

Bootstrap detects common stacks (`dotnet`, `npm/node`, `python`, `cargo/tauri`, `go`, `maven/gradle`, `git`, `docker`) and generates:

- default workflows
- toolchain/tooling defaults
- debug profiles + diagnostics defaults

## Config Model

SDT supports both:

- `workflows` (preferred)
- `targets` (legacy; compat mode only)

### Legacy Migration Mode (v1.2)

- Default: strict mode
- Behavior: `targets`-only config fails early with migration instructions
- Preview file: SDT writes `devtool.generated.workflows.json` for migration help
- Temporary rollback: set `SDT_LEGACY_MODE=compat`

Permanent fix (recommended):

1. Open `devtool.generated.workflows.json`
2. Copy its `workflows` into `devtool.json`
3. Remove or empty legacy `targets`
4. Run `sdt.exe` again in strict mode

### Workflow shape (preferred)

```json
{
  "id": "build",
  "label": "Build",
  "description": "Build project",
  "group": "Build",
  "dependsOn": [],
  "steps": [
    {
      "id": "dotnet-build",
      "label": "dotnet build",
      "action": "dotnet-build",
      "actionArgs": [],
      "workingDir": ".",
      "requires": [
        { "tool": "dotnet", "installPolicy": "Prompt" }
      ]
    }
  ]
}
```

### Extra sections

- `tooling.tools[].preferredInstallCommands`: preferred install commands per tool
- `tooling.tools[].executables`: explicit executable candidates for non-standard PATH setups
- `project.rootHints`: files/folders that identify project root
- `env`: session-level environment variable editor values
- `debug.profiles[]`: run/attach debug profiles
- `debug.diagnostics`: diagnostics bundle policy (`.sdt/debug` by default)
  - secure default: allowlist-only environment capture
  - set `includeAllEnv=true` to opt into full environment capture

### Workspace Defaults Layering

If SDT finds `sdt-defaults.json` in the project directory tree (current project root or an ancestor), it merges it into the effective config before runtime:

- base layer: `sdt-defaults.json`
- override layer: project `devtool.json` (project values win)

Merge behavior:

- objects merge recursively
- arrays/scalars are replaced when project provides the property

This is useful for shared defaults like toolchains, diagnostics policies, and baseline env definitions across multiple projects in one workspace.

## Execution Behavior

For each workflow step:

1. Resolve dependencies (topological order)
2. Probe required tools
3. If missing, show install commands and prompt (`Prompt` policy)
4. On decline/install failure/step failure, stop immediately
5. Render step summary table with exit code + elapsed time
6. On workflow/debug failure, generate diagnostics bundle when enabled

Installer command precedence:

1. `tooling.tools[].preferredInstallCommands`
2. `scripts/diag.py install-plan`
3. built-in C# fallback templates (used automatically if script planning fails)

When a tool probe fails, SDT now prints probe diagnostics (including command resolution source/path) in run output before prompting for installs.

Headless exit code contract:

- `0` success
- `10` missing prerequisite
- `11` install failed
- `12` command failed
- `13` validation/config error
- `14` user-declined / non-interactive prompt refusal

## Scripts

See [scripts/README.md](/scripts/README.md).

Primary Python entrypoints:

- `scripts/diag.py`
- `scripts/build.py`
- `scripts/dotnet-min.py`
- `scripts/pip-min.py`
- `scripts/publish-*.py`

## Workspace Support

- Uses `sdt-workspace.json` when present
- If missing, can auto-discover nearby projects containing `devtool.json`
- Workspace screen can add external project roots (absolute paths supported)
- `projects[].disabled`, `projects[].tags`, and `projects[].toolFamilies` are supported
- Hybrid inventory model discovers marker-only candidates (`.slnx/.sln/.csproj`) without silently mutating workspace config
- TUI workspace screen supports:
  - `Add candidate`
  - `Add + initialize devtool.json`
  - `Ignore for now` (session-only)
- Inventory snapshot is cached at `.sdt/workspace-inventory.json` for GUI-readiness

## GUI Direction

- Planned GUI stack for current phase: **Tauri-first**
- Avalonia is deferred for re-evaluation after first GUI milestone ships on top of the same headless contracts
- GUI workspace scaffold: [TauriShell README](/src/DevTool.Host.Gui/TauriShell/README.md)
- Hybrid GUI bridge is active:
  - execution: `sdt run/debug --json`
  - read/manage: `sdt bridge --stdio`
- Bridge contract doc: [gui-bridge-contract.md](/docs/gui-bridge-contract.md)
- Parity manifest: [gui-tui-parity.json](/docs/gui-tui-parity.json)
- GUI will consume:
  - `sdt workspace scan --json` inventory payload
  - `run/debug --json` summaries
  - persisted run events from `.sdt/events/*.jsonl`

## Dev Shell Bootstrap

Python-first cross-shell dev environment bootstrap:

```powershell
# PowerShell
. ./scripts/dev-shell.ps1

# cmd
scripts\dev-shell.cmd
```

```bash
# bash/zsh
source ./scripts/dev-shell.sh
```

Underlying implementation is `scripts/dev_shell.py`:

- `python scripts/dev_shell.py export --shell pwsh --json`
- `python scripts/dev_shell.py doctor`

## Legacy PowerShell Compatibility

Legacy `.ps1` scripts remain for migration compatibility only. New functionality is implemented in Python scripts first. `script-common.ps1` is legacy-only.

Legacy runtime behavior in v1.2:

- strict mode rejects `targets`-only configs by default
- compat mode (`SDT_LEGACY_MODE=compat`) temporarily allows legacy execution
- TUI `SYSTEM` includes `Migrate legacy targets -> workflows` to apply migration in place (with backup)
- Python reroute is authoritative for legacy `pwsh -File ...ps1` targets
- `.ps1` fallback is opt-in only: set `SDT_PWSH_LEGACY_FALLBACK=1` for temporary compatibility

Deprecation target:

- v1.x: compatibility only (no new behavior guarantees)
- v2.0: remove legacy `.ps1` scripts from default SDT workflows and docs

## Testing

Run unit/integration tests:

```powershell
dotnet test tests/DevTool.Tests/DevTool.Tests.csproj
```

Run Python script smoke checks:

```powershell
python -m py_compile scripts/*.py
```

Verify workflow route/path resolution:

```powershell
python scripts/verify-workflow-routes.py --project-root .
python scripts/verify-workflow-routes.py --project-root . --workflow build --workflow tauri --execute --env-profile dev
```

## Reliability Matrix

- CI matrix workflow: [reliability-matrix.yml](/.github/workflows/reliability-matrix.yml)
- Runbook: [reliability-matrix-runbook.md](/docs/reliability-matrix-runbook.md)
- Results log: [reliability-matrix-results.md](/docs/reliability-matrix-results.md)
- Milestone status (Windows/Linux shipped, macOS delegated): [matrix-status.md](/docs/matrix-status.md)