iterate-skill-installer 2.8.1 → 2.9.1

package/lib/installer.js

@@ -38,6 +38,15 @@ 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`;
 
+// Release asset filenames — named constants so the magic strings are not
+// scattered through the download / verify pipeline.
+const TARBALL_ASSET_NAME = 'iterate-skill.tar.gz';
+const CHECKSUMS_ASSET_NAME = 'SHA256SUMS.txt';
+
+// Hard cap on a single curl download: a misbehaving CDN or a corrupt release
+// must never hang the installer forever.
+const CURL_MAX_TIME_SECONDS = '120';
+
 // Package version read from package.json at runtime so the --version/-v flag
 // and the published npm version always stay in sync.
 const VERSION = require('../package.json').version;
@@ -127,7 +136,7 @@ function commandExists(bin) {
 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'];
+  const args = ['-sSL', '--fail-with-body', '--max-time', CURL_MAX_TIME_SECONDS, '-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}`);
   }
@@ -140,13 +149,26 @@ async function fetchJson(url, token) {
   }
 }
 
-async function downloadFile(url, destPath, token) {
-  const args = ['-sSL', '--fail-with-body', '-o', destPath, '-H', 'User-Agent: iterate-skill-installer'];
+/**
+ * Download a file with curl.
+ *
+ * When ``progress`` is enabled (used for the tarball), curl's ``--progress-bar``
+ * writes a live percentage bar straight to the terminal (stderr is inherited so
+ * the bar is visible; stdout stays captured for non-progress downloads).
+ */
+async function downloadFile(url, destPath, token, { progress = false } = {}) {
+  const args = ['-sSL', '--fail-with-body', '--max-time', CURL_MAX_TIME_SECONDS, '-o', destPath, '-H', 'User-Agent: iterate-skill-installer'];
+  if (progress) args.push('--progress-bar');
   if (token) {
     args.push('-H', `Authorization: Bearer ${token}`);
   }
   args.push(url);
-  await runCommand('curl', args);
+  if (progress) {
+    // Let curl write its progress bar directly to the terminal.
+    await runCommand('curl', args, { stdio: ['ignore', 'ignore', 'inherit'] });
+  } else {
+    await runCommand('curl', args);
+  }
 }
 
 function sha256File(filePath) {
@@ -166,11 +188,14 @@ function parseChecksums(text) {
     if (!trimmed) continue;
     const parts = trimmed.split(/\s+/);
     if (parts.length >= 2) {
-      // Strip the GNU tar binary-mode marker ('*') so that both
-      // "HASH  filename" and "HASH *filename" formats match the target
-      // filename, consistent with scripts/install.py (name.lstrip('*')).
-      const name = parts[1].replace(/^\*/, '');
-      map.set(name, parts[0]);
+      // Normalize the filename the same way scripts/install.py does
+      // (_parse_checksum): strip the GNU tar binary-mode marker ('*') and the
+      // './' prefix, then match on the basename so entries with a subpath or
+      // versioned component (e.g. "dist/iterate-skill.tar.gz" or
+      // "./iterate-skill.tar.gz") still resolve to the expected asset.
+      const normalized = parts[1].replace(/^\*/, '').replace(/^\.\//, '');
+      const basename = normalized.split('/').pop();
+      map.set(basename, parts[0]);
     }
   }
   return map;
@@ -412,7 +437,7 @@ async function resolveInstallMode(options, ask = askYesNo) {
   const home = os.homedir();
   if (cwd !== home) {
     const answer = await ask(
-      `当前目录 ${cwd} 看起来是项目目录，是否安装到此项目？(选择否则全局安装到用户目录)`,
+      `当前目录 ${cwd} 看起来是项目目录，是否安装到此项目？(输入 n 则全局安装到用户目录)`,
     );
     if (answer) {
       options.target = cwd;
@@ -437,6 +462,25 @@ async function installRequirements(pythonBin, requirementsPath) {
   await runCommand(pythonBin, ['-m', 'pip', 'install', '--quiet', '--requirement', requirementsPath]);
 }
 
+/**
+ * Build the argv passed to the Python installer (scripts/install.py install).
+ *
+ * Exported as a pure function so the flag surface — including the relative
+ * ``--target`` resolution — can be unit-tested without running the full
+ * download pipeline. A relative ``--target`` is resolved against the current
+ * working directory here because the Python installer runs with ``cwd`` set
+ * to the extracted release directory; passing the raw relative path would
+ * make it point at the wrong place.
+ */
+function buildPythonInstallArgs(options) {
+  const args = [];
+  if (options.ai) args.push('--ai', options.ai);
+  if (options.target) args.push('--target', path.resolve(options.target));
+  if (options.force) args.push('--force');
+  if (options.globalInstall) args.push('--global');
+  return args;
+}
+
 /**
  * Parse the installer's command-line arguments.
  *
@@ -468,24 +512,30 @@ function parseArgs(argv) {
 
     switch (arg) {
       case '--ai':
-        if (!next) {
-          console.error('Error: --ai requires a value');
+        if (!next || next.startsWith('-')) {
+          console.error('Error: --ai requires a value (a flag was found instead)');
           process.exit(1);
         }
         options.ai = next;
         i++;
         break;
       case '--target':
-        if (!next) {
-          console.error('Error: --target requires a value');
+        if (!next || next.startsWith('-')) {
+          console.error('Error: --target requires a value (a flag was found instead)');
           process.exit(1);
         }
+        if (options.globalExplicit) {
+          warning('--target overrides --global: installing into the project directory instead.');
+        }
         options.target = next;
         options.global = false;
         options.targetExplicit = true;
         i++;
         break;
       case '--global':
+        if (options.targetExplicit) {
+          warning('--global overrides --target: installing into the user home directory instead.');
+        }
         options.global = true;
         options.target = null;
         options.globalExplicit = true;
@@ -509,8 +559,8 @@ function parseArgs(argv) {
         options.mode = 'version';
         break;
       case '--token':
-        if (!next) {
-          console.error('Error: --token requires a value');
+        if (!next || next.startsWith('-')) {
+          console.error('Error: --token requires a value (a flag was found instead)');
           process.exit(1);
         }
         options.token = next;
@@ -521,6 +571,9 @@ function parseArgs(argv) {
           console.error(`Error: unknown option ${arg}`);
           process.exit(1);
         }
+        // A bare positional argument is not a valid installer flag; warn so a
+        // typo like "npx iterate-skill-installer trae" is not silently ignored.
+        warning(`Ignoring unexpected positional argument: ${arg}`);
         break;
     }
   }
@@ -575,34 +628,34 @@ async function main(options = {}) {
   }
   success(`Latest release: ${tag}`);
 
-  const tarballAsset = release.assets?.find((a) => a.name === 'iterate-skill.tar.gz');
-  const checksumAsset = release.assets?.find((a) => a.name === 'SHA256SUMS.txt');
+  const tarballAsset = release.assets?.find((a) => a.name === TARBALL_ASSET_NAME);
+  const checksumAsset = release.assets?.find((a) => a.name === CHECKSUMS_ASSET_NAME);
 
   if (!tarballAsset) {
-    error('Release is missing the iterate-skill.tar.gz asset.');
+    error(`Release is missing the ${TARBALL_ASSET_NAME} asset.`);
     return 1;
   }
   if (!checksumAsset) {
-    error('Release is missing SHA256SUMS.txt asset.');
+    error(`Release is missing ${CHECKSUMS_ASSET_NAME} 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');
+  const tarballPath = path.join(tmpDir, TARBALL_ASSET_NAME);
+  const checksumPath = path.join(tmpDir, CHECKSUMS_ASSET_NAME);
 
   try {
-    info('Downloading release tarball...');
-    await downloadFile(tarballAsset.browser_download_url, tarballPath, token);
+    info(`Downloading release tarball (${TARBALL_ASSET_NAME})...`);
+    await downloadFile(tarballAsset.browser_download_url, tarballPath, token, { progress: true });
 
     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');
+    const expectedHash = checksums.get(TARBALL_ASSET_NAME);
     if (!expectedHash) {
-      error('Checksum file does not contain iterate-skill.tar.gz');
+      error(`Checksum file does not contain ${TARBALL_ASSET_NAME}`);
       return 1;
     }
     const actualHash = await sha256File(tarballPath);
@@ -649,11 +702,7 @@ async function main(options = {}) {
       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');
+    const installArgs = buildPythonInstallArgs({ ai, target, force, globalInstall });
 
     info('Starting skill installation (Python installer)...');
     const installExit = await runPythonInstall(venvPython, installScript, installArgs, { cwd: sourceDir });
@@ -692,6 +741,7 @@ async function main(options = {}) {
 module.exports = {
   main,
   parseArgs,
+  buildPythonInstallArgs,
   VERSION,
   ITERATE_BANNER,
   InstallerError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-skill-installer",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "description": "One-command installer for iterate-skill across AI coding assistants",
   "main": "lib/installer.js",
   "bin": {

package/test/mode.test.js

@@ -9,7 +9,7 @@ const assert = require('node:assert');
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
-const { resolveInstallMode, parseChecksums, parseArgs } = require('../lib/installer');
+const { resolveInstallMode, parseChecksums, parseArgs, buildPythonInstallArgs } = require('../lib/installer');
 
 const originalCwd = process.cwd();
 const originalHome = os.homedir;
@@ -96,6 +96,17 @@ async function run() {
   assert.strictEqual(multi.get('a.txt'), 'aa');
   assert.strictEqual(multi.get('b.txt'), 'bb');
 
+  // './' prefix and subpath/basename matching must resolve like the Python
+  // side (scripts/install.py _parse_checksum), which matches on basename.
+  const dotSlash = parseChecksums('abc123  ./iterate-skill.tar.gz\n');
+  assert.strictEqual(dotSlash.get('iterate-skill.tar.gz'), 'abc123', './ prefix should parse');
+
+  const subpath = parseChecksums('abc123  dist/iterate-skill.tar.gz\n');
+  assert.strictEqual(subpath.get('iterate-skill.tar.gz'), 'abc123', 'subpath entries should match by basename');
+
+  const starredSubpath = parseChecksums('abc123  *./release/iterate-skill-1.2.3.tar.gz\n');
+  assert.strictEqual(starredSubpath.get('iterate-skill-1.2.3.tar.gz'), 'abc123', '*./ and versioned subpath should match by basename');
+
   console.log('mode.test.js: all parseChecksums tests passed');
 
   // parseArgs: --no-cli must toggle skill-only mode, and default to off.
@@ -119,7 +130,83 @@ async function run() {
   assert.strictEqual(parseArgs(['--help']).mode, 'help', '--help should set help mode');
   assert.strictEqual(parseArgs(['-h']).mode, 'help', '-h should set help mode');
 
+  // parseArgs: value-consuming flags must reject a following flag as their
+  // value instead of silently swallowing it (regression: `--ai --force`
+  // previously set ai='--force' and misled the Python side with an invalid
+  // choice). process.exit is stubbed so the error path is assertable.
+  const origExit = process.exit;
+  process.exit = (code) => {
+    throw new Error(`exit(${code})`);
+  };
+  try {
+    assert.throws(() => parseArgs(['--ai', '--force']), /exit\(1\)/, '--ai must reject a flag as its value');
+    assert.throws(() => parseArgs(['--target', '--global']), /exit\(1\)/, '--target must reject a flag as its value');
+    assert.throws(() => parseArgs(['--token', '--yes']), /exit\(1\)/, '--token must reject a flag as its value');
+    assert.throws(() => parseArgs(['--ai']), /exit\(1\)/, '--ai without a value must error');
+    assert.throws(() => parseArgs(['--token']), /exit\(1\)/, '--token without a value must error');
+  } finally {
+    process.exit = origExit;
+  }
+
+  // parseArgs: a bare positional argument must produce a warning instead of
+  // being silently ignored (fix: typos like "npx iterate-skill-installer trae").
+  const origLog = console.log;
+  const warnings = [];
+  console.log = (msg) => { warnings.push(msg); };
+  try {
+    const opts = parseArgs(['trae', '--force']);
+    assert.strictEqual(opts.force, true, 'known flags still parse alongside positionals');
+    assert.ok(
+      warnings.some((w) => w.includes('Ignoring unexpected positional argument: trae')),
+      `positional arg should warn, got: ${JSON.stringify(warnings)}`,
+    );
+  } finally {
+    console.log = origLog;
+  }
+
+  // parseArgs: --global + --target together must warn that the later flag wins.
+  const conflictLogs = [];
+  console.log = (msg) => { conflictLogs.push(msg); };
+  try {
+    const targetThenGlobal = parseArgs(['--target', '/proj', '--global']);
+    assert.strictEqual(targetThenGlobal.global, true, 'later --global wins');
+    assert.strictEqual(targetThenGlobal.target, null, 'later --global clears the target');
+    assert.ok(
+      conflictLogs.some((w) => w.includes('--global overrides --target')),
+      `conflict should warn, got: ${JSON.stringify(conflictLogs)}`,
+    );
+    const globalThenTarget = parseArgs(['--global', '--target', '/proj']);
+    assert.strictEqual(globalThenTarget.global, false, 'later --target wins');
+    assert.strictEqual(globalThenTarget.target, '/proj', 'later --target is kept');
+    assert.ok(
+      conflictLogs.some((w) => w.includes('--target overrides --global')),
+      `conflict should warn, got: ${JSON.stringify(conflictLogs)}`,
+    );
+  } finally {
+    console.log = origLog;
+  }
+
   console.log('mode.test.js: all parseArgs tests passed');
+
+  // buildPythonInstallArgs: a relative --target must be resolved against the
+  // current working directory (the Python installer runs with a different
+  // cwd, so the raw relative path would point at the wrong place).
+  const resolved = buildPythonInstallArgs({ ai: 'trae', target: 'rel/sub', force: true, globalInstall: false });
+  assert.deepStrictEqual(
+    resolved,
+    ['--ai', 'trae', '--target', path.resolve('rel/sub'), '--force'],
+    'relative --target should be resolved against cwd',
+  );
+  const globalArgs = buildPythonInstallArgs({ ai: null, target: null, force: false, globalInstall: true });
+  assert.deepStrictEqual(globalArgs, ['--global'], 'global flag should be forwarded');
+  assert.deepStrictEqual(
+    buildPythonInstallArgs({ ai: null, target: '/abs/target', force: false, globalInstall: false }),
+    ['--target', '/abs/target'],
+    'absolute --target is passed through unchanged',
+  );
+  assert.deepStrictEqual(buildPythonInstallArgs({ ai: null, target: null, force: false, globalInstall: false }), [], 'no flags -> empty argv');
+
+  console.log('mode.test.js: all buildPythonInstallArgs tests passed');
 }
 
 run().catch((err) => {