claudekit-cli 1.0.1 → 1.2.0

package/package.json

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

package/src/commands/new.ts

@@ -1,6 +1,7 @@
 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";
@@ -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,12 +1,14 @@
 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";
 
 export async function updateCommand(options: UpdateCommandOptions): Promise<void> {
@@ -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/commands/version.ts

@@ -0,0 +1,135 @@
+import pc from "picocolors";
+import { GitHubClient } from "../lib/github.js";
+import { PromptsManager } from "../lib/prompts.js";
+import {
+	AVAILABLE_KITS,
+	type GitHubRelease,
+	type VersionCommandOptions,
+	VersionCommandOptionsSchema,
+} from "../types.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Format a date as a relative time string
+ */
+function formatRelativeTime(dateString?: string): string {
+	if (!dateString) return "Unknown";
+
+	const date = new Date(dateString);
+	const now = new Date();
+	const diffMs = now.getTime() - date.getTime();
+	const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+	if (diffDays === 0) return "Today";
+	if (diffDays === 1) return "Yesterday";
+	if (diffDays < 7) return `${diffDays} days ago`;
+	if (diffDays < 30) return `${Math.floor(diffDays / 7)} weeks ago`;
+	if (diffDays < 365) return `${Math.floor(diffDays / 30)} months ago`;
+	return `${Math.floor(diffDays / 365)} years ago`;
+}
+
+/**
+ * Display releases for a single kit
+ */
+function displayKitReleases(kitName: string, releases: GitHubRelease[]): void {
+	console.log(`\n${pc.bold(pc.cyan(kitName))} - Available Versions:\n`);
+
+	if (releases.length === 0) {
+		console.log(pc.dim("  No releases found"));
+		return;
+	}
+
+	for (const release of releases) {
+		const version = pc.green(release.tag_name);
+		const name = release.name || "No title";
+		const publishedAt = formatRelativeTime(release.published_at);
+		const assetCount = release.assets.length;
+
+		// Add badges for prerelease and draft
+		const badges: string[] = [];
+		if (release.prerelease) badges.push(pc.yellow("[prerelease]"));
+		if (release.draft) badges.push(pc.gray("[draft]"));
+		const badgeStr = badges.length > 0 ? ` ${badges.join(" ")}` : "";
+
+		// Format: version  |  name  |  time  |  assets
+		const versionPart = version.padEnd(20);
+		const namePart = name.length > 40 ? `${name.slice(0, 37)}...` : name.padEnd(40);
+		const timePart = pc.dim(publishedAt.padEnd(20));
+		const assetPart = pc.dim(`(${assetCount} ${assetCount === 1 ? "asset" : "assets"})`);
+
+		console.log(`  ${versionPart}  ${namePart}  ${timePart}  ${assetPart}${badgeStr}`);
+	}
+
+	console.log(
+		pc.dim(`\nShowing ${releases.length} ${releases.length === 1 ? "release" : "releases"}`),
+	);
+}
+
+/**
+ * Version command - List available versions of ClaudeKit repositories
+ */
+export async function versionCommand(options: VersionCommandOptions): Promise<void> {
+	const prompts = new PromptsManager();
+
+	prompts.intro("📦 ClaudeKit - Available Versions");
+
+	try {
+		// Validate and parse options
+		const validOptions = VersionCommandOptionsSchema.parse(options);
+
+		// Determine which kits to fetch
+		const kitsToFetch = validOptions.kit
+			? [validOptions.kit]
+			: (Object.keys(AVAILABLE_KITS) as Array<keyof typeof AVAILABLE_KITS>);
+
+		// Initialize GitHub client
+		const github = new GitHubClient();
+
+		// Determine limit (default to 30, similar to GitHub CLI)
+		const limit = validOptions.limit || 30;
+
+		// Fetch releases for all requested kits in parallel
+		const releasePromises = kitsToFetch.map(async (kitType) => {
+			const kitConfig = AVAILABLE_KITS[kitType];
+			try {
+				const releases = await github.listReleases(kitConfig, limit);
+
+				// Filter out drafts and prereleases unless --all flag is set
+				const filteredReleases = validOptions.all
+					? releases
+					: releases.filter((r) => !r.draft && !r.prerelease);
+
+				return {
+					kitType,
+					kitConfig,
+					releases: filteredReleases,
+					error: null,
+				};
+			} catch (error) {
+				return {
+					kitType,
+					kitConfig,
+					releases: [],
+					error: error instanceof Error ? error.message : "Unknown error",
+				};
+			}
+		});
+
+		const results = await Promise.all(releasePromises);
+
+		// Display results
+		for (const result of results) {
+			if (result.error) {
+				console.log(`\n${pc.bold(pc.cyan(result.kitConfig.name))} - ${pc.red("Error")}`);
+				console.log(pc.dim(`  ${result.error}`));
+			} else {
+				displayKitReleases(result.kitConfig.name, result.releases);
+			}
+		}
+
+		prompts.outro("✨ Done");
+	} catch (error) {
+		logger.error(error instanceof Error ? error.message : "Unknown error occurred");
+		process.exit(1);
+	}
+}

package/src/index.ts

@@ -6,6 +6,16 @@ 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";
+
+// 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));
 
@@ -14,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")
@@ -34,11 +48,49 @@ cli
 		await updateCommand(options);
 	});
 
+// Versions command
+cli
+	.command("versions", "List available versions of ClaudeKit repositories")
+	.option("--kit <kit>", "Filter by specific kit (engineer, marketing)")
+	.option("--limit <limit>", "Number of releases to show (default: 30)")
+	.option("--all", "Show all releases including prereleases")
+	.action(async (options) => {
+		await versionCommand(options);
+	});
+
 // Version
 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,6 +5,7 @@ import { join } from "node:path";
 import { pipeline } from "node:stream";
 import { promisify } from "node:util";
 import cliProgress from "cli-progress";
+import ignore from "ignore";
 import ora from "ora";
 import * as tar from "tar";
 import unzipper from "unzipper";
@@ -19,6 +20,29 @@ import { logger } from "../utils/logger.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
 	 */
@@ -91,6 +115,90 @@ 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}`;
+			headers.Accept = "application/vnd.github+json";
+		} 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
+		const progressBar =
+			totalSize > 0
+				? new cliProgress.SingleBar({
+						format: "Progress |{bar}| {percentage}% | {value}/{total} MB",
+						barCompleteChar: "\u2588",
+						barIncompleteChar: "\u2591",
+						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
 	 */
@@ -133,6 +241,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 +256,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);
+			}
+		}
 	}
 
 	/**