@adityaaria/spark 6.0.15 → 6.0.17

package/package.json

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

package/skills/using-spark/SKILL.md

@@ -49,6 +49,10 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
 
 **Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
 
+## Announcement Format
+When you invoke a skill, you MUST announce it to the developer using exactly this format as the very first thing you say:
+`spark detection 💥 Using [skill] to [purpose]`
+
 ```dot
 digraph skill_flow {
     "User message received" [shape=doublecircle];
@@ -57,7 +61,7 @@ digraph skill_flow {
     "Invoke brainstorming skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
     "Invoke the skill" [shape=box];
-    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Announce: 'spark detection 💥 Using [skill]...'" [shape=box];
     "Has checklist?" [shape=diamond];
     "Create a todo per item" [shape=box];
     "Follow skill exactly" [shape=box];
@@ -71,8 +75,8 @@ digraph skill_flow {
     "User message received" -> "Might any skill apply?";
     "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
     "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
-    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
-    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Invoke the skill" -> "Announce: 'spark detection 💥 Using [skill]...'";
+    "Announce: 'spark detection 💥 Using [skill]...'" -> "Has checklist?";
     "Has checklist?" -> "Create a todo per item" [label="yes"];
     "Has checklist?" -> "Follow skill exactly" [label="no"];
     "Create a todo per item" -> "Follow skill exactly";

package/src/cli/index.js

@@ -1,26 +1,20 @@
-import { parseArgs } from './parse-args.js';
 import { printHelp, printLine } from './output.js';
 import { runInstall } from './install.js';
 
-export async function run(argv, env) {
-  const options = parseArgs(argv);
-
-  if (options.help || options.command === 'help') {
+export async function run(argv = [], env = process.env) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
     printHelp();
     return;
   }
 
-  if (!options.command) {
-    printHelp();
-    return;
-  }
+  const [command, ...args] = argv;
 
-  if (options.command === 'install') {
-    await runInstall(options, env);
+  if (command === 'install') {
+    await runInstall(args, env);
     return;
   }
 
-  throw new Error(`Unknown command: ${options.command}`);
+  throw new Error(`Unknown command: ${command}`);
 }
 
 export { printLine };

package/src/cli/install.js

@@ -1,168 +1,40 @@
-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,
-    fs,
-    prompt: async (question) => askQuestion(question),
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function runInstall(args = [], env = process.env) {
+  return new Promise((resolve, reject) => {
+    const scriptPath = path.resolve(__dirname, '../../bin/spark-install.sh');
+    const child = spawn('bash', [scriptPath, ...args], {
+      stdio: 'inherit',
+      env,
+    });
+
+    let settled = false;
+
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      if (err.code === 'ENOENT') {
+        process.stderr.write(
+          'Error: "bash" command not found.\n\n' +
+          'SPARK native installer requires bash to run.\n' +
+          'If you are on Windows, please run this command inside WSL, Git Bash, or check README.md for manual installation instructions.\n'
+        );
+        process.exitCode = 1;
+        resolve();
+        return;
+      }
+      reject(err);
+    });
+
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      process.exitCode = code ?? 1;
+      resolve();
+    });
   });
-  const { adapter, source } = selection;
-  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(installPreview.plan, installPreview.metadata ?? {});
-    printSummary('Nothing changed', [bullet('No filesystem changes were made.')], 'info');
-    return;
-  }
-
-  if (typeof adapter.install !== 'function') {
-    throw new InstallerError(`Install flow for ${adapter.label} is not implemented yet.`);
-  }
-
-  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;
-  }
-
-  const installResult = await adapter.install({ options, env });
-
-  if (typeof adapter.verify === 'function') {
-    await adapter.verify({ options, env });
-  }
-  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 && 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('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

@@ -20,11 +20,14 @@ export function printLine(text = '') {
 
 export function printHelp() {
   printCommandHeader('Install');
-  printLine(labelValue('Usage', 'npx @adityaaria/spark install [--harness <name>] [--dry-run] [--yes] [--verbose]'));
+  printLine(labelValue('Usage', 'npx @adityaaria/spark install [options]'));
   printLine('');
-  printMuted('Without --harness, the installer will ask which AI assistance to target.');
+  printMuted('Wraps the native SPARK installer (bin/spark-install.sh).');
   printLine('');
-  printLine(labelValue('Supported', 'Claude Code, Codex CLI, VS Code, Cursor, Copilot CLI, OpenCode, Gemini CLI, Pi, Antigravity'));
+  printLine(labelValue('Options', '-g, --global    Install to global agent config (~/.agent/skills/)'));
+  printLine(labelValue('       ', '--force         Re-install even if already installed'));
+  printLine(labelValue('       ', '--dry-run       Show what would be done without making changes'));
+  printLine(labelValue('       ', '-h, --help      Show this help message'));
 }
 
 export function printCommandHeader(title) {

package/src/cli/parse-args.js

@@ -1,46 +0,0 @@
-export function parseArgs(argv) {
-  const args = [...argv];
-  const options = {
-    command: null,
-    help: false,
-    dryRun: false,
-    yes: false,
-    verbose: false,
-    harness: null,
-  };
-
-  while (args.length) {
-    const arg = args.shift();
-    if (arg === '--help' || arg === '-h') {
-      options.help = true;
-      continue;
-    }
-    if (arg === '--dry-run') {
-      options.dryRun = true;
-      continue;
-    }
-    if (arg === '--yes' || arg === '-y') {
-      options.yes = true;
-      continue;
-    }
-    if (arg === '--verbose' || arg === '-v') {
-      options.verbose = true;
-      continue;
-    }
-    if (arg === '--harness') {
-      options.harness = args.shift() ?? null;
-      continue;
-    }
-    if (arg.startsWith('--harness=')) {
-      options.harness = arg.slice('--harness='.length) || null;
-      continue;
-    }
-    if (!options.command) {
-      options.command = arg;
-      continue;
-    }
-    throw new Error(`Unknown argument: ${arg}`);
-  }
-
-  return options;
-}

package/src/cli/prompt.js

@@ -1,11 +0,0 @@
-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${formatPromptPrefix()}`);
-  } finally {
-    rl.close();
-  }
-}

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

@@ -1,68 +0,0 @@
-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,77 +0,0 @@
-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}`,
-    marketplaceName: 'spark-local',
-  };
-}
-
-function writeMarketplaceManifest(marketplaceRoot) {
-  const manifestPath = path.join(marketplaceRoot, '.agents', 'plugins', 'marketplace.json');
-  const manifest = {
-    name: 'spark-local',
-    interface: {
-      displayName: 'SPARK',
-      shortDescription: 'Local SPARK marketplace for Codex CLI',
-    },
-    plugins: [
-      {
-        name: 'spark',
-        source: {
-          source: 'local',
-          path: './plugins/spark',
-        },
-        policy: {
-          installation: 'AVAILABLE',
-          authentication: 'ON_INSTALL',
-        },
-        category: 'Productivity',
-      },
-    ],
-  };
-
-  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-}

package/src/installer/adapters/common.js

@@ -1,158 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { InstallerError } from '../errors.js';
-import fs from 'node:fs';
-import path from 'node:path';
-
-export function createAdapter({
-  id,
-  label,
-  kind,
-  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: commandList[0] ?? null,
-    commands: commandList,
-    manualSteps,
-    planInstall() {
-      return {
-        kind,
-        bootstrap,
-        installHint,
-        verifyHint,
-        successMessage,
-        command: commandList[0] ?? null,
-        commands: commandList,
-        manualSteps,
-        automatedSteps,
-        automated,
-      };
-    },
-    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.`);
-      }
-
-      const fsImpl = fs ?? nativeFs;
-      if (!dryRun) {
-        assertBinaryAvailability({ label, binaryNames, env, fsImpl });
-      }
-
-      let metadata = {};
-
-      if (typeof customInstall === 'function') {
-        metadata = (await customInstall({ cwd, env, fs, dryRun })) ?? {};
-      }
-
-      if (dryRun) {
-        return { plan: this.planInstall(), metadata };
-      }
-
-      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.error) {
-          throw new InstallerError(`${label} install failed: ${result.error.message}`);
-        }
-
-        if (result.status !== 0) {
-          throw new InstallerError(
-            `${label} install failed: ${result.stderr || result.stdout || 'unknown error'}`
-          );
-        }
-      }
-
-      return { plan: this.planInstall(), metadata };
-    },
-    async verify() {
-      return verifyHint;
-    },
-  };
-}
-
-const nativeFs = fs;
-
-function normalizeCommandList(commands, command) {
-  if (Array.isArray(commands) && commands.length > 0) {
-    return commands;
-  }
-
-  if (command) {
-    return [command];
-  }
-
-  return [];
-}
-
-function assertBinaryAvailability({ label, binaryNames, env, fsImpl }) {
-  if (!binaryNames || binaryNames.length === 0) {
-    return;
-  }
-
-  for (const binaryName of binaryNames) {
-    if (commandExists(binaryName, env, fsImpl)) {
-      return;
-    }
-  }
-
-  throw new InstallerError(`${label} is not installed or not on PATH. Install ${label} first, then rerun SPARK install.`);
-}
-
-function commandExists(commandName, env, fsImpl) {
-  const paths = String(env.PATH ?? '').split(path.delimiter).filter(Boolean);
-  const exts = process.platform === 'win32'
-    ? String(env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
-    : [''];
-
-  for (const dir of paths) {
-    for (const ext of exts) {
-      const candidate = path.join(dir, `${commandName}${ext}`);
-      try {
-        fsImpl.accessSync(candidate, fs.constants.X_OK);
-        return true;
-      } catch {
-        try {
-          fsImpl.accessSync(candidate, fs.constants.F_OK);
-          return true;
-        } catch {
-          continue;
-        }
-      }
-    }
-  }
-
-  return false;
-}
-
-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 ?? '')
-  );
-}