iterate-skill-installer 2.4.3 → 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

@@ -29,6 +29,10 @@ 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
@@ -61,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

@@ -29,6 +29,10 @@ npx iterate-skill-installer --force
 
 # 仅安装技能 —— 跳过安装 iterate CLI
 npx iterate-skill-installer --no-cli
+
+# 查看帮助 / 版本
+npx iterate-skill-installer --help
+npx iterate-skill-installer --version
 ```
 
 ## 它做了什么
@@ -60,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

@@ -17,7 +17,7 @@
  * Python install script bundled in the release.
  */
 
-const { main, parseArgs } = require('../lib/installer');
+const { main, parseArgs, VERSION } = require('../lib/installer');
 
 function printHelp() {
   console.log(`
@@ -43,6 +43,17 @@ Examples:
 
 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']);
 }
 
@@ -380,6 +414,9 @@ function parseArgs(argv) {
     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,
@@ -422,6 +459,16 @@ function parseArgs(argv) {
         // 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');
@@ -606,6 +653,7 @@ 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.3",
+  "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

@@ -111,6 +111,14 @@ async function run() {
   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');
 }