claudekit-cli 1.2.2 → 1.4.0

package/src/index.ts

@@ -1,9 +1,7 @@
 #!/usr/bin/env bun
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { cac } from "cac";
+import packageInfo from "../package.json" assert { type: "json" };
 import { newCommand } from "./commands/new.js";
 import { updateCommand } from "./commands/update.js";
 import { versionCommand } from "./commands/version.js";
@@ -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 = packageInfo.version;
 
 const cli = cac("ck");
 
@@ -34,7 +29,13 @@ 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")
+	.option("--exclude <pattern>", "Exclude files matching glob pattern (can be used multiple times)")
 	.action(async (options) => {
+		// Normalize exclude to always be an array (CAC may pass string for single value)
+		if (options.exclude && !Array.isArray(options.exclude)) {
+			options.exclude = [options.exclude];
+		}
 		await newCommand(options);
 	});
 
@@ -44,7 +45,12 @@ 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("--exclude <pattern>", "Exclude files matching glob pattern (can be used multiple times)")
 	.action(async (options) => {
+		// Normalize exclude to always be an array (CAC may pass string for single value)
+		if (options.exclude && !Array.isArray(options.exclude)) {
+			options.exclude = [options.exclude];
+		}
 		await updateCommand(options);
 	});
 
@@ -59,7 +65,7 @@ cli
 	});
 
 // Version
-cli.version(packageJson.version);
+cli.version(packageVersion);
 
 // Help
 cli.help();
@@ -85,7 +91,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,7 +1,7 @@
 import { createWriteStream } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, relative, resolve } from "node:path";
 import cliProgress from "cli-progress";
 import extractZip from "extract-zip";
 import ignore from "ignore";
@@ -16,6 +16,11 @@ import { logger } from "../utils/logger.js";
 import { createSpinner } from "../utils/safe-spinner.js";
 
 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
 	 */
@@ -31,12 +36,89 @@ export class DownloadManager {
 		"*.log",
 	];
 
+	/**
+	 * Track total extracted size to prevent archive bombs
+	 */
+	private totalExtractedSize = 0;
+
+	/**
+	 * Instance-level ignore object with combined default and user patterns
+	 */
+	private ig: ReturnType<typeof ignore>;
+
+	/**
+	 * Store user-defined exclude patterns
+	 */
+	private userExcludePatterns: string[] = [];
+
+	/**
+	 * Initialize DownloadManager with default exclude patterns
+	 */
+	constructor() {
+		// Initialize ignore with default patterns
+		this.ig = ignore().add(DownloadManager.EXCLUDE_PATTERNS);
+	}
+
+	/**
+	 * Set additional user-defined exclude patterns
+	 * These are added to (not replace) the default EXCLUDE_PATTERNS
+	 */
+	setExcludePatterns(patterns: string[]): void {
+		this.userExcludePatterns = patterns;
+		// Reinitialize ignore with both default and user patterns
+		this.ig = ignore().add([...DownloadManager.EXCLUDE_PATTERNS, ...this.userExcludePatterns]);
+
+		if (patterns.length > 0) {
+			logger.info(`Added ${patterns.length} custom exclude pattern(s)`);
+			patterns.forEach((p) => logger.debug(`  - ${p}`));
+		}
+	}
+
 	/**
 	 * Check if file path should be excluded
+	 * Uses instance-level ignore with both default and user patterns
 	 */
 	private shouldExclude(filePath: string): boolean {
-		const ig = ignore().add(DownloadManager.EXCLUDE_PATTERNS);
-		return ig.ignores(filePath);
+		return this.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;
 	}
 
 	/**
@@ -208,6 +290,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);
 
@@ -315,13 +400,14 @@ export class DownloadManager {
 
 	/**
 	 * Check if directory name is a version/release wrapper
-	 * Examples: claudekit-engineer-v1.0.0, claudekit-engineer-1.0.0, repo-abc1234
+	 * 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: project-v1.0.0, project-1.0.0
-		const versionPattern = /^[\w-]+-v?\d+\.\d+\.\d+/;
-		// Match commit hash patterns: project-abc1234
-		const hashPattern = /^[\w-]+-[a-f0-9]{7,}$/;
+		// 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);
 	}
@@ -413,6 +499,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}`);
@@ -425,6 +517,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);
 			}
@@ -447,6 +541,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}`);
@@ -459,6 +559,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);
 			}
@@ -480,8 +582,9 @@ export class DownloadManager {
 
 	/**
 	 * Validate extraction results
+	 * @throws {ExtractionError} If validation fails
 	 */
-	async validateExtraction(extractDir: string): Promise<boolean> {
+	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");
@@ -492,27 +595,38 @@ export class DownloadManager {
 			logger.debug(`Extracted files: ${entries.join(", ")}`);
 
 			if (entries.length === 0) {
-				logger.warning("Extraction resulted in no files");
-				return false;
+				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);
 				}
 			}
 
-			return true;
+			// 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) {
-			logger.error(
+			if (error instanceof ExtractionError) {
+				throw error;
+			}
+			throw new ExtractionError(
 				`Validation failed: ${error instanceof Error ? error.message : "Unknown error"}`,
 			);
-			return false;
 		}
 	}
 

package/src/types.ts

@@ -4,11 +4,22 @@ import { z } from "zod";
 export const KitType = z.enum(["engineer", "marketing"]);
 export type KitType = z.infer<typeof KitType>;
 
+// Exclude pattern validation schema
+export const ExcludePatternSchema = z
+	.string()
+	.trim()
+	.min(1, "Exclude pattern cannot be empty")
+	.max(500, "Exclude pattern too long")
+	.refine((val) => !val.startsWith("/"), "Absolute paths not allowed in exclude patterns")
+	.refine((val) => !val.includes(".."), "Path traversal not allowed in exclude patterns");
+
 // Command options schemas
 export const NewCommandOptionsSchema = z.object({
 	dir: z.string().default("."),
 	kit: KitType.optional(),
 	version: z.string().optional(),
+	force: z.boolean().default(false),
+	exclude: z.array(ExcludePatternSchema).optional().default([]),
 });
 export type NewCommandOptions = z.infer<typeof NewCommandOptionsSchema>;
 
@@ -16,6 +27,7 @@ export const UpdateCommandOptionsSchema = z.object({
 	dir: z.string().default("."),
 	kit: KitType.optional(),
 	version: z.string().optional(),
+	exclude: z.array(ExcludePatternSchema).optional().default([]),
 });
 export type UpdateCommandOptions = z.infer<typeof UpdateCommandOptionsSchema>;
 

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
+```

package/tests/integration/cli.test.ts

@@ -0,0 +1,252 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Integration tests for CLI commands
+ * These tests actually run the CLI and verify the results
+ */
+describe("CLI Integration Tests", () => {
+	let testDir: string;
+	const __dirname = join(fileURLToPath(import.meta.url), "..", "..", "..");
+	const cliPath = join(__dirname, "dist", "index.js");
+
+	// Skip integration tests in CI environments for now due to execution issues
+	const isCI = process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+
+	beforeEach(async () => {
+		// Skip in CI
+		if (isCI) {
+			return;
+		}
+
+		// Create test directory
+		testDir = join(process.cwd(), "test-integration", `cli-test-${Date.now()}`);
+		await mkdir(testDir, { recursive: true });
+
+		// Build the CLI first if not exists
+		if (!existsSync(cliPath)) {
+			execSync("bun run build", { cwd: process.cwd() });
+		}
+	});
+
+	afterEach(async () => {
+		// Skip in CI
+		if (isCI) {
+			return;
+		}
+
+		// Cleanup test directory
+		if (existsSync(testDir)) {
+			await rm(testDir, { recursive: true, force: true });
+		}
+	});
+
+	describe("ck new command", () => {
+		test("should create new project in specified directory", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-ck-new");
+
+			try {
+				// Run ck new command with --kit and --force flags for non-interactive mode
+				execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+					cwd: testDir,
+					stdio: "pipe",
+					timeout: 60000, // 60 second timeout
+				});
+
+				// Verify project structure
+				expect(existsSync(projectDir)).toBe(true);
+				expect(existsSync(join(projectDir, ".claude"))).toBe(true);
+				expect(existsSync(join(projectDir, "CLAUDE.md"))).toBe(true);
+			} catch (error) {
+				// Log error for debugging
+				console.error("Command failed:", error);
+				throw error;
+			}
+		}, 120000); // 2 minute timeout for the test
+
+		test("should create project with correct file contents", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-content");
+
+			try {
+				execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+					cwd: testDir,
+					stdio: "pipe",
+					timeout: 60000,
+				});
+
+				// Verify file contents (basic check)
+				const claudeMd = await Bun.file(join(projectDir, "CLAUDE.md")).text();
+				expect(claudeMd).toContain("CLAUDE.md");
+			} catch (error) {
+				console.error("Command failed:", error);
+				throw error;
+			}
+		}, 120000);
+
+		test("should not overwrite existing project without confirmation", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-no-overwrite");
+
+			// Create existing directory with a file
+			await mkdir(projectDir, { recursive: true });
+			await writeFile(join(projectDir, "existing.txt"), "existing content");
+
+			try {
+				// This should fail because --force is not provided
+				execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer`, {
+					cwd: testDir,
+					stdio: "pipe",
+					timeout: 5000,
+				});
+				// Should not reach here
+				expect(true).toBe(false);
+			} catch (error: any) {
+				// Expected to fail without --force flag
+				expect(error).toBeDefined();
+				expect(error.message).toContain("not empty");
+			}
+
+			// Verify existing file is still there
+			expect(existsSync(join(projectDir, "existing.txt"))).toBe(true);
+		});
+	});
+
+	describe("ck update command", () => {
+		test("should update existing project", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-ck-update");
+
+			// First create a project with --kit and --force flags
+			execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+				cwd: testDir,
+				stdio: "pipe",
+				timeout: 60000,
+			});
+
+			// Add a custom file to .claude directory
+			await writeFile(join(projectDir, ".claude", "custom.md"), "# Custom file");
+
+			// Update the project (will ask for confirmation, so it may timeout/fail)
+			try {
+				execSync(`node ${cliPath} update`, {
+					cwd: projectDir,
+					stdio: "pipe",
+					timeout: 60000,
+				});
+
+				// Note: Update requires confirmation, so this test may need adjustment
+				// based on how confirmation is handled in tests
+			} catch (error) {
+				// May fail due to confirmation prompt
+				console.log("Update command requires confirmation, which is expected");
+			}
+
+			// Verify custom file is preserved
+			expect(existsSync(join(projectDir, ".claude", "custom.md"))).toBe(true);
+		}, 120000);
+
+		test("should fail when not in a project directory", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const emptyDir = join(testDir, "empty");
+			await mkdir(emptyDir, { recursive: true });
+
+			try {
+				execSync(`node ${cliPath} update`, {
+					cwd: emptyDir,
+					stdio: "pipe",
+					timeout: 5000,
+				});
+
+				// Should not reach here
+				expect(true).toBe(false);
+			} catch (error: any) {
+				// Expected to fail
+				expect(error).toBeDefined();
+			}
+		});
+	});
+
+	describe("project structure validation", () => {
+		test("new project should have all required directories", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-structure");
+
+			execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+				cwd: testDir,
+				stdio: "pipe",
+				timeout: 60000,
+			});
+
+			// Check for required directories
+			const requiredDirs = [".claude"];
+
+			for (const dir of requiredDirs) {
+				expect(existsSync(join(projectDir, dir))).toBe(true);
+			}
+		}, 120000);
+
+		test("new project should have all required files", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-files");
+
+			execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+				cwd: testDir,
+				stdio: "pipe",
+				timeout: 60000,
+			});
+
+			// Check for required files
+			const requiredFiles = ["CLAUDE.md"];
+
+			for (const file of requiredFiles) {
+				expect(existsSync(join(projectDir, file))).toBe(true);
+			}
+		}, 120000);
+
+		test("project should not contain excluded files", async () => {
+			if (isCI) {
+				return;
+			}
+
+			const projectDir = join(testDir, "test-exclusions");
+
+			execSync(`node ${cliPath} new --dir ${projectDir} --kit engineer --force`, {
+				cwd: testDir,
+				stdio: "pipe",
+				timeout: 60000,
+			});
+
+			// Verify excluded patterns are not present
+			expect(existsSync(join(projectDir, ".git"))).toBe(false);
+			expect(existsSync(join(projectDir, "node_modules"))).toBe(false);
+			expect(existsSync(join(projectDir, ".DS_Store"))).toBe(false);
+		}, 120000);
+	});
+});