journal/Journal.DevTool

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

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:

dotnet run --project DevTool.csproj -- init

Headless workflow/debug commands:

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:

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

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

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)

{
  "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.

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
• Hybrid GUI bridge is active:
  • execution: sdt run/debug --json
  • read/manage: sdt bridge --stdio
• Bridge contract doc: gui-bridge-contract.md
• Parity manifest: 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
. ./scripts/dev-shell.ps1

# cmd
scripts\dev-shell.cmd

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

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

Run Python script smoke checks:

python -m py_compile scripts/*.py

Verify workflow route/path resolution:

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
• Runbook: reliability-matrix-runbook.md
• Results log: reliability-matrix-results.md
• Milestone status (Windows/Linux shipped, macOS delegated): matrix-status.md