bod-cli 0.3.1

package/.cursor/skills/using-bod-cli/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: using-bod-cli
+description: Guide for AI agents to use the bod CLI to scaffold, deploy, manage, and operate apps on Bodify. Use when creating new projects, deploying code, managing environments, viewing logs, or operating deployed apps.
+---
+
+# Using bod-cli
+
+`bod` is the unified CLI for the Bod product family. Currently supports Bodify (self-hosted deployment platform).
+
+## Setup
+
+```bash
+# Install globally (from the bod-cli directory)
+bun link
+
+# Or run directly
+bun /path/to/bod-cli/src/cli.ts <command>
+
+# First-run: authenticate with a Bodify instance
+bod login https://your-bodify-server.com --key YOUR_API_KEY
+```
+
+Config stored at `~/.bod/config.json`. Supports multiple instances.
+
+## End-to-End: New Project
+
+```bash
+# 1. Create directory and init
+mkdir my-api && cd my-api
+bod init
+# → Select template (caab / caab-db / static / server)
+# → Enter app name
+# → Auto: scaffolds files, git init, registers with Bodify, bun install
+
+# 2. Deploy
+bod deploy
+
+# 3. Monitor
+bod logs my-api -f
+bod apps status my-api
+```
+
+## End-to-End: Existing Project
+
+```bash
+cd my-existing-project
+bod init
+# → Auto-detects type (api.ts=caab, dist/=static, server.ts=server, packages/=mixed)
+# → Creates bodify.yaml, registers with Bodify, sets up .claude/ config
+
+bod deploy
+```
+
+## Command Reference
+
+### `bod login <url>`
+Authenticate with a Bodify instance.
+
+```bash
+bod login https://bodify.example.com              # prompts for API key
+bod login https://bodify.example.com --key=$KEY    # non-interactive
+bod login https://bodify.example.com --name=prod   # custom alias
+```
+
+Verifies connectivity (`/healthz`), fetches capabilities (`/config/public`), saves to config.
+
+### `bod init`
+Initialize or connect a project to Bodify.
+
+**Empty directory:** prompts for template, scaffolds complete project:
+- Source files (api.ts / App.tsx / server.ts)
+- `package.json`, `tsconfig.json`, `bodify.yaml`
+- `.claude/CLAUDE.md` — project context for Claude agents
+- `.claude/mcp_servers.json` — MCP connection to Bodify
+- `.gitignore`, git init + initial commit
+- Registers app with Bodify API
+- `.npmrc` if registry enabled
+- `bun install`
+
+**Existing directory:** detects app type, creates `bodify.yaml`, registers, generates `.claude/` config.
+
+### `bod deploy [app] [--branch=...]`
+Trigger deployment. Reads app name from positional arg or `bodify.yaml`. Auto-detects current git branch.
+
+```bash
+bod deploy                    # from project dir with bodify.yaml
+bod deploy my-api             # explicit app name
+bod deploy my-api --branch=lab  # specific branch
+```
+
+**Two deploy modes** (auto-detected):
+- **Git-based**: if the app has a `repo` URL, Bodify clones from git (standard flow)
+- **Upload-based**: if no repo URL, the CLI tars the local working directory and uploads it directly — no git remote needed
+
+Polls for completion (up to 4 min), shows status updates.
+
+### `bod rollback [app] [--branch=...]`
+Rollback to previous deployment.
+
+```bash
+bod rollback my-api
+bod rollback my-api --branch=lab
+```
+
+### `bod apps list`
+List all registered apps with name, domain, branch, type, repo.
+
+### `bod apps status <app>`
+Detailed view: app config, running instances, recent deployments.
+
+### `bod logs <app> [-f] [--lines=100]`
+View application logs.
+
+```bash
+bod logs my-api               # last 100 lines
+bod logs my-api --lines=500   # more lines
+bod logs my-api -f            # follow mode (polls every 2s)
+```
+
+### `bod open <app>`
+Open an app in the default browser. Resolves the URL from the app's domain.
+
+```bash
+bod open my-api               # opens https://my-api.bodify.example.com
+```
+
+### `bod env list|set|unset <app>`
+Manage environment variables.
+
+```bash
+bod env list my-api
+bod env set my-api DATABASE_URL=postgres://...
+bod env set my-api -f .env            # bulk set from .env file
+bod env unset my-api OLD_VAR
+```
+
+### `bod add <pkg>` / `bod remove <pkg>`
+Registry-aware package management. If Bodify registry is enabled, `bun add` uses it automatically.
+
+```bash
+bod add @bod.ee/db            # from Bodify registry
+bod add lodash                # falls through to npm
+bod remove @bod.ee/db
+```
+
+## Multi-Instance Support
+
+```bash
+# Add another instance
+bod login https://staging.example.com --name=staging
+
+# Use specific instance for a command
+bod apps list --instance=staging
+
+# Or via env var
+BOD_INSTANCE=staging bod apps list
+```
+
+## Templates
+
+| Template | Files | Use Case |
+|----------|-------|----------|
+| `caab` | `api.ts` with Resource convention | REST API, methods → endpoints |
+| `caab-db` | `api.ts` + BodDB setup | API with embedded database |
+| `static` | React + Vite + `vite.config.ts` | SPA, served from `dist/` |
+| `server` | `server.ts` with `Bun.serve()` | Custom HTTP server |
+
+### CaaB Templates Use Resource Convention
+
+```typescript
+abstract class Resource {
+  static readonly [Symbol.for('bodify.Resource')] = true;
+}
+
+class Items extends Resource {
+  async get() { ... }              // GET  /items
+  async getById(id: string) { ... } // GET  /items/by-id/:id
+  async post(body: {...}) { ... }  // POST /items
+  async delete(id: string) { ... } // DELETE /items/:id
+}
+
+export default class Api extends Resource {
+  items = new Items();
+  async getHealthz() { ... }       // GET  /healthz
+}
+```
+
+### Server Template Requirements
+
+- Read `PORT` from `process.env.PORT`
+- Expose `GET /healthz` returning JSON
+- Bodify health-checks this endpoint
+
+## AI-First: Generated `.claude/` Config
+
+`bod init` generates two files for Claude Code integration:
+
+**`.claude/CLAUDE.md`** — Project context with:
+- Commands cheat sheet
+- CaaB convention reference (for caab/caab-db templates)
+- BodDB API reference (for database-enabled apps)
+- Server requirements (for server template)
+- MCP integration note
+
+**`.claude/mcp_servers.json`** — MCP connection using `${BODIFY_API_KEY}` env var reference (not hardcoded keys). Users set the env var and Claude Code can manage the app via MCP tools.
+
+## Config File
+
+`~/.bod/config.json`:
+```json
+{
+  "instances": {
+    "my-server": {
+      "url": "https://bodify.example.com",
+      "apiKey": "$BODIFY_KEY",
+      "capabilities": {
+        "registryEnabled": true,
+        "baseDomain": "bodify.example.com",
+        "githubConfigured": true
+      }
+    }
+  },
+  "defaultInstance": "my-server"
+}
+```
+
+API key supports env var references: `$VAR_NAME` or `env:VAR_NAME`.
+
+## Common Agent Tasks
+
+### "Set up a new CaaB API"
+```bash
+mkdir my-api && cd my-api
+bod init  # select caab or caab-db
+# Edit api.ts to add your resources
+bod deploy
+```
+
+### "Deploy a specific branch"
+```bash
+bod deploy my-app --branch=feature-xyz
+```
+
+### "Deploy without a git remote"
+```bash
+# Works from any local project — tars and uploads source directly
+bod init       # register app (no git remote needed)
+bod deploy     # auto-detects no repo, uploads tarball
+```
+
+### "Debug a failing deployment"
+```bash
+bod apps status my-app    # check deployment status
+bod logs my-app -f        # check logs
+```
+
+### "Add an env var and redeploy"
+```bash
+bod env set my-app API_SECRET=xxx
+bod deploy my-app
+```
+
+### "Bulk set env vars from .env file"
+```bash
+bod env set my-app -f .env
+bod deploy my-app
+```
+
+### "Connect an existing project"
+```bash
+cd existing-project
+bod init    # auto-detects type, registers with Bodify
+bod deploy
+```

package/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish-npm:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org/'
+
+      - uses: oven-sh/setup-bun@v1
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "actions@github.com"
+
+      - name: Bump version and commit
+        run: |
+          npm version patch --no-git-tag-version
+          VERSION=$(node -p "require('./package.json').version")
+          git add package.json
+          git commit -m "chore: release v${VERSION} [skip ci]"
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Push tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          git tag "v${VERSION}"
+          git push --follow-tags

package/CLAUDE.md

@@ -0,0 +1,50 @@
+# bod-cli
+
+Unified CLI for the Bod product family. Currently supports Bodify (self-hosted Vercel alternative).
+
+## Skill Path
+
+See `.cursor/skills/using-bod-cli/SKILL.md` — full command reference, templates, AI integration, common tasks.
+
+## Quick Reference
+
+- Runtime: Bun
+- Framework: citty (defineCommand/runMain)
+- Config: `~/.bod/config.json` (Zod-validated, multi-instance)
+- Interactive prompts: @inquirer/prompts
+
+## Architecture
+
+```
+src/
+├── cli.ts              # citty entry + interactive menu
+├── config.ts           # ~/.bod/config.json management
+├── client.ts           # HTTP client (auth, JSON, errors)
+├── utils/
+│   ├── logger.ts       # component logger
+│   ├── output.ts       # printTable, printJson, printKv
+│   └── resolve.ts      # resolveAppId, readAppNameFromYaml
+└── commands/
+    ├── login.ts        # bod login <url>
+    ├── init/           # bod init (scaffold or connect)
+    │   ├── init.ts
+    │   └── templates.ts
+    ├── deploy.ts       # bod deploy [app]
+    ├── rollback.ts     # bod rollback [app]
+    ├── apps.ts         # bod apps list|status
+    ├── logs.ts         # bod logs <app> [-f]
+    ├── env.ts          # bod env list|set|unset (set supports -f .env)
+    ├── open.ts         # bod open <app>
+    ├── add.ts          # bod add <pkg>
+    └── remove.ts       # bod remove <pkg>
+```
+
+## Key Patterns
+
+- Config supports env var references: `$VAR` or `env:VAR`
+- Client auto-adds Bearer auth from config
+- Commands use citty `defineCommand` with `args` and `run`
+- First-run redirects to `bod login`
+- Global `--instance` flag / `BOD_INSTANCE` env var for multi-instance
+- `resolveAppId` in `utils/resolve.ts` — shared name→ID lookup
+- Templates use proper CaaB Resource convention from bodify scaffolding docs