Workspace Scripts

VS Code extension for running custom workspace scripts from the side panel. Run npm, git, docker, python, bash and other commands without cluttering package.json.

🇵🇱 Polish version of this README is available in README.pl.md.

✨ Features

Core

📋 Command list panel – organized groups with optional icons/emoji
▶️ Run in terminal – single click, cwd automatically set to the workspace
🌐 Universal – run npm, git, docker, python and any other commands
🔄 Auto refresh – the view updates automatically when .vscode/workspace-scripts.json changes
👋 Welcome view – a button to quickly create an example configuration
🌍 Internationalization – full localization support (English, Polish + easily extensible)
🎯 Named terminals – terminals use script names instead of numbers

Advanced

🔤 Placeholders – use {name} in commands and provide values dynamically
💾 Input caching – workspace-level cache for frequently used values
🔇 Silent mode – use cached/default values without asking the user
⚠️ Confirmations – protect "dangerous" commands from accidental runs
🪟 Windows auto-detect – automatically wraps in cmd /c for operators (&&, |) and commands (rmdir, del)
🔁 Steps – run sequences of commands one after another

📦 Installation

From Visual Studio Marketplace

Open the Extensions view in VS Code
Search for Workspace Scripts
Click Install
Open the Workspace Scripts view in the Activity Bar
Click Create Example Configuration to generate an example file

Manual installation from VSIX

Open the Extensions view in VS Code
Click the ... menu
Choose Install from VSIX...
Select the .vsix file
Open the Workspace Scripts view in the Activity Bar

🚀 Configuration

`.vscode/workspace-scripts.json` structure

{
  "version": 1,
  "groups": [
    {
      "id": "build",
      "label": "Build",
      "icon": "🏗️"
    },
    {
      "id": "deploy",
      "label": "Deploy"
    }
  ],
  "scripts": [
    {
      "id": "build-dev",
      "label": "Build Development",
      "groupId": "build",
      "run": {
        "command": "npm run build -- --mode development"
      }
    },
    {
      "id": "deploy-env",
      "label": "Deploy to Environment",
      "groupId": "deploy",
      "run": {
        "command": "npm run deploy -- --env {environment}"
      },
      "inputs": [
        {
          "id": "environment",
          "label": "Target environment (dev/staging/prod)",
          "default": "dev",
          "remember": true
        }
      ],
      "inputsMode": "ask",
      "confirm": {
        "message": "Deploy to production?",
        "confirmText": "Deploy"
      }
    }
  ]
}

Properties

Group

Property	Type	Description
`id`	string	Unique group identifier
`label`	string	Display name in the panel
`icon`	string	(optional) Emoji or text prefix

Script

Property	Type	Description
`id`	string	Unique script identifier
`label`	string	Display name in the panel
`groupId`	string	ID of the group the script belongs to
`run`	RunSpec	Command specification to execute
`inputs`	InputSpec[]	(optional) Input variable definitions
`inputsMode`	"ask" \| "silent"	(optional) How to ask for inputs. Default: `"ask"`
`confirm`	ConfirmSpec	(optional) Confirmation before running

RunSpec – single command

{
  "command": "npm run build",
  "type": "auto"  // auto | shell | cmd | powershell | exec
}

RunSpec – steps

{
  "type": "steps",
  "steps": [
    { "command": "npm run build" },
    { "command": "npm run test" },
    { "command": "npm run deploy" }
  ]
}

InputSpec

Property	Type	Description
`id`	string	Variable name used in `{id}`
`label`	string	Prompt text for the user
`default`	string	(optional) Default value
`remember`	boolean	(optional) Whether to cache the value in the workspace

ConfirmSpec

Property	Type	Description
`message`	string	Confirmation message
`confirmText`	string	(optional) Confirmation button text. Default: `"OK"`

Command types (`type`)

auto (default) – automatic detection (on Windows: uses cmd for operators &&, ||, etc.)
shell – run directly in the current shell
cmd – force cmd /c (Windows)
powershell – run in PowerShell
exec – run as a standalone executable

🏗️ Architecture

Key architectural aspects

Dependency Injection – all dependencies can be injected (easy testing)
Single Responsibility – each module has a clear and focused responsibility
Type Safety – full TypeScript typing, zero any
Internationalization – full multi-language support with automatic detection
Error Handling – comprehensive error handling with friendly messages
Resource Management – proper resource handling, no memory leaks
JSDoc – fully documented API

🎯 Usage examples

Example 1: Simple build commands

{
  "version": 1,
  "groups": [{ "id": "build", "label": "🏗️ Build" }],
  "scripts": [
    {
      "id": "build-dev",
      "label": "Development",
      "groupId": "build",
      "run": { "command": "npm run build:dev" }
    },
    {
      "id": "build-prod",
      "label": "Production",
      "groupId": "build",
      "run": { "command": "npm run build:prod" }
    }
  ]
}

Example 2: Git with inputs and caching

{
  "version": 1,
  "groups": [{ "id": "git", "label": "🔀 Git" }],
  "scripts": [
    {
      "id": "checkout-branch",
      "label": "Checkout Branch",
      "groupId": "git",
      "run": { "command": "git checkout {branchName}" },
      "inputs": [
        {
          "id": "branchName",
          "label": "Branch name",
          "remember": true
        }
      ]
    },
    {
      "id": "git-push",
      "label": "Push to Remote",
      "groupId": "git",
      "run": { "command": "git push origin {branch}" },
      "inputs": [
        {
          "id": "branch",
          "label": "Branch name",
          "default": "main",
          "remember": true
        }
      ],
      "confirm": {
        "message": "Push to remote?",
        "confirmText": "Push"
      }
    }
  ]
}

Example 3: Docker

{
  "version": 1,
  "groups": [{ "id": "docker", "label": "🐳 Docker" }],
  "scripts": [
    {
      "id": "docker-up",
      "label": "Start Containers",
      "groupId": "docker",
      "run": { "command": "docker-compose up -d" }
    },
    {
      "id": "docker-logs",
      "label": "View Logs",
      "groupId": "docker",
      "run": { "command": "docker-compose logs -f {service}" },
      "inputs": [
        {
          "id": "service",
          "label": "Service name (or leave empty for all)",
          "default": "",
          "remember": true
        }
      ]
    }
  ]
}

Example 4: Steps sequence

{
  "version": 1,
  "groups": [{ "id": "release", "label": "Release" }],
  "scripts": [
    {
      "id": "full-release",
      "label": "Full Release Pipeline",
      "groupId": "release",
      "run": {
        "type": "steps",
        "steps": [
          { "command": "npm run lint" },
          { "command": "npm run test" },
          { "command": "npm run build" },
          { "command": "npm run deploy" }
        ]
      },
      "confirm": {
        "message": "Run full release pipeline?",
        "confirmText": "Release"
      }
    }
  ]
}

Example 5: Silent mode with remembered values

{
  "version": 1,
  "groups": [{ "id": "deploy", "label": "🚀 Deploy" }],
  "scripts": [
    {
      "id": "quick-deploy",
      "label": "Quick Deploy (silent)",
      "groupId": "deploy",
      "run": { "command": "npm run deploy -- --env {env} --region {region}" },
      "inputs": [
        {
          "id": "env",
          "label": "Environment",
          "default": "staging",
          "remember": true
        },
        {
          "id": "region",
          "label": "Region",
          "default": "eu-west-1",
          "remember": true
        }
      ],
      "inputsMode": "silent"
    }
  ]
}

🔧 Development

Getting started

Clone the repository
Install dependencies:
```
npm install
```
Start in development mode:
- Press F5 in VS Code – it will compile and launch an Extension Development Host
- Or use the menu: Run > Start Debugging

Requirements

Node.js 18+
VS Code 1.107.0+

Project structure

src/
├── extension.ts                # Extension activation and command registration
├── helperScriptsProvider.ts    # Tree view provider and script execution
├── configLoader.ts             # Config file loading and validation
├── configCreator.ts            # Logic for creating the default config
├── contextManager.ts           # VS Code context management
├── defaultConfig.ts            # Example config template
├── errorHandler.ts             # Centralized error handling
├── inputResolver.ts            # Asking for values and caching
├── commandBuilder.ts           # Building commands with placeholders
├── terminalRunner.ts           # Terminal creation and command execution
├── i18n.ts                     # Localization service
├── types.ts                    # TypeScript type definitions
└── locales/
    ├── en.json                 # English translations
    └── pl.json                 # Polish translations

Adding new languages

Create src/locales/{code}.json (e.g. de.json for German)
Copy the structure from en.json and translate the values
Create package.nls.{code}.json for translations used in package.json
The language will be detected automatically from VS Code settings

Developer scripts

npm run compile      # TypeScript compilation
npm run watch        # Watch mode
npm run lint         # ESLint
npm run build        # Production build
npm run vsix         # Build + package to .vsix

Testing

npm test

📝 Changelog

See the changelog included with the extension package for the full change history.

📄 License

MIT

Author: skaldy.com
Version: 0.2.0

Workspace Scripts

skaldy.com

Workspace Scripts

✨ Features

Core

Advanced

📦 Installation

From Visual Studio Marketplace

Manual installation from VSIX

🚀 Configuration

.vscode/workspace-scripts.json structure

Properties

Group

Script

RunSpec – single command

RunSpec – steps

InputSpec

ConfirmSpec

Command types (type)

🏗️ Architecture

Key architectural aspects

🎯 Usage examples

Example 1: Simple build commands

Example 2: Git with inputs and caching

Example 3: Docker

Example 4: Steps sequence

Example 5: Silent mode with remembered values

🔧 Development

Getting started

Requirements

Project structure

Adding new languages

Developer scripts

Testing

📝 Changelog

📄 License

`.vscode/workspace-scripts.json` structure

Command types (`type`)