claudekit-cli 1.0.0

package/.opencode/command/plan.md

@@ -0,0 +1,10 @@
+---
+description: Research, analyze, and create an implementation plan
+---
+
+Use the `planner` subagent to plan for this task:
+<task>
+ $ARGUMENTS
+</task>
+
+**IMPORTANT**: **Do not** start implementing.

package/.opencode/command/test.md

@@ -0,0 +1,7 @@
+---
+description: Debugging technical issues and providing solutions.
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.

package/.opencode/command/watzup.md

@@ -0,0 +1,8 @@
+---
+description: Review recent changes and wrap up the work
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.

package/.releaserc.json

@@ -0,0 +1,17 @@
+{
+	"branches": ["main"],
+	"plugins": [
+		"@semantic-release/commit-analyzer",
+		"@semantic-release/release-notes-generator",
+		"@semantic-release/changelog",
+		"@semantic-release/npm",
+		[
+			"@semantic-release/git",
+			{
+				"assets": ["package.json", "CHANGELOG.md"],
+				"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+			}
+		],
+		"@semantic-release/github"
+	]
+}

package/.repomixignore

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

package/AGENTS.md

@@ -0,0 +1,217 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+...
+
+## Project Structure
+
+- `docs/` - Product requirements and wireframes
+  - `product-overview-pdr.md` - Complete product requirements document (Vietnamese)
+  - `code-standards.md` - Code standards and conventions
+  - `codebase-summary.md` - Codebase summary & structure
+  - `project-roadmap.md` - Project roadmap
+- `plans/` - Implementation plans
+  - `templates/` - Implementation plan templates
+  - `reports/` - Implementation reports
+
+## Key Features to Implement
+
+...
+
+## Development Commands
+
+...
+
+## Architecture Guidelines
+
+...
+
+---
+
+## 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.
+
+### Orchestration Protocol
+
+#### Sequential Chaining
+Chain subagents when tasks have dependencies or require outputs from previous steps:
+- **Planning → Implementation → Testing → Review**: Use for feature development
+- **Research → Design → Code → Documentation**: Use for new system components
+- Each agent completes fully before the next begins
+- Pass context and outputs between agents in the chain
+
+#### Parallel Execution
+Spawn multiple subagents simultaneously for independent tasks:
+- **Code + Tests + Docs**: When implementing separate, non-conflicting components
+- **Multiple Feature Branches**: Different agents working on isolated features
+- **Cross-platform Development**: iOS and Android specific implementations
+- **Careful Coordination**: Ensure no file conflicts or shared resource contention
+- **Merge Strategy**: Plan integration points before parallel execution begins
+
+### Core Responsibilities
+
+#### 1. Code Implementation
+- Before you start, delegate to `planner` agent to create a implementation plan with TODO tasks in `./plans` directory.
+- When in planning phase, use multiple `researcher` agents in parallel to conduct research on different relevant technical topics and report back to `planner` agent to create implementation plan.
+- Write clean, readable, and maintainable code
+- Follow established architectural patterns
+- Implement features according to specifications
+- Handle edge cases and error scenarios
+- **DO NOT** create new enhanced files, update to the existing files directly.
+- **[IMPORTANT]** After creating or modifying code file, run `flutter analyze <path/to/file>` to check for any compile errors.
+
+#### 2. Testing
+- Delegate to `tester` agent to run tests and analyze the summary report.
+  - Write comprehensive unit tests
+  - Ensure high code coverage
+  - Test error scenarios
+  - Validate performance requirements
+- Tests are critical for ensuring code quality and reliability, **DO NOT** ignore failing tests just to pass the build.
+- **IMPORTANT:** Always fix failing tests follow the recommendations and delegate to `tester` agent to run tests again, only finish your session when all tests pass.
+
+#### 3. Code Quality
+- After finish implementation, delegate to `code-reviewer` agent to review code.
+- Follow coding standards and conventions
+- Write self-documenting code
+- Add meaningful comments for complex logic
+- Optimize for performance and maintainability
+
+#### 4. Integration
+- Always follow the plan given by `planner` agent
+- Ensure seamless integration with existing code
+- Follow API contracts precisely
+- Maintain backward compatibility
+- Document breaking changes
+- Delegate to `docs-manager` agent to update docs in `./docs` directory if any.
+
+#### 5. Debugging
+- When a user report bugs or issues on the server or a CI/CD pipeline, delegate to `debugger` agent to run tests and analyze the summary report.
+- Read the summary report from `debugger` agent and implement the fix.
+- Delegate to `tester` agent to run tests and analyze the summary report.
+- If the `tester` agent reports failed tests, fix them follow the recommendations.
+
+---
+
+## Context Management & Anti-Rot Guidelines
+
+**REMEMBER: Everything is Context Engineering!** 
+Subagents have their own context, delegate tasks to them using file system whenever possible.
+
+### Context Refresh Protocol
+To prevent context degradation and maintain performance in long conversations:
+
+#### Agent Handoff Refresh Points
+- **Between Agents**: Reset context when switching between specialized agents
+- **Phase Transitions**: Clear context between planning → implementation → testing → review phases
+- **Document Generation**: Use fresh context for creating plans, reports, and documentation
+- **Error Recovery**: Reset context after debugging sessions to avoid confusion
+
+#### Information Handoff Structure
+When delegating to agents, provide only essential context:
+```markdown
+## Task Summary
+- **Objective**: [brief description]
+- **Scope**: [specific boundaries]
+- **Critical Context**: [requirements, constraints, current state]
+- **Reference Files**: [relevant file paths and line numbers - don't include full content]
+- **Success Criteria**: [clear acceptance criteria]
+```
+
+#### Context Health Guidelines
+- **Prioritize Recent Changes**: Emphasize recent modifications over historical data
+- **Use References Over Content**: Link to files instead of including full content
+- **Summary Over Details**: Provide bullet points instead of verbose explanations
+
+### Agent Interaction Best Practices
+- Each agent should complete its task and provide a focused summary report
+- Avoid circular dependencies between agents  
+- Use clear "handoff complete" signals when transitioning
+- Include only task-relevant context in agent instructions
+- Pass plan file path across subagents
+
+---
+
+## Project Documentation Management
+
+### Roadmap & Changelog Maintenance
+- **Project Roadmap** (`./docs/development-roadmap.md`): Living document tracking project phases, milestones, and progress
+- **Project Changelog** (`./docs/project-changelog.md`): Detailed record of all significant changes, features, and fixes
+- **System Architecture** (`./docs/system-architecture.md`): Detailed record of all significant changes, features, and fixes
+- **Code Standards** (`./docs/code-standards.md`): Detailed record of all significant changes, features, and fixes
+
+### Automatic Updates Required
+- **After Feature Implementation**: Update roadmap progress status and changelog entries
+- **After Major Milestones**: Review and adjust roadmap phases, update success metrics
+- **After Bug Fixes**: Document fixes in changelog with severity and impact
+- **After Security Updates**: Record security improvements and version updates
+- **Weekly Reviews**: Update progress percentages and milestone statuses
+
+### Documentation Triggers
+The `project-manager` agent MUST update these documents when:
+- A development phase status changes (e.g., from "In Progress" to "Complete")
+- Major features are implemented or released
+- Significant bugs are resolved or security patches applied
+- Project timeline or scope adjustments are made
+- External dependencies or breaking changes occur
+
+### Update Protocol
+1. **Before Updates**: Always read current roadmap and changelog status
+2. **During Updates**: Maintain version consistency and proper formatting
+3. **After Updates**: Verify links, dates, and cross-references are accurate
+4. **Quality Check**: Ensure updates align with actual implementation progress
+
+---
+
+## Development Rules
+
+### General
+- **File Size Management**: Keep individual code files under 500 lines for optimal context management
+  - Split large files into smaller, focused components
+  - Use composition over inheritance for complex widgets
+  - Extract utility functions into separate modules
+  - Create dedicated service classes for business logic
+- You ALWAYS follow these principles: **YANGI (You Aren't Gonna Need It) - KISS (Keep It Simple, Stupid) - DRY (Don't Repeat Yourself)**
+- Use `context7` mcp tools for exploring latest docs of plugins/packages
+- Use `senera` mcp tools for semantic retrieval and editing capabilities
+- Use `psql` bash command to query database for debugging.
+- Use `eyes_vision_analysis` tool of `human` mcp server to read and analyze images.
+- **[IMPORTANT]** Follow the codebase structure and code standards in `./docs` during implementation
+- **[IMPORTANT]** When you finish the implementation, send a full summary report to Discord channel with `./.claude/send-discord.sh 'Your message here'` script (remember to escape the string).
+- **[IMPORTANT]** Do not just simulate the implementation or mocking them, always implement the real code.
+
+### Subagents
+Delegate detailed tasks to these subagents according to their roles & expertises:
+- Use file system (in markdown format) to hand over reports in `./plans/reports` directory from agent to agent with this file name format: `YYMMDD-from-agent-name-to-agent-name-task-name-report.md`.
+- Use `planner` agent to plan for the implementation plan using templates in `./plans/templates/` (`planner` agent can spawn multiple `researcher` agents in parallel to explore different approaches with "Query Fan-Out" technique).
+- Use `database-admin` agent to run tests and analyze the summary report.
+- Use `tester` agent to run tests and analyze the summary report.
+- Use `debugger` agent to collect logs in server or github actions to analyze the summary report.
+- Use `code-reviewer` agent to review code according to the implementation plan.
+- Use `docs-manager` agent to update docs in `./docs` directory if any (espcially for `./docs/codebase-summary.md` when significant changes are made).
+- Use `git-manager` agent to commit and push code changes.
+- Use `project-manager` agent for project's progress tracking, completion verification & TODO status management.
+- **[IMPORTANT]** Always delegate to `project-manager` agent after completing significant features, major milestones, or when requested to update project documentation.
+**IMPORTANT:** You can intelligently spawn multiple subagents **in parallel** or **chain them sequentially** to handle the tasks efficiently.
+
+### Code Quality Guidelines
+- Read and follow codebase structure and code standards in `./docs`
+- Don't be too harsh on code linting, but make sure there are no syntax errors and code are compilable
+- Prioritize functionality and readability over strict style enforcement and code formatting
+- Use reasonable code quality standards that enhance developer productivity
+- Use try catch error handling & cover security standards
+- Use `code-reviewer` agent to review code after every implementation
+
+### Pre-commit/Push Rules
+- Run linting before commit
+- Run tests before push (DO NOT ignore failed tests just to pass the build or github actions)
+- Keep commits focused on the actual code changes
+- **DO NOT** commit and push any confidential information (such as dotenv files, API keys, database credentials, etc.) to git repository!
+- NEVER automatically add AI attribution signatures like:
+  "🤖 Generated with [Claude Code]"
+  "Co-Authored-By: Claude noreply@anthropic.com"
+  Any AI tool attribution or signature
+- Create clean, professional commit messages without AI references. Use conventional commit format.

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 1.0.0 (2025-10-09)
+
+
+### Bug Fixes
+
+* add libsecret system dependency for keytar in CI workflows ([9f9bb5a](https://github.com/mrgoonie/claudekit-cli/commit/9f9bb5a351fb3071d3929fbc8c916ca88ec0167d))
+* configure biome linter rules and fix formatting issues ([d68e10b](https://github.com/mrgoonie/claudekit-cli/commit/d68e10bb1e65e525069ac3b3401ae9fc8131c15e))
+* ensure clearToken always clears in-memory token even if keytar fails ([ffdbb12](https://github.com/mrgoonie/claudekit-cli/commit/ffdbb12dc20f5f171be94f4fb51745eff9b6c799))
+* mark native and optional dependencies as external in build ([c8a25c4](https://github.com/mrgoonie/claudekit-cli/commit/c8a25c40fb53e5bcda6fe48522ffa21f9e2907e5))
+* prevent auth tests from prompting for input in CI ([4e8b8b1](https://github.com/mrgoonie/claudekit-cli/commit/4e8b8b149f03b1ae05b3fb27846786c34e58d284))
+
+
+### Features
+
+* enhance UI/UX designer agent with improved tools and workflow clarity ([57e3467](https://github.com/mrgoonie/claudekit-cli/commit/57e3467c88c951e83fe5680358a4a5ac0e3b44d3))
+* initial implementation of ClaudeKit CLI ([2e4f308](https://github.com/mrgoonie/claudekit-cli/commit/2e4f308bc99b8811ea0cc72b91a18b286b9fbd3e))

package/CLAUDE.md

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

package/README.md

@@ -0,0 +1,214 @@
+# ClaudeKit CLI
+
+Command-line tool for bootstrapping and updating ClaudeKit projects.
+
+## Project Overview
+
+**ClaudeKit CLI** (`ck`) is a command-line tool for bootstrapping and updating projects from private GitHub repository releases. Built with Bun and TypeScript, it provides fast, secure, and user-friendly project setup and maintenance.
+
+**Key Features:**
+- Multi-tier GitHub authentication (gh CLI → env vars → keychain → prompt)
+- Streaming downloads with progress tracking
+- Smart file merging with conflict detection
+- Secure credential storage using OS keychain
+- Beautiful CLI interface with interactive prompts
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+bun add -g claudekit-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/mrgoonie/claudekit-cli
+cd claudekit-cli
+bun install
+bun link
+```
+
+## Usage
+
+### Create a New Project
+
+```bash
+# Interactive mode
+ck new
+
+# With options
+ck new --dir my-project --kit engineer
+
+# Specific version
+ck new --kit engineer --version v1.0.0
+```
+
+### Update Existing Project
+
+```bash
+# Interactive mode
+ck update
+
+# With options
+ck update --kit engineer
+
+# Specific version
+ck update --kit engineer --version v1.0.0
+```
+
+### Other Commands
+
+```bash
+# Show version
+ck --version
+ck -v
+
+# Show help
+ck --help
+ck -h
+```
+
+## Authentication
+
+The CLI requires a GitHub Personal Access Token (PAT) to download releases from private repositories. The authentication flow follows a multi-tier fallback:
+
+1. **GitHub CLI**: Uses `gh auth token` if GitHub CLI is installed and authenticated
+2. **Environment Variables**: Checks `GITHUB_TOKEN` or `GH_TOKEN`
+3. **OS Keychain**: Retrieves stored token from system keychain
+4. **User Prompt**: Prompts for token input and offers to save it securely
+
+### Creating a Personal Access Token
+
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Generate new token with `repo` scope (for private repositories)
+3. Copy the token
+
+### Setting Token via Environment Variable
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+```
+
+## Available Kits
+
+- **engineer**: ClaudeKit Engineer - Engineering toolkit for building with Claude
+- **marketing**: ClaudeKit Marketing - [Coming Soon]
+
+## Configuration
+
+Configuration is stored in `~/.claudekit/config.json`:
+
+```json
+{
+  "github": {
+    "token": "stored_in_keychain"
+  },
+  "defaults": {
+    "kit": "engineer",
+    "dir": "."
+  }
+}
+```
+
+## Protected Files
+
+The following file patterns are protected and will not be overwritten during updates:
+
+- `.env`, `.env.local`, `.env.*.local`
+- `*.key`, `*.pem`, `*.p12`
+- `node_modules/**`, `.git/**`
+- `dist/**`, `build/**`
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development
+bun run dev new --kit engineer
+
+# Build
+bun run build
+
+# Compile standalone binary
+bun run compile
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Lint & Format
+bun run lint
+bun run format
+```
+
+## Project Structure
+
+```
+claudekit-cli/
+├── docs/                       # Documentation
+│   ├── project-pdr.md         # Product requirements
+│   ├── code-standards.md      # Coding standards
+│   ├── system-architecture.md # Architecture diagrams
+│   ├── codebase-summary.md    # Codebase overview
+│   └── tech-stack.md          # Technology stack
+├── plans/                      # Implementation plans & reports
+│   ├── 251008-claudekit-cli-implementation-plan.md
+│   ├── reports/               # Agent reports
+│   ├── research/              # Research documents
+│   └── templates/             # Plan templates
+├── src/                        # Source code
+│   ├── commands/              # Command implementations
+│   │   ├── new.ts            # 'ck new' command
+│   │   └── update.ts         # 'ck update' command
+│   ├── lib/                   # Core libraries
+│   │   ├── auth.ts           # Authentication manager
+│   │   ├── github.ts         # GitHub API client
+│   │   ├── download.ts       # Download manager
+│   │   ├── merge.ts          # File merger
+│   │   └── prompts.ts        # Interactive prompts
+│   ├── utils/                 # Utilities
+│   │   ├── config.ts         # Configuration manager
+│   │   └── logger.ts         # Logger with sanitization
+│   ├── index.ts               # CLI entry point
+│   └── types.ts               # Type definitions
+├── tests/                      # Test files (mirrors src/)
+│   ├── lib/
+│   ├── utils/
+│   └── types.test.ts
+├── README.md                   # User documentation
+├── package.json                # Package manifest
+└── tsconfig.json              # TypeScript config
+```
+
+---
+
+## Key Features & Components
+
+### 1. Commands
+- **`ck new`**: Create new project from release
+- **`ck update`**: Update existing project
+- **`ck --version`**: Show version
+- **`ck --help`**: Show help
+
+### 2. Authentication (Multi-Tier Fallback)
+1. GitHub CLI (`gh auth token`)
+2. Environment variables (GITHUB_TOKEN, GH_TOKEN)
+3. Configuration file (~/.claudekit/config.json)
+4. OS Keychain (via keytar)
+5. User prompt (with optional secure storage)
+
+### 3. Core Operations
+- **Download**: Streaming downloads with progress bars
+- **Extract**: TAR.GZ and ZIP support with path traversal protection
+- **Merge**: Smart file merging with conflict detection
+- **Protected Files**: .env, *.key, *.pem, node_modules/, .git/, etc.
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"complexity": {
+				"noForEach": "off",
+				"noStaticOnlyClass": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "off",
+				"noImplicitAnyLet": "off"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"lineWidth": 100
+	}
+}