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)
• 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
• 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)

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

Bootstrap detects common stacks (dotnet, npm/node, python, cargo/tauri, 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.

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

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)

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