@adityaaria/spark 6.0.5 → 6.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adityaaria/spark",
-  "version": "6.0.5",
+  "version": "6.0.7",
   "description": "SPARK skills and runtime bootstrap for coding agents",
   "type": "module",
   "publishConfig": {

package/src/cli/install.js

@@ -27,12 +27,13 @@ export async function runInstall(options, env) {
   const plan = adapter.planInstall();
 
   if (options.dryRun) {
+    const installPreview = await adapter.install({ dryRun: true, cwd: process.cwd(), env });
     printSection('Preview');
     printLine(labelValue('Mode', 'dry-run'));
     printLine(labelValue('Harness', `${adapter.label} (${adapter.id})`));
     printLine(labelValue('Selection', source));
     printLine(labelValue('Bootstrap', plan.bootstrap));
-    printPlanDetails(plan, {});
+    printPlanDetails(installPreview.plan, installPreview.metadata ?? {});
     printSummary('Nothing changed', [bullet('No filesystem changes were made.')], 'info');
     return;
   }
@@ -82,7 +83,13 @@ function printPlanDetails(plan, metadata) {
     printLine('');
     printSection('Commands');
     for (const [index, command] of plan.commands.entries()) {
-      printLine(step(index + 1, plan.commands.length, commandText(formatCommand(command))));
+      printLine(
+        step(
+          index + 1,
+          plan.commands.length,
+          commandText(formatCommand(command, metadata))
+        )
+      );
     }
   }
 
@@ -109,32 +116,52 @@ function printPlanDetails(plan, metadata) {
   if (metadata.relativeTargetRoot) {
     printLine(labelValue('Bundle path', pathText(metadata.relativeTargetRoot)));
   }
+  if (metadata.relativeMarketplaceRoot) {
+    printLine(labelValue('Marketplace path', pathText(metadata.relativeMarketplaceRoot)));
+  }
 }
 
-function formatCommand(command) {
-  return [command.file, ...(command.args ?? [])].join(' ');
+function formatCommand(command, metadata = {}) {
+  return [command.file, ...(command.args ?? [])]
+    .map((part) => interpolatePlanText(part, metadata))
+    .join(' ');
 }
 
 function interpolatePlanText(text, metadata) {
-  return String(text).replaceAll('{targetRoot}', metadata.targetRoot ?? '').replaceAll(
-    '{relativeTargetRoot}',
-    metadata.relativeTargetRoot ?? ''
-  );
+  return String(text)
+    .replaceAll('{targetRoot}', metadata.targetRoot ?? '')
+    .replaceAll('{relativeTargetRoot}', metadata.relativeTargetRoot ?? '')
+    .replaceAll('{marketplaceRoot}', metadata.marketplaceRoot ?? '')
+    .replaceAll('{relativeMarketplaceRoot}', metadata.relativeMarketplaceRoot ?? '')
+    .replaceAll('{marketplaceName}', metadata.marketplaceName ?? '');
 }
 
 function buildReadyLines(adapter, plan, metadata) {
   const lines = [];
 
-  if (metadata.relativeTargetRoot) {
+  if (metadata.relativeTargetRoot && adapter.id === 'vscode') {
+    lines.push(bullet(`Local VS Code bundle prepared at ${pathText(metadata.relativeTargetRoot)}.`));
+  } else if (metadata.relativeTargetRoot) {
     lines.push(bullet(`Plugin bundle staged at ${pathText(metadata.relativeTargetRoot)}.`));
   }
 
+  if (metadata.relativeMarketplaceRoot) {
+    lines.push(bullet(`Local marketplace staged at ${pathText(metadata.relativeMarketplaceRoot)}.`));
+  }
+
   if (adapter.id === 'codex') {
-    lines.push(bullet(`In Codex, install or import the local plugin from ${pathText(metadata.relativeTargetRoot ?? '.spark/codex-plugin')}.`));
     lines.push(bullet('Start a fresh Codex session to confirm using-spark loads before coding.'));
     return lines;
   }
 
+  if (adapter.id === 'vscode') {
+    if (metadata.relativeSettingsPath) {
+      lines.push(bullet(`VS Code plugin registration was written to ${pathText(metadata.relativeSettingsPath)}.`));
+    }
+    lines.push(bullet('Open a fresh VS Code agent session to confirm using-spark loads before coding.'));
+    return lines;
+  }
+
   lines.push(bullet('Start a fresh session in the selected harness to confirm using-spark loads before coding.'));
   return lines;
 }

package/src/cli/output.js

@@ -24,7 +24,7 @@ export function printHelp() {
   printLine('');
   printMuted('Without --harness, the installer will ask which AI assistance to target.');
   printLine('');
-  printLine(labelValue('Supported', 'Codex, Cursor, Antigravity, Copilot, OpenCode, Gemini, Pi'));
+  printLine(labelValue('Supported', 'Claude Code, Codex CLI, VS Code, Cursor, Copilot CLI, OpenCode, Gemini CLI, Pi, Antigravity'));
 }
 
 export function printCommandHeader(title) {
@@ -101,9 +101,15 @@ export function formatPromptPrefix() {
   return `${styled('◆', 'spark')} ${styled('Select', 'pink', true)} ${styled('›', 'dimGray')} `;
 }
 
-export function promptOption(index, label, id, hint = null) {
+export function promptOption(index, label, id, hint = null, detail = null) {
   const base = `${styled(`${index}.`, 'spark', true)} ${styled(label, 'white', true)} ${styled(`(${id})`, 'dimGray')}`;
-  return hint ? `${base} ${styled(hint, 'warning')}` : base;
+  const header = hint ? `${base} ${styled(hint, 'warning')}` : base;
+
+  if (!detail) {
+    return header;
+  }
+
+  return `${header}\n   ${styled(detail, 'dimGray')}`;
 }
 
 function styled(text, tone, bold = false) {

package/src/installer/adapters/claude-staging.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CLAUDE_MARKETPLACE_DIR = path.join('.spark', 'claude-marketplace');
+const CLAUDE_PLUGIN_DIR = path.join(CLAUDE_MARKETPLACE_DIR, 'plugins', 'spark');
+const COPY_PATHS = [
+  '.claude-plugin',
+  'assets',
+  path.join('hooks', 'hooks.json'),
+  path.join('hooks', 'run-hook.cmd'),
+  path.join('hooks', 'session-start'),
+  'skills',
+];
+
+export function stageClaudePlugin({ cwd = process.cwd(), packageRoot, dryRun = false }) {
+  const marketplaceRoot = path.join(cwd, CLAUDE_MARKETPLACE_DIR);
+  const targetRoot = path.join(cwd, CLAUDE_PLUGIN_DIR);
+
+  if (!dryRun) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+
+    for (const relativePath of COPY_PATHS) {
+      const sourcePath = path.join(packageRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      const stat = fs.statSync(sourcePath);
+
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, targetPath, { recursive: true });
+        continue;
+      }
+
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      fs.chmodSync(targetPath, stat.mode);
+    }
+
+    writeMarketplaceManifest(marketplaceRoot);
+  }
+
+  return {
+    targetRoot,
+    relativeTargetRoot: CLAUDE_PLUGIN_DIR,
+    marketplaceRoot,
+    relativeMarketplaceRoot: CLAUDE_MARKETPLACE_DIR,
+    marketplaceName: 'spark-local',
+  };
+}
+
+function writeMarketplaceManifest(marketplaceRoot) {
+  const manifestPath = path.join(marketplaceRoot, 'marketplace.json');
+  const manifest = {
+    name: 'spark-local',
+    plugins: [
+      {
+        name: 'spark',
+        description: 'SPARK local marketplace for Claude Code',
+        version: 'local',
+        source: './plugins/spark',
+        author: {
+          name: 'SPARK',
+        },
+      },
+    ],
+  };
+
+  fs.mkdirSync(marketplaceRoot, { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}

package/src/installer/adapters/codex-staging.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const CODEX_STAGE_DIR = path.join('.spark', 'codex-plugin');
+const CODEX_MARKETPLACE_DIR = path.join('.spark', 'codex-marketplace');
+const CODEX_PLUGIN_DIR = path.join(CODEX_MARKETPLACE_DIR, 'plugins', 'spark');
 const COPY_PATHS = [
   '.codex-plugin',
   'assets',
@@ -11,28 +12,61 @@ const COPY_PATHS = [
   'skills',
 ];
 
-export function stageCodexPlugin({ cwd = process.cwd(), packageRoot }) {
-  const targetRoot = path.join(cwd, CODEX_STAGE_DIR);
+export function stageCodexPlugin({ cwd = process.cwd(), packageRoot, dryRun = false }) {
+  const marketplaceRoot = path.join(cwd, CODEX_MARKETPLACE_DIR);
+  const targetRoot = path.join(cwd, CODEX_PLUGIN_DIR);
 
-  fs.mkdirSync(targetRoot, { recursive: true });
+  if (!dryRun) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+  }
+
+  if (!dryRun) {
+    for (const relativePath of COPY_PATHS) {
+      const sourcePath = path.join(packageRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      const stat = fs.statSync(sourcePath);
 
-  for (const relativePath of COPY_PATHS) {
-    const sourcePath = path.join(packageRoot, relativePath);
-    const targetPath = path.join(targetRoot, relativePath);
-    const stat = fs.statSync(sourcePath);
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, targetPath, { recursive: true });
+        continue;
+      }
 
-    if (stat.isDirectory()) {
-      fs.cpSync(sourcePath, targetPath, { recursive: true });
-      continue;
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      fs.chmodSync(targetPath, stat.mode);
     }
 
-    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    fs.copyFileSync(sourcePath, targetPath);
-    fs.chmodSync(targetPath, stat.mode);
+    writeMarketplaceManifest(marketplaceRoot);
   }
 
   return {
     targetRoot,
-    relativeTargetRoot: CODEX_STAGE_DIR,
+    relativeTargetRoot: CODEX_PLUGIN_DIR,
+    marketplaceRoot,
+    relativeMarketplaceRoot: CODEX_MARKETPLACE_DIR,
+  };
+}
+
+function writeMarketplaceManifest(marketplaceRoot) {
+  const manifestPath = path.join(marketplaceRoot, 'marketplace.json');
+  const manifest = {
+    name: 'spark-local',
+    plugins: [
+      {
+        name: 'spark',
+        source: {
+          source: 'local',
+          path: './plugins/spark',
+        },
+        policy: {
+          installation: 'AVAILABLE',
+          authentication: 'ON_INSTALL',
+        },
+        category: 'Productivity',
+      },
+    ],
   };
+
+  fs.mkdirSync(marketplaceRoot, { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 }

package/src/installer/adapters/common.js

@@ -45,21 +45,22 @@ export function createAdapter({
       };
     },
     async install({ runner = spawnSync, dryRun = false, cwd = process.cwd(), env = process.env, fs = null } = {}) {
-      if (dryRun) {
-        return { plan: this.planInstall(), metadata: {} };
-      }
-
       if (!automated) {
         throw new InstallerError(`${label} install is not fully automatable yet.`);
       }
 
+      let metadata = {};
+
       if (typeof customInstall === 'function') {
-        const metadata = await customInstall({ cwd, env, fs });
-        return { plan: this.planInstall(), metadata: metadata ?? {} };
+        metadata = (await customInstall({ cwd, env, fs, dryRun })) ?? {};
+      }
+
+      if (dryRun) {
+        return { plan: this.planInstall(), metadata };
       }
 
       for (const entry of commandList) {
-        const result = runner(entry.file, entry.args ?? [], {
+        const result = runner(entry.file, interpolateArgs(entry.args ?? [], metadata), {
           cwd: entry.cwd ?? cwd,
           env: entry.env ?? env,
           encoding: 'utf8',
@@ -72,7 +73,7 @@ export function createAdapter({
         }
       }
 
-      return { plan: this.planInstall(), metadata: {} };
+      return { plan: this.planInstall(), metadata };
     },
     async verify() {
       return verifyHint;
@@ -91,3 +92,14 @@ function normalizeCommandList(commands, command) {
 
   return [];
 }
+
+function interpolateArgs(args, metadata) {
+  return args.map((arg) =>
+    String(arg)
+      .replaceAll('{targetRoot}', metadata.targetRoot ?? '')
+      .replaceAll('{relativeTargetRoot}', metadata.relativeTargetRoot ?? '')
+      .replaceAll('{marketplaceRoot}', metadata.marketplaceRoot ?? '')
+      .replaceAll('{relativeMarketplaceRoot}', metadata.relativeMarketplaceRoot ?? '')
+      .replaceAll('{marketplaceName}', metadata.marketplaceName ?? '')
+  );
+}

package/src/installer/adapters/cursor-staging.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CURSOR_PLUGIN_DIR = path.join('.cursor', 'plugins', 'spark');
+const COPY_PATHS = [
+  '.cursor-plugin',
+  'assets',
+  path.join('hooks', 'hooks-cursor.json'),
+  path.join('hooks', 'run-hook.cmd'),
+  path.join('hooks', 'session-start'),
+  'skills',
+];
+
+export function installCursorPlugin({ packageRoot, env = process.env, dryRun = false }) {
+  const homeDir = env.HOME || env.USERPROFILE || os.homedir();
+  const targetRoot = path.join(homeDir, CURSOR_PLUGIN_DIR);
+
+  if (!dryRun) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+
+    for (const relativePath of COPY_PATHS) {
+      const sourcePath = path.join(packageRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      const stat = fs.statSync(sourcePath);
+
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, targetPath, { recursive: true });
+        continue;
+      }
+
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      fs.chmodSync(targetPath, stat.mode);
+    }
+  }
+
+  return {
+    targetRoot,
+    relativeTargetRoot: `~/${CURSOR_PLUGIN_DIR}`,
+  };
+}

package/src/installer/adapters/extension-style.js

@@ -1,4 +1,9 @@
 import { createAdapter } from './common.js';
+import { installOpenCodePlugin } from './opencode-staging.js';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 
 export function createOpenCodeAdapter() {
   return createAdapter({
@@ -10,11 +15,16 @@ export function createOpenCodeAdapter() {
     configPaths: ['opencode.json'],
     bootstrap: 'using-spark -> .opencode/plugins/spark.js -> message transform bootstrap',
     installHint: '.opencode/plugins/spark.js + .opencode/INSTALL.md',
-    verifyHint: 'Run opencode logs or a fresh OpenCode session and confirm bootstrap injection.',
-    manualSteps: [
-      'Add `spark@git+https://github.com/adityaaria/SPARK.git` to the `plugin` array in `opencode.json`.',
-      'Restart OpenCode.',
+    verifyHint: 'Restart OpenCode, then confirm spark loads in a fresh session.',
+    successMessage: 'Installed SPARK for OpenCode.',
+    automatedSteps: [
+      'Install the SPARK package into the OpenCode config directory.',
+      'Register the spark plugin entry inside the OpenCode plugins directory.',
+      'Restart OpenCode to load the plugin and skills.',
     ],
+    customInstall({ env, dryRun }) {
+      return installOpenCodePlugin({ packageRoot, env, dryRun });
+    },
   });
 }
 
@@ -46,6 +56,11 @@ export function createGeminiAdapter() {
     bootstrap: 'using-spark -> gemini-extension.json -> GEMINI.md context file',
     installHint: 'gemini-extension.json + GEMINI.md + references/gemini-tools.md',
     verifyHint: 'Run a fresh Gemini CLI session and confirm using-spark loads at session start.',
+    successMessage: 'Installed SPARK for Gemini CLI.',
+    automatedSteps: [
+      'Install the SPARK extension into Gemini CLI.',
+      'Start a fresh Gemini CLI session to confirm using-spark loads at startup.',
+    ],
     command: {
       file: 'gemini',
       args: ['extensions', 'install', 'https://github.com/adityaaria/SPARK'],
@@ -63,6 +78,11 @@ export function createAntigravityAdapter() {
     bootstrap: 'using-spark -> agy plugin install -> contextFileName bootstrap',
     installHint: 'skills/using-spark/references/antigravity-tools.md + plugin install flow',
     verifyHint: 'Run a fresh Antigravity session and confirm using-spark loads from the plugin install.',
+    successMessage: 'Installed SPARK for Antigravity.',
+    automatedSteps: [
+      'Install the SPARK plugin into Antigravity.',
+      'Start a fresh Antigravity session to confirm using-spark loads before coding.',
+    ],
     command: {
       file: 'agy',
       args: ['plugin', 'install', 'https://github.com/adityaaria/SPARK'],

package/src/installer/adapters/opencode-staging.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PACKAGE_DIR = 'spark';
+const SPARK_PLUGIN_FILE = path.join(PACKAGE_DIR, '.opencode', 'plugins', 'spark.js');
+
+export function installOpenCodePlugin({ packageRoot, env = process.env, dryRun = false }) {
+  const homeDir = env.HOME || env.USERPROFILE || os.homedir();
+  const configDir = env.OPENCODE_CONFIG_DIR
+    ? resolveHomeAwarePath(env.OPENCODE_CONFIG_DIR, homeDir)
+    : path.join(homeDir, '.config', 'opencode');
+
+  const sparkRoot = path.join(configDir, PACKAGE_DIR);
+  const pluginFile = path.join(configDir, SPARK_PLUGIN_FILE);
+  const registeredPlugin = path.join(configDir, 'plugins', 'spark.js');
+
+  if (!dryRun) {
+    fs.mkdirSync(sparkRoot, { recursive: true });
+    fs.cpSync(path.join(packageRoot, 'skills'), path.join(sparkRoot, 'skills'), { recursive: true });
+
+    fs.mkdirSync(path.dirname(pluginFile), { recursive: true });
+    fs.copyFileSync(path.join(packageRoot, '.opencode', 'plugins', 'spark.js'), pluginFile);
+
+    fs.mkdirSync(path.dirname(registeredPlugin), { recursive: true });
+    safeReplace(registeredPlugin);
+    fs.symlinkSync(pluginFile, registeredPlugin);
+  }
+
+  return {
+    targetRoot: sparkRoot,
+    relativeTargetRoot: simplifyHomePath(sparkRoot, homeDir),
+    pluginFile: simplifyHomePath(pluginFile, homeDir),
+    registeredPlugin: simplifyHomePath(registeredPlugin, homeDir),
+  };
+}
+
+function resolveHomeAwarePath(target, homeDir) {
+  if (target === '~') {
+    return homeDir;
+  }
+  if (target.startsWith('~/')) {
+    return path.join(homeDir, target.slice(2));
+  }
+  return path.resolve(target);
+}
+
+function simplifyHomePath(target, homeDir) {
+  if (target.startsWith(`${homeDir}${path.sep}`)) {
+    return `~/${path.relative(homeDir, target).split(path.sep).join('/')}`;
+  }
+  return target;
+}
+
+function safeReplace(target) {
+  try {
+    fs.rmSync(target, { force: true });
+  } catch {
+    // Ignore missing targets.
+  }
+}

package/src/installer/adapters/shell-hook.js

@@ -1,5 +1,8 @@
 import { createAdapter } from './common.js';
+import { stageClaudePlugin } from './claude-staging.js';
 import { stageCodexPlugin } from './codex-staging.js';
+import { installCursorPlugin } from './cursor-staging.js';
+import { installVsCodePlugin } from './vscode-staging.js';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -15,29 +18,76 @@ export function createClaudeCodeAdapter() {
     bootstrap: 'shell hook -> hooks/session-start -> using-spark',
     installHint: '.claude-plugin/plugin.json + hooks/hooks.json + hooks/session-start',
     verifyHint: 'Run a fresh Claude Code session and confirm using-spark loads before coding.',
-    manualSteps: [
-      '/plugin install spark@claude-plugins-official',
+    successMessage: 'Installed SPARK for Claude Code.',
+    commands: [
+      {
+        file: 'claude',
+        args: ['plugin', 'marketplace', 'add', '{relativeMarketplaceRoot}'],
+      },
+      {
+        file: 'claude',
+        args: ['plugin', 'install', 'spark@{marketplaceName}'],
+      },
+    ],
+    automatedSteps: [
+      'Stage a local Claude Code marketplace at .spark/claude-marketplace.',
+      'Register the local marketplace with Claude Code.',
+      'Install the spark plugin from that marketplace.',
     ],
+    customInstall({ cwd, dryRun }) {
+      return stageClaudePlugin({ cwd, packageRoot, dryRun });
+    },
   });
 }
 
 export function createCodexAdapter() {
   return createAdapter({
     id: 'codex',
-    label: 'Codex',
+    label: 'Codex CLI',
     kind: 'shell-hook',
     envKeys: ['CLAUDE_PLUGIN_ROOT'],
     binaryNames: ['codex'],
     bootstrap: 'shell hook -> hooks/session-start-codex -> using-spark',
     installHint: '.codex-plugin/plugin.json + hooks/hooks-codex.json + hooks/session-start-codex',
-    verifyHint: 'Open Codex plugin install, point it at .spark/codex-plugin, then confirm using-spark loads in a fresh session.',
-    successMessage: 'Staged SPARK for Codex in .spark/codex-plugin.',
+    verifyHint: 'Run a fresh Codex session and confirm using-spark loads before coding.',
+    successMessage: 'Installed SPARK for Codex CLI.',
+    commands: [
+      {
+        file: 'codex',
+        args: ['plugin', 'marketplace', 'add', '{relativeMarketplaceRoot}'],
+      },
+      {
+        file: 'codex',
+        args: ['plugin', 'add', 'spark'],
+      },
+    ],
+    automatedSteps: [
+      'Stage a local Codex marketplace at .spark/codex-marketplace.',
+      'Register the local marketplace with Codex.',
+      'Install the spark plugin from that marketplace.',
+    ],
+    customInstall({ cwd, dryRun }) {
+      return stageCodexPlugin({ cwd, packageRoot, dryRun });
+    },
+  });
+}
+
+export function createVsCodeAdapter() {
+  return createAdapter({
+    id: 'vscode',
+    label: 'VS Code',
+    kind: 'shell-hook',
+    bootstrap: 'workspace plugin bundle -> VS Code chat.pluginLocations -> hooks/session-start -> using-spark',
+    installHint: 'A Claude-compatible plugin bundle is staged locally and registered through .vscode/settings.json chat.pluginLocations.',
+    verifyHint: 'Open a fresh VS Code agent session and confirm using-spark loads before coding.',
+    successMessage: 'SPARK is ready in VS Code.',
     automatedSteps: [
-      'Stage a project-local Codex plugin bundle at .spark/codex-plugin.',
-      'Open Codex plugin install and point it at .spark/codex-plugin.',
+      'Prepare a local VS Code plugin bundle at .spark/vscode-plugin.',
+      'Register that bundle in .vscode/settings.json via chat.pluginLocations.',
+      'Start a fresh VS Code agent session so using-spark loads before coding.',
     ],
-    customInstall({ cwd }) {
-      return stageCodexPlugin({ cwd, packageRoot });
+    customInstall({ cwd, dryRun }) {
+      return installVsCodePlugin({ cwd, packageRoot, dryRun });
     },
   });
 }
@@ -51,10 +101,16 @@ export function createCursorAdapter() {
     binaryNames: ['cursor'],
     bootstrap: 'shell hook -> hooks/session-start -> using-spark',
     installHint: '.cursor-plugin/plugin.json + hooks/hooks-cursor.json + hooks/session-start',
-    verifyHint: 'Run a fresh Cursor Agent session and confirm using-spark loads before coding.',
-    manualSteps: [
-      '/add-plugin spark',
+    verifyHint: 'Restart Cursor fully, then confirm using-spark loads in a fresh Agent session.',
+    successMessage: 'Installed SPARK for Cursor.',
+    automatedSteps: [
+      'Copy the SPARK plugin into ~/.cursor/plugins/spark.',
+      'Restart Cursor fully to load the new plugin.',
+      'Start a fresh Cursor Agent session and confirm using-spark loads before coding.',
     ],
+    customInstall({ env, dryRun }) {
+      return installCursorPlugin({ packageRoot, env, dryRun });
+    },
   });
 }
 

package/src/installer/adapters/vscode-staging.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const VSCODE_PLUGIN_DIR = path.join('.spark', 'vscode-plugin');
+const SETTINGS_PATH = path.join('.vscode', 'settings.json');
+const COPY_PATHS = [
+  '.claude-plugin',
+  'assets',
+  path.join('hooks', 'hooks.json'),
+  path.join('hooks', 'run-hook.cmd'),
+  path.join('hooks', 'session-start'),
+  'skills',
+];
+
+export function installVsCodePlugin({ cwd = process.cwd(), packageRoot, dryRun = false }) {
+  const targetRoot = path.join(cwd, VSCODE_PLUGIN_DIR);
+  const settingsPath = path.join(cwd, SETTINGS_PATH);
+
+  if (!dryRun) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+
+    for (const relativePath of COPY_PATHS) {
+      const sourcePath = path.join(packageRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      const stat = fs.statSync(sourcePath);
+
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, targetPath, { recursive: true });
+        continue;
+      }
+
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      fs.chmodSync(targetPath, stat.mode);
+    }
+
+    writeVsCodeSettings(settingsPath, targetRoot);
+  }
+
+  return {
+    targetRoot,
+    relativeTargetRoot: VSCODE_PLUGIN_DIR,
+    settingsPath,
+    relativeSettingsPath: SETTINGS_PATH,
+  };
+}
+
+function writeVsCodeSettings(settingsPath, targetRoot) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  }
+
+  const pluginLocations = isPlainObject(settings['chat.pluginLocations'])
+    ? { ...settings['chat.pluginLocations'] }
+    : {};
+
+  pluginLocations[targetRoot] = true;
+  settings['chat.pluginLocations'] = pluginLocations;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/installer/detect.js

@@ -164,7 +164,15 @@ function renderPrompt(candidates, validationMessage = null) {
 
   for (const [index, candidate] of candidates.entries()) {
     const hint = recommendedIds.has(candidate.id) ? 'recommended' : null;
-    lines.push(promptOption(index + 1, candidate.label, candidate.id, hint));
+    lines.push(
+      promptOption(
+        index + 1,
+        candidate.label,
+        candidate.id,
+        hint,
+        describeHarness(candidate.id)
+      )
+    );
   }
 
   return formatPromptBlock(
@@ -189,6 +197,42 @@ function resolvePromptAnswer(answer, candidates) {
   return getAdapterById(exact.id);
 }
 
+function describeHarness(id) {
+  const descriptions = {
+    claude: 'Best for Claude Code sessions and project-local plugin workflows.',
+    codex: 'For the Codex CLI plugin marketplace flow in terminal sessions.',
+    vscode: 'One install path for VS Code agent sessions across Claude, Copilot, GPT, and other supported models.',
+    cursor: 'Native Cursor plugin install for fresh Agent sessions.',
+    copilot: 'For GitHub Copilot CLI in terminal-based agent sessions.',
+    opencode: 'Registers the OpenCode plugin in your local config directory.',
+    gemini: 'Installs the Gemini CLI extension and loads SPARK at startup.',
+    pi: 'Installs the Pi extension from the SPARK repository.',
+    antigravity: 'Installs the Antigravity plugin and loads SPARK on new sessions.',
+  };
+
+  return descriptions[id] ?? null;
+}
+
 function normalizeHarness(value) {
-  return String(value ?? '').trim().toLowerCase();
+  const normalized = String(value ?? '').trim().toLowerCase();
+
+  if (!normalized) {
+    return '';
+  }
+
+  const aliases = new Map([
+    ['codex cli', 'codex'],
+    ['codex-cli', 'codex'],
+    ['codex vscode', 'vscode'],
+    ['codex vs code', 'vscode'],
+    ['codex-vs-code', 'vscode'],
+    ['codex app', 'vscode'],
+    ['copilot vscode', 'vscode'],
+    ['copilot vs code', 'vscode'],
+    ['copilot-vs-code', 'vscode'],
+    ['vscode agent', 'vscode'],
+    ['vs code', 'vscode'],
+  ]);
+
+  return aliases.get(normalized) ?? normalized;
 }

package/src/installer/registry.js

@@ -3,6 +3,7 @@ import {
   createCodexAdapter,
   createCopilotAdapter,
   createCursorAdapter,
+  createVsCodeAdapter,
 } from './adapters/shell-hook.js';
 import {
   createAntigravityAdapter,
@@ -14,6 +15,7 @@ import {
 const ADAPTERS = [
   createClaudeCodeAdapter(),
   createCodexAdapter(),
+  createVsCodeAdapter(),
   createCursorAdapter(),
   createCopilotAdapter(),
   createOpenCodeAdapter(),