Extension PEZ 🚀

Scaffold, standardize, link, manage, and uninstall VS Code extensions — all from one tool inside your editor.

Extension PEZ is a VS Code extension that builds other VS Code extensions. It automates the entire lifecycle: creating new extension projects from templates, wiring them into your VS Code install directories so they load immediately, tracking everything in a registry, and safely cleaning up when you are done.

Created by Gewey — a module of the Viktor Substrate Nexus.

📌 Table of Contents

• Features
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Set Your Identity
  • Scaffold Your First Extension
• Usage
  • Commands Reference
  • Settings Reference
  • The PEZ Registry Tree View
• How It Works
• Development
• Contributing
• License
• Contact

✨ Features

🏗️ Scaffold New Extensions

Right-click any folder and PEZ interactively asks you for your license choice (MIT or AGPLv3 with plain-English descriptions), categories, keywords, and extension dependencies. It then creates a complete, production-ready extension project — package.json, README.md, LICENSE, AGENTS.md, .gitignore, .vscodeignore, a working src/extension.js entry point, and a placeholder icon — and optionally initializes git, commits, and pushes a private GitHub repo.

🔗 Auto-Link to VS Code

After scaffolding, PEZ can automatically create junctions from your VS Code extension directories to your working folder — no copying, no manual installs. Reload your window and your extension is live. Controlled by the pez.autoLink setting (stable, insiders, both, or none).

🗑️ Uninstall Extensions Safely

Right-click any extension in the PEZ Registry tree view or any registered folder in the explorer. PEZ removes the junction, cleans up extensions.json in all VS Code directories, and deletes the registry entry. Your source folder is never touched.

🐙 Git & GitHub Integration

Optionally initializes a git repo, commits all files, and creates a private GitHub repository via the gh CLI. Gracefully degrades if git or gh are not installed.

🪪 Identity Wizard (Webview-Based)

On first run, PEZ detects that your publisher identity is not configured and launches an integrated webview form with 6 fields: publisher ID, GitHub username, author name, author URL (optional), homepage (optional), and package manager preference (npm or pnpm). All fields are validated in real-time with helpful error messages. All values are saved to VS Code global settings and reused on every scaffold.

🩺 Doctor, Scan & Registry Management

• Doctor validates every extension in your registry — checks folders, manifests, junctions, and extensions.json entries.
• Scan & Rebuild Registry discovers all extension folders in your workshop and junction directories.
• Re-standardize All re-links and re-registers every discovered extension.
• Provision GitHub Repos creates and pushes private repos for any extension that does not have one yet.

📦 License Tagging

When enabled, PEZ zips a full backup of your folder, then walks every .py, .js, .ts, .jsx, and .tsx file and prepends a copyright header. Skips files that already have one.

📂 PEZ Registry Tree View

A dedicated activity bar view with three sections:

• PEZ Settings — all pez.* configuration values at a glance
• PEZ Registry — every extension PEZ has interacted with, with version, folder, junctions, and timestamps. Click to open the folder, right-click to uninstall.
• PEZ Backups — all backup .zip files organized by location with file sizes. Click to reveal in your file explorer.

🛠 Tech Stack

• Runtime: VS Code Extension API (TypeScript)
• Build: esbuild (bundling), TypeScript (type-checking), ESLint (linting)
• Core architecture: Pure-function core layer (src/core/), I/O execution layer (src/exec/), VS Code adapter layer (src/config.ts, src/commands.ts)
• Dependencies: adm-zip (zip backups), @vscode/test-cli / @vscode/test-electron (testing)
• Testing: Node built-in test runner (node --test), 51 unit tests

🚀 Getting Started

Prerequisites

• VS Code ^1.96.0
• Node.js (for building extensions with the output you scaffold)
• git (optional — for git operations)
• GitHub CLI (gh) (optional — for automatic private repo creation)

Installation

# Install from the VS Code Marketplace, or clone for development:
git clone https://github.com/gewey/EXTENSION_PEZ.git
cd EXTENSION_PEZ
npm install

Then reload your VS Code window. On first activation, PEZ prompts you to set your publisher identity.

1. Set Your Identity

Run PEZ: Set Identity from the command palette, or click Set Identity on the welcome prompt. The webview form requests:

1. Publisher ID (required) — your VS Code marketplace publisher name (e.g. my-name, lowercase letters and hyphens only)
2. GitHub username (required) — used for repository URLs on scaffolded extensions
3. Author name (required) — your name, written into every LICENSE file
4. Author URL (optional) — your website or GitHub profile URL
5. Homepage (optional) — your extension suite's homepage
6. Package manager (required) — npm (default, widely compatible) or pnpm (shared store, saves disk space)

All fields validate in real-time with clear error messages. Submit to atomically save all values to your VS Code global settings, or cancel anytime without saving. All values are reused every time you scaffold.

2. Scaffold Your First Extension

1. Right-click any empty folder in the VS Code explorer → PEZ: Scaffold New Extension
2. Choose a license (MIT is permissive, AGPLv3 is strong copyleft — descriptions provided)
3. Enter categories, keywords, and any extension dependencies (or leave blank)
4. Review the summary and confirm
5. PEZ creates all files, optionally runs git init + commit, auto-links to VS Code
6. Reload your VS Code window — your extension is now loaded

💡 Usage

Commands Reference

All commands are available from the command palette (Ctrl+Shift+P) and the right-click context menu on folders.

Settings Reference

The PEZ Registry Tree View

After scaffolding your first extension, click the PEZ icon in the VS Code activity bar. You will see:

• PEZ Settings — every pez.* setting and its current value
• PEZ Registry — your scaffolded extensions listed with their version, folder path, junctions, repository URL, and timestamps. Click any extension to open its folder. Right-click to uninstall.
• PEZ Backups — all .zip backup files created during license tagging or extensions.json edits, organized by location with file sizes. Click any backup to reveal it in your file explorer.

🔧 How It Works

Plan / Execute Split

Every filesystem mutation follows the same four-step spine:

1. Plan — PEZ builds a typed list of actions (create folder, write file, create link, remove link, zip backup, update extensions.json)
2. Preview — the plan is rendered to the Output Channel for you to inspect
3. Confirm — a modal dialog presents three choices: Dry Run (log only, no writes), Run for Real (execute everything), or Export Script (save the plan as a .ps1 or .sh file to run later)
4. Execute — the plan runs, or the script is saved

Templates

Every scaffolded file is a 1:1 copy from the config/ directory. Placeholders like {year}, {author}, {displayName}, and {extId} are filled from your settings. You can customize these templates to change what PEZ generates for future scaffolds.

Registry

Stored in VS Code's ExtensionContext.globalState (key pez.registry), not on the filesystem. Tracks ID, publisher, name, version, folder path, junction paths, repository URL, and timestamps.

Backups

Before editing extensions.json, PEZ creates a zip backup in your configured backup directory. Before license tagging, the entire folder is zipped to .pez-stamp-backups/. All backups are visible in the PEZ Backups tree view section.

🛠 Development

Prerequisites for Development

• Node.js >= 18
• npm >= 9
• VS Code ^1.96.0

Setup

git clone https://github.com/gewey/EXTENSION_PEZ.git
cd EXTENSION_PEZ
npm install

Build & Test

# Type-check
npm run check-types

# Lint
npm run lint

# Compile (type-check + lint + bundle with esbuild)
npm run compile

# Run core unit tests (51 tests, no VS Code host needed)
npm run test:core

# Package into .vsix
npm run package

Press F5 in VS Code to launch an extension development host with PEZ loaded.

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

All contributions are expected to maintain or improve test coverage (currently 51 unit tests). Run npm run test:core before submitting.

📄 License

Distributed under the GNU Affero General Public License v3.0. See LICENSE for more information.

✉️ Contact

Gewey - https://github.com/gewey

Project Link: https://github.com/gewey/EXTENSION_PEZ

VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=gewey-viktor.extension-pez