create-kuckit-app 0.1.1 → 0.2.1

package/templates/base/.claude/skills/kuckit/references/CLI-COMMANDS.md

@@ -0,0 +1,365 @@
+# Kuckit CLI Command Reference
+
+Complete reference for all `kuckit` CLI commands.
+
+## Module Commands
+
+### `kuckit generate module <name>`
+
+Scaffold a new Kuckit module with proper structure.
+
+```bash
+bunx kuckit generate module billing
+bunx kuckit generate module billing --org acme
+bunx kuckit generate module billing --dir packages/modules
+```
+
+**Options:**
+
+- `--org <name>` - Organization prefix (default: `kuckit`)
+- `--dir <path>` - Output directory (default: `packages`)
+
+**Generated Structure:**
+
+```
+packages/billing-module/
+├── src/
+│   ├── module.ts           # Server module definition
+│   ├── client/
+│   │   └── module.ts       # Client module definition
+│   └── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+### `kuckit add <package>`
+
+Install and wire a Kuckit module into your project.
+
+```bash
+bunx kuckit add @acme/billing-module
+bunx kuckit add @acme/billing-module --skip-install
+```
+
+**Options:**
+
+- `--skip-install` - Skip npm/bun install
+
+**Actions:**
+
+1. Detects package manager from lock file
+2. Installs the package
+3. Reads `kuckit` metadata from package.json
+4. Updates `kuckit.config.ts`
+5. Wires client module if applicable
+
+### `kuckit search <keyword>`
+
+Search npm registry for Kuckit-compatible modules.
+
+```bash
+bunx kuckit search billing
+bunx kuckit search auth --limit 20
+bunx kuckit search --json
+```
+
+**Options:**
+
+- `--limit <n>` - Number of results (default: 10)
+- `--json` - Output as JSON
+
+### `kuckit discover`
+
+Find installed but unconfigured Kuckit modules.
+
+```bash
+bunx kuckit discover
+bunx kuckit discover --json
+bunx kuckit discover --interactive
+```
+
+**Options:**
+
+- `--json` - Output as JSON
+- `--interactive` - Prompt to enable discovered modules
+
+**Scans:**
+
+- `packages/` directory for local modules
+- `node_modules/` for packages with `kuckit` metadata
+
+### `kuckit doctor`
+
+Validate project setup and module configuration.
+
+```bash
+bunx kuckit doctor
+bunx kuckit doctor --json
+```
+
+**Checks:**
+
+1. Config file exists
+2. Config parses correctly
+3. Modules configured
+4. Packages installed
+5. Kuckit metadata valid
+6. Module exports exist
+7. SDK packages available
+
+---
+
+## Database Commands
+
+### `kuckit db push`
+
+Push all module schemas to database using Drizzle Kit.
+
+```bash
+bunx kuckit db push
+bunx kuckit db push --url postgres://...
+```
+
+### `kuckit db generate`
+
+Generate migration files for module schemas.
+
+```bash
+bunx kuckit db generate
+```
+
+### `kuckit db studio`
+
+Open Drizzle Studio with all module schemas.
+
+```bash
+bunx kuckit db studio
+```
+
+**Common Options:**
+
+- `--url <url>` - Database connection URL
+
+---
+
+## Authentication Commands
+
+### `kuckit auth login`
+
+Authenticate using OAuth device flow.
+
+```bash
+bunx kuckit auth login
+bunx kuckit auth login --server https://api.example.com
+bunx kuckit auth login --scopes read,write
+```
+
+**Options:**
+
+- `-s, --server <url>` - Server URL
+- `--scopes <scopes>` - Comma-separated scopes
+
+**Flow:**
+
+1. Initiates device flow with server
+2. Displays user code
+3. Auto-opens browser
+4. Polls for approval
+5. Stores token in `~/.kuckit/config.json`
+
+### `kuckit auth logout`
+
+Clear stored credentials.
+
+```bash
+bunx kuckit auth logout
+```
+
+### `kuckit auth whoami`
+
+Show current authentication status.
+
+```bash
+bunx kuckit auth whoami
+```
+
+---
+
+## Infrastructure Commands
+
+All infrastructure commands require authentication and use Pulumi for GCP deployment.
+
+### `kuckit infra init`
+
+Initialize base infrastructure (Cloud SQL, Redis, Artifact Registry).
+
+```bash
+bunx kuckit infra init
+bunx kuckit infra init --provider gcp --project my-project --region us-central1 --env dev
+bunx kuckit infra init -y  # Skip prompts
+```
+
+**Options:**
+
+- `-p, --provider <provider>` - Cloud provider (only 'gcp' supported)
+- `--project <id>` - GCP project ID
+- `--region <region>` - Deployment region (default: us-central1)
+- `-e, --env <env>` - Environment (dev/prod)
+- `-y, --yes` - Skip prompts
+
+**Creates:**
+
+- Artifact Registry repository
+- Cloud SQL PostgreSQL instance
+- Memorystore Redis instance
+- Secrets in Secret Manager
+- VPC networking
+
+### `kuckit infra deploy`
+
+Build and deploy to Cloud Run.
+
+```bash
+bunx kuckit infra deploy --env dev
+bunx kuckit infra deploy --env dev --preview
+bunx kuckit infra deploy --env dev --skip-build
+bunx kuckit infra deploy --env dev --image gcr.io/my-project/app:tag
+```
+
+**Options:**
+
+- `-e, --env <env>` - Environment
+- `--preview` - Preview only (no apply)
+- `--skip-build` - Use existing image
+- `--image <url>` - Use specific image
+
+### `kuckit infra destroy`
+
+Destroy infrastructure resources.
+
+```bash
+bunx kuckit infra destroy --env dev
+bunx kuckit infra destroy --env dev --app-only
+bunx kuckit infra destroy --env dev --force
+```
+
+**Options:**
+
+- `--app-only` - Only destroy Cloud Run, keep DB/Redis
+- `--force` - Skip confirmation
+
+### `kuckit infra repair`
+
+Repair infrastructure state issues.
+
+```bash
+bunx kuckit infra repair --env dev
+bunx kuckit infra repair --env dev --refresh
+bunx kuckit infra repair --env dev --cancel
+```
+
+**Options:**
+
+- `--refresh` - Refresh state from cloud
+- `--cancel` - Cancel stuck operations
+
+### `kuckit infra db:push`
+
+Push database schema to Cloud SQL.
+
+```bash
+bunx kuckit infra db:push --env dev
+bunx kuckit infra db:push --env dev --force
+bunx kuckit infra db:push --env dev --public-ip
+```
+
+**Options:**
+
+- `--force` - Skip confirmation
+- `--public-ip` - Use public IP
+
+### `kuckit infra db:migrate`
+
+Run database migrations on Cloud SQL.
+
+```bash
+bunx kuckit infra db:migrate --env dev
+bunx kuckit infra db:migrate --env dev --dry-run
+bunx kuckit infra db:migrate --env dev --rollback
+```
+
+**Options:**
+
+- `--dry-run` - Show without applying
+- `--rollback` - Rollback last migration
+
+### `kuckit infra rollback`
+
+Rollback Cloud Run to previous revision.
+
+```bash
+bunx kuckit infra rollback --env dev
+```
+
+### `kuckit infra logs`
+
+View Cloud Run service logs.
+
+```bash
+bunx kuckit infra logs --env dev
+bunx kuckit infra logs --env dev -f
+bunx kuckit infra logs --env dev --since 1h
+bunx kuckit infra logs --env dev --severity ERROR
+```
+
+**Options:**
+
+- `-f, --follow` - Stream logs
+- `--since <duration>` - Time range (e.g., 1h, 30m)
+- `--severity <level>` - Filter by severity
+
+### `kuckit infra status`
+
+Show current infrastructure state.
+
+```bash
+bunx kuckit infra status --env dev
+```
+
+### `kuckit infra outputs`
+
+Display infrastructure outputs (URLs, connection strings).
+
+```bash
+bunx kuckit infra outputs --env dev
+```
+
+---
+
+## Package Manager Detection
+
+The CLI detects package manager from lock files:
+
+| Lock File           | Package Manager |
+| ------------------- | --------------- |
+| `bun.lock`          | bun             |
+| `yarn.lock`         | yarn            |
+| `pnpm-lock.yaml`    | pnpm            |
+| `package-lock.json` | npm             |
+
+---
+
+## Programmatic Usage
+
+```typescript
+import { generateModule, addModule, discoverModules } from '@kuckit/cli'
+
+// Generate module
+await generateModule('billing', { org: 'acme', dir: 'packages' })
+
+// Add module
+await addModule('@acme/billing-module', { skipInstall: false })
+
+// Discover modules
+await discoverModules({ json: true, interactive: false })
+```