Add VS code marketplace extension

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Build VS Code extension
+        run: npm run build:extension
+
+      - name: Extension integration tests
+        run: xvfb-run -a npm run test:extension
+
+      - name: Check extension bundle size
+        run: test $(wc -c < extension/dist/extension.js) -lt 5242880

.github/workflows/publish-extension.yml

@@ -0,0 +1,79 @@
+# Publish AI Stack Kit VS Code extension to the Marketplace on version tags.
+# See https://code.visualstudio.com/api/working-with-extensions/continuous-integration
+#
+# Setup: add repository secret VSCE_PAT (Azure DevOps PAT, Marketplace → Manage).
+# Release: bump extension/package.json version + CHANGELOG, commit, then:
+#   git tag v1.1.3 && git push origin v1.1.3
+
+name: Publish VS Code Extension
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Build VS Code extension
+        run: npm run build:extension
+
+      - name: Extension integration tests
+        run: xvfb-run -a npm run test:extension
+
+      - name: Check extension bundle size
+        run: test $(wc -c < extension/dist/extension.js) -lt 5242880
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build extension package
+        run: npm run build:extension
+
+      - name: Package VSIX artifact
+        working-directory: extension
+        run: npm run vsix
+
+      - name: Upload VSIX
+        uses: actions/upload-artifact@v4
+        with:
+          name: ai-stack-kit-vsix
+          path: extension/*.vsix
+          if-no-files-found: error
+
+      - name: Publish to Visual Studio Marketplace
+        working-directory: extension
+        run: npm run deploy
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}

.gitignore

@@ -17,13 +17,23 @@ build/
 *.d.ts
 !templates/**/*.js
 
+# VS Code extension test/build artifacts
+extension/.vscode-test/
+extension/out/
+extension/media/catalog/
+extension/test-workspace/spec.yaml
+extension/test-workspace/sources.config.yaml
+extension/test-workspace/.gitignore
+extension/*.vsix
+
 # Testing
 coverage/
 .nyc_output/
 *.lcov
 
 # IDEs
 .vscode/
+!extension/.vscode/
 .idea/
 *.swp
 *.swo
@@ -69,3 +79,4 @@ tests/fixtures/**/.aistack/cache/
 
 # Maintainer-only local notes (never commit)
 private.md
+extension/PUBLISHING.md

ARCHITECTURE.md

@@ -16,6 +16,14 @@ CLI tool that reads `spec.yaml`, resolves **skills**, **subagents**, and **hooks
 4. **CLI-first**: kubectl-style UX (`aistack` / `ai-stack`).
 5. **Loose coupling**: Boundaries over concrete types; composition over inheritance.
 
+### VS Code extension host
+
+The [`extension/`](extension/) package is published as **[AI Stack Kit on the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** (`deb-adarsh.ai-stack-kit`). It bundles the **headless API** (`src/api/workspace-api.ts` → `AistackWorkspace`) via esbuild. The extension host sets `AISTACK_TEMPLATES_CLIENTS` and `AISTACK_SOURCES_CONFIG_TEMPLATE` to shipped `extension/templates/` so sync works without `import.meta.url` at runtime. UI (trees, catalog webview, commands) calls the same `apply()` pipeline as the CLI.
+
+```
+Activity Bar / commands / webview  →  extension services  →  AistackWorkspace  →  pipeline + adapters
+```
+
 ---
 
 ## System architecture (diagram)

README.md

@@ -1,6 +1,7 @@
 # AI Stack Kit
 
 [![npm](https://img.shields.io/npm/v/ai-stack-kit)](https://www.npmjs.com/package/ai-stack-kit)
+[![VS Code extension](https://img.shields.io/badge/VS%20Code%20extension-Install%20on%20Marketplace-007ACC?style=flat&logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)
 [![license](https://img.shields.io/github/license/deb-adarsh/ai-stack-kit)](https://github.com/deb-adarsh/ai-stack-kit/blob/main/LICENSE)
 [![Skill browser](https://img.shields.io/badge/skill%20browser-live-informational)](https://deb-adarsh.github.io/ai-stack-kit/)
 
@@ -12,6 +13,29 @@ A CLI to **discover, install, apply and sync reusable AI capabilities** from Git
 
 > Think: npm (distribution) + Terraform (setup) for AI dev environments
 
+### Install options
+
+| Method | Command |
+|--------|---------|
+| **npm registry** (public) | `npm install -g ai-stack-kit` |
+| **GitHub Packages** | `npm install -g @deb-adarsh/ai-stack-kit` (requires [`.npmrc` auth](https://github.com/deb-adarsh/ai-stack-kit/blob/main/USER_GUIDE.md#github-packages)) |
+| **No global install** | `npx github:deb-adarsh/ai-stack-kit <command>` (same as the [Skill browser](https://deb-adarsh.github.io/ai-stack-kit/)) |
+| **VS Code / Cursor extension** | [**Install from Marketplace**](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit) — `ext install deb-adarsh.ai-stack-kit` — or build a `.vsix` with `npm run build:extension` then `cd extension && npm run vsix` |
+
+### VS Code extension
+
+**[Install AI Stack Kit on the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** (works in VS Code and Cursor). Quick Open (`Ctrl+P` / `Cmd+P`) → `ext install deb-adarsh.ai-stack-kit`.
+
+The bundled extension in [`extension/`](extension/) uses the same engine as the CLI (`AistackWorkspace` API) — no global `aistack` install required.
+
+- **Activity Bar** → **Modules**, **Outputs**, and **Catalog** (skill browser)
+- Commands: **Initialize**, **Sync**, **Doctor**, **Search/Add**, **Switch Client** (cursor / copilot / claude)
+- Settings: `aiStackKit.clientType`, `aiStackKit.githubToken`, `aiStackKit.dryRun`, `aiStackKit.autoSyncOnSave`
+
+From the repo root: `npm run build:extension` bundles core + catalog snapshot. Press **F5** in the `extension/` folder to run the Extension Development Host. See **[USER_GUIDE.md](./USER_GUIDE.md#vs-code--cursor-extension)** for workflows.
+
+**Publish to Marketplace:** see **[extension/PUBLISHING.md](./extension/PUBLISHING.md)** — manual (`vsce` / VSIX upload) or CI on `git tag v1.x.x` with GitHub secret `VSCE_PAT` ([Continuous Integration](https://code.visualstudio.com/api/working-with-extensions/continuous-integration)).
+
 ---
 
 ## 🔄 Keeps your AI stack in sync
@@ -78,24 +102,14 @@ AI Stack Kit introduces a spec-driven approach:
 
 ## 🔁 The workflow
 
-search → add → sync
+**search → add → sync**
 
-### 1. Faster clarity (first 5 seconds)
-- “install AI capabilities like npm packages” → instantly understandable  
-- removes heavy phrasing early  
+1. **`aistack init`** — create `spec.yaml` + `sources.config.yaml` (auto-detects Cursor / Copilot / Claude)
+2. **`aistack search <query>`** — discover modules from configured catalogs ([Skill browser](https://deb-adarsh.github.io/ai-stack-kit/) too)
+3. **`aistack skill add <name>`** — append to `spec.yaml`
+4. **`aistack sync`** — resolve, install, and write IDE outputs from one spec
 
-### 2. Your BEST feature is now prominent
-- auto-sync is now **top section**, not buried  
-
-### 3. UX strength is explicit
-- auto-detection highlighted clearly  
-
-### 4. Reduces cognitive load
-- no long paragraphs upfront  
-- tight, scannable sections  
-
-### 5. Strong mental model
-- spec → sync → generated outputs is crystal clear  
+Run **`aistack doctor`** to validate your setup. See **[USER_GUIDE.md](./USER_GUIDE.md)** for full workflows.
 
 ---
 
@@ -289,6 +303,7 @@ For the **full command list** — **`skill` / `subagent` / `hook`**, **`catalog
 - **[CONTRIBUTING.md](./CONTRIBUTING.md)**: How to contribute—including extending the **default catalog** (`templates/sources.config.yaml`) for the CLI and Skill browser.
 
 - **[USER_GUIDE.md](./USER_GUIDE.md)**: Install paths, **`spec.yaml`** example, full CLI reference, env vars, workflows, troubleshooting.
+- **[VS Code extension (Marketplace)](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)**: Activity Bar UI, catalog search, sync without a global CLI install.
 
 ### 📝 Configuration
 
@@ -375,31 +390,28 @@ export class GitLabSource extends BaseSkillSource {
 }
 ```
 
-### Add a New IDE (e.g., IntelliJ)
+### Add a New IDE client (e.g., Windsurf)
 
-1. Create `src/adapters/intellij/intellij-adapter.ts`
-2. Implement `IDEAdapter` interface
-3. Register in adapter factory
-4. Add detection logic
+1. Create `src/client-adapters/windsurf/windsurf-adapter.ts`
+2. Implement the `ClientAdapter` interface (see `src/client-adapters/client-adapter.ts`)
+3. Register in `AdapterFactory` (`src/client-adapters/adapter-factory.ts`)
+4. Add output paths in `src/client-adapters/client-paths.ts` if needed
 
 **Example:**
 ```typescript
-import { BaseIDEAdapter } from '../base/ide-adapter';
+import type { ClientAdapter } from '../client-adapter.js';
 
-export class IntelliJAdapter extends BaseIDEAdapter {
-  constructor() {
-    super('intellij', ['skills', 'settings']);
+export class WindsurfClientAdapter implements ClientAdapter {
+  readonly name = 'windsurf';
+  supports(clientType: string): boolean {
+    return clientType === 'windsurf';
   }
-
-  async detect(): Promise<IDEDetectionResult> {
-    // Detect IntelliJ installation
+  generateConfig(input: NormalizedWorkspaceInput): AdapterOutput {
+    // Map skills, agents, prompts to Windsurf layout
   }
-
-  async applySkill(skill: SkillContent): Promise<ApplyResult> {
-    // Transform and write to IntelliJ format
+  async apply(output, projectRoot, options) {
+    // Write files under project or user scope
   }
-
-  // ... implement other methods
 }
 ```
 
@@ -428,7 +440,7 @@ Snapshot of **what’s in the repo today** and **what might come next**—adjust
 | **`spec.yaml`** | Load + **Zod validation**, apply pipeline, modules merge (`skills` + `modules`). |
 | **Sources** | **GitHub** fetch/install + **npm** packages; **dynamic catalogs** from `sources.config.yaml` (GitHub tree + npm tree providers). |
 | **Discovery** | Composite registry, hybrid search, **`catalog refresh`** for additive spec merges. |
-| **IDE outputs** | **Cursor**, **Copilot** (VS Code settings path), **Claude** client adapters in the apply pipeline—not a full generic “VS Code extension marketplace” story. |
+| **IDE outputs** | **Cursor**, **Copilot** (VS Code settings path), **Claude** client adapters; **[VS Code extension](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** for in-editor sync and catalog browse. |
 | **Skill browser** | **Static web app** + `catalog.json` build + **GitHub Pages** deploy (weekly cron + pushes). |
 | **Hosted registry product** | No dedicated **public registry server** or npm-like **publish** flow yet—discovery is **aggregate-from-upstreams** plus local spec. |
 
@@ -451,6 +463,7 @@ Licensed under the **Apache License 2.0**. See [LICENSE](./LICENSE).
 ## Support
 
 - 📖 Documentation: **[USER_GUIDE.md](./USER_GUIDE.md)** · **[ARCHITECTURE.md](./ARCHITECTURE.md)**
+- 🧩 VS Code extension: **[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** (`deb-adarsh.ai-stack-kit`)
 - 🐛 Issues: [GitHub Issues](https://github.com/deb-adarsh/ai-stack-kit/issues)
 - ✉️ Maintainer: [debadarsh7@gmail.com](mailto:debadarsh7@gmail.com)
 

USER_GUIDE.md

@@ -8,6 +8,8 @@ Hands-on install, **`spec.yaml`** patterns, the full command surface, and troubl
 
 Install with **`npm install -g ai-stack-kit`** (**npm registry**) or **`npm install -g @deb-adarsh/ai-stack-kit`** (**GitHub registry** — see **[GitHub Packages](#github-packages)** below), or **`npm link`** from a clone.
 
+Prefer VS Code or Cursor without a global CLI? **[Install the extension from the Marketplace](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** — see **[VS Code / Cursor extension](#vs-code--cursor-extension)**.
+
 ```bash
 # Install (examples — pick one)
 # npm install -g ai-stack-kit                   # npm registry (public)
@@ -61,6 +63,33 @@ Browse and filter the default catalogs; copy-paste commands use **`npx github:de
 
 The UI reflects **`templates/sources.config.yaml`**: each deploy **re-queries those upstream skill trees** (GitHub Contents API / npm layouts), regenerates **`catalog.json`**, and publishes — so the demo tracks **upstream repos**, not a manually edited skill list. Your project’s **`sources.config.yaml`** and cache stay **separate**; use **`aistack catalog refresh`** locally to pull newly discovered IDs into **`spec.yaml`**. To propose another **public** upstream for the shared template, see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.
 
+### VS Code / Cursor extension
+
+**[Install AI Stack Kit from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=deb-adarsh.ai-stack-kit)** (publisher **deb-adarsh**, id **`deb-adarsh.ai-stack-kit`**).
+
+- **Marketplace:** open the link above and click **Install**, or use Quick Open (`Ctrl+P` / `Cmd+P`) → `ext install deb-adarsh.ai-stack-kit`
+- **Local dev:** build a `.vsix` from this repo (`npm run build:extension` → `cd extension && npm run vsix`) and install via **Extensions: Install from VSIX…**
+
+| UI area | What it does |
+|---------|----------------|
+| **Modules** tree | Reads `spec.yaml` — skills, subagents, hooks; enable/disable or remove from context menu |
+| **Outputs** tree | On-disk paths for the active `client.type` (e.g. `.github/skills/`, `.cursor/skills/`) |
+| **Catalog** webview | Bundled catalog snapshot; search, **Add to spec**, copy module id |
+
+**Typical flow:** open a folder → **AI Stack Kit: Initialize Workspace** → browse **Catalog** or **Search Catalog…** → **Sync**. Status bar: click **$(sync) AI Stack** to sync; right side shows `client.type` and module count (opens **Doctor**).
+
+**Settings** (Settings → Extensions → AI Stack Kit):
+
+| Setting | Purpose |
+|---------|---------|
+| `aiStackKit.clientType` | Default `cursor` / `copilot` / `claude` on init and **Switch Client** |
+| `aiStackKit.installScope` | `project` or `user` install roots |
+| `aiStackKit.githubToken` | PAT for catalog search (same as `GITHUB_TOKEN` for CLI) |
+| `aiStackKit.dryRun` | Preview sync without writing files |
+| `aiStackKit.autoSyncOnSave` | Run sync when `spec.yaml` is saved |
+
+**Developers:** `npm run build:extension` from repo root; **F5** in `extension/` launches the Extension Development Host. Integration tests: `npm run test:extension`.
+
 ---
 
 ## Example `spec.yaml`

docs/CLI_UX_FLOWS.md

@@ -1,6 +1,6 @@
 # CLI UX Flow Examples
 
-This document shows the exact user experience for each CLI command.
+This document shows the **target** user experience for each CLI command. Implemented today: `init`, `search`, `add` / typed `skill|subagent|hook`, `sync` (with `--dry-run`, `-v`, `--offline`, `--force`), `validate`, `status`, `doctor`, `clean`, `catalog refresh`. Placeholders: full `update`, registry publish.
 
 ---
 
@@ -32,10 +32,9 @@ $ aistack init
 
 ? Select client/IDE: 
 ❯ Cursor
-  VS Code
-  IntelliJ IDEA
-  Neovim
-  Other
+  GitHub Copilot (VS Code)
+  Claude
+  Other (advanced — defaults to cursor; edit spec.yaml)
 
 ⠋ Analyzing project...
 ✔ Found skill suggestions

extension/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["connor4312.esbuild-problem-matchers"]
+}

extension/.vscode/launch.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}", "${workspaceFolder}/test-workspace"],
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "preLaunchTask": "npm: compile"
+    }
+  ]
+}