claudekit-cli 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.4.1](https://github.com/mrgoonie/claudekit-cli/compare/v1.4.0...v1.4.1) (2025-10-21)
+
+
+### Bug Fixes
+
+* handle protected files during merge ([fe90767](https://github.com/mrgoonie/claudekit-cli/commit/fe907670932fc5b39521586ef798f73cd1130180))
+
 # [1.4.0](https://github.com/mrgoonie/claudekit-cli/compare/v1.3.0...v1.4.0) (2025-10-21)
 
 

package/dist/index.js

@@ -6403,7 +6403,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "claudekit-cli",
-  version: "1.3.0",
+  version: "1.4.0",
   description: "CLI tool for bootstrapping and updating ClaudeKit projects",
   type: "module",
   bin: {
@@ -11056,6 +11056,10 @@ var PROTECTED_PATTERNS = [
   "*.key",
   "*.pem",
   "*.p12",
+  ".gitignore",
+  ".repomixignore",
+  ".mcp.json",
+  "CLAUDE.md",
   "node_modules/**",
   ".git/**",
   "dist/**",
@@ -21292,6 +21296,22 @@ class DownloadManager {
   shouldExclude(filePath) {
     return this.ig.ignores(filePath);
   }
+  decodeFilePath(path8) {
+    if (!path8.includes("%")) {
+      return path8;
+    }
+    try {
+      if (/%[0-9A-F]{2}/i.test(path8)) {
+        const decoded = decodeURIComponent(path8);
+        logger.debug(`Decoded path: ${path8} -> ${decoded}`);
+        return decoded;
+      }
+      return path8;
+    } catch (error2) {
+      logger.warning(`Failed to decode path "${path8}": ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+      return path8;
+    }
+  }
   isPathSafe(basePath, targetPath) {
     const resolvedBase = resolve(basePath);
     const resolvedTarget = resolve(targetPath);
@@ -21443,22 +21463,23 @@ class DownloadManager {
         cwd: tempExtractDir,
         strip: 0,
         filter: (path8) => {
-          const shouldInclude = !this.shouldExclude(path8);
+          const decodedPath = this.decodeFilePath(path8);
+          const shouldInclude = !this.shouldExclude(decodedPath);
           if (!shouldInclude) {
-            logger.debug(`Excluding: ${path8}`);
+            logger.debug(`Excluding: ${decodedPath}`);
           }
           return shouldInclude;
         }
       });
       logger.debug(`Extracted TAR.GZ to temp: ${tempExtractDir}`);
-      const entries = await readdir(tempExtractDir);
+      const entries = await readdir(tempExtractDir, { encoding: "utf8" });
       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()) {
-          const rootContents = await readdir(rootPath);
+          const rootContents = await readdir(rootPath, { encoding: "utf8" });
           logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
           const isWrapper = this.isWrapperDirectory(rootEntry);
           logger.debug(`Is wrapper directory: ${isWrapper}`);
@@ -21499,14 +21520,14 @@ class DownloadManager {
     try {
       await import_extract_zip.default(archivePath, { dir: tempExtractDir });
       logger.debug(`Extracted ZIP to temp: ${tempExtractDir}`);
-      const entries = await readdir(tempExtractDir);
+      const entries = await readdir(tempExtractDir, { encoding: "utf8" });
       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()) {
-          const rootContents = await readdir(rootPath);
+          const rootContents = await readdir(rootPath, { encoding: "utf8" });
           logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
           const isWrapper = this.isWrapperDirectory(rootEntry);
           logger.debug(`Is wrapper directory: ${isWrapper}`);
@@ -21538,7 +21559,7 @@ class DownloadManager {
     const { readdir, stat, mkdir: mkdirPromise, copyFile } = await import("node:fs/promises");
     const { join: pathJoin, relative: relative2 } = await import("node:path");
     await mkdirPromise(destDir, { recursive: true });
-    const entries = await readdir(sourceDir);
+    const entries = await readdir(sourceDir, { encoding: "utf8" });
     for (const entry of entries) {
       const sourcePath = pathJoin(sourceDir, entry);
       const destPath = pathJoin(destDir, entry);
@@ -21564,7 +21585,7 @@ class DownloadManager {
     const { readdir, stat, mkdir: mkdirPromise, copyFile } = await import("node:fs/promises");
     const { join: pathJoin, relative: relative2 } = await import("node:path");
     await mkdirPromise(destDir, { recursive: true });
-    const entries = await readdir(sourceDir);
+    const entries = await readdir(sourceDir, { encoding: "utf8" });
     for (const entry of entries) {
       const sourcePath = pathJoin(sourceDir, entry);
       const destPath = pathJoin(destDir, entry);
@@ -21600,7 +21621,7 @@ class DownloadManager {
     const { join: pathJoin } = await import("node:path");
     const { constants: constants2 } = await import("node:fs");
     try {
-      const entries = await readdir(extractDir);
+      const entries = await readdir(extractDir, { encoding: "utf8" });
       logger.debug(`Extracted files: ${entries.join(", ")}`);
       if (entries.length === 0) {
         throw new ExtractionError("Extraction resulted in no files");
@@ -21811,11 +21832,12 @@ class FileMerger {
     const files = await this.getFiles(sourceDir);
     for (const file of files) {
       const relativePath = relative2(sourceDir, file);
-      if (this.ig.ignores(relativePath)) {
-        continue;
-      }
       const destPath = join4(destDir, relativePath);
       if (await import_fs_extra.pathExists(destPath)) {
+        if (this.ig.ignores(relativePath)) {
+          logger.debug(`Protected file exists but won't be overwritten: ${relativePath}`);
+          continue;
+        }
         conflicts.push(relativePath);
       }
     }
@@ -21827,12 +21849,12 @@ class FileMerger {
     let skippedCount = 0;
     for (const file of files) {
       const relativePath = relative2(sourceDir, file);
-      if (this.ig.ignores(relativePath)) {
-        logger.debug(`Skipping protected file: ${relativePath}`);
+      const destPath = join4(destDir, relativePath);
+      if (this.ig.ignores(relativePath) && await import_fs_extra.pathExists(destPath)) {
+        logger.debug(`Skipping protected file (exists in destination): ${relativePath}`);
         skippedCount++;
         continue;
       }
-      const destPath = join4(destDir, relativePath);
       await import_fs_extra.copy(file, destPath, { overwrite: true });
       copiedCount++;
     }
@@ -21840,7 +21862,7 @@ class FileMerger {
   }
   async getFiles(dir) {
     const files = [];
-    const entries = await import_fs_extra.readdir(dir);
+    const entries = await import_fs_extra.readdir(dir, { encoding: "utf8" });
     for (const entry of entries) {
       const fullPath = join4(dir, entry);
       const stats = await import_fs_extra.stat(fullPath);
@@ -22092,7 +22114,7 @@ class FileScanner {
       return files;
     }
     try {
-      const entries = await import_fs_extra3.readdir(dirPath);
+      const entries = await import_fs_extra3.readdir(dirPath, { encoding: "utf8" });
       for (const entry of entries) {
         const fullPath = join5(dirPath, entry);
         if (!FileScanner.isSafePath(basePath, fullPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudekit-cli",
-	"version": "1.4.0",
+	"version": "1.4.1",
 	"description": "CLI tool for bootstrapping and updating ClaudeKit projects",
 	"type": "module",
 	"bin": {

package/src/lib/download.ts

@@ -82,6 +82,39 @@ export class DownloadManager {
 		return this.ig.ignores(filePath);
 	}
 
+	/**
+	 * Decode percent-encoded file paths to handle Mojibake issues
+	 *
+	 * GitHub tarballs may contain percent-encoded paths (e.g., %20 for space, %C3%A9 for é)
+	 * that need to be decoded to prevent character encoding corruption.
+	 *
+	 * @param path - File path that may contain URL-encoded characters
+	 * @returns Decoded path, or original path if decoding fails
+	 * @private
+	 */
+	private decodeFilePath(path: string): string {
+		// Early exit for non-encoded paths (performance optimization)
+		if (!path.includes("%")) {
+			return path;
+		}
+
+		try {
+			// Only decode if path contains valid percent-encoding pattern (%XX)
+			if (/%[0-9A-F]{2}/i.test(path)) {
+				const decoded = decodeURIComponent(path);
+				logger.debug(`Decoded path: ${path} -> ${decoded}`);
+				return decoded;
+			}
+			return path;
+		} catch (error) {
+			// If decoding fails (malformed encoding), return original path
+			logger.warning(
+				`Failed to decode path "${path}": ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+			return path;
+		}
+	}
+
 	/**
 	 * Validate path to prevent path traversal attacks (zip slip)
 	 */
@@ -334,10 +367,12 @@ export class DownloadManager {
 				cwd: tempExtractDir,
 				strip: 0, // Don't strip yet - we'll decide based on wrapper detection
 				filter: (path: string) => {
+					// Decode percent-encoded paths from GitHub tarballs
+					const decodedPath = this.decodeFilePath(path);
 					// Exclude unwanted files
-					const shouldInclude = !this.shouldExclude(path);
+					const shouldInclude = !this.shouldExclude(decodedPath);
 					if (!shouldInclude) {
-						logger.debug(`Excluding: ${path}`);
+						logger.debug(`Excluding: ${decodedPath}`);
 					}
 					return shouldInclude;
 				},
@@ -346,7 +381,7 @@ export class DownloadManager {
 			logger.debug(`Extracted TAR.GZ to temp: ${tempExtractDir}`);
 
 			// Apply same wrapper detection logic as zip
-			const entries = await readdir(tempExtractDir);
+			const entries = await readdir(tempExtractDir, { encoding: "utf8" });
 			logger.debug(`Root entries: ${entries.join(", ")}`);
 
 			if (entries.length === 1) {
@@ -356,7 +391,7 @@ export class DownloadManager {
 
 				if (rootStat.isDirectory()) {
 					// Check contents of root directory
-					const rootContents = await readdir(rootPath);
+					const rootContents = await readdir(rootPath, { encoding: "utf8" });
 					logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
 
 					// Only strip if root is a version/release wrapper
@@ -430,7 +465,7 @@ export class DownloadManager {
 			logger.debug(`Extracted ZIP to temp: ${tempExtractDir}`);
 
 			// Find the root directory in the zip (if any)
-			const entries = await readdir(tempExtractDir);
+			const entries = await readdir(tempExtractDir, { encoding: "utf8" });
 			logger.debug(`Root entries: ${entries.join(", ")}`);
 
 			// If there's a single root directory, check if it's a wrapper
@@ -441,7 +476,7 @@ export class DownloadManager {
 
 				if (rootStat.isDirectory()) {
 					// Check contents of root directory
-					const rootContents = await readdir(rootPath);
+					const rootContents = await readdir(rootPath, { encoding: "utf8" });
 					logger.debug(`Root directory '${rootEntry}' contains: ${rootContents.join(", ")}`);
 
 					// Only strip if root is a version/release wrapper
@@ -492,7 +527,7 @@ export class DownloadManager {
 
 		await mkdirPromise(destDir, { recursive: true });
 
-		const entries = await readdir(sourceDir);
+		const entries = await readdir(sourceDir, { encoding: "utf8" });
 
 		for (const entry of entries) {
 			const sourcePath = pathJoin(sourceDir, entry);
@@ -534,7 +569,7 @@ export class DownloadManager {
 
 		await mkdirPromise(destDir, { recursive: true });
 
-		const entries = await readdir(sourceDir);
+		const entries = await readdir(sourceDir, { encoding: "utf8" });
 
 		for (const entry of entries) {
 			const sourcePath = pathJoin(sourceDir, entry);
@@ -591,7 +626,7 @@ export class DownloadManager {
 
 		try {
 			// Check if extract directory exists and is not empty
-			const entries = await readdir(extractDir);
+			const entries = await readdir(extractDir, { encoding: "utf8" });
 			logger.debug(`Extracted files: ${entries.join(", ")}`);
 
 			if (entries.length === 0) {

package/src/lib/merge.ts

@@ -37,6 +37,7 @@ export class FileMerger {
 
 	/**
 	 * Detect files that will be overwritten
+	 * Protected files that exist in destination are not considered conflicts (they won't be overwritten)
 	 */
 	private async detectConflicts(sourceDir: string, destDir: string): Promise<string[]> {
 		const conflicts: string[] = [];
@@ -44,14 +45,15 @@ export class FileMerger {
 
 		for (const file of files) {
 			const relativePath = relative(sourceDir, file);
-
-			// Skip protected files
-			if (this.ig.ignores(relativePath)) {
-				continue;
-			}
-
 			const destPath = join(destDir, relativePath);
+
+			// Check if file exists in destination
 			if (await pathExists(destPath)) {
+				// Protected files won't be overwritten, so they're not conflicts
+				if (this.ig.ignores(relativePath)) {
+					logger.debug(`Protected file exists but won't be overwritten: ${relativePath}`);
+					continue;
+				}
 				conflicts.push(relativePath);
 			}
 		}
@@ -69,15 +71,16 @@ export class FileMerger {
 
 		for (const file of files) {
 			const relativePath = relative(sourceDir, file);
+			const destPath = join(destDir, relativePath);
 
-			// Skip protected files
-			if (this.ig.ignores(relativePath)) {
-				logger.debug(`Skipping protected file: ${relativePath}`);
+			// Skip protected files ONLY if they already exist in destination
+			// This allows new protected files to be added, but prevents overwriting existing ones
+			if (this.ig.ignores(relativePath) && (await pathExists(destPath))) {
+				logger.debug(`Skipping protected file (exists in destination): ${relativePath}`);
 				skippedCount++;
 				continue;
 			}
 
-			const destPath = join(destDir, relativePath);
 			await copy(file, destPath, { overwrite: true });
 			copiedCount++;
 		}
@@ -90,7 +93,7 @@ export class FileMerger {
 	 */
 	private async getFiles(dir: string): Promise<string[]> {
 		const files: string[] = [];
-		const entries = await readdir(dir);
+		const entries = await readdir(dir, { encoding: "utf8" });
 
 		for (const entry of entries) {
 			const fullPath = join(dir, entry);

package/src/types.ts

@@ -105,12 +105,19 @@ export const AVAILABLE_KITS: Record<KitType, KitConfig> = {
 
 // Protected file patterns (files to skip during update)
 export const PROTECTED_PATTERNS = [
+	// Environment and secrets
 	".env",
 	".env.local",
 	".env.*.local",
 	"*.key",
 	"*.pem",
 	"*.p12",
+	// User configuration files (only skip if they exist)
+	".gitignore",
+	".repomixignore",
+	".mcp.json",
+	"CLAUDE.md",
+	// Dependencies and build artifacts
 	"node_modules/**",
 	".git/**",
 	"dist/**",

package/src/utils/file-scanner.ts

@@ -29,7 +29,7 @@ export class FileScanner {
 		}
 
 		try {
-			const entries = await readdir(dirPath);
+			const entries = await readdir(dirPath, { encoding: "utf8" });
 
 			for (const entry of entries) {
 				const fullPath = join(dirPath, entry);

package/tests/lib/merge.test.ts

@@ -62,26 +62,60 @@ describe("FileMerger", () => {
 			expect(existsSync(join(testDestDir, "readme.md"))).toBe(true);
 		});
 
-		test("should skip protected files like .env", async () => {
-			// Create test files including protected ones
+		test("should skip protected files like .env if they exist in destination", async () => {
+			// Create test files in source
+			await writeFile(join(testSourceDir, "normal.txt"), "normal");
+			await writeFile(join(testSourceDir, ".env"), "NEW_SECRET=new_value");
+
+			// Create existing .env in destination
+			await writeFile(join(testDestDir, ".env"), "OLD_SECRET=old_value");
+
+			await merger.merge(testSourceDir, testDestDir, true);
+
+			// Verify normal file was copied
+			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
+
+			// Verify .env was NOT overwritten (still has old value)
+			const envContent = await Bun.file(join(testDestDir, ".env")).text();
+			expect(envContent).toBe("OLD_SECRET=old_value");
+		});
+
+		test("should copy protected files like .env if they don't exist in destination", async () => {
+			// Create test files in source
 			await writeFile(join(testSourceDir, "normal.txt"), "normal");
 			await writeFile(join(testSourceDir, ".env"), "SECRET=value");
 
 			await merger.merge(testSourceDir, testDestDir, true);
 
-			// Verify normal file was copied but .env was not
+			// Verify both files were copied (no existing .env to protect)
 			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
-			expect(existsSync(join(testDestDir, ".env"))).toBe(false);
+			expect(existsSync(join(testDestDir, ".env"))).toBe(true);
 		});
 
-		test("should skip protected patterns like *.key", async () => {
+		test("should skip protected patterns like *.key if they exist in destination", async () => {
+			await writeFile(join(testSourceDir, "normal.txt"), "normal");
+			await writeFile(join(testSourceDir, "private.key"), "new key data");
+
+			// Create existing key file in destination
+			await writeFile(join(testDestDir, "private.key"), "old key data");
+
+			await merger.merge(testSourceDir, testDestDir, true);
+
+			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
+
+			// Verify key file was NOT overwritten
+			const keyContent = await Bun.file(join(testDestDir, "private.key")).text();
+			expect(keyContent).toBe("old key data");
+		});
+
+		test("should copy protected patterns like *.key if they don't exist in destination", async () => {
 			await writeFile(join(testSourceDir, "normal.txt"), "normal");
 			await writeFile(join(testSourceDir, "private.key"), "key data");
 
 			await merger.merge(testSourceDir, testDestDir, true);
 
 			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
-			expect(existsSync(join(testDestDir, "private.key"))).toBe(false);
+			expect(existsSync(join(testDestDir, "private.key"))).toBe(true);
 		});
 
 		test("should handle nested directories", async () => {
@@ -123,7 +157,25 @@ describe("FileMerger", () => {
 			expect(existsSync(join(testDestDir, specialFileName))).toBe(true);
 		});
 
-		test("should skip custom ignore patterns", async () => {
+		test("should skip custom ignore patterns if they exist in destination", async () => {
+			merger.addIgnorePatterns(["custom-*"]);
+
+			await writeFile(join(testSourceDir, "normal.txt"), "normal");
+			await writeFile(join(testSourceDir, "custom-ignore.txt"), "new content");
+
+			// Create existing file in destination
+			await writeFile(join(testDestDir, "custom-ignore.txt"), "old content");
+
+			await merger.merge(testSourceDir, testDestDir, true);
+
+			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
+
+			// Verify custom file was NOT overwritten
+			const customContent = await Bun.file(join(testDestDir, "custom-ignore.txt")).text();
+			expect(customContent).toBe("old content");
+		});
+
+		test("should copy custom ignore patterns if they don't exist in destination", async () => {
 			merger.addIgnorePatterns(["custom-*"]);
 
 			await writeFile(join(testSourceDir, "normal.txt"), "normal");
@@ -132,7 +184,7 @@ describe("FileMerger", () => {
 			await merger.merge(testSourceDir, testDestDir, true);
 
 			expect(existsSync(join(testDestDir, "normal.txt"))).toBe(true);
-			expect(existsSync(join(testDestDir, "custom-ignore.txt"))).toBe(false);
+			expect(existsSync(join(testDestDir, "custom-ignore.txt"))).toBe(true);
 		});
 	});
 

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

@@ -1,13 +0,0 @@
-{
-	"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

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

package/test-integration/demo/CLAUDE.md

@@ -1,34 +0,0 @@
-# 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
-```