apero-kit-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Apero Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# Apero Kit CLI
+
+> Scaffold AI agent projects with pre-configured kits for Claude Code, OpenCode, and Codex.
+
+[![npm version](https://badge.fury.io/js/apero-kit-cli.svg)](https://www.npmjs.com/package/apero-kit-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install -g apero-kit-cli
+```
+
+## Quick Start
+
+```bash
+# Initialize a new project with the engineer kit
+ak init my-app --kit engineer
+
+# Or use interactive mode
+ak init my-app
+```
+
+## Commands
+
+### `ak init [project-name]`
+
+Initialize a new project with an agent kit.
+
+```bash
+ak init my-app --kit engineer      # Full-stack development kit
+ak init my-app --kit researcher    # Research and analysis kit
+ak init my-app --kit designer      # UI/UX design kit
+ak init my-app --kit minimal       # Lightweight essential kit
+ak init my-app --kit full          # Everything included
+ak init my-app                     # Interactive mode
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-k, --kit <type>` | Kit type: engineer, researcher, designer, minimal, full, custom |
+| `-t, --target <target>` | Target folder: claude (default), opencode, generic |
+| `-s, --source <path>` | Custom source path for templates |
+| `-f, --force` | Overwrite existing directory |
+
+### `ak add <type>:<name>`
+
+Add an agent, skill, or command to an existing project.
+
+```bash
+ak add skill:databases         # Add databases skill
+ak add agent:debugger          # Add debugger agent
+ak add command:fix/ci          # Add fix/ci command
+```
+
+### `ak list [type]`
+
+List available kits, agents, skills, or commands.
+
+```bash
+ak list              # Show available list commands
+ak list kits         # List all kits
+ak list agents       # List available agents
+ak list skills       # List available skills
+ak list commands     # List available commands
+```
+
+### `ak update`
+
+Update/sync from source templates. Only updates unchanged files (safe by default).
+
+```bash
+ak update                      # Update from configured source
+ak update --source ~/AGENTS.md # Update from specific source
+ak update --skills             # Update only skills
+ak update --dry-run            # Preview what would be updated
+ak update --force              # Update without confirmation
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-s, --source <path>` | Source path to sync from |
+| `--agents` | Update only agents |
+| `--skills` | Update only skills |
+| `--commands` | Update only commands |
+| `-n, --dry-run` | Show what would be updated without making changes |
+| `-f, --force` | Force update without confirmation |
+
+### `ak status`
+
+Show project status and file changes.
+
+```bash
+ak status            # Show status summary
+ak status --verbose  # Show all files
+```
+
+### `ak doctor`
+
+Check project health and diagnose issues.
+
+```bash
+ak doctor
+```
+
+## Available Kits
+
+| Kit | Description | Agents | Skills | Commands |
+|-----|-------------|--------|--------|----------|
+| 🛠️ **engineer** | Full-stack development | 7 | 7 | 17 |
+| 🔬 **researcher** | Research and analysis | 6 | 4 | 10 |
+| 🎨 **designer** | UI/UX design | 3 | 3 | 5 |
+| 📦 **minimal** | Lightweight essentials | 2 | 2 | 3 |
+| 🚀 **full** | Everything included | ALL | ALL | ALL |
+| 🔧 **custom** | Pick your own | - | - | - |
+
+## How It Works
+
+### Source Detection
+
+The CLI automatically finds your source templates by searching up from the current directory:
+
+```
+cwd → parent → git root
+```
+
+It looks for:
+- `AGENTS.md` file
+- `.claude/` directory
+- `.opencode/` directory
+
+You can also specify a custom source with `--source`.
+
+### State Tracking
+
+Each project stores its state in `.ak/state.json`:
+- What kit was used
+- Source location
+- Installed components
+- File hashes for safe updates
+
+### Safe Updates
+
+When you run `ak update`:
+1. Files you haven't modified → **Updated**
+2. Files you've modified → **Skipped** (preserves your changes)
+3. New files from source → **Added**
+
+## Project Structure
+
+After `ak init my-app --kit engineer`:
+
+```
+my-app/
+├── .claude/
+│   ├── agents/          # AI agent definitions
+│   ├── commands/        # Slash commands
+│   ├── skills/          # Knowledge packages
+│   ├── router/          # Decision logic
+│   ├── hooks/           # Automation scripts
+│   ├── README.md
+│   └── settings.json
+├── .ak/
+│   └── state.json       # Project state for updates
+└── AGENTS.md            # Core ruleset
+```
+
+## Examples
+
+### Workflow: Create and Develop
+
+```bash
+# 1. Initialize project
+ak init my-api --kit engineer
+cd my-api
+
+# 2. Start coding with Claude Code
+# ... develop features ...
+
+# 3. Check status
+ak status
+
+# 4. Add more skills as needed
+ak add skill:databases
+ak add skill:devops
+
+# 5. Update when source has new content
+ak update
+```
+
+### Workflow: Team Sharing
+
+```bash
+# Team lead: publish CLI with your custom kits
+npm publish
+
+# Team members: install and use
+npm install -g apero-kit-cli
+ak init my-project --kit engineer
+```
+
+## Configuration
+
+### Global Config (Optional)
+
+Create `~/.ak-cli.json`:
+
+```json
+{
+  "defaultSource": "/path/to/your/AGENTS.md",
+  "defaultKit": "engineer"
+}
+```
+
+## Troubleshooting
+
+Run `ak doctor` to diagnose issues:
+
+```bash
+$ ak doctor
+
+Apero Kit Doctor
+
+Checking project health...
+
+✓ ak project detected
+✓ State file (.ak/state.json) exists
+✓ Target directory exists (.claude)
+✓ AGENTS.md exists
+✓ Source directory accessible
+✓ agents/ exists (15 items)
+✓ commands/ exists (40 items)
+✓ skills/ exists (25 items)
+
+────────────────────────────────────────
+
+✓ All checks passed!
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Acknowledgments
+
+Built for use with [Claude Code](https://claude.ai/code), [OpenCode](https://opencode.dev), and similar AI coding assistants.

package/bin/ak.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/commands/init.js';
+import { addCommand } from '../src/commands/add.js';
+import { listCommand } from '../src/commands/list.js';
+import { updateCommand } from '../src/commands/update.js';
+import { statusCommand } from '../src/commands/status.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+
+const VERSION = '1.0.0';
+
+console.log(chalk.cyan.bold('\n  Apero Kit CLI') + chalk.gray(` v${VERSION}\n`));
+
+program
+  .name('ak')
+  .description('Scaffold AI agent projects with pre-configured kits')
+  .version(VERSION);
+
+// ak init [project-name] --kit <kit-type>
+program
+  .command('init [project-name]')
+  .description('Initialize a new project with an agent kit')
+  .option('-k, --kit <type>', 'Kit type (engineer, researcher, designer, minimal, full, custom)')
+  .option('-t, --target <target>', 'Target folder (claude, opencode, generic)', 'claude')
+  .option('-s, --source <path>', 'Custom source path for templates')
+  .option('-f, --force', 'Overwrite existing directory')
+  .action(initCommand);
+
+// ak add <type>:<name>
+program
+  .command('add <item>')
+  .description('Add agent, skill, or command (e.g., ak add skill:databases)')
+  .option('-s, --source <path>', 'Custom source path')
+  .option('-p, --path <path>', 'Target project path', '.')
+  .action(addCommand);
+
+// ak list [type]
+program
+  .command('list [type]')
+  .description('List available kits, agents, skills, or commands')
+  .option('-s, --source <path>', 'Custom source path')
+  .action(listCommand);
+
+// ak update
+program
+  .command('update')
+  .description('Update/sync from source templates')
+  .option('-s, --source <path>', 'Source path to sync from')
+  .option('--agents', 'Update only agents')
+  .option('--skills', 'Update only skills')
+  .option('--commands', 'Update only commands')
+  .option('--all', 'Update everything')
+  .option('-n, --dry-run', 'Show what would be updated without making changes')
+  .option('-f, --force', 'Force update without confirmation')
+  .action(updateCommand);
+
+// ak status
+program
+  .command('status')
+  .description('Show project status and file changes')
+  .option('-v, --verbose', 'Show all files')
+  .action(statusCommand);
+
+// ak doctor
+program
+  .command('doctor')
+  .description('Check project health and diagnose issues')
+  .action(doctorCommand);
+
+// ak kits - alias
+program
+  .command('kits')
+  .description('List all available kits')
+  .action(() => listCommand('kits'));
+
+program.parse();

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "apero-kit-cli",
+  "version": "1.0.0",
+  "description": "CLI tool to scaffold AI agent projects with pre-configured kits (Claude, OpenCode, Codex)",
+  "type": "module",
+  "bin": {
+    "ak": "bin/ak.js",
+    "apero-kit": "bin/ak.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./kits": "./src/kits/index.js"
+  },
+  "scripts": {
+    "start": "node bin/ak.js",
+    "link": "npm link",
+    "unlink": "npm unlink",
+    "test": "node --test src/**/*.test.js",
+    "prepublishOnly": "echo 'Ready to publish!'"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "claude-code",
+    "opencode",
+    "codex",
+    "cli",
+    "scaffold",
+    "template",
+    "llm",
+    "apero"
+  ],
+  "author": "Apero Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thanh-apero/apero-kit-cli.git"
+  },
+  "homepage": "https://github.com/Thanh-apero/apero-kit-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Thanh-apero/apero-kit-cli/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,126 @@
+import fs from 'fs-extra';
+import { join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { resolveSource, isAkProject } from '../utils/paths.js';
+import { copyItems, copyAllOfType, listAvailable } from '../utils/copy.js';
+import { loadState, updateState } from '../utils/state.js';
+import { hashDirectory } from '../utils/hash.js';
+
+export async function addCommand(item, options = {}) {
+  // Parse item format: type:name (e.g., skill:databases, agent:debugger)
+  const parts = item.split(':');
+  if (parts.length !== 2) {
+    console.log(chalk.red('Invalid format. Use: ak add <type>:<name>'));
+    console.log(chalk.gray('Examples:'));
+    console.log(chalk.gray('  ak add skill:databases'));
+    console.log(chalk.gray('  ak add agent:debugger'));
+    console.log(chalk.gray('  ak add command:fix/ci'));
+    return;
+  }
+
+  const [type, name] = parts;
+  const validTypes = ['agent', 'agents', 'skill', 'skills', 'command', 'commands', 'workflow', 'workflows'];
+
+  if (!validTypes.includes(type)) {
+    console.log(chalk.red(`Invalid type: ${type}`));
+    console.log(chalk.gray(`Valid types: agent, skill, command, workflow`));
+    return;
+  }
+
+  // Normalize type to plural
+  const typeMap = {
+    agent: 'agents',
+    agents: 'agents',
+    skill: 'skills',
+    skills: 'skills',
+    command: 'commands',
+    commands: 'commands',
+    workflow: 'workflows',
+    workflows: 'workflows'
+  };
+  const normalizedType = typeMap[type];
+
+  const projectDir = options.path || process.cwd();
+
+  // Check if in ak project
+  if (!isAkProject(projectDir)) {
+    console.log(chalk.red('Not in an ak project.'));
+    console.log(chalk.gray('Run "ak init" first or use --path to specify project directory.'));
+    return;
+  }
+
+  // Load state
+  const state = await loadState(projectDir);
+  if (!state) {
+    console.log(chalk.yellow('Warning: No state file found. Creating fresh state after add.'));
+  }
+
+  // Resolve source
+  const sourceFlag = options.source || (state ? state.source : null);
+  const source = resolveSource(sourceFlag);
+  if (source.error) {
+    console.log(chalk.red(`Error: ${source.error}`));
+    return;
+  }
+
+  // Check if item exists in source
+  const available = listAvailable(normalizedType, source.claudeDir);
+  const exists = available.some(a => a.name === name);
+
+  if (!exists) {
+    console.log(chalk.red(`${type} "${name}" not found in source.`));
+    console.log(chalk.gray(`Use "ak list ${normalizedType}" to see available options.`));
+    return;
+  }
+
+  // Determine target directory
+  const targetFolder = state?.target || '.claude';
+  const targetDir = join(projectDir, targetFolder);
+
+  // Check if already installed
+  const destPath = join(targetDir, normalizedType, name);
+  const destPathMd = destPath + '.md';
+  if (fs.existsSync(destPath) || fs.existsSync(destPathMd)) {
+    console.log(chalk.yellow(`${type} "${name}" already exists in project.`));
+    console.log(chalk.gray('Use "ak update" to refresh from source.'));
+    return;
+  }
+
+  // Copy
+  const spinner = ora(`Adding ${type} "${name}"...`).start();
+
+  try {
+    const result = await copyItems([name], normalizedType, source.claudeDir, targetDir);
+
+    if (result.copied.length > 0) {
+      spinner.succeed(chalk.green(`Added ${type}: ${name}`));
+
+      // Update state
+      if (state) {
+        const installed = state.installed || {};
+        installed[normalizedType] = installed[normalizedType] || [];
+        if (!installed[normalizedType].includes(name)) {
+          installed[normalizedType].push(name);
+        }
+
+        // Recalculate hashes
+        const newHashes = await hashDirectory(targetDir);
+
+        await updateState(projectDir, {
+          installed,
+          originalHashes: newHashes
+        });
+      }
+
+      console.log(chalk.gray(`Location: ${targetFolder}/${normalizedType}/${name}`));
+    } else if (result.skipped.length > 0) {
+      spinner.fail(chalk.red(`Could not find ${type}: ${name}`));
+    } else if (result.errors.length > 0) {
+      spinner.fail(chalk.red(`Error adding ${type}: ${result.errors[0].error}`));
+    }
+  } catch (error) {
+    spinner.fail(chalk.red(`Failed to add ${type}`));
+    console.error(chalk.red(error.message));
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,129 @@
+import fs from 'fs-extra';
+import { join } from 'path';
+import chalk from 'chalk';
+import { isAkProject, resolveSource, TARGETS } from '../utils/paths.js';
+import { loadState } from '../utils/state.js';
+
+export async function doctorCommand(options = {}) {
+  const projectDir = process.cwd();
+
+  console.log(chalk.cyan.bold('\nApero Kit Doctor\n'));
+  console.log(chalk.gray('Checking project health...\n'));
+
+  let issues = 0;
+  let warnings = 0;
+
+  // Check 1: Is this an ak project?
+  const isProject = isAkProject(projectDir);
+  if (isProject) {
+    console.log(chalk.green('✓ ak project detected'));
+  } else {
+    console.log(chalk.red('✗ Not an ak project'));
+    issues++;
+  }
+
+  // Check 2: State file
+  const state = await loadState(projectDir);
+  if (state) {
+    console.log(chalk.green('✓ State file (.ak/state.json) exists'));
+  } else if (isProject) {
+    console.log(chalk.yellow('⚠ No state file - project may have been created manually'));
+    warnings++;
+  }
+
+  // Check 3: Target directory
+  let targetDir = null;
+  for (const [name, folder] of Object.entries(TARGETS)) {
+    const dir = join(projectDir, folder);
+    if (fs.existsSync(dir)) {
+      targetDir = { name, folder, dir };
+      break;
+    }
+  }
+
+  if (targetDir) {
+    console.log(chalk.green(`✓ Target directory exists (${targetDir.folder})`));
+  } else {
+    console.log(chalk.red('✗ No target directory (.claude/, .opencode/, .agent/)'));
+    issues++;
+  }
+
+  // Check 4: AGENTS.md
+  const agentsMd = join(projectDir, 'AGENTS.md');
+  if (fs.existsSync(agentsMd)) {
+    console.log(chalk.green('✓ AGENTS.md exists'));
+  } else {
+    console.log(chalk.yellow('⚠ AGENTS.md not found (optional but recommended)'));
+    warnings++;
+  }
+
+  // Check 5: Source availability
+  if (state && state.source) {
+    if (fs.existsSync(state.source)) {
+      console.log(chalk.green(`✓ Source directory accessible`));
+    } else {
+      console.log(chalk.red(`✗ Source directory not found: ${state.source}`));
+      issues++;
+    }
+  }
+
+  // Check 6: Key subdirectories
+  if (targetDir) {
+    const checkDirs = ['agents', 'commands', 'skills'];
+    for (const dir of checkDirs) {
+      const fullPath = join(targetDir.dir, dir);
+      if (fs.existsSync(fullPath)) {
+        const items = fs.readdirSync(fullPath).length;
+        console.log(chalk.green(`✓ ${dir}/ exists (${items} items)`));
+      } else {
+        console.log(chalk.yellow(`⚠ ${dir}/ not found`));
+        warnings++;
+      }
+    }
+  }
+
+  // Check 7: Auto-detect source in parent directories
+  console.log('');
+  console.log(chalk.gray('Source detection:'));
+  const source = resolveSource();
+  if (source.error) {
+    console.log(chalk.yellow(`  ⚠ ${source.error}`));
+    warnings++;
+  } else {
+    console.log(chalk.green(`  ✓ Found source: ${source.path}`));
+    console.log(chalk.gray(`    Type: ${source.type || 'unknown'}`));
+  }
+
+  // Summary
+  console.log('');
+  console.log(chalk.cyan('─'.repeat(40)));
+
+  if (issues === 0 && warnings === 0) {
+    console.log(chalk.green.bold('\n✓ All checks passed!\n'));
+  } else if (issues === 0) {
+    console.log(chalk.yellow(`\n⚠ ${warnings} warning(s), no critical issues\n`));
+  } else {
+    console.log(chalk.red(`\n✗ ${issues} issue(s), ${warnings} warning(s)\n`));
+  }
+
+  // Suggestions
+  if (issues > 0 || warnings > 0) {
+    console.log(chalk.cyan('Suggestions:'));
+
+    if (!isProject) {
+      console.log(chalk.white('  • Run "ak init ." to initialize this directory'));
+    }
+
+    if (!state && isProject) {
+      console.log(chalk.white('  • State file is missing. Re-run "ak init" or create manually'));
+    }
+
+    if (state && state.source && !fs.existsSync(state.source)) {
+      console.log(chalk.white('  • Update source path: ak update --source <new-path>'));
+    }
+
+    console.log('');
+  }
+
+  return { issues, warnings };
+}