@adityaaria/spark 6.0.4 → 6.0.5

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.5",
   "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,13 @@ 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');
+    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, {});
+    printSummary('Nothing changed', [bullet('No filesystem changes were made.')], 'info');
     return;
   }
 
@@ -27,21 +41,100 @@ 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))));
+    }
+  }
+
+  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)));
+  }
+}
+
+function formatCommand(command) {
+  return [command.file, ...(command.args ?? [])].join(' ');
+}
+
+function interpolatePlanText(text, metadata) {
+  return String(text).replaceAll('{targetRoot}', metadata.targetRoot ?? '').replaceAll(
+    '{relativeTargetRoot}',
+    metadata.relativeTargetRoot ?? ''
+  );
+}
+
+function buildReadyLines(adapter, plan, metadata) {
+  const lines = [];
+
+  if (metadata.relativeTargetRoot) {
+    lines.push(bullet(`Plugin bundle staged at ${pathText(metadata.relativeTargetRoot)}.`));
+  }
+
+  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;
+  }
+
+  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/codex-staging.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CODEX_STAGE_DIR = path.join('.spark', 'codex-plugin');
+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 }) {
+  const targetRoot = path.join(cwd, CODEX_STAGE_DIR);
+
+  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: CODEX_STAGE_DIR,
+  };
+}

package/src/installer/adapters/common.js

@@ -8,52 +8,86 @@ 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 } = {}) {
+    async install({ runner = spawnSync, dryRun = false, cwd = process.cwd(), env = process.env, fs = null } = {}) {
       if (dryRun) {
-        return this.planInstall();
+        return { plan: this.planInstall(), metadata: {} };
       }
 
-      if (!command) {
+      if (!automated) {
         throw new InstallerError(`${label} install is not fully automatable yet.`);
       }
 
-      const result = runner(command.file, command.args ?? [], {
-        cwd: command.cwd ?? process.cwd(),
-        env: command.env ?? process.env,
-        encoding: 'utf8',
-      });
+      if (typeof customInstall === 'function') {
+        const metadata = await customInstall({ cwd, env, fs });
+        return { plan: this.planInstall(), metadata: metadata ?? {} };
+      }
+
+      for (const entry of commandList) {
+        const result = runner(entry.file, entry.args ?? [], {
+          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 [];
+}

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

@@ -11,6 +11,10 @@ export function createOpenCodeAdapter() {
     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.',
+    ],
   });
 }
 

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

@@ -1,4 +1,9 @@
 import { createAdapter } from './common.js';
+import { stageCodexPlugin } from './codex-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 +15,9 @@ 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',
+    ],
   });
 }
 
@@ -22,7 +30,15 @@ export function createCodexAdapter() {
     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: 'Run a fresh Codex session and confirm using-spark loads before coding.',
+    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.',
+    automatedSteps: [
+      'Stage a project-local Codex plugin bundle at .spark/codex-plugin.',
+      'Open Codex plugin install and point it at .spark/codex-plugin.',
+    ],
+    customInstall({ cwd }) {
+      return stageCodexPlugin({ cwd, packageRoot });
+    },
   });
 }
 
@@ -36,6 +52,9 @@ export function createCursorAdapter() {
     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',
+    ],
   });
 }
 
@@ -49,9 +68,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) {