sun-agent-kit-cli 1.1.1

package/README.md

@@ -0,0 +1,217 @@
+# Sun Agent Kit CLI
+
+Command-line tool for bootstrapping and managing Sun Agent Kit projects.
+
+## Overview
+
+Sun Agent Kit CLI (`sk`) manages Sun Agent Kit projects — install, update, migrate, and configure kits from GitHub releases. Built with Bun + TypeScript for development; published CLI runs on plain Node.js.
+
+**Key Features:**
+- **16 CLI Commands**: new, init, config, projects, setup, skills, agents, commands, migrate, doctor, versions, update, uninstall, watch, content, easter-egg
+- **Projects Registry**: Centralized registry at `~/.sun-agent-kit/projects.json` with file locking
+- **Skill Installation**: Install skills to other coding agents (Cursor, Codex, etc.)
+- **Multi-tier Auth**: gh CLI → env vars → keychain → prompt fallback
+- **Smart Merging**: Conflict detection with user customization preservation
+- **Idempotent Migration**: 3-phase reconciliation (RECONCILE → EXECUTE → REPORT)
+- **Offline Installation**: From local archives or directories
+- **Security**: Path traversal protection, symlink validation, UNC path protection
+- **Cross-Platform**: macOS, Linux, Windows
+
+## Prerequisites
+
+1. **Purchase a Sun Agent Kit Starter Kit** from [Sun Agent Kit.cc](https://sun-agent-kit.cc)
+2. **Get Repository Access**: After purchase, you receive access to the private GitHub repository
+3. **Install GitHub CLI** and authenticate: `gh auth login` (select "Login with a web browser")
+
+## Installation
+
+```bash
+npm install -g sun-agent-kit-cli
+# or: bun add -g / yarn global add / pnpm add -g
+```
+
+Verify: `sk --version`
+
+## Usage
+
+### Quick Start
+
+```bash
+sk --help                      # All commands
+sk new                         # Create new project (interactive)
+sk new --kit engineer          # Create with specific kit
+sk init                        # Initialize/update in current project
+sk config get defaults.kit     # Read config
+sk config set defaults.kit engineer  # Write config
+```
+
+### Create New Project
+
+```bash
+sk new                                  # Interactive
+sk new --dir my-project --kit engineer  # With options
+sk new --beta                           # Show beta versions
+sk new --archive ~/kit.zip              # Offline install
+sk new --install-skills                 # Auto-install skill deps
+sk new --prefix                         # /sk: namespace for commands
+```
+
+### Initialize or Update
+
+Run from project root:
+
+```bash
+sk init                        # Interactive
+sk init -y                     # Non-interactive, sensible defaults
+sk init -g --kit engineer -y   # Global, specific kit, non-interactive
+sk init --fresh                # Clean reinstall (destructive)
+sk init --archive ~/kit.zip    # Offline install
+```
+
+### Update CLI
+
+```bash
+sk update                      # Update to latest
+sk update --check              # Check only
+sk update --version 1.17.0     # Specific version
+```
+
+### Diagnostics
+
+```bash
+sk doctor                      # Full health check
+sk doctor --fix                # Auto-fix issues
+sk doctor --report             # Shareable diagnostic report
+sk doctor --check-only --json  # CI mode
+```
+
+### Skills & Agents
+
+```bash
+sk skills --help               # Skill installation workflows
+sk agents --help               # Agent management
+sk commands --help             # Command discovery
+```
+
+### Watch GitHub Issues
+
+```bash
+sk watch                       # Start monitoring
+sk watch --dry-run             # Preview mode
+```
+
+Autonomous daemon: monitors issues → analyzes with Claude → generates plans → creates PRs. Config in `.sk.json` under `watch` key. See [docs/sk-watch.md](./docs/sk-watch.md).
+
+### Content Generation
+
+```bash
+sk content setup               # Interactive setup
+sk content start               # Start daemon
+sk content status              # Check status
+```
+
+Scans git activity → generates social content with Claude → publishes to X/Twitter and Facebook. Config in `.sk.json` under `content` key. See [docs/sk-content.md](./docs/sk-content.md).
+
+### Other Commands
+
+```bash
+sk versions                    # List available versions
+sk versions --kit engineer     # Filter by kit
+sk migrate                     # Run migration pipeline
+sk uninstall                   # Remove Sun Agent Kit
+sk --version                   # Show version + update check
+```
+
+### Debugging
+
+```bash
+sk new --verbose                       # Verbose logging
+sk new --verbose --log-file debug.log  # Save to file
+SUN_AGENT_KIT_VERBOSE=1 sk new        # Via env var
+```
+
+## Authentication
+
+```
+1. GitHub CLI (gh auth token)
+   ↓ fallback
+2. Environment Variables (GITHUB_TOKEN)
+   ↓ fallback
+3. Config File (~/.sun-agent-kit/config.json)
+   ↓ fallback
+4. OS Keychain
+   ↓ fallback
+5. User Prompt (with save option)
+```
+
+**Setup:** `gh auth login` → select "Login with a web browser" → complete OAuth in browser.
+
+## Configuration
+
+Stored in `~/.sun-agent-kit/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/**`
+
+### Exclude Patterns
+
+```bash
+sk new --exclude "*.log" --exclude "temp/**"
+```
+
+## Available Kits
+
+| Kit | Description |
+|-----|-------------|
+| **engineer** | Engineering toolkit for building with Claude |
+| **marketing** | Content automation toolkit |
+
+Purchase at [Sun Agent Kit.cc](https://sun-agent-kit.cc).
+
+## Development
+
+```bash
+bun install                    # Install deps
+bun run dev new --kit engineer # Run locally
+bun test                       # Run tests
+bun run lint:fix               # Auto-fix lint
+bun run typecheck              # Type check
+bun run build                  # Build for npm
+bun run test:integration       # CLI integration tests
+```
+
+See [AGENTS.md](./AGENTS.md) for project structure and coding patterns.
+
+## Documentation
+
+- [Codebase Summary](./docs/codebase-summary.md) — Architecture overview
+- [Project Overview & PDR](./docs/project-overview-pdr.md) — Requirements, roadmap
+- [System Architecture](./docs/system-architecture.md) — Technical details
+- [Reconciliation Architecture](./docs/reconciliation-architecture.md) — `sk migrate` design
+- [Code Standards](./docs/code-standards.md) — Conventions
+- [Deployment Guide](./docs/deployment-guide.md) — Release procedures
+- [sk watch](./docs/sk-watch.md) — Issue monitoring
+- [sk content](./docs/sk-content.md) — Content generation
+
+## FAQ
+
+**Q: Do I need GitHub CLI?**
+A: Yes. Required for authentication with private repositories.
+
+**Q: "Access denied" error?**
+A: Accept GitHub repo invitation, re-run `gh auth login` with web browser, wait 2-5min.
+
+**Q: Is my token secure?**
+A: Yes. GitHub CLI manages tokens via OAuth, stored encrypted in OS keychain.
+
+## License
+
+MIT

package/bin/sk.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for npm-installed Sun Agent Kit 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 Sun Agent Kit 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/issues");
+		process.exit(1);
+	}
+};
+
+main();