@tdk-landscape/tdk-cli-core 1.3.44 → 1.3.48

package/install.sh

@@ -0,0 +1,242 @@
+#!/bin/bash
+# TDK CLI Install Script
+# Install the Tilt Development Kit CLI
+# Usage: curl -fsSL https://raw.githubusercontent.com/tdk-landscape/tdk-cli-core/main/install.sh | bash
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+REPO_URL="https://github.com/tdk-landscape/tdk-cli-core.git"
+INSTALL_DIR="${HOME}/.tdk"
+BIN_DIR="${HOME}/.bun/bin"
+
+# Print functions
+print_info() {
+    echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+print_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+print_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Detect OS
+detect_os() {
+    case "$(uname -s)" in
+        Linux*)     echo "linux";;
+        Darwin*)    echo "macos";;
+        CYGWIN*)    echo "windows";;
+        MINGW*)     echo "windows";;
+        MSYS*)      echo "windows";;
+        *)          echo "unknown";;
+    esac
+}
+
+# Check prerequisites
+check_prerequisites() {
+    print_info "Checking prerequisites..."
+    
+    OS=$(detect_os)
+    print_info "Detected OS: $OS"
+    
+    # Check for git
+    if ! command_exists git; then
+        print_error "git is required but not installed."
+        echo "Please install git first:"
+        echo "  macOS: brew install git"
+        echo "  Linux: sudo apt-get install git (or your package manager)"
+        exit 1
+    fi
+    
+    # Check for a JavaScript runtime (bun or node)
+    if command_exists bun; then
+        RUNTIME="bun"
+        print_success "Found bun runtime"
+    elif command_exists node; then
+        RUNTIME="node"
+        print_success "Found node runtime"
+        
+        # Check for npm
+        if ! command_exists npm; then
+            print_error "npm is required with node but not found"
+            exit 1
+        fi
+    else
+        print_warning "No JavaScript runtime found (bun or node)"
+        echo ""
+        echo "Would you like to install Bun? (Recommended - much faster)"
+        echo "  curl -fsSL https://bun.sh/install | bash"
+        echo ""
+        read -p "Install Bun now? [Y/n] " -n 1 -r
+        echo
+        if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
+            print_info "Installing Bun..."
+            curl -fsSL https://bun.sh/install | bash
+            
+            # Source bun setup
+            if [ -f "${HOME}/.bashrc" ]; then
+                export BUN_INSTALL="${HOME}/.bun"
+                export PATH="${BUN_INSTALL}/bin:$PATH"
+            fi
+            
+            if command_exists bun; then
+                RUNTIME="bun"
+                print_success "Bun installed successfully"
+            else
+                print_error "Bun installation failed or not in PATH"
+                print_info "Please restart your terminal and run this script again"
+                exit 1
+            fi
+        else
+            print_error "Bun or Node.js is required to install TDK"
+            exit 1
+        fi
+    fi
+}
+
+# Setup directories
+setup_directories() {
+    print_info "Setting up directories..."
+    
+    mkdir -p "$INSTALL_DIR"
+    mkdir -p "$BIN_DIR"
+    
+    print_success "Directories created"
+}
+
+# Clone or update repository
+clone_repository() {
+    print_info "Cloning TDK CLI repository..."
+    
+    if [ -d "${INSTALL_DIR}/tdk-cli" ]; then
+        print_warning "Existing installation found, updating..."
+        cd "${INSTALL_DIR}/tdk-cli"
+        git fetch origin
+        git reset --hard origin/main
+    else
+        git clone --depth 1 "$REPO_URL" "${INSTALL_DIR}/tdk-cli"
+        cd "${INSTALL_DIR}/tdk-cli"
+    fi
+    
+    print_success "Repository cloned/updated"
+}
+
+# Install dependencies and link
+install_and_link() {
+    print_info "Installing dependencies..."
+    
+    cd "${INSTALL_DIR}/tdk-cli/cli"
+    
+    if [ "$RUNTIME" = "bun" ]; then
+        bun install
+        print_success "Dependencies installed with bun"
+        
+        print_info "Linking TDK CLI..."
+        bun link --force
+        print_success "TDK CLI linked globally"
+    else
+        npm install
+        print_success "Dependencies installed with npm"
+        
+        print_info "Linking TDK CLI..."
+        npm link --force
+        print_success "TDK CLI linked globally"
+    fi
+}
+
+# Setup PATH
+setup_path() {
+    print_info "Setting up PATH..."
+    
+    SHELL_CONFIG=""
+    if [ -f "${HOME}/.zshrc" ]; then
+        SHELL_CONFIG="${HOME}/.zshrc"
+    elif [ -f "${HOME}/.bashrc" ]; then
+        SHELL_CONFIG="${HOME}/.bashrc"
+    elif [ -f "${HOME}/.bash_profile" ]; then
+        SHELL_CONFIG="${HOME}/.bash_profile"
+    fi
+    
+    if [ -n "$SHELL_CONFIG" ]; then
+        if ! grep -q "\.bun/bin" "$SHELL_CONFIG" 2>/dev/null; then
+            echo "" >> "$SHELL_CONFIG"
+            echo "# TDK CLI (installed via install.sh)" >> "$SHELL_CONFIG"
+            echo 'export PATH="${HOME}/.bun/bin:${PATH}"' >> "$SHELL_CONFIG"
+            print_success "Added ~/.bun/bin to PATH in $(basename "$SHELL_CONFIG")"
+            print_warning "Please restart your terminal or run: source $SHELL_CONFIG"
+        else
+            print_info "PATH already configured in $(basename "$SHELL_CONFIG")"
+        fi
+    else
+        print_warning "Could not detect shell config file"
+        print_info "Please manually add to your shell config:"
+        echo 'export PATH="${HOME}/.bun/bin:${PATH}"'
+    fi
+}
+
+# Verify installation
+verify_installation() {
+    print_info "Verifying installation..."
+    
+    export PATH="${BIN_DIR}:${PATH}"
+    
+    if command_exists tdk; then
+        VERSION=$(tdk -v 2>/dev/null || echo "unknown")
+        print_success "TDK CLI installed successfully!"
+        echo ""
+        echo "Version: $VERSION"
+        echo "Location: $(which tdk)"
+        echo ""
+        echo "Quick start:"
+        echo "  tdk --help       # Show all commands"
+        echo "  tdk project      # Initialize a new project"
+        echo "  tdk resource api # Create a new resource"
+        echo ""
+        print_info "Happy coding! 🚀"
+    else
+        print_error "Installation verification failed"
+        print_info "tdk command not found in PATH"
+        print_info "You may need to restart your terminal or run:"
+        echo "  export PATH=\"${HOME}/.bun/bin:\${PATH}\""
+        exit 1
+    fi
+}
+
+# Main installation flow
+main() {
+    echo ""
+    echo "╔════════════════════════════════════════════════════════════╗"
+    echo "║               🚀 TDK CLI Installer                         ║"
+    echo "║          Tilt Development Kit - Install Script            ║"
+    echo "╚════════════════════════════════════════════════════════════╝"
+    echo ""
+    
+    check_prerequisites
+    setup_directories
+    clone_repository
+    install_and_link
+    setup_path
+    verify_installation
+}
+
+# Run main function
+main "$@"

package/knip.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "workspaces": {
+    "cli": {
+      "entry": ["src/cli.ts"],
+      "project": ["src/**/*.ts", "src/**/*.tsx"],
+      "ignoreBinaries": ["biome"]
+    }
+  }
+}

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-21

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/design.md

@@ -0,0 +1,102 @@
+## Context
+
+TDK CLI manages local microservice development through project, stack, resource, doctor, status, and Tilt-oriented commands. The current developer workflow is terminal-heavy: developers run commands manually, inspect logs across tools, and infer root causes from mixed CLI, Docker, Bun, Tilt, port, and config output.
+
+The MVP introduces a VS Code-only extension in a new repository/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension` that treats the TDK CLI as the operational backend. The extension should not fork orchestration logic from the CLI. It should call the CLI, parse structured output where available, preserve raw output for debugging, and present a focused editor-native workflow for orchestration and troubleshooting.
+
+Stakeholders are TDK CLI maintainers, developers using TDK-managed repositories, and maintainers who need failure reports with enough context to debug quickly.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a VS Code extension MVP that can be developed and versioned separately from the CLI.
+- Deliver a runnable one-shot implementation with scaffold, source code, tests, documentation, and a verification record.
+- Detect TDK projects and expose project, stack, resource, doctor, status, and lifecycle actions from VS Code.
+- Provide a real troubleshooting flow that classifies failures, shows likely causes, links evidence, and offers safe next actions.
+- Manage notifications so background monitoring is useful without becoming noisy.
+- Document CLI JSON/status output gaps as follow-up work without changing the TDK CLI during this MVP.
+- Include a spec critique and final requirement trace before implementation is considered complete.
+
+**Non-Goals:**
+
+- Support JetBrains, Vim, browser IDEs, or a standalone Electron IDE in the MVP.
+- Replace the Tilt UI or reimplement Tilt orchestration.
+- Automatically run destructive or state-changing repairs without explicit user confirmation.
+- Build a full AI assistant or free-form chat interface in the first release.
+- Add remote/team dashboard features, cloud sync, or marketplace publishing automation in the MVP.
+- Modify the TDK CLI command contract in the MVP.
+
+## Decisions
+
+1. Create a new extension repo/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
+
+   Rationale: VS Code extension packaging, activation lifecycle, tests, and release cadence differ from the CLI. A separate package keeps the CLI focused and allows extension-specific dependencies such as `@types/vscode`, `vsce`, and VS Code test harnesses.
+
+   Alternative considered: place the extension under `tdk-cli-core/ext`. That is quicker initially, but it risks coupling extension release mechanics to CLI internals and makes it harder to ship independently. For one-shot implementation, the location is fixed to avoid blocking on repository placement.
+
+2. Use the TDK CLI as the source of truth.
+
+   Rationale: The extension should orchestrate and troubleshoot through commands such as `tdk doctor`, `tdk status`, `tdk stacks`, `tdk resources`, `tdk up`, and `tdk down`. This avoids two implementations of project discovery, stack/resource state, and health logic.
+
+   Alternative considered: read config files and Tilt state directly from the extension. That may be needed for display hints, but it must not become the primary orchestration model.
+
+   One-shot constraint: do not modify the CLI during the MVP. If structured output is incomplete, implement resilient adapters that keep raw output available and document the missing CLI contract in `docs/cli-contract-gaps.md`.
+
+3. Introduce a command runner boundary.
+
+   Rationale: A typed command runner can capture command, cwd, stdout, stderr, exit code, duration, cancellation, and parsed JSON payloads. This gives orchestration, troubleshooting, tests, and notifications a shared event model.
+
+   Alternative considered: run commands ad hoc from each UI command. That would make troubleshooting weaker because failures would lack consistent metadata.
+
+4. Build troubleshooting as deterministic rules first.
+
+   Rationale: The MVP needs reliable, reviewable classification for common failures: missing TDK CLI, unsupported CLI version, non-TDK workspace, Docker daemon unavailable, Tilt unavailable, Bun unavailable, occupied ports, invalid or missing master config, invalid service manifest, failed health endpoint, duplicate daemon, and Tilt startup failures.
+
+   Alternative considered: use an LLM-based troubleshooter first. That would be flashy but harder to test and risky for repair suggestions. LLM assistance can be considered later once deterministic evidence capture is solid.
+
+5. Use quiet-by-default notification policy.
+
+   Rationale: Background status checks can easily become spam. The extension should deduplicate repeated failures, escalate only when state changes or user action is required, and let users tune categories such as doctor failures, stack failures, and repair completion.
+
+   Alternative considered: notify on every failed poll. That is easier, but it teaches users to ignore the extension.
+
+6. Keep repair actions explicit and safe.
+
+   Rationale: Troubleshooting can recommend actions such as opening logs, rerunning doctor, starting Docker docs, freeing a port guide, regenerating configs, or running a specific TDK command. Any command that changes project files, starts/stops services, prunes Docker, or modifies config must require explicit confirmation and show the exact command.
+
+   Alternative considered: one-click auto-fix for every known issue. That is too risky for an MVP in developer workspaces.
+
+7. Ship three concrete VS Code surfaces.
+
+   Rationale: A one-shot MVP needs enough UI to prove value without becoming a full IDE. The required surfaces are a TDK Explorer tree, a Troubleshooter view, and a TDK output channel. Commands can be exposed through command palette and tree actions.
+
+   Alternative considered: command palette only. That is faster, but too weak to satisfy the orchestration and notification requirements.
+
+## Risks / Trade-offs
+
+- CLI output is not structured enough for robust parsing -> Use conservative parsing and mocked adapters for tests, preserve raw output, and document gaps for a later CLI change.
+- Extension becomes a thin command palette wrapper -> Require project tree views, status surfaces, troubleshooter evidence, and notification policy as MVP acceptance criteria.
+- Troubleshooter over-promises root cause accuracy -> Display confidence, evidence, and next safe step rather than pretending every issue has a single guaranteed cause.
+- Notifications become noisy -> Deduplicate by issue fingerprint, workspace, resource, severity, and state transition.
+- New repo setup slows the first implementation -> Generate a minimal VS Code TypeScript extension scaffold with focused tests before expanding UI.
+- Repair actions could damage local state -> Require confirmation for all state-changing actions and block destructive commands from automatic execution.
+
+## Migration Plan
+
+1. Scaffold `/private/var/www/2025/ollamar1/tdk-vscode-extension` with TypeScript, VS Code engine constraints, test harness, linting, and basic activation.
+2. Implement the command runner and workspace detector against the installed or workspace-local TDK CLI.
+3. Add orchestration commands and tree/status views for projects, stacks, and resources.
+4. Add deterministic diagnostic rules and the troubleshooter webview/tree/detail UI.
+5. Add notification policy, deduplication, and user settings.
+6. Document missing CLI structured-output gaps without changing the CLI.
+7. Run spec critique, implementation review, automated tests, and manual VS Code smoke tests.
+
+Rollback is simple for the MVP: disable or uninstall the VS Code extension. Follow-up CLI structured-output improvements, if implemented after this MVP, must be additive and preserve existing command behavior.
+
+## Fixed MVP Answers
+
+- Repository path: `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
+- Minimum CLI version: detect and display the installed CLI version when available; do not enforce a minimum version in the MVP unless the CLI command is missing.
+- Repair actions: support command suggestions and confirmed command execution for safe, explicit commands only.
+- Notification history: use VS Code native notifications plus the Troubleshooter view as the persistent issue history.

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+TDK CLI already provides project, stack, resource, health, and Tilt orchestration commands, but developers still have to leave the editor to understand what is running, why something failed, and what to do next. A VS Code-only plugin can turn the CLI into an operational cockpit with guided troubleshooting, clearer failure notifications, and one-click orchestration for the common local development loop.
+
+## What Changes
+
+- Create a new VS Code extension repository/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension` for a TDK IDE plugin instead of embedding extension code in the CLI package.
+- Add VS Code commands and panels for TDK project detection, stack/resource orchestration, status inspection, logs, and doctor checks.
+- Add a real troubleshooter that classifies common TDK/Tilt/Docker/Bun/port/config failures, explains likely causes, and offers safe, explicit repair actions.
+- Add notification management so normal background polling remains quiet, while actionable failures surface with deduplicated severity, context, and next steps.
+- Add an implementation review workflow that validates the shipped extension against every requirement and records critique findings before the one-shot MVP is considered done.
+
+## Capabilities
+
+### New Capabilities
+
+- `vscode-tdk-orchestration`: VS Code extension behavior for detecting TDK projects and orchestrating project, stack, and resource actions through the TDK CLI.
+- `vscode-tdk-troubleshooting`: Diagnostic and remediation behavior for identifying common local development failures and presenting safe recovery actions.
+- `vscode-tdk-notifications`: Notification policy behavior for quiet background monitoring, actionable alerts, deduplication, and user-controlled notification preferences.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Adds a new VS Code extension repo/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
+- Uses the existing TDK CLI as the source of truth for project status, orchestration, health checks, and remediation commands.
+- The one-shot MVP MUST NOT require changing the TDK CLI. If structured CLI output is missing, the extension must use mocked adapters in tests and conservative raw-output parsing at runtime, then document follow-up CLI improvements.
+- Adds extension tests, command-runner tests, diagnostic classifier tests, and manual VS Code extension smoke testing.
+- Does not change the CLI command contract for existing users in the MVP.

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-notifications/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Notifications are quiet by default
+The extension SHALL avoid user-visible notifications for successful background polling and unchanged non-actionable states.
+
+#### Scenario: Background poll succeeds
+- **WHEN** a background status or health poll succeeds
+- **THEN** the extension updates internal state without showing a user-visible notification
+
+#### Scenario: Existing issue remains unchanged
+- **WHEN** a background poll observes an already-reported issue with the same fingerprint and severity
+- **THEN** the extension suppresses duplicate user-visible notifications
+
+### Requirement: Actionable failures notify the user
+The extension SHALL notify the user when a new or escalated issue requires attention.
+
+#### Scenario: New critical issue
+- **WHEN** a new critical TDK, Tilt, Docker, Bun, port, or configuration issue is detected
+- **THEN** the extension shows a notification with a concise summary and an action to open troubleshooting details
+
+#### Scenario: Issue severity escalates
+- **WHEN** a known issue changes to a higher severity
+- **THEN** the extension shows a new notification for the escalation
+
+### Requirement: Notifications are user configurable
+The extension SHALL provide settings that allow users to control notification categories and quiet behavior.
+
+#### Scenario: User disables stack failure notifications
+- **WHEN** stack failure notifications are disabled in settings
+- **THEN** the extension records stack failures in the troubleshooting view without showing user-visible stack failure notifications
+
+#### Scenario: User keeps critical notifications enabled
+- **WHEN** critical notifications are enabled
+- **THEN** the extension continues to notify for critical new or escalated issues
+
+### Requirement: Notification actions route to context
+The extension SHALL route notification actions to the relevant stack, resource, command output, or troubleshooting issue.
+
+#### Scenario: User opens issue from notification
+- **WHEN** the user selects the notification action to inspect an issue
+- **THEN** the extension opens the troubleshooting detail for the issue that triggered the notification
+
+### Requirement: Troubleshooter acts as notification history
+The extension SHALL retain actionable notification issues in the Troubleshooter view so users can revisit them after dismissing native VS Code notifications.
+
+#### Scenario: User dismisses notification
+- **WHEN** the user dismisses a native VS Code notification for an actionable issue
+- **THEN** the issue remains available in the Troubleshooter view until resolved or superseded

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-orchestration/spec.md

@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: VS Code extension detects TDK workspaces
+The extension SHALL detect whether the active VS Code workspace contains a TDK project before enabling orchestration actions.
+
+#### Scenario: TDK project detected
+- **WHEN** a workspace contains TDK project configuration or a valid TDK CLI project root
+- **THEN** the extension enables TDK views and commands for that workspace
+
+#### Scenario: Non-TDK workspace
+- **WHEN** a workspace does not contain a TDK project
+- **THEN** the extension shows a non-blocking empty state and keeps orchestration actions disabled
+
+### Requirement: Extension is delivered as a new package
+The extension SHALL be implemented as a new VS Code extension package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
+
+#### Scenario: One-shot implementation starts
+- **WHEN** implementation begins
+- **THEN** the extension package is scaffolded outside `tdk-cli-core` at `/private/var/www/2025/ollamar1/tdk-vscode-extension`
+
+#### Scenario: Extension package is verified
+- **WHEN** the MVP is complete
+- **THEN** the package contains source code, package metadata, tests, documentation, and verification notes
+
+### Requirement: Extension runs orchestration through TDK CLI
+The extension SHALL execute project, stack, resource, doctor, status, up, and down actions through the TDK CLI instead of duplicating orchestration logic.
+
+#### Scenario: User starts a stack
+- **WHEN** the user starts a stack from VS Code
+- **THEN** the extension runs the corresponding TDK CLI stack lifecycle command in the workspace root and captures the command result
+
+#### Scenario: CLI command fails
+- **WHEN** a TDK CLI orchestration command exits with a non-zero status
+- **THEN** the extension preserves stdout, stderr, exit code, command, workspace, and duration for troubleshooting
+
+### Requirement: Extension exposes project, stack, and resource status
+The extension SHALL show project, stack, and resource status inside VS Code using TDK CLI status data.
+
+#### Scenario: Status refresh succeeds
+- **WHEN** the user refreshes TDK status
+- **THEN** the extension updates the visible project, stack, and resource state from the latest CLI result
+
+#### Scenario: Status refresh is cancelled
+- **WHEN** the user cancels an in-progress status refresh
+- **THEN** the extension stops the command and leaves the previous known status visible with a cancellation indication
+
+### Requirement: Extension provides required MVP surfaces
+The extension SHALL provide a TDK Explorer view, a Troubleshooter view, and a TDK output channel.
+
+#### Scenario: Extension activates in a TDK workspace
+- **WHEN** the extension activates in a detected TDK workspace
+- **THEN** the TDK Explorer, Troubleshooter view, and TDK output channel are available
+
+#### Scenario: Command output is produced
+- **WHEN** a TDK command runs through the extension
+- **THEN** the raw command output is appended to the TDK output channel
+
+### Requirement: MVP is VS Code only
+The IDE plugin SHALL support VS Code only for the MVP.
+
+#### Scenario: Non-VS Code IDE support requested
+- **WHEN** implementation scope is reviewed for the MVP
+- **THEN** JetBrains, Vim, browser IDE, and standalone Electron support are excluded from required delivery

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-troubleshooting/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: Troubleshooter classifies common TDK failures
+The extension SHALL classify common local development failures using deterministic diagnostic rules based on CLI results, environment checks, and captured command evidence.
+
+#### Scenario: Missing prerequisite
+- **WHEN** Docker, Tilt, Bun, or the TDK CLI is missing or unavailable
+- **THEN** the troubleshooter identifies the missing prerequisite and presents the evidence that caused the classification
+
+#### Scenario: Port conflict
+- **WHEN** a TDK command or doctor result indicates that a required port is occupied
+- **THEN** the troubleshooter identifies the affected port and resource when that information is available
+
+#### Scenario: Invalid project configuration
+- **WHEN** TDK project defaults, tech stack config, Tiltfile, or service manifests are missing or invalid
+- **THEN** the troubleshooter identifies the invalid configuration area and links to the relevant file or command output when available
+
+#### Scenario: Tilt startup failure
+- **WHEN** a TDK lifecycle command reports a Tilt startup failure
+- **THEN** the troubleshooter identifies the failure as Tilt-related and preserves the relevant command output as evidence
+
+### Requirement: Troubleshooter presents likely cause and next action
+The extension SHALL show likely cause, confidence, evidence, and recommended next action for each classified issue.
+
+#### Scenario: Classified issue displayed
+- **WHEN** the troubleshooter opens a classified issue
+- **THEN** the issue detail includes severity, likely cause, confidence, evidence, and at least one next action
+
+#### Scenario: Unknown issue displayed
+- **WHEN** the troubleshooter cannot classify a failure
+- **THEN** the issue detail shows the raw command evidence and recommends a safe next diagnostic step
+
+### Requirement: Repair actions require explicit confirmation
+The extension SHALL require explicit user confirmation before running any repair action that changes files, starts or stops services, prunes resources, or modifies local environment state.
+
+#### Scenario: User selects state-changing repair
+- **WHEN** the user selects a repair action that changes local state
+- **THEN** the extension displays the exact command or operation and waits for confirmation before execution
+
+#### Scenario: User declines repair
+- **WHEN** the user declines a repair confirmation
+- **THEN** the extension does not run the repair and keeps the troubleshooting issue available
+
+### Requirement: Troubleshooter preserves diagnostic context
+The extension SHALL retain recent diagnostic context for failed commands so users can review evidence without rerunning the command immediately.
+
+#### Scenario: Failed orchestration command
+- **WHEN** an orchestration command fails
+- **THEN** the troubleshooter records the command metadata, raw output, parsed issue fingerprints, and timestamp
+
+### Requirement: CLI contract gaps are documented
+The extension SHALL document any missing or unstable TDK CLI output contract encountered during implementation instead of requiring CLI changes for the MVP.
+
+#### Scenario: CLI output cannot be parsed robustly
+- **WHEN** an adapter cannot reliably parse a TDK CLI command output
+- **THEN** the extension keeps raw output available and records the missing structured-output need in CLI contract gap documentation

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/tasks.md

@@ -0,0 +1,61 @@
+## 1. Scope Review and Repository Setup
+
+- [x] 1.1 Create `/private/var/www/2025/ollamar1/tdk-vscode-extension` as the new VS Code-only extension package location.
+- [x] 1.2 Add `docs/spec-critique.md` documenting MVP creep risks, unsafe repair risks, missing CLI contract risks, and how this implementation constrains each one.
+- [x] 1.3 Scaffold a TypeScript VS Code extension package with activation, command registration, test harness, lint/typecheck scripts, packaging metadata, and README.
+- [x] 1.4 Add extension configuration settings for TDK CLI path, polling behavior, notification categories, and safe repair confirmation behavior.
+- [x] 1.5 Add a verification checklist document that maps each spec requirement to implementation and test evidence.
+
+## 2. TDK CLI Integration Layer
+
+- [x] 2.1 Implement a command runner that captures command, cwd, stdout, stderr, exit code, duration, cancellation, and timestamp.
+- [x] 2.2 Implement TDK CLI discovery with support for configured binary path, workspace-local binary, and PATH fallback.
+- [x] 2.3 Implement workspace detection for TDK project roots and disabled empty-state behavior for non-TDK workspaces.
+- [x] 2.4 Implement typed adapters for `tdk doctor`, `tdk status`, `tdk stacks`, `tdk resources`, `tdk up`, and `tdk down`.
+- [x] 2.5 Add conservative raw-output parsing for adapters where structured JSON is unavailable.
+- [x] 2.6 Document missing structured-output needs in `docs/cli-contract-gaps.md` without modifying the TDK CLI.
+
+## 3. VS Code Orchestration UI
+
+- [x] 3.1 Add a TDK Explorer tree view for detected project, stacks, resources, and last known status.
+- [x] 3.2 Add commands for refresh status, run doctor, start stack/resource, stop stack/resource, and stop all services.
+- [x] 3.3 Add cancellation support for long-running refresh/doctor/orchestration commands.
+- [x] 3.4 Add a TDK output channel and append every executed command plus raw stdout/stderr.
+- [x] 3.5 Preserve raw command output and surface it from the relevant project, stack, resource, or command result.
+
+## 4. Troubleshooter
+
+- [x] 4.1 Define diagnostic issue types, severity levels, confidence levels, fingerprints, evidence records, and recommended next-action models.
+- [x] 4.2 Implement deterministic classifiers for missing TDK CLI, unsupported CLI version, non-TDK workspace, Docker unavailable, Tilt unavailable, Bun unavailable, occupied ports, missing/invalid master config, invalid service manifest, failed health endpoint, duplicate daemon, and Tilt startup failure.
+- [x] 4.3 Add a Troubleshooter view that shows issue list, severity, likely cause, confidence, evidence, raw output, and next actions.
+- [x] 4.4 Implement safe repair actions with explicit confirmation and exact command/operation preview for any state-changing action.
+- [x] 4.5 Ensure unknown failures retain raw command evidence and recommend a safe diagnostic next step.
+- [x] 4.6 Keep actionable issues available in the Troubleshooter view after native VS Code notifications are dismissed.
+
+## 5. Notification Management
+
+- [x] 5.1 Implement quiet-by-default background polling with no notifications for successful checks or unchanged non-actionable states.
+- [x] 5.2 Implement notification deduplication by issue fingerprint, workspace, resource, severity, and state transition.
+- [x] 5.3 Implement notifications for new critical issues, escalations, and completed user-triggered repair actions.
+- [x] 5.4 Route notification actions to the relevant troubleshooting detail, command output, stack, or resource.
+- [x] 5.5 Honor user settings for notification categories and quiet behavior.
+- [x] 5.6 Add tests proving dismissed native notifications do not remove issues from Troubleshooter history.
+
+## 6. Tests and Manual Validation
+
+- [x] 6.1 Add unit tests for command runner success, failure, cancellation, and output capture.
+- [x] 6.2 Add unit tests for TDK workspace detection and CLI discovery fallbacks.
+- [x] 6.3 Add unit tests for every deterministic diagnostic classifier and unknown-failure fallback.
+- [x] 6.4 Add tests for notification deduplication, escalation, and category suppression.
+- [x] 6.5 Add VS Code extension integration tests for activation, command registration, disabled non-TDK workspace state, and at least one orchestration command using a mocked CLI.
+- [x] 6.6 Add mocked CLI fixtures for success, failure, missing prerequisites, port conflict, invalid config, Tilt startup failure, and unknown failure.
+- [x] 6.7 Run lint, typecheck, unit tests, and VS Code extension tests.
+- [x] 6.8 Package or dry-run package the extension to prove the MVP can be installed locally.
+
+## 7. Documentation and Final Review
+
+- [x] 7.1 Document MVP usage, settings, supported commands, troubleshooting behavior, notification policy, and safe repair guarantees.
+- [x] 7.2 Document known limitations and follow-up candidates such as richer Tilt links, marketplace publishing, and optional AI-assisted troubleshooting.
+- [x] 7.3 Complete the verification checklist mapping every scenario in the three spec files to source code and test evidence.
+- [x] 7.4 Perform a final critical review of the specs and implementation for overreach, missed failure modes, notification noise, unsafe repair actions, and any gap that blocks one-shot MVP acceptance.
+- [x] 7.5 Record final commands run and results in the verification notes.

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-27