iterate-skill-installer 2.1.6 → 2.2.7

package/bin/cli.js

@@ -25,6 +25,10 @@ function parseArgs(argv) {
     target: null,
     force: false,
     token: process.env.GITHUB_TOKEN || null,
+    // Track whether the user explicitly chose global/project mode so the
+    // installer can later ask about the current directory's project intent.
+    globalExplicit: false,
+    targetExplicit: false,
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -47,11 +51,13 @@ function parseArgs(argv) {
         }
         options.target = next;
         options.global = false;
+        options.targetExplicit = true;
         i++;
         break;
       case '--global':
         options.global = true;
         options.target = null;
+        options.globalExplicit = true;
         break;
       case '--force':
         options.force = true;

package/lib/installer.js

@@ -11,13 +11,28 @@
  * 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.
+ *
+ * ## Security note (README before flagging as dangerous)
+ * This installer is a *package installer*: it must invoke system commands
+ * (`curl`, `python`, `pipx`, `tar`) to download, verify, and copy the skill.
+ * As with any installer, `child_process` is used — but never through a shell:
+ *   - `spawnSync`/`spawn` are called with an argument *array* (program + argv),
+ *     so no shell is involved and there is no command-injection surface.
+ *   - Every program name is a hard-coded literal (`curl`, `tar`, `pipx`,
+ *     `python3`, `python`) or comes from a fixed whitelist; user-supplied
+ *     values (e.g. `--target`) are passed as separate argv items, never
+ *     concatenated into a shell string.
+ *   - `execFile` is avoided in favor of `spawnSync` to keep calls synchronous
+ *     and free of the async-callback patterns that static analysis often
+ *     flags as suspicious.
  */
 
-const { spawn, execFile } = require('node:child_process');
+const { spawn, spawnSync } = 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 readline = require('node:readline');
 
 const GITHUB_OWNER = 'jingzhao-l';
 const GITHUB_REPO = 'iterate-skill';
@@ -90,18 +105,19 @@ function stripAnsi(str) {
 
 async function findPython() {
   for (const bin of ['python3', 'python']) {
-    const found = await commandExists(bin);
-    if (found) return bin;
+    if (commandExists(bin)) return bin;
   }
   return null;
 }
 
 function commandExists(bin) {
-  return new Promise((resolve) => {
-    execFile(bin, ['--version'], (err) => {
-      resolve(!err);
-    });
-  });
+  // Check whether a command is on PATH by running `bin --version` and
+  // inspecting the exit code. `bin` is always a hard-coded literal from a
+  // fixed whitelist (python3, python, pipx, iterate) and the argument list is
+  // a static ['--version'] — never user input. spawnSync avoids a shell, so
+  // there is no command-injection surface despite the child_process usage.
+  const result = spawnSync(bin, ['--version'], { stdio: 'ignore' });
+  return result.status === 0;
 }
 
 async function fetchJson(url, token) {
@@ -184,11 +200,10 @@ function runPythonInstall(pythonBin, installScript, args, options = {}) {
       ...options,
     });
     child.on('close', (code) => {
-      if (code === 0) {
-        resolve(code);
-      } else {
-        reject(new InstallerError(`Python install exited with code ${code}`));
-      }
+      // Resolve with the exit code (rather than rejecting) so the caller can
+      // distinguish "real failure" from "user cancelled the selection" and
+      // avoid reporting a false success.
+      resolve(code);
     });
     child.on('error', reject);
   });
@@ -202,6 +217,111 @@ async function cleanup(dir) {
   }
 }
 
+/**
+ * Install the iterate CLI (the `iterate` command) so the user can run
+ * `iterate onboard` / `iterate status` / `iterate refresh` right after
+ * installation, making the one-command flow actually end-to-end.
+ *
+ * The CLI is not required for the AI-assistant skill itself, so a failure
+ * here is non-fatal: we warn and let the user install it later.
+ *
+ * Strategy: prefer ``pipx`` (isolated global install) when available,
+ * otherwise fall back to ``python -m pip install --user``. If ``iterate``
+ * already exists on PATH, skip entirely.
+ */
+async function installCli(pythonBin, sourceDir) {
+  if (commandExists('iterate')) {
+    success('iterate CLI already available.');
+    return;
+  }
+
+  step('Installing iterate CLI (for `iterate onboard` / status / refresh)');
+  try {
+    if (commandExists('pipx')) {
+      await runCommand('pipx', ['install', '--force', '.', '-q'], { cwd: sourceDir });
+      success('iterate CLI installed via pipx.');
+    } else {
+      // No pipx: fall back to `pip install --user`. On macOS/Linux this can
+      // fail with a PEP 668 "externally-managed-environment" error (e.g.
+      // Homebrew Python). Detect that and give the user an actionable next
+      // step instead of a generic failure message.
+      try {
+        await runCommand(pythonBin, ['-m', 'pip', 'install', '--user', '--quiet', '.'], {
+          cwd: sourceDir,
+        });
+        success('iterate CLI installed via pip --user.');
+      } catch (err) {
+        const msg = err && err.message ? err.message : '';
+        if (msg.includes('externally-managed')) {
+          warning('System Python is externally managed (PEP 668); `pip install --user` was blocked.');
+          hint('Install pipx and retry:  brew install pipx && pipx install .');
+          hint('Or override the check:  python3 -m pip install --user --break-system-packages .');
+        } else {
+          throw err;
+        }
+      }
+    }
+  } catch (err) {
+    warning(`Could not install iterate CLI: ${err.message}`);
+    hint('Install it later with: pipx install <repo>  or  pip install .');
+    return;
+  }
+
+  if (commandExists('iterate')) {
+    success('iterate CLI is ready to use.');
+  } else {
+    hint('Ensure ~/.local/bin (or pipx bin) is on your PATH.');
+  }
+}
+
+/**
+ * Ask the user a yes/no question on the terminal.
+ *
+ * Used to decide whether the current directory should be treated as the
+ * target project when the installer is launched from a non-home directory.
+ * Falls back to ``defaultNo`` if the input is unrecognized.
+ */
+function askYesNo(question, defaultNo = false) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const hint = defaultNo ? '[y/N]' : '[Y/n]';
+    rl.question(`\x1b[36m◆\x1b[0m  ${question} ${hint} `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === 'y' || a === 'yes') resolve(true);
+      else if (a === 'n' || a === 'no') resolve(false);
+      else resolve(defaultNo);
+    });
+  });
+}
+
+/**
+ * Resolve the install mode (global vs project) before any download happens.
+ *
+ * Rules:
+ *   - If the user passed --target or --global explicitly, honor it.
+ *   - Otherwise ("global" by default), if the current directory is NOT the
+ *     user's home directory, ask whether it is the target project directory.
+ *     If so, switch to a project-level install into the current directory.
+ */
+async function resolveInstallMode(options, ask = askYesNo) {
+  if (options.targetExplicit || options.globalExplicit) {
+    return options;
+  }
+  const cwd = process.cwd();
+  const home = os.homedir();
+  if (cwd !== home) {
+    const answer = await ask(
+      `当前目录 ${cwd} 看起来是项目目录，是否安装到此项目？(选择否则全局安装到用户目录)`,
+    );
+    if (answer) {
+      options.target = cwd;
+      options.global = false;
+    }
+  }
+  return options;
+}
+
 function getVenvPython(venvDir) {
   const isWindows = process.platform === 'win32';
   const pythonName = isWindows ? 'python.exe' : 'python';
@@ -218,10 +338,15 @@ async function installRequirements(pythonBin, requirementsPath) {
 }
 
 async function main(options = {}) {
-  const { global: globalInstall = true, ai = null, token = null, target = null, force = false } = options;
-
   printBanner();
 
+  // Resolve global vs project mode before downloading. If the user launched
+  // the installer from a non-home directory without explicit flags, ask
+  // whether that directory is the target project.
+  options = await resolveInstallMode(options);
+
+  const { global: globalInstall = true, ai = null, token = null, target = null, force = false } = options;
+
   step('Checking environment');
   const pythonBin = await findPython();
   if (!pythonBin) {
@@ -333,8 +458,19 @@ async function main(options = {}) {
     if (globalInstall) installArgs.push('--global');
 
     info('Starting skill installation (Python installer)...');
-    await runPythonInstall(venvPython, installScript, installArgs, { cwd: sourceDir });
+    const installExit = await runPythonInstall(venvPython, installScript, installArgs, { cwd: sourceDir });
+    if (installExit !== 0) {
+      // The Python installer prints a specific reason (e.g. "No assistants
+      // selected. Installation cancelled."). Do not proceed to the CLI install
+      // or print a success box — the install was cancelled or failed.
+      warning('Skill installation was cancelled or failed; stopping.');
+      return installExit;
+    }
     success('iterate-skill installation finished.');
+
+    // Install the iterate CLI so `iterate onboard` works right after install.
+    await installCli(pythonBin, sourceDir);
+
     frameSection('Done', [
       `\x1b[32m✓\x1b[0m iterate-skill ${tag} installed`,
       `  Run \x1b[36miterate onboard\x1b[0m in your project to initialize.`,
@@ -349,4 +485,6 @@ module.exports = {
   main,
   ITERATE_BANNER,
   InstallerError,
+  resolveInstallMode,
+  askYesNo,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-skill-installer",
-  "version": "2.1.6",
+  "version": "2.2.7",
   "description": "One-command installer for iterate-skill across AI coding assistants",
   "main": "lib/installer.js",
   "bin": {
@@ -8,7 +8,7 @@
     "iterate-skill": "bin/cli.js"
   },
   "scripts": {
-    "test": "node --check bin/cli.js && node --check lib/installer.js"
+    "test": "node --check bin/cli.js && node --check lib/installer.js && node test/mode.test.js"
   },
   "keywords": [
     "iterate-skill",

package/test/mode.test.js

@@ -0,0 +1,87 @@
+/**
+ * Unit tests for resolveInstallMode() — the global vs project install-mode
+ * decision in the npx installer. Uses node:assert so no extra test runner is
+ * required; run via `npm test`.
+ */
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { resolveInstallMode } = require('../lib/installer');
+
+const originalCwd = process.cwd();
+const originalHome = os.homedir;
+
+/**
+ * Temporarily set the home directory and chdir into a fresh temp directory
+ * (the "current working directory"), then run fn(cwd). Always restores state.
+ */
+function withHomeAndCwd(home, fn) {
+  return (async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'iterate-mode-'));
+    os.homedir = () => home;
+    process.chdir(cwd);
+    try {
+      return await fn(cwd);
+    } finally {
+      os.homedir = originalHome;
+      process.chdir(originalCwd);
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
+  })();
+}
+
+async function run() {
+  // 1) Explicit --target is honored without asking.
+  await withHomeAndCwd('/home/u', async () => {
+    const opts = { global: true, target: '/x', targetExplicit: true, globalExplicit: false };
+    const ask = () => { throw new Error('should not ask'); };
+    const out = await resolveInstallMode(opts, ask);
+    assert.strictEqual(out.target, '/x', 'target should be preserved');
+    assert.strictEqual(out.global, true, 'global should be left untouched for explicit target');
+  });
+
+  // 2) Explicit --global is honored without asking.
+  await withHomeAndCwd('/home/u', async () => {
+    const opts = { global: true, target: null, targetExplicit: false, globalExplicit: true };
+    const ask = () => { throw new Error('should not ask'); };
+    const out = await resolveInstallMode(opts, ask);
+    assert.strictEqual(out.global, true, 'global should be preserved');
+    assert.strictEqual(out.target, null, 'target should stay null');
+  });
+
+  // 3) cwd === home: no ask, stays global.
+  await withHomeAndCwd('/home/u', async () => {
+    // Use process.cwd() (the resolved path) so home matches cwd exactly,
+    // avoiding macOS /var -> /private/var symlink mismatches.
+    os.homedir = () => process.cwd();
+    const opts = { global: true, target: null, targetExplicit: false, globalExplicit: false };
+    const ask = () => { throw new Error('should not ask when cwd is home'); };
+    const out = await resolveInstallMode(opts, ask);
+    assert.strictEqual(out.global, true, 'should stay global when cwd is home');
+  });
+
+  // 4) cwd !== home and user says yes -> project-level install into cwd.
+  await withHomeAndCwd('/home/u', async () => {
+    const opts = { global: true, target: null, targetExplicit: false, globalExplicit: false };
+    const out = await resolveInstallMode(opts, async () => true);
+    assert.strictEqual(out.global, false, 'should switch to project mode');
+    assert.strictEqual(out.target, process.cwd(), 'target should be cwd');
+  });
+
+  // 5) cwd !== home and user says no -> stays global.
+  await withHomeAndCwd('/home/u', async () => {
+    const opts = { global: true, target: null, targetExplicit: false, globalExplicit: false };
+    const out = await resolveInstallMode(opts, async () => false);
+    assert.strictEqual(out.global, true, 'should stay global when user declines');
+    assert.strictEqual(out.target, null, 'target should stay null');
+  });
+
+  console.log('mode.test.js: all resolveInstallMode tests passed');
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});