iterate-skill-installer 2.4.1 → 2.4.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jingzhao L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,6 +26,13 @@ npx iterate-skill-installer --target ./my-project
 
 # Force overwrite existing skill files
 npx iterate-skill-installer --force
+
+# Skill-only install — skip installing the iterate CLI
+npx iterate-skill-installer --no-cli
+
+# Show help / version
+npx iterate-skill-installer --help
+npx iterate-skill-installer --version
 ```
 
 ## What it does
@@ -42,12 +49,11 @@ npx iterate-skill-installer --force
 7. Installs the `iterate` CLI onto your PATH (prefers `pipx`, otherwise
    `pip install --user`) so you can run `iterate onboard` directly.
 
-> **Note:** the installer always puts the `iterate` CLI on your PATH so a single
+> **Note:** the installer normally puts the `iterate` CLI on your PATH so a single
 > command gives you both the skill and the CLI. If you **don't** want the CLI
-> auto-installed, use a manual install instead — copy `SKILL.md` + `config/` +
-> `scripts/` + `templates/` to your assistant dir, or run
-> `python scripts/install.py install` directly. If the CLI install fails, you can
-> still install it later with `pipx install .` or `pip install .` from a checkout.
+> auto-installed, pass `--no-cli` to install the skill only — you can install the
+> CLI later with `pipx install .` or `pip install .` from a checkout. If the CLI
+> install fails, you can still install it later the same way.
 
 ## Supported AI assistants
 
@@ -59,6 +65,14 @@ Trae, Claude / Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI,
 - Python 3.10+
 - `tar` command available on PATH (available by default on macOS, Linux, Windows 10+)
 
+## Release tarball structure
+
+The GitHub release asset `iterate-skill.tar.gz` must contain **exactly one
+top-level directory** (e.g. `iterate-skill/`). The installer extracts it with
+`tar --strip-components=1`, so a tarball with multiple top-level directories,
+or with entries whose path disappears after stripping the top level, is
+rejected instead of being silently mis-extracted.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -26,6 +26,13 @@ npx iterate-skill-installer --target ./my-project
 
 # 强制覆盖已有技能文件
 npx iterate-skill-installer --force
+
+# 仅安装技能 —— 跳过安装 iterate CLI
+npx iterate-skill-installer --no-cli
+
+# 查看帮助 / 版本
+npx iterate-skill-installer --help
+npx iterate-skill-installer --version
 ```
 
 ## 它做了什么
@@ -42,11 +49,10 @@ npx iterate-skill-installer --force
 7. 把 `iterate` CLI 安装到你的 PATH（优先 `pipx`，否则 `pip install --user`），
    以便你直接运行 `iterate onboard`。
 
-> **注意：** 安装器总是会把你 PATH 上的 `iterate` CLI 装好，所以一条命令就能同时
-> 得到技能和 CLI。如果**不**想自动安装 CLI，请改用手动安装——把
-> `SKILL.md` + `config/` + `scripts/` + `templates/` 复制到你的助手目录，或直接运行
-> `python scripts/install.py install`。如果 CLI 安装失败，你之后仍可从检出目录用
-> `pipx install .` 或 `pip install .` 补装。
+> **注意：** 安装器通常会在你 PATH 上装好 `iterate` CLI，这样一条命令就能同时
+> 得到技能和 CLI。如果**不**想自动安装 CLI，请加 `--no-cli` 只装技能——之后可从
+> 检出目录用 `pipx install .` 或 `pip install .` 补装。如果 CLI 安装失败，你之后
+> 也可用同样的方式补装。
 
 ## 支持的 AI 助手
 
@@ -58,6 +64,12 @@ Trae、Claude / Claude Code、Cursor、Windsurf、GitHub Copilot、Codex、Gemin
 - Python 3.10+
 - PATH 上存在 `tar` 命令（macOS、Linux、Windows 10+ 默认可用）
 
+## 发布 tarball 结构
+
+GitHub Release 资产 `iterate-skill.tar.gz` 必须**恰好包含一个顶层目录**（例如
+`iterate-skill/`）。安装器使用 `tar --strip-components=1` 解压，因此包含多个顶层
+目录、或条目在剥离顶层后路径为空的 tarball 会被拒绝，而不是被静默错误地解压。
+
 ## License / 许可证
 
 MIT

package/bin/cli.js

@@ -10,87 +10,14 @@
  *   npx iterate-skill-installer --ai trae
  *   npx iterate-skill-installer --target /path/to/project
  *   npx iterate-skill-installer --global
+ *   npx iterate-skill-installer --no-cli
  *
  * 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,
-    // 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++) {
-    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;
-        options.targetExplicit = true;
-        i++;
-        break;
-      case '--global':
-        options.global = true;
-        options.target = null;
-        options.globalExplicit = true;
-        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;
-}
+const { main, parseArgs, VERSION } = require('../lib/installer');
 
 function printHelp() {
   console.log(`
@@ -101,6 +28,7 @@ Options:
   --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.
+  --no-cli            Skip installing the iterate CLI (skill-only install).
   --token <token>     GitHub token for higher API rate limits.
   -h, --help          Show this help message.
   -v, --version       Show version.
@@ -109,11 +37,23 @@ Examples:
   npx iterate-skill-installer
   npx iterate-skill-installer --ai trae
   npx iterate-skill-installer --target ./my-project
+  npx iterate-skill-installer --no-cli
 `);
 }
 
 async function run() {
   const options = parseArgs(process.argv.slice(2));
+
+  if (options.mode === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (options.mode === 'version') {
+    console.log(`iterate-skill-installer ${VERSION}`);
+    process.exit(0);
+  }
+
   try {
     const code = await main(options);
     process.exit(code);

package/lib/installer.js

@@ -38,6 +38,10 @@ 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`;
 
+// 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;
+
 const ITERATE_BANNER = [
   '██╗████████╗███████╗██████╗  █████╗ ████████╗███████╗',
   '██║╚══██╔══╝██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝',
@@ -196,18 +200,48 @@ async function extractTarball(tarballPath, destDir) {
   // archive contents and refuse to extract any entry whose resolved path
   // escapes destDir (e.g. a "../" prefix). This keeps the installer
   // dependency-free while closing the theoretical escape vector.
+  //
+  // Extraction uses --strip-components=1, which relies on the archive having
+  // exactly one top-level directory (see README "Release tarball structure").
+  // Archives that violate that contract — multiple top-level directories, or
+  // entries with no path left after stripping — are rejected outright.
   const absoluteDest = path.resolve(destDir);
   fs.mkdirSync(absoluteDest, { recursive: true });
 
   // 1. List archive entries (no extraction yet).
   const listing = await runCommand('tar', ['-tzf', tarballPath]);
+  const entries = listing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (entries.length === 0) {
+    throw new InstallerError('Refusing to extract tarball: archive contains no entries.');
+  }
+
+  // 2. Enforce the single-top-level-directory contract required by
+  //    --strip-components=1.
+  const topLevelComponents = new Set(entries.map((entry) => entry.split('/')[0]));
+  if (topLevelComponents.size !== 1) {
+    const tops = [...topLevelComponents].join(', ');
+    throw new InstallerError(
+      `Refusing to extract tarball: expected exactly one top-level directory, found multiple (${tops}).`,
+    );
+  }
+  const topLevel = entries[0].split('/')[0];
 
-  // 2. Validate every entry stays inside destDir after stripping the single
+  // 3. Validate every entry stays inside destDir after stripping the single
   //    top-level directory component (--strip-components=1).
-  const entries = listing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   for (const entry of entries) {
     const stripped = entry.split('/').slice(1).join('/');
-    const resolved = path.resolve(absoluteDest, stripped || entry);
+    if (stripped === '') {
+      // The single top-level directory entry itself maps to destDir after
+      // stripping; any other entry that strips to an empty path is malformed.
+      const isTopLevelEntry = entry === topLevel || entry === `${topLevel}/`;
+      if (!isTopLevelEntry) {
+        throw new InstallerError(
+          `Refusing to extract tarball: entry "${entry}" has an empty path after stripping the top-level directory.`,
+        );
+      }
+      continue;
+    }
+    const resolved = path.resolve(absoluteDest, stripped);
     if (resolved !== absoluteDest && !resolved.startsWith(absoluteDest + path.sep)) {
       throw new InstallerError(
         `Refusing to extract tarball: entry "${entry}" escapes destination directory.`,
@@ -215,7 +249,7 @@ async function extractTarball(tarballPath, destDir) {
     }
   }
 
-  // 3. Now extract safely — the content has been validated above.
+  // 4. Now extract safely — the content has been validated above.
   await runCommand('tar', ['-xzf', tarballPath, '-C', absoluteDest, '--strip-components=1']);
 }
 
@@ -364,6 +398,97 @@ async function installRequirements(pythonBin, requirementsPath) {
   await runCommand(pythonBin, ['-m', 'pip', 'install', '--quiet', '--requirement', requirementsPath]);
 }
 
+/**
+ * Parse the installer's command-line arguments.
+ *
+ * Kept as a pure function (exported) so the flag surface — including the
+ * skill-only ``--no-cli`` switch — can be unit-tested without spawning the
+ * full download-and-install pipeline. ``process.exit`` is only reached for
+ * hard argument errors (e.g. a value-consuming flag missing its value).
+ */
+function parseArgs(argv) {
+  const options = {
+    global: true,
+    ai: null,
+    target: null,
+    force: false,
+    noCli: false,
+    token: process.env.GITHUB_TOKEN || null,
+    // Non-install action requested via -h/--help/-v/--version. bin/cli.js
+    // inspects this before running main() and exits 0 without installing.
+    mode: 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++) {
+    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;
+        options.targetExplicit = true;
+        i++;
+        break;
+      case '--global':
+        options.global = true;
+        options.target = null;
+        options.globalExplicit = true;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--no-cli':
+        // Skill-only install: skip the automated `iterate` CLI install so a
+        // user who only wants the skill is not surprised by a global install.
+        options.noCli = true;
+        break;
+      case '--help':
+      case '-h':
+        // Show usage and exit 0 (handled by bin/cli.js).
+        options.mode = 'help';
+        break;
+      case '--version':
+      case '-v':
+        // Print the package version and exit 0 (handled by bin/cli.js).
+        options.mode = 'version';
+        break;
+      case '--token':
+        if (!next) {
+          console.error('Error: --token requires a value');
+          process.exit(1);
+        }
+        options.token = next;
+        i++;
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Error: unknown option ${arg}`);
+          process.exit(1);
+        }
+        break;
+    }
+  }
+
+  return options;
+}
+
 async function main(options = {}) {
   printBanner();
 
@@ -372,7 +497,14 @@ async function main(options = {}) {
   // whether that directory is the target project.
   options = await resolveInstallMode(options);
 
-  const { global: globalInstall = true, ai = null, token = null, target = null, force = false } = options;
+  const {
+    global: globalInstall = true,
+    ai = null,
+    token = null,
+    target = null,
+    force = false,
+    noCli = false,
+  } = options;
 
   step('Checking environment');
   const pythonBin = await findPython();
@@ -495,8 +627,18 @@ async function main(options = {}) {
     }
     success('iterate-skill installation finished.');
 
-    // Install the iterate CLI so `iterate onboard` works right after install.
-    await installCli(pythonBin, sourceDir);
+    if (noCli) {
+      // Skill-only install: explain how to add the CLI later instead of
+      // silently installing it globally.
+      hint('Skipped installing the iterate CLI (--no-cli).');
+      hint('Install it later for `iterate onboard` with:  pipx install <repo>  (or)  pip install .');
+    } else {
+      // Install the iterate CLI so `iterate onboard` works right after
+      // install. Made explicit up front so skill-only users are not surprised
+      // by a global CLI install (skip with --no-cli).
+      step('Installing the iterate CLI (skip with --no-cli)');
+      await installCli(pythonBin, sourceDir);
+    }
 
     frameSection('Done', [
       `\x1b[32m✓\x1b[0m iterate-skill ${tag} installed`,
@@ -510,6 +652,8 @@ async function main(options = {}) {
 
 module.exports = {
   main,
+  parseArgs,
+  VERSION,
   ITERATE_BANNER,
   InstallerError,
   resolveInstallMode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-skill-installer",
-  "version": "2.4.1",
+  "version": "2.4.5",
   "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 } = require('../lib/installer');
+const { resolveInstallMode, parseChecksums, parseArgs } = require('../lib/installer');
 
 const originalCwd = process.cwd();
 const originalHome = os.homedir;
@@ -97,6 +97,29 @@ async function run() {
   assert.strictEqual(multi.get('b.txt'), 'bb');
 
   console.log('mode.test.js: all parseChecksums tests passed');
+
+  // parseArgs: --no-cli must toggle skill-only mode, and default to off.
+  assert.strictEqual(parseArgs([]).noCli, false, 'noCli should default to false');
+  assert.strictEqual(parseArgs(['--no-cli']).noCli, true, '--no-cli should set noCli');
+  assert.strictEqual(parseArgs(['--no-cli', '--force', '--global']).noCli, true, 'noCli persists with other flags');
+  assert.strictEqual(parseArgs(['--global']).noCli, false, 'unrelated flags do not set noCli');
+
+  // parseArgs: unrelated flag surface is preserved (target/global/ai/force).
+  const combo = parseArgs(['--ai', 'trae', '--target', '/proj', '--force']);
+  assert.strictEqual(combo.ai, 'trae', 'ai should parse');
+  assert.strictEqual(combo.target, '/proj', 'target should parse');
+  assert.strictEqual(combo.force, true, 'force should parse');
+  assert.strictEqual(combo.global, false, 'target forces project mode');
+
+  // parseArgs: --version/-v/--help/-h must set the corresponding mode instead
+  // of falling through to the unknown-option error.
+  assert.strictEqual(parseArgs([]).mode, null, 'mode should default to null');
+  assert.strictEqual(parseArgs(['--version']).mode, 'version', '--version should set version mode');
+  assert.strictEqual(parseArgs(['-v']).mode, 'version', '-v should set version mode');
+  assert.strictEqual(parseArgs(['--help']).mode, 'help', '--help should set help mode');
+  assert.strictEqual(parseArgs(['-h']).mode, 'help', '-h should set help mode');
+
+  console.log('mode.test.js: all parseArgs tests passed');
 }
 
 run().catch((err) => {