claudekit-cli 1.1.0 → 1.2.1

package/package.json

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

package/src/commands/new.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { pathExists, readdir } from "fs-extra";
-import ora from "ora";
+import { AuthManager } from "../lib/auth.js";
 import { DownloadManager } from "../lib/download.js";
 import { GitHubClient } from "../lib/github.js";
 import { FileMerger } from "../lib/merge.js";
@@ -8,6 +8,7 @@ import { PromptsManager } from "../lib/prompts.js";
 import { AVAILABLE_KITS, type NewCommandOptions, NewCommandOptionsSchema } from "../types.js";
 import { ConfigManager } from "../utils/config.js";
 import { logger } from "../utils/logger.js";
+import { createSpinner } from "../utils/safe-spinner.js";
 
 export async function newCommand(options: NewCommandOptions): Promise<void> {
 	const prompts = new PromptsManager();
@@ -58,7 +59,7 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 		const github = new GitHubClient();
 
 		// Check repository access
-		const spinner = ora("Checking repository access...").start();
+		const spinner = createSpinner("Checking repository access...").start();
 		const hasAccess = await github.checkAccess(kitConfig);
 		if (!hasAccess) {
 			spinner.fail("Access denied to repository");
@@ -81,20 +82,51 @@ export async function newCommand(options: NewCommandOptions): Promise<void> {
 
 		logger.success(`Found release: ${release.tag_name} - ${release.name}`);
 
-		// Find downloadable asset
-		const asset = release.assets.find(
-			(a) => a.name.endsWith(".tar.gz") || a.name.endsWith(".tgz") || a.name.endsWith(".zip"),
-		);
+		// Get downloadable asset (custom asset or GitHub tarball)
+		const downloadInfo = GitHubClient.getDownloadableAsset(release);
 
-		if (!asset) {
-			logger.error("No downloadable archive found in release");
-			return;
-		}
+		logger.info(`Download source: ${downloadInfo.type}`);
+		logger.debug(`Download URL: ${downloadInfo.url}`);
 
 		// Download asset
 		const downloadManager = new DownloadManager();
 		const tempDir = await downloadManager.createTempDir();
-		const archivePath = await downloadManager.downloadAsset(asset, tempDir);
+
+		// Get authentication token for API requests
+		const { token } = await AuthManager.getToken();
+
+		let archivePath: string;
+		try {
+			// Try downloading the asset/tarball with authentication
+			archivePath = await downloadManager.downloadFile({
+				url: downloadInfo.url,
+				name: downloadInfo.name,
+				size: downloadInfo.size,
+				destDir: tempDir,
+				token, // Always pass token for private repository access
+			});
+		} catch (error) {
+			// If asset download fails, fallback to GitHub tarball
+			if (downloadInfo.type === "asset") {
+				logger.warning("Asset download failed, falling back to GitHub tarball...");
+				const tarballInfo = {
+					type: "github-tarball" as const,
+					url: release.tarball_url,
+					name: `${kitConfig.repo}-${release.tag_name}.tar.gz`,
+					size: 0, // Size unknown for tarball
+				};
+
+				archivePath = await downloadManager.downloadFile({
+					url: tarballInfo.url,
+					name: tarballInfo.name,
+					size: tarballInfo.size,
+					destDir: tempDir,
+					token,
+				});
+			} else {
+				throw error;
+			}
+		}
 
 		// Extract archive
 		const extractDir = `${tempDir}/extracted`;

package/src/commands/update.ts

@@ -1,13 +1,15 @@
 import { resolve } from "node:path";
 import { pathExists } from "fs-extra";
-import ora from "ora";
+import { AuthManager } from "../lib/auth.js";
 import { DownloadManager } from "../lib/download.js";
 import { GitHubClient } from "../lib/github.js";
 import { FileMerger } from "../lib/merge.js";
 import { PromptsManager } from "../lib/prompts.js";
 import { AVAILABLE_KITS, type UpdateCommandOptions, UpdateCommandOptionsSchema } from "../types.js";
 import { ConfigManager } from "../utils/config.js";
+import { FileScanner } from "../utils/file-scanner.js";
 import { logger } from "../utils/logger.js";
+import { createSpinner } from "../utils/safe-spinner.js";
 
 export async function updateCommand(options: UpdateCommandOptions): Promise<void> {
 	const prompts = new PromptsManager();
@@ -50,7 +52,7 @@ export async function updateCommand(options: UpdateCommandOptions): Promise<void
 		const github = new GitHubClient();
 
 		// Check repository access
-		const spinner = ora("Checking repository access...").start();
+		const spinner = createSpinner("Checking repository access...").start();
 		const hasAccess = await github.checkAccess(kitConfig);
 		if (!hasAccess) {
 			spinner.fail("Access denied to repository");
@@ -73,36 +75,80 @@ export async function updateCommand(options: UpdateCommandOptions): Promise<void
 
 		logger.success(`Found release: ${release.tag_name} - ${release.name}`);
 
-		// Find downloadable asset
-		const asset = release.assets.find(
-			(a) => a.name.endsWith(".tar.gz") || a.name.endsWith(".tgz") || a.name.endsWith(".zip"),
-		);
+		// Get downloadable asset (custom asset or GitHub tarball)
+		const downloadInfo = GitHubClient.getDownloadableAsset(release);
 
-		if (!asset) {
-			logger.error("No downloadable archive found in release");
-			return;
-		}
+		logger.info(`Download source: ${downloadInfo.type}`);
+		logger.debug(`Download URL: ${downloadInfo.url}`);
 
 		// Download asset
 		const downloadManager = new DownloadManager();
 		const tempDir = await downloadManager.createTempDir();
-		const archivePath = await downloadManager.downloadAsset(asset, tempDir);
+
+		// Get authentication token for API requests
+		const { token } = await AuthManager.getToken();
+
+		let archivePath: string;
+		try {
+			// Try downloading the asset/tarball with authentication
+			archivePath = await downloadManager.downloadFile({
+				url: downloadInfo.url,
+				name: downloadInfo.name,
+				size: downloadInfo.size,
+				destDir: tempDir,
+				token, // Always pass token for private repository access
+			});
+		} catch (error) {
+			// If asset download fails, fallback to GitHub tarball
+			if (downloadInfo.type === "asset") {
+				logger.warning("Asset download failed, falling back to GitHub tarball...");
+				const tarballInfo = {
+					type: "github-tarball" as const,
+					url: release.tarball_url,
+					name: `${kitConfig.repo}-${release.tag_name}.tar.gz`,
+					size: 0, // Size unknown for tarball
+				};
+
+				archivePath = await downloadManager.downloadFile({
+					url: tarballInfo.url,
+					name: tarballInfo.name,
+					size: tarballInfo.size,
+					destDir: tempDir,
+					token,
+				});
+			} else {
+				throw error;
+			}
+		}
 
 		// Extract archive
 		const extractDir = `${tempDir}/extracted`;
 		await downloadManager.extractArchive(archivePath, extractDir);
 
+		// Identify custom .claude files to preserve
+		logger.info("Scanning for custom .claude files...");
+		const customClaudeFiles = await FileScanner.findCustomFiles(resolvedDir, extractDir, ".claude");
+
 		// Merge files with confirmation
 		const merger = new FileMerger();
+
+		// Add custom .claude files to ignore patterns
+		if (customClaudeFiles.length > 0) {
+			merger.addIgnorePatterns(customClaudeFiles);
+			logger.success(`Protected ${customClaudeFiles.length} custom .claude file(s)`);
+		}
+
 		await merger.merge(extractDir, resolvedDir, false); // Show confirmation for updates
 
 		prompts.outro(`✨ Project updated successfully at ${resolvedDir}`);
 
 		// Show next steps
-		prompts.note(
-			"Your project has been updated with the latest version.\nProtected files (.env, etc.) were not modified.",
-			"Update complete",
-		);
+		const protectedNote =
+			customClaudeFiles.length > 0
+				? "Your project has been updated with the latest version.\nProtected files (.env, .claude custom files, etc.) were not modified."
+				: "Your project has been updated with the latest version.\nProtected files (.env, etc.) were not modified.";
+
+		prompts.note(protectedNote, "Update complete");
 	} catch (error) {
 		if (error instanceof Error && error.message === "Merge cancelled by user") {
 			logger.warning("Update cancelled");

package/src/index.ts

@@ -7,6 +7,15 @@ 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";
+
+// Set proper output encoding to prevent unicode rendering issues
+if (process.stdout.setEncoding) {
+	process.stdout.setEncoding("utf8");
+}
+if (process.stderr.setEncoding) {
+	process.stderr.setEncoding("utf8");
+}
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 
@@ -15,6 +24,10 @@ const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"),
 
 const cli = cac("ck");
 
+// Global options
+cli.option("--verbose, -v", "Enable verbose logging for debugging");
+cli.option("--log-file <path>", "Write logs to file");
+
 // New command
 cli
 	.command("new", "Bootstrap a new ClaudeKit project")
@@ -51,5 +64,33 @@ cli.version(packageJson.version);
 // Help
 cli.help();
 
-// Parse CLI arguments
+// Parse to get global options first
+const parsed = cli.parse(process.argv, { run: false });
+
+// Check environment variable
+const envVerbose =
+	process.env.CLAUDEKIT_VERBOSE === "1" || process.env.CLAUDEKIT_VERBOSE === "true";
+
+// Enable verbose if flag or env var is set
+const isVerbose = parsed.options.verbose || envVerbose;
+
+if (isVerbose) {
+	logger.setVerbose(true);
+}
+
+// Set log file if specified
+if (parsed.options.logFile) {
+	logger.setLogFile(parsed.options.logFile);
+}
+
+// Log startup info in verbose mode
+logger.verbose("ClaudeKit CLI starting", {
+	version: packageJson.version,
+	command: parsed.args[0] || "none",
+	options: parsed.options,
+	cwd: process.cwd(),
+	node: process.version,
+});
+
+// Parse again to run the command
 cli.parse();

package/src/lib/download.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { pipeline } from "node:stream";
 import { promisify } from "node:util";
 import cliProgress from "cli-progress";
-import ora from "ora";
+import ignore from "ignore";
 import * as tar from "tar";
 import unzipper from "unzipper";
 import {
@@ -15,10 +15,34 @@ import {
 	type GitHubReleaseAsset,
 } from "../types.js";
 import { logger } from "../utils/logger.js";
+import { createSpinner } from "../utils/safe-spinner.js";
 
 const streamPipeline = promisify(pipeline);
 
 export class DownloadManager {
+	/**
+	 * Patterns to exclude from extraction
+	 */
+	private static EXCLUDE_PATTERNS = [
+		".git",
+		".git/**",
+		".github",
+		".github/**",
+		"node_modules",
+		"node_modules/**",
+		".DS_Store",
+		"Thumbs.db",
+		"*.log",
+	];
+
+	/**
+	 * Check if file path should be excluded
+	 */
+	private shouldExclude(filePath: string): boolean {
+		const ig = ignore().add(DownloadManager.EXCLUDE_PATTERNS);
+		return ig.ignores(filePath);
+	}
+
 	/**
 	 * Download asset from URL with progress tracking
 	 */
@@ -31,11 +55,11 @@ export class DownloadManager {
 
 			logger.info(`Downloading ${asset.name} (${this.formatBytes(asset.size)})...`);
 
-			// Create progress bar
+			// Create progress bar with simple ASCII characters
 			const progressBar = new cliProgress.SingleBar({
 				format: "Progress |{bar}| {percentage}% | {value}/{total} MB",
-				barCompleteChar: "\u2588",
-				barIncompleteChar: "\u2591",
+				barCompleteChar: "=",
+				barIncompleteChar: "-",
 				hideCursor: true,
 			});
 
@@ -91,6 +115,92 @@ export class DownloadManager {
 		}
 	}
 
+	/**
+	 * Download file from URL with progress tracking (supports both assets and API URLs)
+	 */
+	async downloadFile(params: {
+		url: string;
+		name: string;
+		size?: number;
+		destDir: string;
+		token?: string;
+	}): Promise<string> {
+		const { url, name, size, destDir, token } = params;
+		const destPath = join(destDir, name);
+
+		await mkdir(destDir, { recursive: true });
+
+		logger.info(`Downloading ${name}${size ? ` (${this.formatBytes(size)})` : ""}...`);
+
+		const headers: Record<string, string> = {};
+
+		// Add authentication for GitHub API URLs
+		if (token && url.includes("api.github.com")) {
+			headers.Authorization = `Bearer ${token}`;
+			// Use application/octet-stream for asset downloads (not vnd.github+json)
+			headers.Accept = "application/octet-stream";
+			headers["X-GitHub-Api-Version"] = "2022-11-28";
+		} else {
+			headers.Accept = "application/octet-stream";
+		}
+
+		const response = await fetch(url, { headers });
+
+		if (!response.ok) {
+			throw new DownloadError(`Failed to download: ${response.statusText}`);
+		}
+
+		const totalSize = size || Number(response.headers.get("content-length")) || 0;
+		let downloadedSize = 0;
+
+		// Create progress bar only if we know the size (using simple ASCII characters)
+		const progressBar =
+			totalSize > 0
+				? new cliProgress.SingleBar({
+						format: "Progress |{bar}| {percentage}% | {value}/{total} MB",
+						barCompleteChar: "=",
+						barIncompleteChar: "-",
+						hideCursor: true,
+					})
+				: null;
+
+		if (progressBar) {
+			progressBar.start(Math.round(totalSize / 1024 / 1024), 0);
+		}
+
+		const fileStream = createWriteStream(destPath);
+		const reader = response.body?.getReader();
+
+		if (!reader) {
+			throw new DownloadError("Failed to get response reader");
+		}
+
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+
+				if (done) break;
+
+				fileStream.write(value);
+				downloadedSize += value.length;
+
+				if (progressBar) {
+					progressBar.update(Math.round(downloadedSize / 1024 / 1024));
+				}
+			}
+
+			fileStream.end();
+			if (progressBar) progressBar.stop();
+
+			logger.success(`Downloaded ${name}`);
+			return destPath;
+		} catch (error) {
+			fileStream.close();
+			if (progressBar) progressBar.stop();
+			throw error;
+		}
+	}
+
 	/**
 	 * Extract archive to destination
 	 */
@@ -99,7 +209,7 @@ export class DownloadManager {
 		destDir: string,
 		archiveType?: ArchiveType,
 	): Promise<void> {
-		const spinner = ora("Extracting files...").start();
+		const spinner = createSpinner("Extracting files...").start();
 
 		try {
 			// Detect archive type from filename if not provided
@@ -133,6 +243,14 @@ export class DownloadManager {
 			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}`);
+				}
+				return shouldInclude;
+			},
 		});
 	}
 
@@ -140,7 +258,121 @@ export class DownloadManager {
 	 * Extract zip archive
 	 */
 	private async extractZip(archivePath: string, destDir: string): Promise<void> {
-		await streamPipeline(createReadStream(archivePath), unzipper.Extract({ path: destDir }));
+		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 zip to temp directory
+			await streamPipeline(
+				createReadStream(archivePath),
+				unzipper.Extract({ path: tempExtractDir }),
+			);
+
+			// Find the root directory in the zip (if any)
+			const entries = await readdir(tempExtractDir);
+
+			// If there's a single root directory, strip it
+			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);
+				} else {
+					// Single file, just move it
+					await mkdirPromise(destDir, { recursive: true });
+					await copyFile(rootPath, pathJoin(destDir, rootEntry));
+				}
+			} else {
+				// Multiple entries at root, move them all
+				await this.moveDirectoryContents(tempExtractDir, 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;
+		}
+	}
+
+	/**
+	 * Move directory contents from source to destination, applying exclusion filters
+	 */
+	private async moveDirectoryContents(sourceDir: string, destDir: string): Promise<void> {
+		const { readdir, stat, mkdir: mkdirPromise, copyFile } = await import("node:fs/promises");
+		const { join: pathJoin, relative } = await import("node:path");
+
+		await mkdirPromise(destDir, { recursive: true });
+
+		const entries = await readdir(sourceDir);
+
+		for (const entry of entries) {
+			const sourcePath = pathJoin(sourceDir, entry);
+			const destPath = pathJoin(destDir, entry);
+			const relativePath = relative(sourceDir, sourcePath);
+
+			// Skip excluded files
+			if (this.shouldExclude(relativePath)) {
+				logger.debug(`Excluding: ${relativePath}`);
+				continue;
+			}
+
+			const entryStat = await stat(sourcePath);
+
+			if (entryStat.isDirectory()) {
+				// Recursively copy directory
+				await this.copyDirectory(sourcePath, destPath);
+			} else {
+				// Copy file
+				await copyFile(sourcePath, destPath);
+			}
+		}
+	}
+
+	/**
+	 * Recursively copy directory
+	 */
+	private async copyDirectory(sourceDir: string, destDir: string): Promise<void> {
+		const { readdir, stat, mkdir: mkdirPromise, copyFile } = await import("node:fs/promises");
+		const { join: pathJoin, relative } = await import("node:path");
+
+		await mkdirPromise(destDir, { recursive: true });
+
+		const entries = await readdir(sourceDir);
+
+		for (const entry of entries) {
+			const sourcePath = pathJoin(sourceDir, entry);
+			const destPath = pathJoin(destDir, entry);
+			const relativePath = relative(sourceDir, sourcePath);
+
+			// Skip excluded files
+			if (this.shouldExclude(relativePath)) {
+				logger.debug(`Excluding: ${relativePath}`);
+				continue;
+			}
+
+			const entryStat = await stat(sourcePath);
+
+			if (entryStat.isDirectory()) {
+				// Recursively copy directory
+				await this.copyDirectory(sourcePath, destPath);
+			} else {
+				// Copy file
+				await copyFile(sourcePath, destPath);
+			}
+		}
 	}
 
 	/**

package/src/lib/github.ts

@@ -154,4 +154,77 @@ export class GitHubClient {
 			);
 		}
 	}
+
+	/**
+	 * Get downloadable asset or source code URL from release
+	 * Priority:
+	 * 1. "ClaudeKit Engineer Package" or "ClaudeKit Marketing Package" zip file
+	 * 2. Other custom uploaded assets (.tar.gz, .tgz, .zip) excluding "Source code" archives
+	 * 3. GitHub's automatic tarball URL
+	 */
+	static getDownloadableAsset(release: GitHubRelease): {
+		type: "asset" | "tarball" | "zipball";
+		url: string;
+		name: string;
+		size?: number;
+	} {
+		// Log all available assets for debugging
+		logger.debug(`Available assets for ${release.tag_name}:`);
+		if (release.assets.length === 0) {
+			logger.debug("  No custom assets found");
+		} else {
+			release.assets.forEach((asset, index) => {
+				logger.debug(`  ${index + 1}. ${asset.name} (${(asset.size / 1024 / 1024).toFixed(2)} MB)`);
+			});
+		}
+
+		// First priority: Look for official ClaudeKit package assets
+		const packageAsset = release.assets.find((a) => {
+			const nameLower = a.name.toLowerCase();
+			return (
+				nameLower.includes("claudekit") &&
+				nameLower.includes("package") &&
+				nameLower.endsWith(".zip")
+			);
+		});
+
+		if (packageAsset) {
+			logger.debug(`✓ Selected ClaudeKit package asset: ${packageAsset.name}`);
+			return {
+				type: "asset",
+				url: packageAsset.url, // Use API endpoint for authenticated downloads
+				name: packageAsset.name,
+				size: packageAsset.size,
+			};
+		}
+
+		logger.debug("⚠ No ClaudeKit package asset found, checking for other custom assets...");
+
+		// Second priority: Look for any custom uploaded assets (excluding GitHub's automatic source code archives)
+		const customAsset = release.assets.find(
+			(a) =>
+				(a.name.endsWith(".tar.gz") || a.name.endsWith(".tgz") || a.name.endsWith(".zip")) &&
+				!a.name.toLowerCase().startsWith("source") &&
+				!a.name.toLowerCase().includes("source code"),
+		);
+
+		if (customAsset) {
+			logger.debug(`✓ Selected custom asset: ${customAsset.name}`);
+			return {
+				type: "asset",
+				url: customAsset.url, // Use API endpoint for authenticated downloads
+				name: customAsset.name,
+				size: customAsset.size,
+			};
+		}
+
+		// Fall back to GitHub's automatic tarball
+		logger.debug("⚠ No custom assets found, falling back to GitHub automatic tarball");
+		return {
+			type: "tarball",
+			url: release.tarball_url,
+			name: `${release.tag_name}.tar.gz`,
+			size: undefined, // Size unknown for automatic tarballs
+		};
+	}
 }

package/src/lib/prompts.ts

@@ -1,5 +1,6 @@
 import * as clack from "@clack/prompts";
 import { AVAILABLE_KITS, type KitType } from "../types.js";
+import { intro, note, outro } from "../utils/safe-prompts.js";
 
 export class PromptsManager {
 	/**
@@ -94,20 +95,20 @@ export class PromptsManager {
 	 * Show intro message
 	 */
 	intro(message: string): void {
-		clack.intro(message);
+		intro(message);
 	}
 
 	/**
 	 * Show outro message
 	 */
 	outro(message: string): void {
-		clack.outro(message);
+		outro(message);
 	}
 
 	/**
 	 * Show note
 	 */
 	note(message: string, title?: string): void {
-		clack.note(message, title);
+		note(message, title);
 	}
 }