claudekit-cli 1.0.0

package/src/lib/prompts.ts

@@ -0,0 +1,113 @@
+import * as clack from "@clack/prompts";
+import { AVAILABLE_KITS, type KitType } from "../types.js";
+
+export class PromptsManager {
+	/**
+	 * Prompt user to select a kit
+	 */
+	async selectKit(defaultKit?: KitType): Promise<KitType> {
+		const kit = await clack.select({
+			message: "Select a ClaudeKit:",
+			options: Object.entries(AVAILABLE_KITS).map(([key, config]) => ({
+				value: key as KitType,
+				label: config.name,
+				hint: config.description,
+			})),
+			initialValue: defaultKit,
+		});
+
+		if (clack.isCancel(kit)) {
+			throw new Error("Kit selection cancelled");
+		}
+
+		return kit as KitType;
+	}
+
+	/**
+	 * Prompt user to select a version
+	 */
+	async selectVersion(versions: string[], defaultVersion?: string): Promise<string> {
+		if (versions.length === 0) {
+			throw new Error("No versions available");
+		}
+
+		// If only one version or default is latest, return first version
+		if (versions.length === 1 || !defaultVersion) {
+			return versions[0];
+		}
+
+		const version = await clack.select({
+			message: "Select a version:",
+			options: versions.map((v) => ({
+				value: v,
+				label: v,
+			})),
+			initialValue: defaultVersion,
+		});
+
+		if (clack.isCancel(version)) {
+			throw new Error("Version selection cancelled");
+		}
+
+		return version as string;
+	}
+
+	/**
+	 * Prompt user for target directory
+	 */
+	async getDirectory(defaultDir = "."): Promise<string> {
+		const dir = await clack.text({
+			message: "Enter target directory:",
+			placeholder: defaultDir,
+			defaultValue: defaultDir,
+			validate: (value) => {
+				if (!value || value.trim().length === 0) {
+					return "Directory path is required";
+				}
+				return;
+			},
+		});
+
+		if (clack.isCancel(dir)) {
+			throw new Error("Directory input cancelled");
+		}
+
+		return dir.trim();
+	}
+
+	/**
+	 * Confirm action
+	 */
+	async confirm(message: string): Promise<boolean> {
+		const result = await clack.confirm({
+			message,
+		});
+
+		if (clack.isCancel(result)) {
+			return false;
+		}
+
+		return result;
+	}
+
+	/**
+	 * Show intro message
+	 */
+	intro(message: string): void {
+		clack.intro(message);
+	}
+
+	/**
+	 * Show outro message
+	 */
+	outro(message: string): void {
+		clack.outro(message);
+	}
+
+	/**
+	 * Show note
+	 */
+	note(message: string, title?: string): void {
+		clack.note(message, title);
+	}
+}

package/src/types.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+
+// Kit types
+export const KitType = z.enum(["engineer", "marketing"]);
+export type KitType = z.infer<typeof KitType>;
+
+// Command options schemas
+export const NewCommandOptionsSchema = z.object({
+	dir: z.string().default("."),
+	kit: KitType.optional(),
+	version: z.string().optional(),
+});
+export type NewCommandOptions = z.infer<typeof NewCommandOptionsSchema>;
+
+export const UpdateCommandOptionsSchema = z.object({
+	dir: z.string().default("."),
+	kit: KitType.optional(),
+	version: z.string().optional(),
+});
+export type UpdateCommandOptions = z.infer<typeof UpdateCommandOptionsSchema>;
+
+// Config schemas
+export const ConfigSchema = z.object({
+	github: z
+		.object({
+			token: z.string().optional(),
+		})
+		.optional(),
+	defaults: z
+		.object({
+			kit: KitType.optional(),
+			dir: z.string().optional(),
+		})
+		.optional(),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+// GitHub schemas
+export const GitHubReleaseAssetSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	browser_download_url: z.string().url(),
+	size: z.number(),
+	content_type: z.string(),
+});
+export type GitHubReleaseAsset = z.infer<typeof GitHubReleaseAssetSchema>;
+
+export const GitHubReleaseSchema = z.object({
+	id: z.number(),
+	tag_name: z.string(),
+	name: z.string(),
+	draft: z.boolean(),
+	prerelease: z.boolean(),
+	assets: z.array(GitHubReleaseAssetSchema),
+	published_at: z.string().optional(),
+});
+export type GitHubRelease = z.infer<typeof GitHubReleaseSchema>;
+
+// Kit configuration
+export const KitConfigSchema = z.object({
+	name: z.string(),
+	repo: z.string(),
+	owner: z.string(),
+	description: z.string(),
+});
+export type KitConfig = z.infer<typeof KitConfigSchema>;
+
+// Available kits
+export const AVAILABLE_KITS: Record<KitType, KitConfig> = {
+	engineer: {
+		name: "ClaudeKit Engineer",
+		repo: "claudekit-engineer",
+		owner: "mrgoonie",
+		description: "Engineering toolkit for building with Claude",
+	},
+	marketing: {
+		name: "ClaudeKit Marketing",
+		repo: "claudekit-marketing",
+		owner: "mrgoonie",
+		description: "[Coming Soon] Marketing toolkit",
+	},
+};
+
+// Protected file patterns (files to skip during update)
+export const PROTECTED_PATTERNS = [
+	".env",
+	".env.local",
+	".env.*.local",
+	"*.key",
+	"*.pem",
+	"*.p12",
+	"node_modules/**",
+	".git/**",
+	"dist/**",
+	"build/**",
+];
+
+// Archive types
+export type ArchiveType = "tar.gz" | "zip";
+
+// Download progress
+export interface DownloadProgress {
+	total: number;
+	current: number;
+	percentage: number;
+}
+
+// Authentication method
+export type AuthMethod = "gh-cli" | "env-var" | "keychain" | "prompt";
+
+// Error types
+export class ClaudeKitError extends Error {
+	constructor(
+		message: string,
+		public code?: string,
+		public statusCode?: number,
+	) {
+		super(message);
+		this.name = "ClaudeKitError";
+	}
+}
+
+export class AuthenticationError extends ClaudeKitError {
+	constructor(message: string) {
+		super(message, "AUTH_ERROR", 401);
+		this.name = "AuthenticationError";
+	}
+}
+
+export class GitHubError extends ClaudeKitError {
+	constructor(message: string, statusCode?: number) {
+		super(message, "GITHUB_ERROR", statusCode);
+		this.name = "GitHubError";
+	}
+}
+
+export class DownloadError extends ClaudeKitError {
+	constructor(message: string) {
+		super(message, "DOWNLOAD_ERROR");
+		this.name = "DownloadError";
+	}
+}
+
+export class ExtractionError extends ClaudeKitError {
+	constructor(message: string) {
+		super(message, "EXTRACTION_ERROR");
+		this.name = "ExtractionError";
+	}
+}

package/src/utils/config.ts

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Config, ConfigSchema } from "../types.js";
+import { logger } from "./logger.js";
+
+const CONFIG_DIR = join(homedir(), ".claudekit");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export class ConfigManager {
+	private static config: Config | null = null;
+
+	static async load(): Promise<Config> {
+		if (ConfigManager.config) {
+			return ConfigManager.config;
+		}
+
+		try {
+			if (existsSync(CONFIG_FILE)) {
+				const content = await readFile(CONFIG_FILE, "utf-8");
+				const data = JSON.parse(content);
+				ConfigManager.config = ConfigSchema.parse(data);
+				logger.debug(`Config loaded from ${CONFIG_FILE}`);
+				return ConfigManager.config;
+			}
+		} catch (error) {
+			logger.warning(
+				`Failed to load config: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+
+		// Return default config
+		ConfigManager.config = { github: {}, defaults: {} };
+		return ConfigManager.config;
+	}
+
+	static async save(config: Config): Promise<void> {
+		try {
+			// Validate config
+			const validConfig = ConfigSchema.parse(config);
+
+			// Ensure config directory exists
+			if (!existsSync(CONFIG_DIR)) {
+				await mkdir(CONFIG_DIR, { recursive: true });
+			}
+
+			// Write config file
+			await writeFile(CONFIG_FILE, JSON.stringify(validConfig, null, 2), "utf-8");
+			ConfigManager.config = validConfig;
+			logger.debug(`Config saved to ${CONFIG_FILE}`);
+		} catch (error) {
+			throw new Error(
+				`Failed to save config: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+	}
+
+	static async get(): Promise<Config> {
+		return ConfigManager.load();
+	}
+
+	static async set(key: string, value: unknown): Promise<void> {
+		const config = await ConfigManager.load();
+		const keys = key.split(".");
+		let current: any = config;
+
+		for (let i = 0; i < keys.length - 1; i++) {
+			if (!(keys[i] in current)) {
+				current[keys[i]] = {};
+			}
+			current = current[keys[i]];
+		}
+
+		current[keys[keys.length - 1]] = value;
+		await ConfigManager.save(config);
+	}
+
+	static async getToken(): Promise<string | undefined> {
+		const config = await ConfigManager.load();
+		return config.github?.token;
+	}
+
+	static async setToken(token: string): Promise<void> {
+		await ConfigManager.set("github.token", token);
+	}
+}

package/src/utils/logger.ts

@@ -0,0 +1,37 @@
+import pc from "picocolors";
+
+export const logger = {
+	info: (message: string) => {
+		console.log(pc.blue("ℹ"), message);
+	},
+
+	success: (message: string) => {
+		console.log(pc.green("✔"), message);
+	},
+
+	warning: (message: string) => {
+		console.log(pc.yellow("⚠"), message);
+	},
+
+	error: (message: string) => {
+		console.error(pc.red("✖"), message);
+	},
+
+	debug: (message: string) => {
+		if (process.env.DEBUG) {
+			console.log(pc.gray("[DEBUG]"), message);
+		}
+	},
+
+	// Sanitize sensitive data from logs
+	sanitize: (text: string): string => {
+		// Remove GitHub tokens
+		return text
+			.replace(/ghp_[a-zA-Z0-9]{36}/g, "ghp_***")
+			.replace(/github_pat_[a-zA-Z0-9_]{82}/g, "github_pat_***")
+			.replace(/gho_[a-zA-Z0-9]{36}/g, "gho_***")
+			.replace(/ghu_[a-zA-Z0-9]{36}/g, "ghu_***")
+			.replace(/ghs_[a-zA-Z0-9]{36}/g, "ghs_***")
+			.replace(/ghr_[a-zA-Z0-9]{36}/g, "ghr_***");
+	},
+};

package/tests/lib/auth.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { AuthManager } from "../../src/lib/auth.js";
+import { AuthenticationError } from "../../src/types.js";
+
+describe("AuthManager", () => {
+	beforeEach(() => {
+		// Reset AuthManager state
+		(AuthManager as any).token = null;
+		(AuthManager as any).authMethod = null;
+	});
+
+	afterEach(() => {
+		// Clean up environment variables
+		process.env.GITHUB_TOKEN = undefined;
+		process.env.GH_TOKEN = undefined;
+	});
+
+	describe("isValidTokenFormat", () => {
+		test("should accept ghp_ tokens", () => {
+			expect(AuthManager.isValidTokenFormat("ghp_1234567890")).toBe(true);
+		});
+
+		test("should accept github_pat_ tokens", () => {
+			expect(AuthManager.isValidTokenFormat("github_pat_1234567890")).toBe(true);
+		});
+
+		test("should reject invalid token formats", () => {
+			expect(AuthManager.isValidTokenFormat("invalid_token")).toBe(false);
+			expect(AuthManager.isValidTokenFormat("gho_1234567890")).toBe(false);
+			expect(AuthManager.isValidTokenFormat("")).toBe(false);
+			expect(AuthManager.isValidTokenFormat("token123")).toBe(false);
+		});
+
+		test("should handle empty and malformed tokens", () => {
+			expect(AuthManager.isValidTokenFormat("")).toBe(false);
+			expect(AuthManager.isValidTokenFormat("ghp")).toBe(false);
+			expect(AuthManager.isValidTokenFormat("github_pat")).toBe(false);
+		});
+	});
+
+	describe("getToken - environment variables", () => {
+		test("should get token from environment (gh-cli, env-var, or cached)", async () => {
+			// Set environment variable to avoid prompting in CI
+			process.env.GITHUB_TOKEN = "ghp_test_token_ci_123";
+
+			// This test acknowledges that the token can come from multiple sources
+			// in the fallback chain: gh-cli > env-var > config > keychain > prompt
+			const result = await AuthManager.getToken();
+
+			expect(result.token).toBeDefined();
+			expect(result.token.length).toBeGreaterThan(0);
+			expect(result.method).toBeDefined();
+			// Method could be 'gh-cli', 'env-var', 'keychain', or 'prompt'
+			expect(["gh-cli", "env-var", "keychain", "prompt"]).toContain(result.method);
+		});
+
+		test("should cache token after first retrieval", async () => {
+			// Set environment variable to avoid prompting in CI
+			process.env.GITHUB_TOKEN = "ghp_test_token_cache_456";
+
+			// Clear cache first
+			(AuthManager as any).token = null;
+			(AuthManager as any).authMethod = null;
+
+			const result1 = await AuthManager.getToken();
+			const result2 = await AuthManager.getToken();
+
+			expect(result1.token).toBe(result2.token);
+			expect(result1.method).toBe(result2.method);
+		});
+
+		test("should handle GITHUB_TOKEN env var when gh-cli is not available", async () => {
+			// Note: If gh CLI is installed and authenticated, it will take precedence
+			// This test documents the expected behavior but may not enforce it
+			process.env.GITHUB_TOKEN = "ghp_test_token_123";
+
+			// Clear cache
+			(AuthManager as any).token = null;
+			(AuthManager as any).authMethod = null;
+
+			const result = await AuthManager.getToken();
+
+			// Token should either be from gh-cli or env-var
+			expect(result.token).toBeDefined();
+			expect(["gh-cli", "env-var"]).toContain(result.method);
+		});
+
+		test("should handle GH_TOKEN env var when GITHUB_TOKEN is not set", async () => {
+			process.env.GITHUB_TOKEN = undefined;
+			process.env.GH_TOKEN = "ghp_test_token_456";
+
+			// Clear cache
+			(AuthManager as any).token = null;
+			(AuthManager as any).authMethod = null;
+
+			const result = await AuthManager.getToken();
+
+			// Token should either be from gh-cli or env-var
+			expect(result.token).toBeDefined();
+			expect(["gh-cli", "env-var"]).toContain(result.method);
+		});
+	});
+
+	describe("clearToken", () => {
+		test("should clear cached token", async () => {
+			// Set a cached token
+			(AuthManager as any).token = "test-token";
+			(AuthManager as any).authMethod = "env-var";
+
+			await AuthManager.clearToken();
+
+			expect((AuthManager as any).token).toBeNull();
+			expect((AuthManager as any).authMethod).toBeNull();
+		});
+	});
+});

package/tests/lib/download.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { DownloadManager } from "../../src/lib/download.js";
+import { DownloadError, ExtractionError } from "../../src/types.js";
+
+describe("DownloadManager", () => {
+	let manager: DownloadManager;
+
+	beforeEach(() => {
+		manager = new DownloadManager();
+	});
+
+	describe("constructor", () => {
+		test("should create DownloadManager instance", () => {
+			expect(manager).toBeInstanceOf(DownloadManager);
+		});
+	});
+
+	describe("createTempDir", () => {
+		test("should create temporary directory", async () => {
+			const tempDir = await manager.createTempDir();
+
+			expect(tempDir).toBeDefined();
+			expect(typeof tempDir).toBe("string");
+			expect(tempDir).toContain("claudekit-");
+			expect(existsSync(tempDir)).toBe(true);
+
+			// Cleanup
+			await rm(tempDir, { recursive: true, force: true });
+		});
+
+		test("should create unique directories", async () => {
+			const tempDir1 = await manager.createTempDir();
+
+			// Wait 1ms to ensure different timestamps
+			await new Promise((resolve) => setTimeout(resolve, 1));
+
+			const tempDir2 = await manager.createTempDir();
+
+			expect(tempDir1).not.toBe(tempDir2);
+
+			// Cleanup
+			await rm(tempDir1, { recursive: true, force: true });
+			await rm(tempDir2, { recursive: true, force: true });
+		});
+	});
+
+	describe("error classes", () => {
+		test("DownloadError should store message", () => {
+			const error = new DownloadError("Download failed");
+			expect(error.message).toBe("Download failed");
+			expect(error.code).toBe("DOWNLOAD_ERROR");
+			expect(error.name).toBe("DownloadError");
+		});
+
+		test("ExtractionError should store message", () => {
+			const error = new ExtractionError("Extraction failed");
+			expect(error.message).toBe("Extraction failed");
+			expect(error.code).toBe("EXTRACTION_ERROR");
+			expect(error.name).toBe("ExtractionError");
+		});
+	});
+
+	// Note: Testing actual download and extraction would require:
+	// 1. Mock GitHub API responses
+	// 2. Test fixture archives
+	// 3. Network mocking
+	// These are integration tests that would be better suited for e2e testing
+});

package/tests/lib/github.test.ts

@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { GitHubClient } from "../../src/lib/github.js";
+import { AVAILABLE_KITS, GitHubError } from "../../src/types.js";
+
+describe("GitHubClient", () => {
+	let client: GitHubClient;
+
+	beforeEach(() => {
+		client = new GitHubClient();
+		// Set environment variable to avoid auth prompts during tests
+		process.env.GITHUB_TOKEN = "ghp_test_token_for_testing";
+	});
+
+	describe("constructor", () => {
+		test("should create GitHubClient instance", () => {
+			expect(client).toBeInstanceOf(GitHubClient);
+		});
+	});
+
+	describe("error handling", () => {
+		test("GitHubError should contain message and status code", () => {
+			const error = new GitHubError("Test error", 404);
+			expect(error.message).toBe("Test error");
+			expect(error.statusCode).toBe(404);
+			expect(error.code).toBe("GITHUB_ERROR");
+			expect(error.name).toBe("GitHubError");
+		});
+
+		test("GitHubError should work without status code", () => {
+			const error = new GitHubError("Test error");
+			expect(error.message).toBe("Test error");
+			expect(error.statusCode).toBeUndefined();
+		});
+	});
+
+	describe("integration scenarios", () => {
+		test("should handle kit configuration correctly", () => {
+			const engineerKit = AVAILABLE_KITS.engineer;
+			expect(engineerKit.owner).toBe("mrgoonie");
+			expect(engineerKit.repo).toBe("claudekit-engineer");
+		});
+
+		test("should handle marketing kit configuration", () => {
+			const marketingKit = AVAILABLE_KITS.marketing;
+			expect(marketingKit.owner).toBe("mrgoonie");
+			expect(marketingKit.repo).toBe("claudekit-marketing");
+		});
+	});
+
+	// Note: Actual API tests would require mocking Octokit or using a test fixture
+	// We're keeping these tests simple to avoid external dependencies
+});