@sunasteriskrnd/takumi 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# Takumi CLI
+
+Command-line tool for bootstrapping and managing [Takumi](https://github.com/sun-asterisk-internal/takumi-cli) projects.
+
+## Overview
+
+`takumi` manages Takumi installations — install, update, migrate, and configure kits from GitHub releases. Built with Bun + TypeScript for development; published CLI runs on plain Node.js.
+
+**Key features:**
+- Install/update kits from GitHub releases or local archives
+- Smart merge with user customization preservation
+- Multi-tier GitHub auth (gh CLI, env vars, keychain, prompt)
+- Idempotent migration with 3-phase reconciliation
+- Cross-platform: macOS, Linux, Windows
+
+## Prerequisites
+
+1. **GitHub access** to `sun-asterisk-internal/takumi`
+2. **GitHub CLI** installed and authenticated: `gh auth login`
+3. **Node.js** 18+ (runtime) or **Bun** (development)
+
+## Installation
+
+```bash
+npm install -g @sunasteriskrnd/takumi
+```
+
+Verify: `takumi --version`
+
+## Usage
+
+### Quick Start
+
+```bash
+takumi --help                      # All commands
+takumi new                         # Create new project (interactive)
+takumi new --kit engineer          # Create with specific kit
+takumi init                        # Initialize/update in current project
+takumi init -g -y                  # Global install, non-interactive
+```
+
+### Create New Project
+
+```bash
+takumi new                                  # Interactive
+takumi new --dir my-project --kit engineer  # With options
+takumi new --archive ~/kit.zip              # Offline install
+takumi new --install-skills                 # Auto-install skill deps
+takumi new --prefix                         # /takumi: namespace for commands
+```
+
+### Initialize or Update
+
+Run from project root:
+
+```bash
+takumi init                        # Interactive
+takumi init -y                     # Non-interactive, latest version
+takumi init -g --kit engineer -y   # Global install
+takumi init --fresh                # Clean reinstall (destructive)
+takumi init --archive ~/kit.zip    # Offline install
+takumi init --local                # From local monorepo (development)
+```
+
+### Update CLI
+
+```bash
+takumi update                      # Update to latest
+takumi update --check              # Check only
+takumi update --version 1.1.3     # Specific version
+```
+
+### Diagnostics
+
+```bash
+takumi doctor                      # Full health check
+takumi doctor --fix                # Auto-fix issues
+takumi doctor --report             # Shareable diagnostic report
+```
+
+### Skills & Agents
+
+```bash
+takumi skills --help               # Skill management
+takumi agents --help               # Agent management
+takumi commands --help             # Command discovery
+```
+
+### Other Commands
+
+```bash
+takumi versions                    # List available versions
+takumi migrate                     # Run migration pipeline
+takumi uninstall                   # Remove Takumi
+takumi config get defaults.kit     # Read config
+takumi config set defaults.kit engineer  # Write config
+```
+
+### Debugging
+
+```bash
+takumi new --verbose                       # Verbose logging
+takumi new --verbose --log-file debug.log  # Save to file
+SUN_AGENT_KIT_VERBOSE=1 takumi new        # Via env var
+```
+
+## Authentication
+
+```
+1. GitHub CLI (gh auth token)
+   ↓ fallback
+2. Environment Variables (GITHUB_TOKEN)
+   ↓ fallback
+3. Config File (~/.sun-takumi/config.json)
+   ↓ fallback
+4. OS Keychain
+   ↓ fallback
+5. User Prompt (with save option)
+```
+
+**Recommended:** `gh auth login` with web browser OAuth.
+
+## Configuration
+
+Stored in `~/.sun-takumi/config.json`:
+
+```json
+{
+  "github": { "token": "stored_in_keychain" },
+  "defaults": { "kit": "engineer", "dir": "." }
+}
+```
+
+### Protected Files
+
+Never overwritten during updates: `.env*`, `*.key`, `*.pem`, `node_modules/**`, `.git/**`, `dist/**`
+
+## Development
+
+```bash
+bun install                    # Install deps
+bun run dev new --kit engineer # Run locally
+bun test                       # Run tests (3600+ tests)
+bun run lint:fix               # Auto-fix lint
+bun run typecheck              # Type check
+bun run build                  # Build for npm
+bun run validate               # Full quality gate
+```
+
+See [AGENTS.md](./AGENTS.md) for project structure and coding patterns.
+
+## License
+
+Internal use — Sun Asterisk.

package/bin/takumi.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for npm-installed Takumi CLI.
+ * Runs the packaged Node-targeted bundle without requiring Bun on user machines.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const MIN_NODE_VERSION = [18, 0];
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const getErrorMessage = (err) => {
+	return err instanceof Error ? err.message : String(err);
+};
+
+const checkNodeVersion = () => {
+	const [major, minor] = process.versions.node.split(".").map(Number);
+	const [minMajor, minMinor] = MIN_NODE_VERSION;
+
+	if (major < minMajor || (major === minMajor && minor < minMinor)) {
+		console.error(
+			`[X] Node.js ${MIN_NODE_VERSION.join(".")}+ is required. Current version: ${process.versions.node}`,
+		);
+		console.error("   Please upgrade Node.js: https://nodejs.org/");
+		process.exit(1);
+	}
+};
+
+const runWithNode = async () => {
+	const distPath = join(__dirname, "..", "dist", "index.js");
+	if (!existsSync(distPath)) {
+		throw new Error(
+			"Compiled distribution not found. Reinstall Takumi CLI or report a packaging issue.",
+		);
+	}
+
+	const distUrl = pathToFileURL(distPath).href;
+	await import(distUrl);
+};
+
+const main = async () => {
+	checkNodeVersion();
+
+	try {
+		await runWithNode();
+	} catch (err) {
+		console.error(`[X] Failed to run CLI: ${getErrorMessage(err)}`);
+		console.error("Please report this issue at: https://github.com/sun-asterisk-internal/agent-kit-cli/issues");
+		process.exit(1);
+	}
+};
+
+main();