cdiag/Workstation-Setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Workstation-Setup/PHASE-2-IMPROVED-ARCHITECTURE.md
T
Vasyl Palamarchuk 44cebca879 Sync documentation.
2026-09-28 17:39:45 -07:00

20 KiB
Raw Permalink Blame History

PHASE 2: IMPROVED ARCHITECTURE

Target Design for Automotive Workstation Setup v2

Phase Start Date: 2026-09-09
Scope: Redesigned configuration schema, architecture patterns, and module structure
Outcomes: Foundation for all implementation phases that follow

2.1 ARCHITECTURAL PRINCIPLES

Design Goals

  1. Parameter-Driven: All paths and options derive from configuration and parameters (no hard-coded P:, S:)
  2. Configuration-Centric: JSON files are single source of truth; script contains only logic
  3. Resilient: Continue after non-critical failures; track and recover from errors
  4. Idempotent: Safe to run multiple times; no duplicate side effects
  5. Auditable: Complete logging, inventory, and recovery information
  6. Extensible: New profiles, apps, and settings without script modification
  7. Secure: Layered validation for downloads; hash/signature verification
  8. Testable: Pure functions separated from state-changing operations

Anti-Patterns to Avoid

  • ❌ Hard-coded drive letters in script (use derived paths)
  • ❌ Multiple code paths for same application (consolidate)
  • ❌ Ambiguous regex patterns (explicit and tested)
  • ❌ Silent failures (validate and report)
  • ❌ Undocumented exceptions (explicit allow-lists)
  • ❌ Untrusted downloads (validation at multiple layers)
  • ❌ Profile duplication (single definition with overrides)

2.2 CONFIGURATION SCHEMA REDESIGN

Current Problems

  • apps-core.json and apps-optional.json have inconsistent root structures
  • No validation schema (JSON files can contain invalid data)
  • No ProfileAllowList/DenyList on apps
  • No version management
  • No hash/signature requirements
  • Profiles lack customization hooks

Proposed Solution: Unified Application Definition

New Schema Structure:

{
  "ApplicationCatalog": {
    "Apps": [
      {
        "Id": "unique-app-id",
        "Name": "Display Name",
        "Category": "Development|Automotive|Utility|Network|Security|System",
        
        "InstallationType": "WinGet|Portable|Exe|Archive|ManualOnly",
        "SourceType": "WinGet|GitHub|Direct|ChromeForTesting",
        
        "WinGet": {
          "PackageId": "Vendor.Product.Version",
          "Scope": "Machine|User",
          "Arguments": "--silent",
          "Enabled": true
        },
        
        "Portable": {
          "Uri": "https://example.com/app.zip",
          "ArchiveName": "app.zip",
          "Folder": "Development\\App",
          "Executable": "app.exe",
          "Flatten": false,
          "Archive": "zip"
        },
        
        "GitHub": {
          "Repository": "owner/repo",
          "AssetRegex": "(?i)app.*x64.*portable\\.zip$",
          "IncludePrerelease": false,
          "IncludeDraft": false
        },
        
        "Validation": {
          "MinimumBytes": 1048576,
          "MaximumBytes": 1073741824,
          "ExpectedPublisher": "Company Name",
          "SignatureRequired": false,
          "ExpectedSHA256": "abc123...",
          "ArchiveIntegrityCheck": true
        },
        
        "Profiles": {
          "AllowList": ["DailyTech-Tuning", "ODIS-XENTRY", "PIWIS-ISTA"],
          "DenyList": []
        },
        
        "Versioning": {
          "Policy": "Latest|Stable|Pinned",
          "MinimumVersion": "2.0.0",
          "PinnedVersion": "2.15.3"
        },
        
        "Dependencies": [
          { "AppId": "prereq-app", "MinVersion": "1.0" }
        ],
        
        "Conflicts": [
          { "AppId": "conflicting-app" }
        ],
        
        "Features": {
          "Portable": true,
          "Shortcut": true,
          "PATHEligible": false,
          "LauncherVisible": true,
          "HealthCheck": true
        },
        
        "PostInstall": {
          "ConfigPath": "data\\settings.json",
          "Scripts": ["setup.ps1"],
          "EnvironmentVariables": {
            "VAR_NAME": "value"
          }
        },
        
        "Backup": {
          "Paths": ["data", "config"],
          "PreserveVersions": 2
        },
        
        "License": {
          "Type": "OpenSource|Commercial|Trial|Freeware",
          "OfficialPage": "https://example.com",
          "Notes": "Any special notes"
        },
        
        "Metadata": {
          "AutomotiveUseCase": "CAN analysis, ECU reading, binary inspection",
          "Status": "Active|Deprecated|Experimental",
          "LastVerified": "2026-09-09",
          "VerifiedBy": "user@example.com",
          "Notes": "Additional context"
        }
      }
    ]
  },
  
  "ProfileConfiguration": {
    "Profiles": [
      {
        "Id": "DailyTech-Tuning",
        "Name": "DailyTech & Tuning",
        "Description": "Daily technical work, ECU tuning, cloning, reverse engineering",
        "Enabled": true,
        
        "Applications": {
          "CorePackages": ["git", "python", "vscode", ...],
          "OptionalPackages": ["cmake", "make", ...],
          "PortableApps": ["ghidra", "imhex", "winhex", ...],
          "VSCodeExtensions": ["python", "c++", "hex-editor", ...]
        },
        
        "Windows": {
          "PowerPlan": "High Performance",
          "Hibernation": "Disabled",
          "USBSelectiveSuspend": "Disabled",
          "FastStartup": "Enabled",
          "UpdateActiveHours": { "Start": "08:00", "End": "17:00" },
          "RestorePoints": "Enabled",
          "DefenderStatus": "Enabled",
          "ControlledFolderAccess": "Disabled",
          "Firewall": "Enabled",
          "LongPathSupport": "Enabled",
          "PageFilePolicy": "System Managed",
          "DriverSignaturePolicy": "Enforce",
          "OptionalFeatures": ["Hyper-V", "WindowsSandbox"],
          "Services": {
            "Start": ["TermService"],
            "Stop": ["DiagTrack", "dmwappushservice"]
          }
        },
        
        "Workspace": {
          "Template": "DailyTech",
          "BaseFolder": "DailyTech-Tuning",
          "CreateProjectInitializer": true,
          "DefaultMetadata": {
            "Manufacturer": "Generic",
            "ModuleType": "ECU"
          }
        },
        
        "Shortcuts": {
          "FolderGroups": ["Workspace", "Projects", "Research", "Backups"],
          "ToolGroups": ["Sysinternals", "Portable Apps", "Development"],
          "CommercialToolWorkspaces": ["Xhorse", "WinOLS", "FlexFuel"]
        }
      },
      // ODIS-XENTRY and PIWIS-ISTA follow same structure
    ]
  },
  
  "DownloadTrust": {
    "HTTPAllowList": [
      { "Uri": "http://dl.xhorse.com", "Reason": "Vendor CDN limitation", "Verified": true }
    ],
    "TrustedPublishers": [
      { "Publisher": "Microsoft Corporation", "Threshold": "Required" },
      { "Publisher": "Xhorse", "Threshold": "Required" }
    ],
    "HashSources": [
      { "Vendor": "Microsoft", "Url": "https://releases.visualstudio.com/hashes" }
    ]
  },
  
  "ExecutionModes": {
    "Audit": { "Description": "Analyze config, validate schema, no changes" },
    "Plan": { "Description": "Show what would be installed, no changes" },
    "Apply": { "Description": "Install everything as planned" },
    "Repair": { "Description": "Retry failed installations, fix broken config" },
    "HealthCheck": { "Description": "Validate system state, dependencies, storage" },
    "Backup": { "Description": "Backup current config and installed apps" },
    "Restore": { "Description": "Restore from backup, optional category filter" },
    "Inventory": { "Description": "Scan installed apps and generate reports" },
    "UpdatePortable": { "Description": "Update portable apps only, skip WinGet" },
    "CreateWorkspace": { "Description": "Initialize new job/project from template" }
  }
}

2.3 NEW CONFIGURATION FILES

Files to Create/Modify

File Purpose New Replace
config-schema.json JSON Schema for validation ✅ -
app-catalog.json Unified app definitions ✅ apps-core/optional/portable
profile-configuration.json Profile specs and Windows settings ✅ workstation-profiles
download-trust.json HTTP allow-list, publishers, hashes ✅ -
execution-modes.json Mode definitions and parameters ✅ -
workspace-templates.json Folder structures per profile ✅ -
windows-settings.json OS configuration per profile ✅ -
automotive-resources.json Xhorse/Autel/specialized tools ✅ Keep, consolidate
folder-structure.json Local/shared folder structure - Keep, minor update

2.4 SCRIPT RESTRUCTURING

New Module Organization

Automotive-Workstation-Setup.ps1
├── Module: Core
│   ├── Initialize-Setup
│   ├── Load-Configuration
│   ├── Validate-Configuration
│   ├── Write-Log
│   └── Add-Result
├── Module: Validation
│   ├── Test-Administrator
│   ├── Test-WorkstationHealth
│   ├── Validate-JSONSchema
│   ├── Validate-ApplicationDependencies
│   └── Validate-ProfileConfiguration
├── Module: Path Management
│   ├── Resolve-Paths
│   ├── Initialize-FolderStructure
│   ├── Create-Junctions
│   └── Test-SharedPartitions
├── Module: Package Management
│   ├── Install-WingetPackage
│   ├── Update-WingetSources
│   └── Inventory-InstalledApps
├── Module: Portable Applications
│   ├── Resolve-GitHubRelease
│   ├── Download-Reliably
│   ├── Validate-Download (Hash/Sig/Archive)
│   ├── Install-PortableApp
│   ├── Test-PortableInstallation
│   └── Update-PortableApp
├── Module: Security
│   ├── Verify-Authenticode
│   ├── Verify-SHA256
│   ├── Test-ZipIntegrity
│   └── Validate-Publisher
├── Module: Windows Configuration
│   ├── Set-PowerPlan
│   ├── Set-USBPolicy
│   ├── Set-Hibernation
│   ├── Configure-Features
│   ├── Configure-Services
│   └── Detect-PendingRestart
├── Module: Shortcuts & Links
│   ├── New-Shortcut
│   ├── New-DirectoryLink
│   ├── Create-Shortcuts
│   └── Create-LauncherManifest
├── Module: State Management
│   ├── New-ExecutionContext
│   ├── Save-ExecutionState
│   ├── Load-ExecutionState
│   ├── Track-PendingActions
│   └── Handle-Interruption
├── Module: Workspace
│   ├── New-AutomotiveProject
│   ├── Initialize-WorkspaceTemplate
│   └── Create-ProjectMetadata
├── Module: Reporting
│   ├── Export-HealthReport
│   ├── Export-InventoryReport
│   ├── Export-SetupReport
│   ├── Export-PendingActions
│   └── Generate-RecoveryInstructions
└── Main Execution Flow
    ├── Parse-Parameters
    ├── Validate-ExecutionMode
    ├── Execute-Mode-Audit
    ├── Execute-Mode-Plan
    ├── Execute-Mode-Apply
    ├── etc.
    └── Export-FinalReport

Key Functions to Add

  1. Validate-JSONSchema — Validate all JSON files against schema before execution
  2. Verify-Authenticode — Check executable signatures
  3. Verify-SHA256 — Compare downloaded file against trusted hash
  4. Test-ZipIntegrity — Test ZIP file before extraction
  5. Detect-PendingRestart — Check registry for pending restart
  6. Track-PendingActions — Save interactive installer state
  7. Resolve-GitHubRelease — Enhanced with stable-release filtering
  8. New-AutomotiveProject — Create job folder structure + metadata
  9. Save-ExecutionState — Persist progress for resume-after-restart
  10. Filter-AppsByProfile — Apply ProfileAllowList/DenyList

2.5 EXECUTION MODES

Current Mode (Linear Execution)

1. Disable hibernation
2. Disable USB suspend
3. Create folder structure
4. Create junctions
5. Install WinGet packages
6. Download portable apps
7. Create shortcuts
8. Export reports
9. Done

Proposed Modes (Non-Linear, Resumable)

Mode: -Mode Audit

  • Parse and validate all JSON files
  • Check schema compliance
  • Report duplicates, conflicts, invalid paths
  • Validate profile definitions
  • Do not make any changes
  • Exit code 0 if valid, 1 if issues found

Mode: -Mode Plan

  • Load configuration
  • Show what would be installed (per profile)
  • Calculate storage requirements
  • Check for dependency conflicts
  • Show estimated time
  • Output to console and JSON
  • No changes made

Mode: -Mode Apply (Default)

  • Execute full setup (current behavior)
  • Resume from last checkpoint if interrupted
  • Support -Confirm for high-impact operations
  • Track completion status
  • Save state for recovery

Mode: -Mode Repair

  • Load last successful configuration
  • Scan for incomplete installations
  • Retry failed packages
  • Fix broken junctions/shortcuts
  • Verify shared partition state

Mode: -Mode HealthCheck

  • Check admin privileges
  • Validate shared partitions (S:, P:)
  • Test write permissions
  • Check disk space
  • Verify command availability (winget, git, python, code)
  • Scan for pending restart
  • Report antivirus/defender status
  • Exit with comprehensive JSON report

Mode: -Mode Backup

  • Backup current configuration (JSON)
  • Export installed package list (CSV/JSON)
  • Export VS Code extensions (JSON)
  • Backup all config files (ZIP)
  • Save to timestamped location
  • Return backup path

Mode: -Mode Restore

  • List available backups
  • Accept backup timestamp parameter
  • Optionally filter by category (Apps|Config|Settings)
  • Restore selected items
  • Verify restoration success

Mode: -Mode Inventory

  • Scan installed WinGet packages
  • Scan portable app directories
  • List VS Code extensions
  • List drivers and USB devices
  • Export disk inventory
  • Generate compatibility report

Mode: -Mode UpdatePortable

  • Check for newer portable app versions
  • Apply -ForcePortableUpdates logic
  • Preserve current versions as .previous
  • Create rollback instructions

Mode: -Mode CreateWorkspace

  • Accept project metadata (ID, vehicle, module, etc.)
  • Initialize folder structure from template
  • Create metadata JSON file
  • Create job log (Markdown)
  • Set up hash tracking
  • Generate initial README

2.6 EXECUTION STATE & RECOVERY

New Execution Context Structure

{
  "RunId": "UUID",
  "Profile": "DailyTech-Tuning",
  "Mode": "Apply",
  "StartTime": "2026-09-09T14:30:00Z",
  "Parameters": { "InstallOptionalApps": true, ... },
  
  "CheckpointIndex": 5,
  "Checkpoints": [
    { "Index": 0, "Action": "CreateFolders", "Status": "Complete", "Time": "2026-09-09T14:30:30Z" },
    { "Index": 1, "Action": "CreateJunctions", "Status": "Complete", "Time": "2026-09-09T14:31:00Z" },
    { "Index": 2, "Action": "UpdateWinget", "Status": "Complete", "Time": "2026-09-09T14:31:15Z" },
    { "Index": 3, "Action": "InstallCorePackages", "Status": "InProgress", "Time": "2026-09-09T14:35:00Z" },
    { "Index": 4, "Action": "DownloadPortableApps", "Status": "Skipped", "Time": "2026-09-09T14:35:01Z" },
    { "Index": 5, "Action": "RestartRequired", "Status": "Pending", "Reason": "WinGet install" }
  ],
  
  "PendingActions": [
    { "Type": "InteractiveInstaller", "App": "MVCI PRO", "Installer": "C:\\...\\_MVCI_PRO.exe", "Status": "Pending" },
    { "Type": "Restart", "Status": "Pending", "Reason": "WinGet" }
  ],
  
  "State": {
    "CurrentStep": "RestartPending",
    "LastSuccessfulStep": "InstallCorePackages",
    "ResumeAfterRestart": true,
    "SkippedPackages": [],
    "FailedPackages": [],
    "InstalledPackages": ["7zip.7zip", "git.git", ...]
  }
}

Recovery Workflow

  1. Interruption (Network, User Cancel, Restart)

    • Save execution context to file
    • Log pending actions
    • Generate recovery instructions

  2. Resume After Restart

    • Load execution context from file
    • Detect last completed step
    • Skip already-installed packages
    • Resume from next checkpoint
    • Revalidate system state

  3. Completion Verification

    • Cross-check installed packages against configuration
    • Verify all required applications present
    • Generate completion report

2.7 DOWNLOAD VALIDATION LAYERS

Current (Insufficient)

Download → Size Check (> 1KB) → Extract/Use → DONE

Proposed (Layered)

1. HTTPS only (or HTTP in allow-list)?
   ├─ YES: Continue
   └─ NO: Reject (unless allow-listed)

2. Validate file size
   ├─ Within range? → Continue
   └─ NO: Reject

3. Archive integrity check (if ZIP)
   ├─ Extracts cleanly? → Continue
   └─ NO: Reject

4. Expected executable exists?
   ├─ YES: Continue
   └─ NO: Reject

5. [Optional] SHA256 verification
   ├─ Vendor published? → Compare
   └─ Match? → Continue
   └─ NO: Reject/Quarantine

6. [Optional] Authenticode signature
   ├─ .exe file? → Verify
   └─ Valid sig? → Check publisher
   └─ Trusted? → Continue
   └─ NO: Reject/Quarantine

7. [Optional] Malware scan
   ├─ Windows Defender available? → Scan
   └─ Clean? → Continue
   └─ Infected: Quarantine

8. Atomic replacement
   ├─ Backup current version (.previous)
   └─ Move downloaded → destination
   └─ Log completion

2.8 BACKWARD COMPATIBILITY

Breaking Changes (Unavoidable)

  • JSON structure changes (apps-core/optional consolidation)
  • Profile configuration enhanced (new fields, but backward-compatible)
  • Function signatures may change (new parameters for validation)

Backward-Compatible Decisions

  • Keep parameter names unchanged (e.g., -InstallOptionalApps)
  • ValidateSet for $WorkstationProfile unchanged
  • Paths derivation follows same pattern
  • Idempotency preserved

Migration Path

  1. Load old JSON configs
  2. Validate against new schema (report issues)
  3. Transform old configs to new format automatically where possible
  4. Flag manual review items
  5. Generate migration report

2.9 CONFIGURATION VALIDATION SCHEMA (JSON Schema)

Will be created as config-schema.json:

  • Validate app definitions (required fields, types)
  • Validate profile configurations
  • Check for duplicate IDs
  • Validate ProfileAllowList references
  • Check path safety (no traversal sequences)
  • Validate regex patterns
  • Verify URI formats
  • Ensure required application categories present

2.10 SUMMARY OF ARCHITECTURAL CHANGES

Aspect Current Proposed Benefit
App Definition 3 separate JSON arrays 1 unified catalog Single source of truth
Profile Config Name/Folder/Focus only Extended with Windows/Apps/Workspace Profile-specific setup
Path Derivation Mixed (some hard-coded) All derived from parameters Flexible storage
Validation Minimal (file exists, size) Layered (hash, sig, archive, malware) Secure downloads
Execution Linear/non-resumable Checkpoint-based, resumable Robust to interruptions
State Tracking Results CSV/JSON Comprehensive execution context JSON Full recovery capability
Download Schemes HTTP without documentation Explicit allow-list with exceptions Documented trust model
Windows Config Limited (2 settings only) Comprehensive per-profile Optimized workstations
Workspace Folders only Templates + project initializer Faster job setup
Error Recovery Continue after fail Detect/recover/resume High availability

NEXT STEPS

This architecture will inform:

  • Phase 3: Application recommendation matrix
  • Phase 4: Windows settings per profile
  • Phase 5: Workspace template definitions
  • Phase 6: Download trust chain implementation
  • Phase 7: Execution mode implementations
  • Phase 8: Pester test coverage
  • Phase 9: Revised PowerShell script and all JSON configs

Architecture Review Checkpoint: Approve this design before proceeding to Phase 3+.

Reference in New Issue View Git Blame Copy Permalink