@adityaaria/spark 6.0.4 → 6.0.6

package/bin/spark.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { run } from '../src/cli/index.js';
+import { formatError } from '../src/cli/output.js';
 
 run(process.argv.slice(2), process.env).catch((error) => {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(`${formatError(error instanceof Error ? error.message : String(error))}\n`);
   process.exitCode = 1;
 });

package/package.json

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

package/src/cli/install.js

@@ -1,10 +1,22 @@
-import { printLine } from './output.js';
+import {
+  bullet,
+  commandText,
+  labelValue,
+  pathText,
+  printCommandHeader,
+  printLine,
+  printSection,
+  printSummary,
+  statusText,
+  step,
+} from './output.js';
 import { askQuestion } from './prompt.js';
 import { chooseHarness } from '../installer/detect.js';
 import { InstallerError } from '../installer/errors.js';
 import fs from 'node:fs';
 
 export async function runInstall(options, env) {
+  printCommandHeader('Install');
   const selection = await chooseHarness({
     forcedHarness: normalizeHarness(options.harness),
     env,
@@ -15,11 +27,14 @@ export async function runInstall(options, env) {
   const plan = adapter.planInstall();
 
   if (options.dryRun) {
-    printLine(`dry-run: selected adapter ${adapter.label} (${adapter.id})`);
-    printLine(`dry-run: selection source ${source}`);
-    printLine(`dry-run: would install SPARK for ${adapter.label}`);
-    printLine(`dry-run: bootstrap ${plan.bootstrap}`);
-    printLine('dry-run: no filesystem changes made');
+    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(installPreview.plan, installPreview.metadata ?? {});
+    printSummary('Nothing changed', [bullet('No filesystem changes were made.')], 'info');
     return;
   }
 
@@ -27,21 +42,116 @@ export async function runInstall(options, env) {
     throw new InstallerError(`Install flow for ${adapter.label} is not implemented yet.`);
   }
 
-  if (!plan.command) {
-    printLine(`No fully automated install command is available for ${adapter.label}.`);
-    printLine(`Install hint: ${plan.installHint}`);
-    printLine(`Verify hint: ${plan.verifyHint}`);
+  if (!plan.automated) {
+    printSection('Install');
+    printLine(labelValue('Harness', adapter.label));
+    printLine(statusText(`Interactive install is required for ${adapter.label}.`, 'warning'));
+    printPlanDetails(plan, {});
+    printSummary(
+      'Next step',
+      [bullet(`Complete the steps above inside ${adapter.label} and then start a fresh session.`)],
+      'warning'
+    );
     return;
   }
 
-  await adapter.install({ options, env });
+  const installResult = await adapter.install({ options, env });
   if (typeof adapter.verify === 'function') {
     await adapter.verify({ options, env });
   }
-  printLine(`Installed SPARK for ${adapter.label}.`);
+  const resolvedPlan = installResult?.plan ?? plan;
+  const metadata = installResult?.metadata ?? {};
+
+  printSection('Install');
+  printLine(labelValue('Harness', adapter.label));
+  printLine(statusText(resolvedPlan.successMessage ?? plan.successMessage, 'success'));
+  printPlanDetails(resolvedPlan, metadata);
+  printSummary(
+    'Ready',
+    buildReadyLines(adapter, resolvedPlan, metadata),
+    'success'
+  );
 }
 
 function normalizeHarness(harness) {
   if (!harness) return null;
   return String(harness).trim().toLowerCase();
 }
+
+function printPlanDetails(plan, metadata) {
+  if (plan.automated && plan.commands?.length) {
+    printLine('');
+    printSection('Commands');
+    for (const [index, command] of plan.commands.entries()) {
+      printLine(
+        step(
+          index + 1,
+          plan.commands.length,
+          commandText(formatCommand(command, metadata))
+        )
+      );
+    }
+  }
+
+  if (plan.automated && plan.automatedSteps?.length) {
+    printLine('');
+    printSection('Steps');
+    for (const [index, automatedStep] of plan.automatedSteps.entries()) {
+      printLine(step(index + 1, plan.automatedSteps.length, interpolatePlanText(automatedStep, metadata)));
+    }
+  }
+
+  if (!plan.automated && plan.manualSteps?.length) {
+    printLine('');
+    printSection('Steps');
+    for (const [index, manualStep] of plan.manualSteps.entries()) {
+      printLine(step(index + 1, plan.manualSteps.length, manualStep));
+    }
+  }
+
+  printLine('');
+  printSection('Notes');
+  printLine(labelValue('Install hint', plan.installHint));
+  printLine(labelValue('Verify hint', plan.verifyHint));
+  if (metadata.relativeTargetRoot) {
+    printLine(labelValue('Bundle path', pathText(metadata.relativeTargetRoot)));
+  }
+  if (metadata.relativeMarketplaceRoot) {
+    printLine(labelValue('Marketplace path', pathText(metadata.relativeMarketplaceRoot)));
+  }
+}
+
+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 ?? '')
+    .replaceAll('{marketplaceRoot}', metadata.marketplaceRoot ?? '')
+    .replaceAll('{relativeMarketplaceRoot}', metadata.relativeMarketplaceRoot ?? '')
+    .replaceAll('{marketplaceName}', metadata.marketplaceName ?? '');
+}
+
+function buildReadyLines(adapter, plan, metadata) {
+  const lines = [];
+
+  if (metadata.relativeTargetRoot) {
+    lines.push(bullet(`Plugin bundle staged at ${pathText(metadata.relativeTargetRoot)}.`));
+  }
+
+  if (metadata.relativeMarketplaceRoot) {
+    lines.push(bullet(`Local Codex marketplace staged at ${pathText(metadata.relativeMarketplaceRoot)}.`));
+  }
+
+  if (adapter.id === 'codex') {
+    lines.push(bullet('Start a fresh Codex 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

@@ -1,13 +1,117 @@
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  white: '\x1b[38;2;245;245;245m',
+  spark: '\x1b[38;2;255;107;53m',
+  accent: '\x1b[38;2;0;245;255m',
+  success: '\x1b[38;2;46;204;113m',
+  warning: '\x1b[38;2;255;215;0m',
+  error: '\x1b[38;2;255;71;87m',
+  pink: '\x1b[38;2;255;27;107m',
+  dimGray: '\x1b[38;2;107;114;128m',
+};
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR !== '1';
+
 export function printLine(text = '') {
   process.stdout.write(`${text}\n`);
 }
 
 export function printHelp() {
-  printLine('SPARK npm installer');
+  printCommandHeader('Install');
+  printLine(labelValue('Usage', 'npx @adityaaria/spark install [--harness <name>] [--dry-run] [--yes] [--verbose]'));
+  printLine('');
+  printMuted('Without --harness, the installer will ask which AI assistance to target.');
   printLine('');
-  printLine('Usage: npx @adityaaria/spark install [--harness <name>] [--dry-run] [--yes] [--verbose]');
+  printLine(labelValue('Supported', 'Codex, Cursor, Antigravity, Copilot, OpenCode, Gemini, Pi'));
+}
+
+export function printCommandHeader(title) {
+  printLine(styled('⚡', 'warning') + ' ' + styled('SPARK', 'spark', true) + ' ' + styled('›', 'dimGray') + ' ' + styled(title, 'white', true));
+  printLine(styled('Skills installer for coding agents', 'dimGray'));
   printLine('');
-  printLine('Without --harness, the installer will ask which AI assistance to target.');
+}
+
+export function printSection(title) {
+  printLine(styled(title, 'accent', true));
+}
+
+export function printSummary(title, lines = [], tone = 'info') {
+  const toneLabel = {
+    info: styled('ℹ', 'accent'),
+    success: styled('✓', 'success'),
+    warning: styled('•', 'warning'),
+    error: styled('✕', 'error'),
+  }[tone];
+
   printLine('');
-  printLine('Supported harnesses: Codex, Cursor, Antigravity, Copilot, OpenCode, Gemini, Pi');
+  printLine(`${toneLabel} ${styled(title, tone === 'error' ? 'error' : tone === 'success' ? 'success' : tone === 'warning' ? 'warning' : 'accent', true)}`);
+  for (const line of lines) {
+    printLine(`  ${line}`);
+  }
+}
+
+export function labelValue(label, value) {
+  return `${styled(`${label}:`, 'dimGray')}${value ? ` ${styled(value, 'white')}` : ''}`;
+}
+
+export function bullet(text, tone = 'dimGray') {
+  return `${styled('•', tone)} ${styled(text, 'white')}`;
+}
+
+export function step(index, total, text) {
+  return `${styled(`[${index}/${total}]`, 'spark', true)} ${styled(text, 'white')}`;
+}
+
+export function commandText(text) {
+  return styled(text, 'warning');
+}
+
+export function pathText(text) {
+  return styled(text, 'accent');
+}
+
+export function statusText(text, tone = 'white') {
+  return styled(text, tone);
+}
+
+export function printMuted(text) {
+  printLine(styled(text, 'dimGray'));
+}
+
+export function formatError(message) {
+  return `${styled('✕', 'error')} ${styled(message, 'error', true)}`;
+}
+
+export function formatPromptBlock(title, lines = [], footer = null) {
+  const output = [];
+  output.push(styled(title, 'accent', true));
+  output.push(styled('Choose the AI assistance you want SPARK to prepare.', 'dimGray'));
+  output.push('');
+  output.push(...lines);
+  if (footer) {
+    output.push('');
+    output.push(styled(footer, 'dimGray'));
+  }
+  return output.join('\n');
+}
+
+export function formatPromptPrefix() {
+  return `${styled('◆', 'spark')} ${styled('Select', 'pink', true)} ${styled('›', 'dimGray')} `;
+}
+
+export function promptOption(index, label, id, hint = null) {
+  const base = `${styled(`${index}.`, 'spark', true)} ${styled(label, 'white', true)} ${styled(`(${id})`, 'dimGray')}`;
+  return hint ? `${base} ${styled(hint, 'warning')}` : base;
+}
+
+function styled(text, tone, bold = false) {
+  if (!useColor) {
+    return text;
+  }
+
+  const color = COLORS[tone] ?? '';
+  const weight = bold ? COLORS.bold : '';
+  return `${weight}${color}${text}${COLORS.reset}`;
 }

package/src/cli/prompt.js

@@ -1,9 +1,10 @@
 import readline from 'node:readline/promises';
+import { formatPromptPrefix } from './output.js';
 
 export async function askQuestion(question, { input = process.stdin, output = process.stdout } = {}) {
   const rl = readline.createInterface({ input, output });
   try {
-    return await rl.question(`${question}\n> `);
+    return await rl.question(`${question}\n${formatPromptPrefix()}`);
   } finally {
     rl.close();
   }

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

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+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',
+  path.join('hooks', 'hooks-codex.json'),
+  path.join('hooks', 'run-hook.cmd'),
+  path.join('hooks', 'session-start-codex'),
+  'skills',
+];
+
+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);
+
+  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);
+
+      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: 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

@@ -8,52 +8,98 @@ export function createAdapter({
   bootstrap,
   installHint,
   verifyHint,
+  successMessage = `Installed SPARK for ${label}.`,
   command = null,
+  commands = [],
+  customInstall = null,
+  manualSteps = [],
+  automatedSteps = [],
   envKeys = [],
   binaryNames = [],
   configPaths = [],
 }) {
+  const commandList = normalizeCommandList(commands, command);
+  const automated = commandList.length > 0 || typeof customInstall === 'function';
+
   return {
     id,
     label,
     envKeys,
     binaryNames,
     configPaths,
-    command,
+    command: commandList[0] ?? null,
+    commands: commandList,
+    manualSteps,
     planInstall() {
       return {
         kind,
         bootstrap,
         installHint,
         verifyHint,
-        command,
+        successMessage,
+        command: commandList[0] ?? null,
+        commands: commandList,
+        manualSteps,
+        automatedSteps,
+        automated,
       };
     },
-    async install({ runner = spawnSync, dryRun = false } = {}) {
-      if (dryRun) {
-        return this.planInstall();
+    async install({ runner = spawnSync, dryRun = false, cwd = process.cwd(), env = process.env, fs = null } = {}) {
+      if (!automated) {
+        throw new InstallerError(`${label} install is not fully automatable yet.`);
       }
 
-      if (!command) {
-        throw new InstallerError(`${label} install is not fully automatable yet.`);
+      let metadata = {};
+
+      if (typeof customInstall === 'function') {
+        metadata = (await customInstall({ cwd, env, fs, dryRun })) ?? {};
+      }
+
+      if (dryRun) {
+        return { plan: this.planInstall(), metadata };
       }
 
-      const result = runner(command.file, command.args ?? [], {
-        cwd: command.cwd ?? process.cwd(),
-        env: command.env ?? process.env,
-        encoding: 'utf8',
-      });
+      for (const entry of commandList) {
+        const result = runner(entry.file, interpolateArgs(entry.args ?? [], metadata), {
+          cwd: entry.cwd ?? cwd,
+          env: entry.env ?? env,
+          encoding: 'utf8',
+        });
 
-      if (result.status !== 0) {
-        throw new InstallerError(
-          `${label} install failed: ${result.stderr || result.stdout || 'unknown error'}`
-        );
+        if (result.status !== 0) {
+          throw new InstallerError(
+            `${label} install failed: ${result.stderr || result.stdout || 'unknown error'}`
+          );
+        }
       }
 
-      return this.planInstall();
+      return { plan: this.planInstall(), metadata };
     },
     async verify() {
       return verifyHint;
     },
   };
 }
+
+function normalizeCommandList(commands, command) {
+  if (Array.isArray(commands) && commands.length > 0) {
+    return commands;
+  }
+
+  if (command) {
+    return [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,7 +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.',
+    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 });
+    },
   });
 }
 
@@ -42,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'],
@@ -59,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,4 +1,11 @@
 import { createAdapter } from './common.js';
+import { stageClaudePlugin } from './claude-staging.js';
+import { stageCodexPlugin } from './codex-staging.js';
+import { installCursorPlugin } from './cursor-staging.js';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 
 export function createClaudeCodeAdapter() {
   return createAdapter({
@@ -10,6 +17,25 @@ 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.',
+    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 });
+    },
   });
 }
 
@@ -23,6 +49,25 @@ export function createCodexAdapter() {
     bootstrap: 'shell hook -> hooks/session-start-codex -> using-spark',
     installHint: '.codex-plugin/plugin.json + hooks/hooks-codex.json + hooks/session-start-codex',
     verifyHint: 'Run a fresh Codex session and confirm using-spark loads before coding.',
+    successMessage: 'Installed SPARK for Codex.',
+    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 });
+    },
   });
 }
 
@@ -35,7 +80,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.',
+    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 });
+    },
   });
 }
 
@@ -49,9 +103,15 @@ export function createCopilotAdapter() {
     bootstrap: 'shell hook -> hooks/session-start -> using-spark',
     installHint: 'skills/using-spark/references/copilot-tools.md + hooks/session-start',
     verifyHint: 'Run a fresh Copilot CLI session and confirm using-spark loads before coding.',
-    command: {
-      file: 'copilot',
-      args: ['plugin', 'install', 'spark@spark-marketplace'],
-    },
+    commands: [
+      {
+        file: 'copilot',
+        args: ['plugin', 'marketplace', 'add', 'adityaaria/SPARK-marketplace'],
+      },
+      {
+        file: 'copilot',
+        args: ['plugin', 'install', 'spark@spark-marketplace'],
+      },
+    ],
   });
 }

package/src/installer/detect.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { formatPromptBlock, promptOption } from '../cli/output.js';
 import { getAdapterById, listAdapters } from './registry.js';
 import { InstallerError } from './errors.js';
 
@@ -146,12 +147,31 @@ function buildPromptCandidates(detectedCandidates) {
 }
 
 function renderPrompt(candidates, validationMessage = null) {
-  return [
-    ...(validationMessage ? [validationMessage] : []),
-    'Install SPARK for which AI assistance?',
-    ...candidates.map((candidate, index) => `${index + 1}. ${candidate.label} (${candidate.id})`),
-    'Enter a number or harness name:',
-  ].join('\n');
+  const lines = [];
+
+  if (validationMessage) {
+    lines.push(validationMessage);
+    lines.push('');
+  }
+
+  const detectedCount = candidates.filter((candidate) => candidate.score > 0).length;
+  const recommendedIds = new Set(candidates.filter((candidate) => candidate.score > 0).map((candidate) => candidate.id));
+
+  if (detectedCount > 0) {
+    lines.push('Recommended from your current environment:');
+    lines.push('');
+  }
+
+  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));
+  }
+
+  return formatPromptBlock(
+    'Install SPARK',
+    lines,
+    'Enter a number or harness name.'
+  );
 }
 
 function resolvePromptAnswer(answer, candidates) {