claudekit-cli 1.0.0

package/plans/templates/bug-fix-template.md

@@ -0,0 +1,69 @@
+# [Bug Fix] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Bug Fix  
+**Priority**: [Critical/High/Medium/Low]  
+**Context Tokens**: <150 words
+
+## Executive Summary
+Brief description of the bug and its impact.
+
+## Issue Analysis
+### Symptoms
+- [ ] Symptom 1
+- [ ] Symptom 2
+
+### Root Cause
+Brief explanation of the underlying cause.
+
+### Evidence
+- **Logs**: Reference to log files (don't include full logs)
+- **Error Messages**: Key error patterns
+- **Affected Components**: List of impacted files/modules
+
+## Context Links
+- **Related Issues**: [GitHub issue numbers]
+- **Recent Changes**: [Relevant commits or PRs]
+- **Dependencies**: [Related systems]
+
+## Solution Design
+### Approach
+High-level fix strategy in 2-3 sentences.
+
+### Changes Required
+1. **File 1** (`path/to/file.ts`): Brief change description
+2. **File 2** (`path/to/file.ts`): Brief change description
+
+### Testing Changes
+- [ ] Update existing tests
+- [ ] Add new test cases
+- [ ] Validate fix doesn't break existing functionality
+
+## Implementation Steps
+1. [ ] Step 1 - file: `path/to/file.ts`
+2. [ ] Step 2 - file: `path/to/file.ts`
+3. [ ] Run test suite
+4. [ ] Validate fix in relevant environments
+
+## Verification Plan
+### Test Cases
+- [ ] Test case 1: Expected behavior
+- [ ] Test case 2: Edge case handling
+- [ ] Regression test: Ensure no new issues
+
+### Rollback Plan
+If the fix causes issues:
+1. Revert commit: `git revert <commit-hash>`
+2. Restore previous behavior in files X, Y, Z
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | Medium | Mitigation plan |
+
+## TODO Checklist
+- [ ] Implement fix
+- [ ] Update tests
+- [ ] Run full test suite
+- [ ] Code review
+- [ ] Deploy and verify

package/plans/templates/feature-implementation-template.md

@@ -0,0 +1,84 @@
+# [Feature Name] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Feature Implementation  
+**Status**: Planning  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief 2-3 sentence description of the feature and its business value.
+
+## Context Links
+- **Related Plans**: [List other plan files - no full content]
+- **Dependencies**: [External systems, APIs, existing features]
+- **Reference Docs**: [Link to docs in ./docs directory]
+
+## Requirements
+### Functional Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Non-Functional Requirements  
+- [ ] Performance target
+- [ ] Security requirement
+- [ ] Scalability requirement
+
+## Architecture Overview
+```mermaid
+[Simple component diagram]
+```
+
+### Key Components
+- **Component 1**: Brief description
+- **Component 2**: Brief description
+
+### Data Models
+- **Model 1**: Key fields
+- **Model 2**: Key fields
+
+## Implementation Phases
+
+### Phase 1: [Name] (Est: X days)
+**Scope**: Specific boundaries
+**Tasks**:
+1. [ ] Task 1 - file: `path/to/file.ts`
+2. [ ] Task 2 - file: `path/to/file.ts`
+
+**Acceptance Criteria**:
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+### Phase 2: [Name] (Est: X days)
+[Repeat structure]
+
+## Testing Strategy
+- **Unit Tests**: Specific test coverage targets
+- **Integration Tests**: Key interaction points
+- **E2E Tests**: Critical user flows
+
+## Security Considerations
+- [ ] Security item 1
+- [ ] Security item 2
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | High | Mitigation strategy |
+
+## Quick Reference
+### Key Commands
+```bash
+npm run command
+```
+
+### Configuration Files
+- `config/file.ts`: Purpose
+- `.env.example`: Environment variables
+
+## TODO Checklist
+- [ ] Phase 1 Task 1
+- [ ] Phase 1 Task 2
+- [ ] Phase 2 Task 1
+- [ ] Testing complete
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/refactor-template.md

@@ -0,0 +1,82 @@
+# [Component/Module] Refactoring Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Refactoring  
+**Scope**: [Module/Component/System level]  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief description of what is being refactored and why.
+
+## Current State Analysis
+### Issues with Current Implementation
+- [ ] Issue 1: Performance bottleneck
+- [ ] Issue 2: Code maintainability
+- [ ] Issue 3: Technical debt
+
+### Metrics (Before)
+- **Performance**: Current benchmarks
+- **Code Quality**: Complexity metrics
+- **Test Coverage**: Current percentage
+
+## Context Links
+- **Affected Modules**: [List without full content]
+- **Dependencies**: [Other systems impacted]
+- **Related Documentation**: [Links to docs]
+
+## Refactoring Strategy
+### Approach
+High-level strategy for the refactoring in 2-3 sentences.
+
+### Architecture Changes
+```mermaid
+[Before/After comparison diagram]
+```
+
+### Key Improvements
+- **Improvement 1**: Brief description
+- **Improvement 2**: Brief description
+
+## Implementation Plan
+
+### Phase 1: Preparation (Est: X days)
+**Scope**: Setup and preparation work
+1. [ ] Create comprehensive tests for current functionality
+2. [ ] Document current behavior
+3. [ ] Identify all dependencies
+
+### Phase 2: Core Refactoring (Est: X days)
+**Scope**: Main refactoring work
+1. [ ] Refactor component A - file: `path/to/file.ts`
+2. [ ] Refactor component B - file: `path/to/file.ts`
+3. [ ] Update integration points
+
+### Phase 3: Integration & Testing (Est: X days)
+**Scope**: Validation and cleanup
+1. [ ] Integration testing
+2. [ ] Performance validation
+3. [ ] Documentation updates
+
+## Backward Compatibility
+- **Breaking Changes**: [List any breaking changes]
+- **Migration Path**: [Steps for users/systems]
+- **Deprecation Timeline**: [If applicable]
+
+## Success Metrics (After)
+- **Performance**: Target improvements
+- **Code Quality**: Target metrics
+- **Test Coverage**: Target percentage
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Breaking changes | High | Comprehensive testing |
+| Performance regression | Medium | Benchmarking |
+
+## TODO Checklist
+- [ ] Phase 1: Preparation complete
+- [ ] Phase 2: Core refactoring complete  
+- [ ] Phase 3: Integration complete
+- [ ] Performance benchmarks validated
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/template-usage-guide.md

@@ -0,0 +1,58 @@
+# Plan Template Usage Guide
+
+## Template Selection
+
+### Feature Implementation Template
+**Use when**: Adding new functionality, endpoints, services, or modules
+**File**: `feature-implementation-template.md`
+**Size**: Medium to large scope changes
+
+### Bug Fix Template  
+**Use when**: Fixing specific issues, errors, or broken functionality
+**File**: `bug-fix-template.md`
+**Size**: Small to medium scope changes
+
+### Refactoring Template
+**Use when**: Improving code structure, performance, or maintainability without changing functionality
+**File**: `refactor-template.md` 
+**Size**: Medium to large scope changes
+
+## Context Management Best Practices
+
+### Keep Plans Focused
+- **Executive Summary**: Max 3 sentences
+- **Context Links**: Reference files, don't include full content
+- **Tasks**: Max 10 per phase
+- **Context Tokens**: Target <200 words for summaries
+
+### Template Adaptation
+1. Copy the appropriate template to `plans/YYMMDD-feature-name-plan.md`
+2. Replace bracketed placeholders with actual content
+3. Remove sections not relevant to your specific use case
+4. Keep the core structure intact for consistency
+
+### Cross-References Instead of Duplication
+- Link to existing documentation in `./docs/`
+- Reference other plans without copying content
+- Use file paths instead of code blocks where possible
+- Focus on "what" and "why", not detailed "how"
+
+## Quality Checklist
+
+Before finalizing any plan:
+- [ ] Executive summary is clear and concise
+- [ ] Tasks are specific and actionable
+- [ ] File paths are included for implementation tasks
+- [ ] Success criteria are measurable
+- [ ] Context links are used instead of full content
+- [ ] TODO checklist is complete and realistic
+
+## Context Refresh Triggers
+
+Use these templates when:
+- Starting a new development phase
+- Switching between different types of work (feature → bugfix)
+- After major context accumulation (>8000 tokens)
+- When agent handoffs occur
+
+This ensures each plan starts with fresh, focused context optimized for the specific task type.

package/src/commands/new.ts

@@ -0,0 +1,118 @@
+import { resolve } from "node:path";
+import { pathExists, readdir } from "fs-extra";
+import ora from "ora";
+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 NewCommandOptions, NewCommandOptionsSchema } from "../types.js";
+import { ConfigManager } from "../utils/config.js";
+import { logger } from "../utils/logger.js";
+
+export async function newCommand(options: NewCommandOptions): Promise<void> {
+	const prompts = new PromptsManager();
+
+	prompts.intro("🚀 ClaudeKit - Create New Project");
+
+	try {
+		// Validate and parse options
+		const validOptions = NewCommandOptionsSchema.parse(options);
+
+		// Load config for defaults
+		const config = await ConfigManager.get();
+
+		// Get kit selection
+		let kit = validOptions.kit || config.defaults?.kit;
+		if (!kit) {
+			kit = await prompts.selectKit();
+		}
+
+		const kitConfig = AVAILABLE_KITS[kit];
+		logger.info(`Selected kit: ${kitConfig.name}`);
+
+		// Get target directory
+		let targetDir = validOptions.dir || config.defaults?.dir || ".";
+		if (!validOptions.dir && !config.defaults?.dir) {
+			targetDir = await prompts.getDirectory(targetDir);
+		}
+
+		const resolvedDir = resolve(targetDir);
+		logger.info(`Target directory: ${resolvedDir}`);
+
+		// Check if directory exists and is not empty
+		if (await pathExists(resolvedDir)) {
+			const files = await readdir(resolvedDir);
+			const isEmpty = files.length === 0;
+			if (!isEmpty) {
+				const continueAnyway = await prompts.confirm(
+					"Directory is not empty. Files may be overwritten. Continue?",
+				);
+				if (!continueAnyway) {
+					logger.warning("Operation cancelled");
+					return;
+				}
+			}
+		}
+
+		// Initialize GitHub client
+		const github = new GitHubClient();
+
+		// Check repository access
+		const spinner = ora("Checking repository access...").start();
+		const hasAccess = await github.checkAccess(kitConfig);
+		if (!hasAccess) {
+			spinner.fail("Access denied to repository");
+			logger.error(
+				`Cannot access ${kitConfig.name}. Make sure your GitHub token has access to private repositories.`,
+			);
+			return;
+		}
+		spinner.succeed("Repository access verified");
+
+		// Get release
+		let release;
+		if (validOptions.version) {
+			logger.info(`Fetching release version: ${validOptions.version}`);
+			release = await github.getReleaseByTag(kitConfig, validOptions.version);
+		} else {
+			logger.info("Fetching latest release...");
+			release = await github.getLatestRelease(kitConfig);
+		}
+
+		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"),
+		);
+
+		if (!asset) {
+			logger.error("No downloadable archive found in release");
+			return;
+		}
+
+		// Download asset
+		const downloadManager = new DownloadManager();
+		const tempDir = await downloadManager.createTempDir();
+		const archivePath = await downloadManager.downloadAsset(asset, tempDir);
+
+		// Extract archive
+		const extractDir = `${tempDir}/extracted`;
+		await downloadManager.extractArchive(archivePath, extractDir);
+
+		// Copy files to target directory
+		const merger = new FileMerger();
+		await merger.merge(extractDir, resolvedDir, true); // Skip confirmation for new projects
+
+		prompts.outro(`✨ Project created successfully at ${resolvedDir}`);
+
+		// Show next steps
+		prompts.note(
+			`cd ${targetDir !== "." ? targetDir : "into the directory"}\nbun install\nbun run dev`,
+			"Next steps",
+		);
+	} catch (error) {
+		logger.error(error instanceof Error ? error.message : "Unknown error occurred");
+		process.exit(1);
+	}
+}

package/src/commands/update.ts

@@ -0,0 +1,114 @@
+import { resolve } from "node:path";
+import { pathExists } from "fs-extra";
+import ora from "ora";
+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 { logger } from "../utils/logger.js";
+
+export async function updateCommand(options: UpdateCommandOptions): Promise<void> {
+	const prompts = new PromptsManager();
+
+	prompts.intro("🔄 ClaudeKit - Update Project");
+
+	try {
+		// Validate and parse options
+		const validOptions = UpdateCommandOptionsSchema.parse(options);
+
+		// Load config for defaults
+		const config = await ConfigManager.get();
+
+		// Get kit selection
+		let kit = validOptions.kit || config.defaults?.kit;
+		if (!kit) {
+			kit = await prompts.selectKit();
+		}
+
+		const kitConfig = AVAILABLE_KITS[kit];
+		logger.info(`Selected kit: ${kitConfig.name}`);
+
+		// Get target directory
+		let targetDir = validOptions.dir || config.defaults?.dir || ".";
+		if (!validOptions.dir && !config.defaults?.dir) {
+			targetDir = await prompts.getDirectory(targetDir);
+		}
+
+		const resolvedDir = resolve(targetDir);
+		logger.info(`Target directory: ${resolvedDir}`);
+
+		// Check if directory exists
+		if (!(await pathExists(resolvedDir))) {
+			logger.error(`Directory does not exist: ${resolvedDir}`);
+			logger.info('Use "ck new" to create a new project');
+			return;
+		}
+
+		// Initialize GitHub client
+		const github = new GitHubClient();
+
+		// Check repository access
+		const spinner = ora("Checking repository access...").start();
+		const hasAccess = await github.checkAccess(kitConfig);
+		if (!hasAccess) {
+			spinner.fail("Access denied to repository");
+			logger.error(
+				`Cannot access ${kitConfig.name}. Make sure your GitHub token has access to private repositories.`,
+			);
+			return;
+		}
+		spinner.succeed("Repository access verified");
+
+		// Get release
+		let release;
+		if (validOptions.version) {
+			logger.info(`Fetching release version: ${validOptions.version}`);
+			release = await github.getReleaseByTag(kitConfig, validOptions.version);
+		} else {
+			logger.info("Fetching latest release...");
+			release = await github.getLatestRelease(kitConfig);
+		}
+
+		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"),
+		);
+
+		if (!asset) {
+			logger.error("No downloadable archive found in release");
+			return;
+		}
+
+		// Download asset
+		const downloadManager = new DownloadManager();
+		const tempDir = await downloadManager.createTempDir();
+		const archivePath = await downloadManager.downloadAsset(asset, tempDir);
+
+		// Extract archive
+		const extractDir = `${tempDir}/extracted`;
+		await downloadManager.extractArchive(archivePath, extractDir);
+
+		// Merge files with confirmation
+		const merger = new FileMerger();
+		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",
+		);
+	} catch (error) {
+		if (error instanceof Error && error.message === "Merge cancelled by user") {
+			logger.warning("Update cancelled");
+			return;
+		}
+		logger.error(error instanceof Error ? error.message : "Unknown error occurred");
+		process.exit(1);
+	}
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cac } from "cac";
+import { newCommand } from "./commands/new.js";
+import { updateCommand } from "./commands/update.js";
+
+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 cli = cac("ck");
+
+// New command
+cli
+	.command("new", "Bootstrap a new ClaudeKit project")
+	.option("--dir <dir>", "Target directory (default: .)")
+	.option("--kit <kit>", "Kit to use (engineer, marketing)")
+	.option("--version <version>", "Specific version to download (default: latest)")
+	.action(async (options) => {
+		await newCommand(options);
+	});
+
+// Update command
+cli
+	.command("update", "Update existing ClaudeKit project")
+	.option("--dir <dir>", "Target directory (default: .)")
+	.option("--kit <kit>", "Kit to use (engineer, marketing)")
+	.option("--version <version>", "Specific version to download (default: latest)")
+	.action(async (options) => {
+		await updateCommand(options);
+	});
+
+// Version
+cli.version(packageJson.version);
+
+// Help
+cli.help();
+
+// Parse CLI arguments
+cli.parse();