iterate-skill-installer 2.1.3

package/README.md

@@ -0,0 +1,46 @@
+# iterate-skill-installer
+
+One-command installer for [iterate-skill](https://github.com/jingzhao-l/iterate-skill) across AI coding assistants.
+
+## Usage
+
+```bash
+# Interactive install — detects your AI assistants and lets you choose
+npx iterate-skill-installer
+
+# Install to a specific assistant only
+npx iterate-skill-installer --ai trae
+npx iterate-skill-installer --ai claude
+
+# Install into a project directory instead of globally
+npx iterate-skill-installer --target ./my-project
+
+# Force overwrite existing skill files
+npx iterate-skill-installer --force
+```
+
+## What it does
+
+1. Checks for Python 3 on your system.
+2. Fetches the latest iterate-skill release from GitHub.
+3. Downloads the release tarball and `SHA256SUMS.txt`.
+4. Verifies the tarball checksum.
+5. Extracts the release into a temporary directory.
+6. Runs the bundled Python install script (`scripts/install.py`) which:
+   - Detects installed AI coding assistants on your machine.
+   - Prompts you to select targets (default: all detected assistants).
+   - Copies the skill files into the correct skills directories.
+
+## Supported AI assistants
+
+Trae, Claude / Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, OpenCode, Aider, AiderDesk, Zed, Warp, Continue, Cline, Roo Code, Qoder, Augment, OpenClaw, Autohand Code CLI, IBM Bob, CodeArts Agent, Antigravity, Amp, Deep Agents, Kimi Code CLI, Astral.
+
+## Requirements
+
+- Node.js 18+
+- Python 3.9+
+- `tar` command available on PATH (available by default on macOS, Linux, Windows 10+)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * iterate-skill-installer CLI
+ *
+ * One-command installer for iterate-skill across AI coding assistants.
+ *
+ * Usage:
+ *   npx iterate-skill-installer
+ *   npx iterate-skill-installer --ai trae
+ *   npx iterate-skill-installer --target /path/to/project
+ *   npx iterate-skill-installer --global
+ *
+ * The installer downloads the latest GitHub release, verifies its SHA256
+ * checksum, then delegates file copying and assistant selection to the
+ * Python install script bundled in the release.
+ */
+
+const { main } = require('../lib/installer');
+
+function parseArgs(argv) {
+  const options = {
+    global: true,
+    ai: null,
+    target: null,
+    force: false,
+    token: process.env.GITHUB_TOKEN || null,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    switch (arg) {
+      case '--ai':
+        if (!next) {
+          console.error('Error: --ai requires a value');
+          process.exit(1);
+        }
+        options.ai = next;
+        i++;
+        break;
+      case '--target':
+        if (!next) {
+          console.error('Error: --target requires a value');
+          process.exit(1);
+        }
+        options.target = next;
+        options.global = false;
+        i++;
+        break;
+      case '--global':
+        options.global = true;
+        options.target = null;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--token':
+        if (!next) {
+          console.error('Error: --token requires a value');
+          process.exit(1);
+        }
+        options.token = next;
+        i++;
+        break;
+      case '-h':
+      case '--help':
+        printHelp();
+        process.exit(0);
+        break;
+      case '-v':
+      case '--version':
+        console.log(require('../package.json').version);
+        process.exit(0);
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Error: unknown option ${arg}`);
+          process.exit(1);
+        }
+        break;
+    }
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`
+Usage: npx iterate-skill-installer [options]
+
+Options:
+  --ai <assistant>    Install only to the specified assistant (e.g. trae, claude, cursor).
+  --target <path>     Install into a project directory instead of the global home dir.
+  --global            Install into the user's home directory (default).
+  --force             Overwrite existing skill files.
+  --token <token>     GitHub token for higher API rate limits.
+  -h, --help          Show this help message.
+  -v, --version       Show version.
+
+Examples:
+  npx iterate-skill-installer
+  npx iterate-skill-installer --ai trae
+  npx iterate-skill-installer --target ./my-project
+`);
+}
+
+async function run() {
+  const options = parseArgs(process.argv.slice(2));
+  try {
+    const code = await main(options);
+    process.exit(code);
+  } catch (err) {
+    console.error(`\nUnexpected error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+run();

package/lib/installer.js

@@ -0,0 +1,352 @@
+/**
+ * iterate-skill-installer — Node.js entry point for npx one-command install.
+ *
+ * This module orchestrates the cross-assistant installation of iterate-skill:
+ *   1. Detect Python / pip availability
+ *   2. Download the latest GitHub release tarball + checksum
+ *   3. Verify SHA256 checksum
+ *   4. Extract to a temporary directory
+ *   5. Run scripts/install.py to copy skill files into selected AI assistants
+ *
+ * The actual copy logic and interactive assistant selection live in the
+ * Python install script (scripts/install.py) so that behavior stays in one
+ * place and can be tested with the Python test suite.
+ */
+
+const { spawn, execFile } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const GITHUB_OWNER = 'jingzhao-l';
+const GITHUB_REPO = 'iterate-skill';
+const RELEASE_API_URL = `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/latest`;
+
+const ITERATE_BANNER = [
+  '██╗████████╗███████╗██████╗  █████╗ ████████╗███████╗',
+  '██║╚══██╔══╝██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝',
+  '██║   ██║   █████╗  ██████╔╝███████║   ██║   █████╗  ',
+  '██║   ██║   ██╔══╝  ██╔══██╗██╔══██║   ██║   ██╔══╝  ',
+  '██║   ██║   ███████╗██║  ██║██║  ██║   ██║   ███████╗',
+  '╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝',
+];
+
+class InstallerError extends Error {}
+
+function printBanner() {
+  console.log();
+  for (const line of ITERATE_BANNER) {
+    console.log(`\x1b[36m${line}\x1b[0m`);
+  }
+  console.log();
+}
+
+function info(message) {
+  console.log(`\x1b[34mℹ\x1b[0m  ${message}`);
+}
+
+function success(message) {
+  console.log(`\x1b[32m✓\x1b[0m  ${message}`);
+}
+
+function warning(message) {
+  console.log(`\x1b[33m⚠\x1b[0m  ${message}`);
+}
+
+function error(message) {
+  console.error(`\x1b[31m✗\x1b[0m  ${message}`);
+}
+
+function hint(message) {
+  console.log(`\x1b[2m   ${message}\x1b[0m`);
+}
+
+function step(message) {
+  console.log(`\x1b[36m◆\x1b[0m  ${message}`);
+}
+
+function frameSection(title, lines) {
+  const maxLen = Math.max(
+    title.length,
+    ...lines.map((l) => stripAnsi(l).length),
+  );
+  const innerWidth = maxLen + 2;
+  const top = `┌─ ${title} ${'─'.repeat(Math.max(0, innerWidth - title.length - 2))}┐`;
+  const bottom = `└${'─'.repeat(innerWidth + 1)}┘`;
+  console.log(top);
+  for (const line of lines) {
+    const visibleLen = stripAnsi(line).length;
+    const padding = ' '.repeat(Math.max(0, innerWidth - visibleLen));
+    console.log(`│ ${line}${padding}│`);
+  }
+  console.log(bottom);
+}
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+async function findPython() {
+  for (const bin of ['python3', 'python']) {
+    const found = await commandExists(bin);
+    if (found) return bin;
+  }
+  return null;
+}
+
+function commandExists(bin) {
+  return new Promise((resolve) => {
+    execFile(bin, ['--version'], (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+async function fetchJson(url, token) {
+  // Prefer curl over Node.js fetch because curl uses the system CA store
+  // and avoids Node-specific certificate issues in some environments.
+  const args = ['-sSL', '--fail-with-body', '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2022-11-28', '-H', 'User-Agent: iterate-skill-installer'];
+  if (token) {
+    args.push('-H', `Authorization: Bearer ${token}`);
+  }
+  args.push(url);
+  const stdout = await runCommand('curl', args);
+  try {
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new InstallerError(`Failed to parse GitHub API response: ${err.message}`);
+  }
+}
+
+async function downloadFile(url, destPath, token) {
+  const args = ['-sSL', '--fail-with-body', '-o', destPath, '-H', 'User-Agent: iterate-skill-installer'];
+  if (token) {
+    args.push('-H', `Authorization: Bearer ${token}`);
+  }
+  args.push(url);
+  await runCommand('curl', args);
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', reject);
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.pipe(hash);
+  });
+}
+
+function parseChecksums(text) {
+  const map = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    if (parts.length >= 2) {
+      map.set(parts[1], parts[0]);
+    }
+  }
+  return map;
+}
+
+function runCommand(bin, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: 'pipe', ...options });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (data) => { stdout += data.toString(); });
+    child.stderr?.on('data', (data) => { stderr += data.toString(); });
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(new InstallerError(`${bin} exited with ${code}: ${stderr || stdout}`));
+      }
+    });
+    child.on('error', reject);
+  });
+}
+
+async function extractTarball(tarballPath, destDir) {
+  // Use the system tar command (available on macOS, Linux, and Windows 10+).
+  // Strip the top-level directory so files land directly in destDir.
+  await runCommand('tar', ['-xzf', tarballPath, '-C', destDir, '--strip-components=1']);
+}
+
+function runPythonInstall(pythonBin, installScript, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(pythonBin, [installScript, 'install', ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, FORCE_COLOR: '1' },
+      ...options,
+    });
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve(code);
+      } else {
+        reject(new InstallerError(`Python install exited with code ${code}`));
+      }
+    });
+    child.on('error', reject);
+  });
+}
+
+async function cleanup(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // ignore cleanup errors
+  }
+}
+
+function getVenvPython(venvDir) {
+  const isWindows = process.platform === 'win32';
+  const pythonName = isWindows ? 'python.exe' : 'python';
+  return path.join(venvDir, isWindows ? 'Scripts' : 'bin', pythonName);
+}
+
+async function createVenv(pythonBin, venvDir) {
+  await runCommand(pythonBin, ['-m', 'venv', venvDir]);
+}
+
+async function installRequirements(pythonBin, requirementsPath) {
+  if (!fs.existsSync(requirementsPath)) return;
+  await runCommand(pythonBin, ['-m', 'pip', 'install', '--quiet', '--requirement', requirementsPath]);
+}
+
+async function main(options = {}) {
+  const { global: globalInstall = true, ai = null, token = null, target = null, force = false } = options;
+
+  printBanner();
+
+  step('Checking environment');
+  const pythonBin = await findPython();
+  if (!pythonBin) {
+    error('Python is required but was not found on PATH.');
+    hint('Install Python 3.9+ and ensure "python3" or "python" is available.');
+    return 1;
+  }
+  success(`Found Python: ${pythonBin}`);
+  frameSection('Environment', [
+    `\x1b[32m✓\x1b[0m Python: ${pythonBin}`,
+    `\x1b[34mℹ\x1b[0m Install mode: ${globalInstall ? 'global' : 'project'}`,
+  ]);
+
+  info('Fetching latest release from GitHub...');
+  let release;
+  try {
+    release = await fetchJson(RELEASE_API_URL, token);
+  } catch (err) {
+    error(`Could not fetch release info: ${err.message}`);
+    hint('You can set GITHUB_TOKEN for higher API rate limits.');
+    return 1;
+  }
+
+  const tag = release.tag_name;
+  if (!tag) {
+    error('Latest release has no tag.');
+    return 1;
+  }
+  success(`Latest release: ${tag}`);
+
+  const tarballUrl = release.tarball_url;
+  const checksumAsset = release.assets?.find((a) => a.name === 'SHA256SUMS.txt');
+
+  if (!tarballUrl) {
+    error('Release has no tarball URL.');
+    return 1;
+  }
+  if (!checksumAsset) {
+    error('Release is missing SHA256SUMS.txt asset.');
+    return 1;
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'iterate-skill-install-'));
+  const tarballPath = path.join(tmpDir, 'iterate-skill.tar.gz');
+  const checksumPath = path.join(tmpDir, 'SHA256SUMS.txt');
+
+  try {
+    info('Downloading release tarball...');
+    await downloadFile(tarballUrl, tarballPath, token);
+
+    info('Downloading checksums...');
+    await downloadFile(checksumAsset.browser_download_url, checksumPath, token);
+
+    info('Verifying checksum...');
+    const checksums = parseChecksums(fs.readFileSync(checksumPath, 'utf8'));
+    const expectedHash = checksums.get('iterate-skill.tar.gz');
+    if (!expectedHash) {
+      error('Checksum file does not contain iterate-skill.tar.gz');
+      return 1;
+    }
+    const actualHash = await sha256File(tarballPath);
+    if (actualHash.toLowerCase() !== expectedHash.toLowerCase()) {
+      error('Checksum mismatch — refusing to install.');
+      return 1;
+    }
+    success('Checksum verified.');
+    frameSection('Release', [
+      `\x1b[32m✓\x1b[0m Version: ${tag}`,
+      `\x1b[32m✓\x1b[0m SHA256 checksum verified`,
+    ]);
+
+    info('Extracting release...');
+    const sourceDir = path.join(tmpDir, 'source');
+    fs.mkdirSync(sourceDir, { recursive: true });
+    await extractTarball(tarballPath, sourceDir);
+    success('Release extracted.');
+
+    const installScript = path.join(sourceDir, 'scripts', 'install.py');
+    if (!fs.existsSync(installScript)) {
+      error(`Install script not found at ${installScript}`);
+      return 1;
+    }
+
+    info('Creating isolated Python environment...');
+    const venvDir = path.join(tmpDir, 'venv');
+    try {
+      await createVenv(pythonBin, venvDir);
+    } catch (err) {
+      error(`Could not create Python venv: ${err.message}`);
+      hint('Ensure the Python "venv" module is available.');
+      return 1;
+    }
+    const venvPython = getVenvPython(venvDir);
+
+    info('Installing Python dependencies...');
+    const requirementsPath = path.join(sourceDir, 'scripts', 'requirements.txt');
+    try {
+      await installRequirements(venvPython, requirementsPath);
+      success('Dependencies ready.');
+    } catch (err) {
+      error(`Could not install Python dependencies: ${err.message}`);
+      return 1;
+    }
+
+    const installArgs = [];
+    if (ai) installArgs.push('--ai', ai);
+    if (target) installArgs.push('--target', target);
+    if (force) installArgs.push('--force');
+    if (globalInstall) installArgs.push('--global');
+
+    info('Starting skill installation (Python installer)...');
+    await runPythonInstall(venvPython, installScript, installArgs, { cwd: sourceDir });
+    success('iterate-skill installation finished.');
+    frameSection('Done', [
+      `\x1b[32m✓\x1b[0m iterate-skill ${tag} installed`,
+      `  Run \x1b[36miterate onboard\x1b[0m in your project to initialize.`,
+    ]);
+    return 0;
+  } finally {
+    await cleanup(tmpDir);
+  }
+}
+
+module.exports = {
+  main,
+  ITERATE_BANNER,
+  InstallerError,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "iterate-skill-installer",
+  "version": "2.1.3",
+  "description": "One-command installer for iterate-skill across AI coding assistants",
+  "main": "lib/installer.js",
+  "bin": {
+    "iterate-skill-installer": "bin/cli.js",
+    "iterate-skill": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --check bin/cli.js && node --check lib/installer.js"
+  },
+  "keywords": [
+    "iterate-skill",
+    "ai-assistant",
+    "skills",
+    "claude",
+    "cursor",
+    "trae",
+    "windsurf",
+    "installer"
+  ],
+  "author": "jingzhao-l",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jingzhao-l/iterate-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
+  },
+  "homepage": "https://github.com/jingzhao-l/iterate-skill#readme"
+}