@adityaaria/spark 6.0.8 → 6.0.10

package/package.json

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

package/src/cli/install.js

@@ -56,6 +56,33 @@ export async function runInstall(options, env) {
   }
 
   const installResult = await adapter.install({ options, env });
+
+  // Handle global copy result
+  if (installResult?.globalCopy) {
+    printSection('Install');
+    printLine(labelValue('Harness', adapter.label));
+
+    if (installResult.cliSuccess) {
+      // Both global copy AND CLI succeeded — full install
+      printLine(statusText(`Installed SPARK for ${adapter.label}.`, 'success'));
+    } else {
+      // Global copy succeeded, CLI was skipped — still fully functional
+      printLine(statusText(`SPARK skills installed to ${installResult.globalSkillsPath}`, 'success'));
+    }
+
+    const readyLines = [
+      bullet(`SPARK skills and hooks copied to ${installResult.globalSkillsPath}.`),
+      bullet(`Open a fresh ${adapter.label} session to confirm using-spark loads before coding.`),
+    ];
+
+    if (installResult.cliSkipped) {
+      readyLines.push(bullet(`CLI integration skipped (optional — SPARK already works without it).`));
+    }
+
+    printSummary('Ready', readyLines, 'success');
+    return;
+  }
+
   if (typeof adapter.verify === 'function') {
     await adapter.verify({ options, env });
   }

package/src/installer/adapters/common.js

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { InstallerError } from '../errors.js';
+import { copyToGlobal } from './global-skills-copy.js';
 
 export function createAdapter({
   id,
@@ -17,6 +18,7 @@ export function createAdapter({
   envKeys = [],
   binaryNames = [],
   configPaths = [],
+  packageRoot = null,
 }) {
   const commandList = normalizeCommandList(commands, command);
   const automated = commandList.length > 0 || typeof customInstall === 'function';
@@ -59,6 +61,17 @@ export function createAdapter({
         return { plan: this.planInstall(), metadata };
       }
 
+      // Step 1: ALWAYS copy skills + hooks to global directory (primary mechanism)
+      let globalCopyResult = { copied: false };
+      if (packageRoot) {
+        try {
+          globalCopyResult = copyToGlobal(id, packageRoot, env);
+        } catch { /* global copy failed — will try CLI next */ }
+      }
+
+      // Step 2: Try CLI commands (optional bonus — for marketplace integration)
+      let cliSuccess = false;
+      let cliSkipped = false;
       for (const entry of commandList) {
         const result = runner(entry.file, interpolateArgs(entry.args ?? [], metadata), {
           cwd: entry.cwd ?? cwd,
@@ -66,11 +79,48 @@ export function createAdapter({
           encoding: 'utf8',
         });
 
+        if (result.error) {
+          if (result.error.code === 'ENOENT') {
+            // CLI not found — not a problem if global copy succeeded
+            cliSkipped = true;
+            break;
+          }
+          // Other errors — also non-fatal if global copy succeeded
+          if (globalCopyResult.copied) {
+            cliSkipped = true;
+            break;
+          }
+          throw new InstallerError(`${label} install failed: ${result.error.message}`);
+        }
+
         if (result.status !== 0) {
+          if (globalCopyResult.copied) {
+            cliSkipped = true;
+            break;
+          }
           throw new InstallerError(
             `${label} install failed: ${result.stderr || result.stdout || 'unknown error'}`
           );
         }
+
+        cliSuccess = true;
+      }
+
+      // Determine result type
+      if (globalCopyResult.copied) {
+        return {
+          plan: this.planInstall(),
+          metadata,
+          globalCopy: true,
+          globalSkillsPath: globalCopyResult.globalSkillsPath,
+          cliSuccess,
+          cliSkipped,
+        };
+      }
+
+      // Neither global copy nor CLI worked — nothing we can do
+      if (!cliSuccess && commandList.length > 0) {
+        throw new InstallerError(`${label} install failed: unable to copy skills or run CLI.`);
       }
 
       return { plan: this.planInstall(), metadata };

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

@@ -50,6 +50,7 @@ export function createGeminiAdapter() {
     id: 'gemini',
     label: 'Gemini CLI',
     kind: 'context-file',
+    packageRoot,
     envKeys: ['GEMINI_HOME', 'GOOGLE_GEMINI_CLI'],
     binaryNames: ['gemini'],
     configPaths: ['GEMINI.md', 'gemini-extension.json'],
@@ -73,6 +74,7 @@ export function createAntigravityAdapter() {
     id: 'antigravity',
     label: 'Antigravity',
     kind: 'context-file',
+    packageRoot,
     envKeys: ['ANTIGRAVITY_PLUGIN_ROOT'],
     binaryNames: ['agy'],
     bootstrap: 'using-spark -> agy plugin install -> contextFileName bootstrap',

package/src/installer/adapters/global-skills-copy.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Mapping of harness ID to its global directory structure.
+ * Each entry defines where skills and hooks should be copied
+ * so the harness discovers SPARK at session start.
+ */
+const GLOBAL_TARGETS = {
+  codex: {
+    skillsDir: path.join('.codex', 'skills'),
+    hooksDir: path.join('.codex', 'hooks'),
+    hookFiles: [
+      { src: 'hooks/hooks-codex.json', dest: 'hooks.json' },
+      { src: 'hooks/session-start-codex', dest: 'session-start-codex' },
+      { src: 'hooks/run-hook.cmd', dest: 'run-hook.cmd' },
+    ],
+    pluginDir: path.join('.codex', '.codex-plugin'),
+    pluginSrc: '.codex-plugin',
+  },
+  claude: {
+    skillsDir: path.join('.claude', 'skills'),
+    hooksDir: path.join('.claude', 'hooks'),
+    hookFiles: [
+      { src: 'hooks/hooks.json', dest: 'hooks.json' },
+      { src: 'hooks/session-start', dest: 'session-start' },
+      { src: 'hooks/run-hook.cmd', dest: 'run-hook.cmd' },
+    ],
+    pluginDir: path.join('.claude', '.claude-plugin'),
+    pluginSrc: '.claude-plugin',
+  },
+};
+
+/**
+ * Copy SPARK skills and hooks directly to a harness's global directory.
+ * This is a fallback mechanism used when the harness CLI is not available.
+ *
+ * @param {string} id - The harness identifier (e.g. 'codex', 'claude')
+ * @param {string} packageRoot - Absolute path to the SPARK package root
+ * @param {object} env - Process environment (to resolve HOME)
+ * @returns {{ globalSkillsPath: string, globalHooksPath: string, copied: boolean }}
+ */
+export function copyToGlobal(id, packageRoot, env = process.env) {
+  const target = GLOBAL_TARGETS[id];
+  if (!target) {
+    return { globalSkillsPath: null, globalHooksPath: null, copied: false };
+  }
+
+  const homeDir = env.HOME || env.USERPROFILE || os.homedir();
+  const globalSkillsPath = path.join(homeDir, target.skillsDir);
+  const globalHooksPath = path.join(homeDir, target.hooksDir);
+
+  // 1. Copy skills
+  const sourceSkills = path.join(packageRoot, 'skills');
+  fs.cpSync(sourceSkills, globalSkillsPath, { recursive: true });
+
+  // 2. Copy hooks
+  fs.mkdirSync(globalHooksPath, { recursive: true });
+  for (const hookFile of target.hookFiles) {
+    const src = path.join(packageRoot, hookFile.src);
+    const dest = path.join(globalHooksPath, hookFile.dest);
+    fs.copyFileSync(src, dest);
+    // Preserve executable permission for shell scripts
+    const stat = fs.statSync(src);
+    fs.chmodSync(dest, stat.mode);
+  }
+
+  // 3. Copy plugin descriptor (e.g. .codex-plugin/)
+  if (target.pluginDir && target.pluginSrc) {
+    const srcPlugin = path.join(packageRoot, target.pluginSrc);
+    const destPlugin = path.join(homeDir, target.pluginDir);
+    fs.cpSync(srcPlugin, destPlugin, { recursive: true });
+  }
+
+  return { globalSkillsPath, globalHooksPath, copied: true };
+}

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

@@ -13,6 +13,7 @@ export function createClaudeCodeAdapter() {
     id: 'claude',
     label: 'Claude Code',
     kind: 'shell-hook',
+    packageRoot,
     envKeys: ['CLAUDE_PLUGIN_ROOT'],
     binaryNames: ['claude'],
     bootstrap: 'shell hook -> hooks/session-start -> using-spark',
@@ -45,6 +46,7 @@ export function createCodexAdapter() {
     id: 'codex',
     label: 'Codex CLI',
     kind: 'shell-hook',
+    packageRoot,
     envKeys: ['CLAUDE_PLUGIN_ROOT'],
     binaryNames: ['codex'],
     bootstrap: 'shell hook -> hooks/session-start-codex -> using-spark',
@@ -119,6 +121,7 @@ export function createCopilotAdapter() {
     id: 'copilot',
     label: 'Copilot CLI',
     kind: 'shell-hook',
+    packageRoot,
     envKeys: ['COPILOT_CLI'],
     binaryNames: ['copilot'],
     bootstrap: 'shell hook -> hooks/session-start -> using-spark',

package/src/installer/detect.js

@@ -33,8 +33,9 @@ export async function chooseHarness({
     throw new InstallerError('No harness selected. Re-run with --harness or use an interactive terminal.');
   }
 
+  const homeDir = os.homedir();
   const detectedCandidates = detectHarnessCandidates({ env, fsImpl: fs });
-  const candidates = buildPromptCandidates(detectedCandidates);
+  const candidates = buildPromptCandidates(detectedCandidates, env, fs, homeDir);
 
   let validationMessage = null;
   while (true) {
@@ -51,6 +52,8 @@ function scoreAdapter(adapter, env, fsImpl, homeDir) {
   let score = 0;
   const reasons = [];
 
+  let missingBinaries = false;
+
   for (const key of adapter.envKeys) {
     if (env[key]) {
       score += 100;
@@ -58,10 +61,15 @@ function scoreAdapter(adapter, env, fsImpl, homeDir) {
     }
   }
 
-  for (const binaryName of adapter.binaryNames) {
-    if (commandExists(binaryName, env, fsImpl)) {
-      score += 70;
-      reasons.push(`path:${binaryName}`);
+  if (adapter.binaryNames && adapter.binaryNames.length > 0) {
+    missingBinaries = true;
+    for (const binaryName of adapter.binaryNames) {
+      if (commandExists(binaryName, env, fsImpl)) {
+        score += 70;
+        reasons.push(`path:${binaryName}`);
+        missingBinaries = false;
+        break;
+      }
     }
   }
 
@@ -80,6 +88,7 @@ function scoreAdapter(adapter, env, fsImpl, homeDir) {
     label: adapter.label,
     score,
     reasons,
+    missingBinaries,
   };
 }
 
@@ -129,7 +138,7 @@ function commandExists(commandName, env, fsImpl) {
   return false;
 }
 
-function buildPromptCandidates(detectedCandidates) {
+function buildPromptCandidates(detectedCandidates, env, fsImpl, homeDir) {
   const allAdapters = listAdapters();
   const detectedIds = new Set(detectedCandidates.map((candidate) => candidate.id));
 
@@ -137,12 +146,12 @@ function buildPromptCandidates(detectedCandidates) {
     ...detectedCandidates,
     ...allAdapters
       .filter((adapter) => !detectedIds.has(adapter.id))
-      .map((adapter) => ({
-        id: adapter.id,
-        label: adapter.label,
-        score: 0,
-        reasons: [],
-      })),
+      .map((adapter) => {
+        const result = scoreAdapter(adapter, env, fsImpl, homeDir);
+        result.score = 0;
+        result.reasons = [];
+        return result;
+      }),
   ];
 }
 
@@ -163,14 +172,19 @@ function renderPrompt(candidates, validationMessage = null) {
   }
 
   for (const [index, candidate] of candidates.entries()) {
+    let label = candidate.label;
+    if (candidate.missingBinaries) {
+      label += ' [Missing CLI]';
+    }
+
     const hint = recommendedIds.has(candidate.id) ? 'recommended' : null;
     lines.push(
       promptOption(
         index + 1,
-        candidate.label,
+        label,
         candidate.id,
         hint,
-        describeHarness(candidate.id)
+        describeHarness(candidate.id, candidate.missingBinaries)
       )
     );
   }
@@ -197,7 +211,7 @@ function resolvePromptAnswer(answer, candidates) {
   return getAdapterById(exact.id);
 }
 
-function describeHarness(id) {
+function describeHarness(id, missingBinaries = false) {
   const descriptions = {
     claude: 'Best for Claude Code sessions and project-local plugin workflows.',
     codex: 'For the Codex CLI plugin marketplace flow in terminal sessions.',
@@ -210,7 +224,12 @@ function describeHarness(id) {
     antigravity: 'Installs the Antigravity plugin and loads SPARK on new sessions.',
   };
 
-  return descriptions[id] ?? null;
+  let description = descriptions[id] ?? null;
+  if (description && missingBinaries) {
+    description += '\n   ⚠️  Requires its official CLI to be installed first.';
+  }
+
+  return description;
 }
 
 function normalizeHarness(value) {