claudekit-cli 1.2.1 → 1.3.0

package/package.json

@@ -1,20 +1,20 @@
 {
 	"name": "claudekit-cli",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "CLI tool for bootstrapping and updating ClaudeKit projects",
 	"type": "module",
 	"bin": {
 		"ck": "./dist/index.js"
 	},
 	"scripts": {
-		"dev": "bun run src/index.ts",
-		"build": "bun build src/index.ts --outdir dist --target node --external unzipper --external keytar --external @octokit/rest",
-		"compile": "bun build src/index.ts --compile --outfile ck",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"lint": "biome check .",
-		"format": "biome format --write .",
-		"typecheck": "tsc --noEmit"
+		"dev": "bun run src/index.ts >> logs.txt 2>&1",
+		"build": "bun build src/index.ts --outdir dist --target node --external keytar --external @octokit/rest >> logs.txt 2>&1",
+		"compile": "bun build src/index.ts --compile --outfile ck >> logs.txt 2>&1",
+		"test": "bun test >> logs.txt 2>&1",
+		"test:watch": "bun test --watch >> logs.txt 2>&1",
+		"lint": "biome check . >> logs.txt 2>&1",
+		"format": "biome format --write . >> logs.txt 2>&1",
+		"typecheck": "tsc --noEmit >> logs.txt 2>&1"
 	},
 	"keywords": [
 		"cli",
@@ -33,6 +33,7 @@
 		"@octokit/rest": "^22.0.0",
 		"cac": "^6.7.14",
 		"cli-progress": "^3.12.0",
+		"extract-zip": "^2.0.1",
 		"fs-extra": "^11.2.0",
 		"ignore": "^5.3.2",
 		"keytar": "^7.9.0",
@@ -40,7 +41,6 @@
 		"picocolors": "^1.1.1",
 		"tar": "^7.4.3",
 		"tmp": "^0.2.3",
-		"unzipper": "^0.12.3",
 		"zod": "^3.23.8"
 	},
 	"devDependencies": {
@@ -53,7 +53,6 @@
 		"@types/node": "^22.10.1",
 		"@types/tar": "^6.1.13",
 		"@types/tmp": "^0.2.6",
-		"@types/unzipper": "^0.10.10",
 		"semantic-release": "^24.2.0",
 		"typescript": "^5.7.2"
 	}

package/src/commands/new.ts

@@ -19,12 +19,19 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 		// Validate and parse options
 		const validOptions = NewCommandOptionsSchema.parse(options);
 
+		// Detect non-interactive mode
+		const isNonInteractive =
+			!process.stdin.isTTY || process.env.CI === "true" || process.env.NON_INTERACTIVE === "true";
+
 		// Load config for defaults
 		const config = await ConfigManager.get();
 
 		// Get kit selection
 		let kit = validOptions.kit || config.defaults?.kit;
 		if (!kit) {
+			if (isNonInteractive) {
+				throw new Error("Kit must be specified via --kit flag in non-interactive mode");
+			}
 			kit = await prompts.selectKit();
 		}
 
@@ -34,7 +41,11 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 		// Get target directory
 		let targetDir = validOptions.dir || config.defaults?.dir || ".";
 		if (!validOptions.dir && !config.defaults?.dir) {
-			targetDir = await prompts.getDirectory(targetDir);
+			if (isNonInteractive) {
+				targetDir = ".";
+			} else {
+				targetDir = await prompts.getDirectory(targetDir);
+			}
 		}
 
 		const resolvedDir = resolve(targetDir);
@@ -45,12 +56,21 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 			const files = await readdir(resolvedDir);
 			const isEmpty = files.length === 0;
 			if (!isEmpty) {
-				const continueAnyway = await prompts.confirm(
-					"Directory is not empty. Files may be overwritten. Continue?",
-				);
-				if (!continueAnyway) {
-					logger.warning("Operation cancelled");
-					return;
+				if (isNonInteractive) {
+					if (!validOptions.force) {
+						throw new Error(
+							"Directory is not empty. Use --force flag to overwrite in non-interactive mode",
+						);
+					}
+					logger.info("Directory is not empty. Proceeding with --force flag");
+				} else {
+					const continueAnyway = await prompts.confirm(
+						"Directory is not empty. Files may be overwritten. Continue?",
+					);
+					if (!continueAnyway) {
+						logger.warning("Operation cancelled");
+						return;
+					}
 				}
 			}
 		}
@@ -132,6 +152,9 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 		const extractDir = `${tempDir}/extracted`;
 		await downloadManager.extractArchive(archivePath, extractDir);
 
+		// Validate extraction
+		await downloadManager.validateExtraction(extractDir);
+
 		// Copy files to target directory
 		const merger = new FileMerger();
 		await merger.merge(extractDir, resolvedDir, true); // Skip confirmation for new projects

package/src/commands/update.ts

@@ -125,6 +125,9 @@ export async function updateCommand(options: UpdateCommandOptions): Promise<void
 		const extractDir = `${tempDir}/extracted`;
 		await downloadManager.extractArchive(archivePath, extractDir);
 
+		// Validate extraction
+		await downloadManager.validateExtraction(extractDir);
+
 		// Identify custom .claude files to preserve
 		logger.info("Scanning for custom .claude files...");
 		const customClaudeFiles = await FileScanner.findCustomFiles(resolvedDir, extractDir, ".claude");

package/src/index.ts

@@ -1,13 +1,11 @@
 #!/usr/bin/env bun
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { cac } from "cac";
 import { newCommand } from "./commands/new.js";
 import { updateCommand } from "./commands/update.js";
 import { versionCommand } from "./commands/version.js";
 import { logger } from "./utils/logger.js";
+import versionInfo from "./version.json" assert { type: "json" };
 
 // Set proper output encoding to prevent unicode rendering issues
 if (process.stdout.setEncoding) {
@@ -17,10 +15,7 @@ if (process.stderr.setEncoding) {
 	process.stderr.setEncoding("utf8");
 }
 
-const __dirname = fileURLToPath(new URL(".", import.meta.url));
-
-// Read package.json for version
-const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const packageVersion = versionInfo.version;
 
 const cli = cac("ck");
 
@@ -34,6 +29,7 @@ cli
 	.option("--dir <dir>", "Target directory (default: .)")
 	.option("--kit <kit>", "Kit to use (engineer, marketing)")
 	.option("--version <version>", "Specific version to download (default: latest)")
+	.option("--force", "Overwrite existing files without confirmation")
 	.action(async (options) => {
 		await newCommand(options);
 	});
@@ -59,7 +55,7 @@ cli
 	});
 
 // Version
-cli.version(packageJson.version);
+cli.version(packageVersion);
 
 // Help
 cli.help();
@@ -85,7 +81,7 @@ if (parsed.options.logFile) {
 
 // Log startup info in verbose mode
 logger.verbose("ClaudeKit CLI starting", {
-	version: packageJson.version,
+	version: packageVersion,
 	command: parsed.args[0] || "none",
 	options: parsed.options,
 	cwd: process.cwd(),

package/src/lib/download.ts

@@ -1,13 +1,11 @@
-import { createReadStream, createWriteStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { pipeline } from "node:stream";
-import { promisify } from "node:util";
+import { join, relative, resolve } from "node:path";
 import cliProgress from "cli-progress";
+import extractZip from "extract-zip";
 import ignore from "ignore";
 import * as tar from "tar";
-import unzipper from "unzipper";
 import {
 	type ArchiveType,
 	DownloadError,
@@ -17,9 +15,12 @@ import {
 import { logger } from "../utils/logger.js";
 import { createSpinner } from "../utils/safe-spinner.js";
 
-const streamPipeline = promisify(pipeline);
-
 export class DownloadManager {
+	/**
+	 * Maximum extraction size (500MB) to prevent archive bombs
+	 */
+	private static MAX_EXTRACTION_SIZE = 500 * 1024 * 1024; // 500MB
+
 	/**
 	 * Patterns to exclude from extraction
 	 */
@@ -35,6 +36,11 @@ export class DownloadManager {
 		"*.log",
 	];
 
+	/**
+	 * Track total extracted size to prevent archive bombs
+	 */
+	private totalExtractedSize = 0;
+
 	/**
 	 * Check if file path should be excluded
 	 */
@@ -43,6 +49,45 @@ export class DownloadManager {
 		return ig.ignores(filePath);
 	}
 
+	/**
+	 * Validate path to prevent path traversal attacks (zip slip)
+	 */
+	private isPathSafe(basePath: string, targetPath: string): boolean {
+		// Resolve both paths to their absolute canonical forms
+		const resolvedBase = resolve(basePath);
+		const resolvedTarget = resolve(targetPath);
+
+		// Calculate relative path from base to target
+		const relativePath = relative(resolvedBase, resolvedTarget);
+
+		// If path starts with .. or is absolute, it's trying to escape
+		// Also block if relative path is empty but resolved paths differ (edge case)
+		return (
+			!relativePath.startsWith("..") &&
+			!relativePath.startsWith("/") &&
+			resolvedTarget.startsWith(resolvedBase)
+		);
+	}
+
+	/**
+	 * Track extracted file size and check against limit
+	 */
+	private checkExtractionSize(fileSize: number): void {
+		this.totalExtractedSize += fileSize;
+		if (this.totalExtractedSize > DownloadManager.MAX_EXTRACTION_SIZE) {
+			throw new ExtractionError(
+				`Archive exceeds maximum extraction size of ${this.formatBytes(DownloadManager.MAX_EXTRACTION_SIZE)}. Possible archive bomb detected.`,
+			);
+		}
+	}
+
+	/**
+	 * Reset extraction size tracker
+	 */
+	private resetExtractionSize(): void {
+		this.totalExtractedSize = 0;
+	}
+
 	/**
 	 * Download asset from URL with progress tracking
 	 */
@@ -212,6 +257,9 @@ export class DownloadManager {
 		const spinner = createSpinner("Extracting files...").start();
 
 		try {
+			// Reset extraction size tracker
+			this.resetExtractionSize();
+
 			// Detect archive type from filename if not provided
 			const detectedType = archiveType || this.detectArchiveType(archivePath);
 
@@ -239,19 +287,96 @@ export class DownloadManager {
 	 * Extract tar.gz archive
 	 */
 	private async extractTarGz(archivePath: string, destDir: string): Promise<void> {
-		await tar.extract({
-			file: archivePath,
-			cwd: destDir,
-			strip: 1, // Strip the root directory from the archive
-			filter: (path: string) => {
-				// Exclude unwanted files
-				const shouldInclude = !this.shouldExclude(path);
-				if (!shouldInclude) {
-					logger.debug(`Excluding: ${path}`);
+		const { readdir, stat, mkdir: mkdirPromise, copyFile, rm } = await import("node:fs/promises");
+		const { join: pathJoin } = await import("node:path");
+
+		// Extract to a temporary directory first
+		const tempExtractDir = `${destDir}-temp`;
+		await mkdirPromise(tempExtractDir, { recursive: true });
+
+		try {
+			// Extract without stripping first
+			await tar.extract({
+				file: archivePath,
+				cwd: tempExtractDir,
+				strip: 0, // Don't strip yet - we'll decide based on wrapper detection
+				filter: (path: string) => {
+					// Exclude unwanted files
+					const shouldInclude = !this.shouldExclude(path);
+					if (!shouldInclude) {
+						logger.debug(`Excluding: ${path}`);
+					}
+					return shouldInclude;
+				},
+			});
+
+			logger.debug(`Extracted TAR.GZ to temp: ${tempExtractDir}`);
+
+			// Apply same wrapper detection logic as zip
+			const entries = await readdir(tempExtractDir);
+			logger.debug(`Root entries: ${entries.join(", ")}`);
+
+			if (entries.length === 1) {
+				const rootEntry = entries[0];
+				const rootPath = pathJoin(tempExtractDir, rootEntry);
+				const rootStat = await stat(rootPath);
+
+				if (rootStat.isDirectory()) {
+					// Check contents of root directory
+					const rootContents = await readdir(rootPath);
+					logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
+
+					// Only strip if root is a version/release wrapper
+					const isWrapper = this.isWrapperDirectory(rootEntry);
+					logger.debug(`Is wrapper directory: ${isWrapper}`);
+
+					if (isWrapper) {
+						// Strip wrapper and move contents
+						logger.debug(`Stripping wrapper directory: ${rootEntry}`);
+						await this.moveDirectoryContents(rootPath, destDir);
+					} else {
+						// Keep root directory - move everything including root
+						logger.debug("Preserving complete directory structure");
+						await this.moveDirectoryContents(tempExtractDir, destDir);
+					}
+				} else {
+					// Single file, just move it
+					await mkdirPromise(destDir, { recursive: true });
+					await copyFile(rootPath, pathJoin(destDir, rootEntry));
 				}
-				return shouldInclude;
-			},
-		});
+			} else {
+				// Multiple entries at root, move them all
+				logger.debug("Multiple root entries - moving all");
+				await this.moveDirectoryContents(tempExtractDir, destDir);
+			}
+
+			logger.debug(`Moved contents to: ${destDir}`);
+
+			// Clean up temp directory
+			await rm(tempExtractDir, { recursive: true, force: true });
+		} catch (error) {
+			// Clean up temp directory on error
+			try {
+				await rm(tempExtractDir, { recursive: true, force: true });
+			} catch {
+				// Ignore cleanup errors
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Check if directory name is a version/release wrapper
+	 * Examples: claudekit-engineer-v1.0.0, claudekit-engineer-1.0.0, repo-abc1234,
+	 *           project-v1.0.0-alpha, project-1.2.3-beta.1, repo-v2.0.0-rc.5
+	 */
+	private isWrapperDirectory(dirName: string): boolean {
+		// Match version patterns with optional prerelease: project-v1.0.0, project-1.0.0-alpha, project-v2.0.0-rc.1
+		const versionPattern = /^[\w-]+-v?\d+\.\d+\.\d+(-[\w.]+)?$/;
+		// Match commit hash patterns: project-abc1234 (7-40 chars for short/full SHA)
+		const hashPattern = /^[\w-]+-[a-f0-9]{7,40}$/;
+
+		return versionPattern.test(dirName) || hashPattern.test(dirName);
 	}
 
 	/**
@@ -266,24 +391,39 @@ export class DownloadManager {
 		await mkdirPromise(tempExtractDir, { recursive: true });
 
 		try {
-			// Extract zip to temp directory
-			await streamPipeline(
-				createReadStream(archivePath),
-				unzipper.Extract({ path: tempExtractDir }),
-			);
+			// Extract zip to temp directory using extract-zip
+			await extractZip(archivePath, { dir: tempExtractDir });
+
+			logger.debug(`Extracted ZIP to temp: ${tempExtractDir}`);
 
 			// Find the root directory in the zip (if any)
 			const entries = await readdir(tempExtractDir);
+			logger.debug(`Root entries: ${entries.join(", ")}`);
 
-			// If there's a single root directory, strip it
+			// If there's a single root directory, check if it's a wrapper
 			if (entries.length === 1) {
 				const rootEntry = entries[0];
 				const rootPath = pathJoin(tempExtractDir, rootEntry);
 				const rootStat = await stat(rootPath);
 
 				if (rootStat.isDirectory()) {
-					// Move contents from the root directory to the destination
-					await this.moveDirectoryContents(rootPath, destDir);
+					// Check contents of root directory
+					const rootContents = await readdir(rootPath);
+					logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
+
+					// Only strip if root is a version/release wrapper
+					const isWrapper = this.isWrapperDirectory(rootEntry);
+					logger.debug(`Is wrapper directory: ${isWrapper}`);
+
+					if (isWrapper) {
+						// Strip wrapper and move contents
+						logger.debug(`Stripping wrapper directory: ${rootEntry}`);
+						await this.moveDirectoryContents(rootPath, destDir);
+					} else {
+						// Keep root directory - move everything including root
+						logger.debug("Preserving complete directory structure");
+						await this.moveDirectoryContents(tempExtractDir, destDir);
+					}
 				} else {
 					// Single file, just move it
 					await mkdirPromise(destDir, { recursive: true });
@@ -291,9 +431,12 @@ export class DownloadManager {
 				}
 			} else {
 				// Multiple entries at root, move them all
+				logger.debug("Multiple root entries - moving all");
 				await this.moveDirectoryContents(tempExtractDir, destDir);
 			}
 
+			logger.debug(`Moved contents to: ${destDir}`);
+
 			// Clean up temp directory
 			await rm(tempExtractDir, { recursive: true, force: true });
 		} catch (error) {
@@ -323,6 +466,12 @@ export class DownloadManager {
 			const destPath = pathJoin(destDir, entry);
 			const relativePath = relative(sourceDir, sourcePath);
 
+			// Validate path safety (prevent path traversal)
+			if (!this.isPathSafe(destDir, destPath)) {
+				logger.warning(`Skipping unsafe path: ${relativePath}`);
+				throw new ExtractionError(`Path traversal attempt detected: ${relativePath}`);
+			}
+
 			// Skip excluded files
 			if (this.shouldExclude(relativePath)) {
 				logger.debug(`Excluding: ${relativePath}`);
@@ -335,6 +484,8 @@ export class DownloadManager {
 				// Recursively copy directory
 				await this.copyDirectory(sourcePath, destPath);
 			} else {
+				// Track file size and check limit
+				this.checkExtractionSize(entryStat.size);
 				// Copy file
 				await copyFile(sourcePath, destPath);
 			}
@@ -357,6 +508,12 @@ export class DownloadManager {
 			const destPath = pathJoin(destDir, entry);
 			const relativePath = relative(sourceDir, sourcePath);
 
+			// Validate path safety (prevent path traversal)
+			if (!this.isPathSafe(destDir, destPath)) {
+				logger.warning(`Skipping unsafe path: ${relativePath}`);
+				throw new ExtractionError(`Path traversal attempt detected: ${relativePath}`);
+			}
+
 			// Skip excluded files
 			if (this.shouldExclude(relativePath)) {
 				logger.debug(`Excluding: ${relativePath}`);
@@ -369,6 +526,8 @@ export class DownloadManager {
 				// Recursively copy directory
 				await this.copyDirectory(sourcePath, destPath);
 			} else {
+				// Track file size and check limit
+				this.checkExtractionSize(entryStat.size);
 				// Copy file
 				await copyFile(sourcePath, destPath);
 			}
@@ -388,6 +547,56 @@ export class DownloadManager {
 		throw new ExtractionError(`Cannot detect archive type from filename: ${filename}`);
 	}
 
+	/**
+	 * Validate extraction results
+	 * @throws {ExtractionError} If validation fails
+	 */
+	async validateExtraction(extractDir: string): Promise<void> {
+		const { readdir, access } = await import("node:fs/promises");
+		const { join: pathJoin } = await import("node:path");
+		const { constants } = await import("node:fs");
+
+		try {
+			// Check if extract directory exists and is not empty
+			const entries = await readdir(extractDir);
+			logger.debug(`Extracted files: ${entries.join(", ")}`);
+
+			if (entries.length === 0) {
+				throw new ExtractionError("Extraction resulted in no files");
+			}
+
+			// Verify critical paths exist
+			const criticalPaths = [".claude", "CLAUDE.md"];
+			const missingPaths: string[] = [];
+
+			for (const path of criticalPaths) {
+				try {
+					await access(pathJoin(extractDir, path), constants.F_OK);
+					logger.debug(`✓ Found: ${path}`);
+				} catch {
+					logger.warning(`Expected path not found: ${path}`);
+					missingPaths.push(path);
+				}
+			}
+
+			// Warn if critical paths are missing but don't fail validation
+			if (missingPaths.length > 0) {
+				logger.warning(
+					`Some expected paths are missing: ${missingPaths.join(", ")}. This may not be a ClaudeKit project.`,
+				);
+			}
+
+			logger.debug("Extraction validation passed");
+		} catch (error) {
+			if (error instanceof ExtractionError) {
+				throw error;
+			}
+			throw new ExtractionError(
+				`Validation failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+	}
+
 	/**
 	 * Create temporary download directory
 	 */

package/src/types.ts

@@ -9,6 +9,7 @@ export const NewCommandOptionsSchema = z.object({
 	dir: z.string().default("."),
 	kit: KitType.optional(),
 	version: z.string().optional(),
+	force: z.boolean().default(false),
 });
 export type NewCommandOptions = z.infer<typeof NewCommandOptionsSchema>;
 

package/src/version.json

@@ -0,0 +1,3 @@
+{
+	"version": "1.2.1"
+}

package/test-integration/demo/.mcp.json

@@ -0,0 +1,13 @@
+{
+	"mcpServers": {
+		"human": {
+			"command": "npx",
+			"args": ["-y", "@goonnguyen/human-mcp@latest"],
+			"env": {
+				"GOOGLE_GEMINI_API_KEY": "",
+				"TRANSPORT_TYPE": "stdio",
+				"LOG_LEVEL": "info"
+			}
+		}
+	}
+}

package/test-integration/demo/.repomixignore

@@ -0,0 +1,15 @@
+docs/*
+plans/*
+assets/*
+dist/*
+coverage/*
+build/*
+ios/*
+android/*
+
+.claude/*
+.serena/*
+.pnpm-store/*
+.github/*
+.dart_tool/*
+.idea/*

package/test-integration/demo/CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Role & Responsibilities
+
+Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards.
+
+## Workflows
+
+- Primary workflow: `./.claude/workflows/primary-workflow.md`
+- Development rules: `./.claude/workflows/development-rules.md`
+- Orchestration protocols: `./.claude/workflows/orchestration-protocol.md`
+- Documentation management: `./.claude/workflows/documentation-management.md`
+
+**IMPORTANT:** You must follow strictly the development rules in `./.claude/workflows/development-rules.md` file.
+**IMPORTANT:** Before you plan or proceed any implementation, always read the `./README.md` file first to get context.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+## Documentation Management
+
+We keep all important docs in `./docs` folder and keep updating them, structure like below:
+
+```
+./docs
+├── project-overview-pdr.md
+├── code-standards.md
+├── codebase-summary.md
+├── design-guidelines.md
+├── deployment-guide.md
+├── system-architecture.md
+└── project-roadmap.md
+```