@bagdock/cli 0.1.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bagdock/cli",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Bagdock developer CLI — build, test, and deploy apps and edges on the Bagdock platform",
   "keywords": [
     "bagdock",
@@ -28,8 +28,14 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills",
+    "skill-evals"
   ],
+  "skills": {
+    "name": "bagdock-cli",
+    "path": "skills/bagdock-cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -37,15 +43,18 @@
     "dev": "bun run bin/bagdock.ts",
     "build": "bun build bin/bagdock.ts --outdir dist --target node --format esm && node -e \"const fs=require('fs');const f='dist/bagdock.js';let c=fs.readFileSync(f,'utf8');c=c.replace(/^#!.*\\n/,'').replace(/^\\/\\/ @bun\\n/,'');fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)\"",
     "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "chalk": "^5.4.1",
     "commander": "^13.1.0",
-    "open": "^10.1.0",
-    "chalk": "^5.4.1"
+    "open": "^10.1.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4"
   }
 }

package/skill-evals/bagdock-cli/evals.json

@@ -0,0 +1,152 @@
+{
+  "skill": "bagdock-cli",
+  "version": "0.3.0",
+  "evals": [
+    {
+      "id": "login-flow",
+      "description": "Agent should authenticate using bagdock login",
+      "input": "Log me into Bagdock",
+      "expected_commands": ["bagdock login"],
+      "expected_behavior": "Opens browser for OAuth device flow, waits for approval"
+    },
+    {
+      "id": "create-api-key",
+      "description": "Agent should create an API key with proper flags",
+      "input": "Create a live API key named 'CI Deploy' for my GitHub Actions",
+      "expected_commands": ["bagdock keys create --name \"CI Deploy\" --environment live --json"],
+      "expected_behavior": "Creates key, captures raw key from JSON output for use in CI"
+    },
+    {
+      "id": "create-test-key",
+      "description": "Agent should create a test environment key",
+      "input": "I need a test API key with read-only access to units and contacts",
+      "expected_commands": ["bagdock keys create --name \"Test Read-Only\" --environment test --category restricted --scopes units:read contacts:read --json"],
+      "expected_behavior": "Creates restricted test key with specified scopes"
+    },
+    {
+      "id": "list-keys",
+      "description": "Agent should list API keys",
+      "input": "Show me all my live API keys",
+      "expected_commands": ["bagdock keys list --environment live"],
+      "expected_behavior": "Lists all active live-environment API keys"
+    },
+    {
+      "id": "revoke-key",
+      "description": "Agent should revoke an API key with confirmation",
+      "input": "Delete the API key ak_abc123, it was compromised",
+      "expected_commands": ["bagdock keys delete ak_abc123 --yes --reason \"Key compromised\""],
+      "expected_behavior": "Revokes the specified key immediately"
+    },
+    {
+      "id": "deploy-staging",
+      "description": "Agent should deploy to staging",
+      "input": "Deploy my adapter to staging",
+      "expected_commands": ["bagdock deploy"],
+      "expected_behavior": "Builds and deploys to staging environment"
+    },
+    {
+      "id": "deploy-production",
+      "description": "Agent should deploy to production with confirmation",
+      "input": "Push this to production",
+      "expected_commands": ["bagdock deploy --production --yes"],
+      "expected_behavior": "Deploys to production, skipping prompt since agent is non-TTY"
+    },
+    {
+      "id": "deploy-preview",
+      "description": "Agent should deploy a preview",
+      "input": "Create a preview deployment for this PR",
+      "expected_commands": ["bagdock deploy --preview --json"],
+      "expected_behavior": "Creates ephemeral preview URL, outputs JSON with URL"
+    },
+    {
+      "id": "set-env-var",
+      "description": "Agent should set an environment variable",
+      "input": "Set the VENDOR_API_KEY to sk_live_abc123 for my adapter",
+      "expected_commands": ["bagdock env set VENDOR_API_KEY sk_live_abc123"],
+      "expected_behavior": "Sets the variable, notes it takes effect on next deploy"
+    },
+    {
+      "id": "init-edge-adapter",
+      "description": "Agent should scaffold a new edge adapter project",
+      "input": "Create a new access control adapter called smart-entry",
+      "expected_commands": ["bagdock init --type edge --kind adapter --category access_control --slug smart-entry --name \"Smart Entry\""],
+      "expected_behavior": "Scaffolds project with bagdock.json and starter files"
+    },
+    {
+      "id": "ci-cd-pipeline",
+      "description": "Agent should set up a CI/CD pipeline using API key",
+      "input": "Set up GitHub Actions to deploy my adapter on push to main",
+      "expected_behavior": "Creates workflow that uses BAGDOCK_API_KEY secret, runs bagdock deploy --production --yes --json"
+    },
+    {
+      "id": "whoami-check",
+      "description": "Agent should check authentication status",
+      "input": "Am I logged into Bagdock?",
+      "expected_commands": ["bagdock whoami"],
+      "expected_behavior": "Shows current user email and operator ID"
+    },
+    {
+      "id": "submit-for-review",
+      "description": "Agent should submit app for marketplace review",
+      "input": "Submit my public adapter for review so I can deploy to production",
+      "expected_commands": ["bagdock submit"],
+      "expected_behavior": "Transitions review_status from draft to submitted"
+    },
+    {
+      "id": "non-tty-detection",
+      "description": "Agent should use --json flag in non-interactive mode",
+      "input": "Get all my API keys in a script-friendly format",
+      "expected_commands": ["bagdock keys list --json"],
+      "expected_behavior": "Outputs JSON array of keys to stdout"
+    },
+    {
+      "id": "doctor-check",
+      "description": "Agent should run diagnostics to verify environment",
+      "input": "Check if my Bagdock setup is working correctly",
+      "expected_commands": ["bagdock doctor"],
+      "expected_behavior": "Runs version, auth, config, and AI agent checks"
+    },
+    {
+      "id": "doctor-json",
+      "description": "Agent should run diagnostics in JSON mode",
+      "input": "Get diagnostics as JSON to check my environment",
+      "expected_commands": ["bagdock doctor --json"],
+      "expected_behavior": "Returns { ok: boolean, checks: [...] } JSON to stdout"
+    },
+    {
+      "id": "profile-switch",
+      "description": "Agent should switch between operator profiles",
+      "input": "Switch to my production profile",
+      "expected_commands": ["bagdock auth switch production"],
+      "expected_behavior": "Switches active profile to 'production'"
+    },
+    {
+      "id": "profile-list",
+      "description": "Agent should list available profiles",
+      "input": "What Bagdock profiles do I have?",
+      "expected_commands": ["bagdock auth list --json"],
+      "expected_behavior": "Lists all stored profiles with email and active status"
+    },
+    {
+      "id": "profile-flag",
+      "description": "Agent should use --profile flag for one-off commands",
+      "input": "Deploy to production using my prod profile",
+      "expected_commands": ["bagdock --profile prod deploy --production --yes"],
+      "expected_behavior": "Uses prod profile credentials for this deployment only"
+    },
+    {
+      "id": "logs-tail",
+      "description": "Agent should tail live logs for debugging",
+      "input": "Show me the live logs for my smart-entry adapter",
+      "expected_commands": ["bagdock logs tail --app smart-entry"],
+      "expected_behavior": "Streams live execution logs for the specified app"
+    },
+    {
+      "id": "apps-list",
+      "description": "Agent should list deployed applications",
+      "input": "What apps do I have deployed?",
+      "expected_commands": ["bagdock apps list --json"],
+      "expected_behavior": "Lists all deployed apps with slugs, types, and status"
+    }
+  ]
+}

package/skills/bagdock-cli/SKILL.md

@@ -0,0 +1,123 @@
+# Bagdock CLI Skill
+
+The `@bagdock/cli` is the developer CLI for building, testing, and deploying apps and edges on the Bagdock self-storage operator platform.
+
+## Installation
+
+```bash
+npm install -g @bagdock/cli
+```
+
+Or use without installing:
+
+```bash
+npx @bagdock/cli <command>
+```
+
+## Agent Protocol
+
+When calling the Bagdock CLI from an AI agent, CI/CD pipeline, or non-interactive environment:
+
+1. **JSON output is automatic** in non-TTY. Force it with `--json`.
+2. **Errors** go to stderr as `{ "error": { "code": "...", "message": "..." } }`.
+3. **Success** data goes to stdout as JSON.
+4. **Exit codes**: `0` = success, `1` = error.
+5. **Use `--quiet` / `-q`** to suppress all status/progress output (implies `--json`).
+6. **Use `--api-key <key>`** to authenticate without `bagdock login` (overrides all other auth).
+7. **Use `--yes`** on destructive commands (e.g., `keys delete`) in non-interactive mode.
+
+### Authentication Priority
+
+The CLI resolves credentials in this order:
+
+1. `--api-key <key>` flag (highest priority)
+2. `BAGDOCK_API_KEY` environment variable
+3. `BAGDOCK_TOKEN` environment variable (M2M JWT)
+4. `~/.bagdock/credentials.json` — active profile or `--profile` override (from `bagdock login`)
+
+For CI/CD, set `BAGDOCK_API_KEY` in your environment. For interactive use, run `bagdock login`.
+
+## Global Flags
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Force JSON output (auto in non-TTY) |
+| `-q, --quiet` | Suppress status messages (implies `--json`) |
+| `--api-key <key>` | Override auth for this invocation |
+| `-p, --profile <name>` | Use a named profile (overrides `BAGDOCK_PROFILE`) |
+| `-V, --version` | Print version |
+| `-h, --help` | Print help |
+
+## Available Commands
+
+| Command | Description |
+| --- | --- |
+| `login` | Authenticate via OAuth2 device flow (opens browser) |
+| `logout` | Clear stored credentials |
+| `whoami` | Show current authenticated user |
+| `init [dir]` | Scaffold a new project with `bagdock.json` |
+| `dev` | Start local dev server |
+| `deploy` | Build and deploy to Bagdock platform |
+| `submit` | Submit app for marketplace review |
+| `env list` | List app environment variables |
+| `env set <key> <value>` | Set an environment variable |
+| `env remove <key>` | Remove an environment variable |
+| `keys create` | Create a new API key (raw key shown once) |
+| `keys list` | List API keys |
+| `keys delete <id>` | Revoke an API key |
+| `doctor` | Run environment diagnostics (version, auth, config, agents) |
+| `auth list` | List stored profiles |
+| `auth switch [name]` | Switch active profile |
+| `apps list` | List deployed applications |
+| `apps get <slug>` | Show details for an application |
+| `logs list` | List recent execution logs |
+| `logs tail` | Tail live logs |
+
+## Common Patterns
+
+### Deploy to staging
+
+```bash
+bagdock deploy
+```
+
+### Deploy to production
+
+```bash
+bagdock deploy --production
+```
+
+### Create an API key for CI/CD
+
+```bash
+bagdock keys create --name "GitHub Actions" --environment live --json
+```
+
+### Use API key in CI/CD
+
+```bash
+BAGDOCK_API_KEY=sk_live_xxx bagdock deploy --production --yes
+```
+
+### List keys as JSON (for scripting)
+
+```bash
+bagdock keys list --json
+```
+
+## Common Mistakes
+
+1. **Forgetting `--yes` in CI/CD** — Destructive commands like `keys delete` require `--yes` in non-interactive environments.
+2. **Using wrong environment** — `sk_live_*` keys access production data, `sk_test_*` access sandbox. Match your intent.
+3. **Missing `bagdock.json`** — `deploy`, `submit`, and `env` commands require a `bagdock.json` in the current directory. Run `bagdock init` first.
+4. **Expired session** — If `whoami` fails, run `bagdock login` again. Sessions expire after 8 hours.
+
+## When to Load References
+
+Load specific reference files when the task involves:
+
+- **Authentication, login, or API keys** → `references/auth.md`
+- **Deploying, submitting, or managing apps** → `references/deploy.md`
+- **Environment variables** → `references/env.md`
+- **Local development** → `references/dev.md`
+- **Error codes or troubleshooting** → `references/error-codes.md`

package/skills/bagdock-cli/references/auth.md

@@ -0,0 +1,113 @@
+# Authentication Reference
+
+## `bagdock login`
+
+Starts an OAuth2 Device Authorization Grant (RFC 8628) flow:
+
+1. CLI requests a device code from the Bagdock API
+2. Opens the operator dashboard's device authorization page
+3. Displays a user code (e.g., `ABCD-1234`)
+4. Polls the token endpoint until the user approves
+5. Stores an HS256 JWT in `~/.bagdock/credentials.json`
+
+Sessions expire after 8 hours.
+
+```bash
+bagdock login
+```
+
+## `bagdock logout`
+
+Clears stored credentials from `~/.bagdock/credentials.json`.
+
+```bash
+bagdock logout
+```
+
+## `bagdock whoami`
+
+Shows the currently authenticated user. Uses the auth priority chain (see SKILL.md).
+
+```bash
+bagdock whoami
+```
+
+JSON output:
+
+```json
+{
+  "email": "dev@example.com",
+  "operator_id": "opreg_abc123",
+  "name": "Developer Name"
+}
+```
+
+## `bagdock keys create`
+
+Creates a new API key. The raw key is shown **once** — save it immediately.
+
+```bash
+bagdock keys create --name "Production CI" --environment live
+bagdock keys create --name "Test key" --environment test --category restricted --scopes units:read contacts:read
+```
+
+Options:
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--name <name>` | Key name (required) | — |
+| `--type <type>` | `secret` or `publishable` | `secret` |
+| `--category <cat>` | `standard`, `restricted`, `personal` | `standard` |
+| `--environment <env>` | `live` or `test` | `live` |
+| `--scopes <scopes...>` | Permission scopes | `[]` (full access for standard) |
+
+Key prefixes follow the Stripe convention:
+
+| Prefix | Meaning |
+| --- | --- |
+| `sk_live_` | Secret, live environment |
+| `sk_test_` | Secret, test environment |
+| `pk_live_` | Publishable, live |
+| `pk_test_` | Publishable, test |
+| `rk_live_` | Restricted, live |
+| `rk_test_` | Restricted, test |
+| `sk_personal_` | Personal key |
+
+## `bagdock keys list`
+
+Lists all active API keys (prefix + metadata only, never the raw key).
+
+```bash
+bagdock keys list
+bagdock keys list --environment test --json
+```
+
+## `bagdock keys delete <id>`
+
+Revokes an API key (soft-delete). Requires `--yes` in non-interactive mode.
+
+```bash
+bagdock keys delete ak_abc123 --yes --reason "Rotating keys"
+```
+
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `BAGDOCK_API_KEY` | API key for all requests (overrides login) |
+| `BAGDOCK_TOKEN` | M2M JWT for service-to-service auth |
+| `BAGDOCK_API_URL` | Override API base URL (default: `https://api.bagdock.com`) |
+| `BAGDOCK_DASHBOARD_URL` | Override dashboard URL (default: `https://dashboard.bagdock.com`) |
+
+## Credential Storage
+
+Credentials are stored at `~/.bagdock/credentials.json` with `0600` permissions (owner-only read/write). The directory is created with `0700` permissions.
+
+```json
+{
+  "accessToken": "<HS256 JWT>",
+  "expiresAt": 1700000000000,
+  "email": "dev@example.com",
+  "operatorId": "opreg_abc123"
+}
+```

package/skills/bagdock-cli/references/deploy.md

@@ -0,0 +1,91 @@
+# Deploy & Apps Reference
+
+## `bagdock deploy`
+
+Builds locally and deploys via the Bagdock API to Cloudflare Workers for Platforms. You never need Cloudflare credentials.
+
+```bash
+bagdock deploy                    # staging (default)
+bagdock deploy --preview          # ephemeral preview URL
+bagdock deploy --production       # live production
+bagdock deploy --production --yes # skip confirmation
+```
+
+### URL Scheme
+
+| Environment | URL Pattern |
+| --- | --- |
+| Preview | `{slug}-{hash}.pre.bdok.dev` |
+| Staging | `{slug}.pre.bdok.dev` |
+| Production | `{slug}.bdok.dev` |
+
+### Governance
+
+- **Private apps**: deploy freely to any environment
+- **Public integrations**: production requires `review_status = 'approved'`
+- Use `bagdock submit` to request marketplace review
+
+### Deploy Flow
+
+1. Reads `bagdock.json` from current directory
+2. Bundles the entry point (`main` field) with Bun
+3. Uploads the compiled Worker to `POST /developer/apps/:slug/deploy`
+4. The API handles CF Workers for Platforms upload
+
+### Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--env <environment>` | Target: `preview`, `staging`, `production` | `staging` |
+| `--preview` | Shortcut for `--env preview` | — |
+| `--production` | Shortcut for `--env production` | — |
+| `-y, --yes` | Skip confirmation prompts | — |
+
+## `bagdock submit`
+
+Submits the current app for Bagdock marketplace review. Required for public integrations before production deploy.
+
+```bash
+bagdock submit
+```
+
+Transitions `review_status` from `draft` to `submitted`.
+
+## `bagdock init [dir]`
+
+Scaffolds a new project with a `bagdock.json` configuration file.
+
+```bash
+bagdock init
+bagdock init my-adapter --type edge --kind adapter --category access_control
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `-t, --type <type>` | `edge` (backend worker) or `app` (UI extension) |
+| `-k, --kind <kind>` | `adapter`, `comms`, `webhook`, `ui-extension`, `microfrontend` |
+| `-c, --category <cat>` | Marketplace category |
+| `-s, --slug <slug>` | Unique project slug (kebab-case) |
+| `-n, --name <name>` | Display name |
+
+## `bagdock.json` Spec
+
+```json
+{
+  "name": "My Adapter",
+  "slug": "my-adapter",
+  "version": "1.0.0",
+  "type": "edge",
+  "kind": "adapter",
+  "category": "access_control",
+  "maintainer": "operator",
+  "visibility": "private",
+  "main": "src/index.ts",
+  "compatibilityDate": "2024-09-23",
+  "env": {
+    "VENDOR_API_KEY": { "description": "API key for vendor", "required": true }
+  }
+}
+```

package/skills/bagdock-cli/references/dev.md

@@ -0,0 +1,45 @@
+# Local Development Reference
+
+## `bagdock dev`
+
+Starts a local development server using Wrangler, mimicking the Cloudflare Workers environment.
+
+```bash
+bagdock dev
+bagdock dev --port 3000
+```
+
+### Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `-p, --port <port>` | Local dev server port | `8787` |
+
+### How It Works
+
+1. Reads `bagdock.json` from the current directory
+2. Generates a temporary `wrangler.toml` from the project config
+3. Starts `wrangler dev` with the appropriate settings
+4. Hot-reloads on file changes
+
+### Requirements
+
+- Wrangler must be installed (globally or as a dev dependency)
+- `bagdock.json` must exist with a valid `main` entry point
+
+### Wrangler Overrides
+
+Add a `wrangler` key to `bagdock.json` to override generated Wrangler config:
+
+```json
+{
+  "name": "my-adapter",
+  "slug": "my-adapter",
+  "main": "src/index.ts",
+  "wrangler": {
+    "kv_namespaces": [
+      { "binding": "CACHE", "id": "abc123" }
+    ]
+  }
+}
+```

package/skills/bagdock-cli/references/env.md

@@ -0,0 +1,37 @@
+# Environment Variables Reference
+
+## `bagdock env list`
+
+Lists environment variable keys (not values) for the current app.
+
+```bash
+bagdock env list
+```
+
+Requires `bagdock.json` in the current directory (uses the `slug` field).
+
+## `bagdock env set <key> <value>`
+
+Sets an environment variable. Takes effect on the next deploy.
+
+```bash
+bagdock env set VENDOR_API_KEY sk_live_xxx
+bagdock env set DATABASE_URL "postgres://..."
+```
+
+Values are stored in Infisical (platform secret manager) and synced to the Worker's Cloudflare secrets on deploy.
+
+## `bagdock env remove <key>`
+
+Removes an environment variable. Takes effect on the next deploy.
+
+```bash
+bagdock env remove VENDOR_API_KEY
+```
+
+## Notes
+
+- Environment variables are scoped to the app (by slug)
+- Values are never returned by the API — only keys and last-updated timestamps
+- Changes take effect on the next `bagdock deploy`, not immediately
+- The API endpoint is `PUT /developer/apps/:slug/env` (set) and `DELETE /developer/apps/:slug/env/:key` (remove)

package/skills/bagdock-cli/references/error-codes.md

@@ -0,0 +1,53 @@
+# Error Codes Reference
+
+All errors follow the structure:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description"
+  }
+}
+```
+
+## Authentication Errors
+
+| Code | Description | Resolution |
+| --- | --- | --- |
+| `UNAUTHENTICATED` | No valid credentials found | Run `bagdock login` or set `BAGDOCK_API_KEY` |
+| `UNAUTHORIZED` | Token is valid but lacks required permissions | Use a token with the correct scopes/role |
+| `SESSION_EXPIRED` | OAuth session has expired | Run `bagdock login` again |
+
+## Validation Errors
+
+| Code | Description | Resolution |
+| --- | --- | --- |
+| `VALIDATION_ERROR` | Request body failed validation | Check the `details` array for specific field errors |
+| `MISSING_CONFIG` | No `bagdock.json` found | Run `bagdock init` in the project directory |
+| `CONFIRMATION_REQUIRED` | Destructive operation needs confirmation | Pass `--yes` flag |
+
+## API Errors
+
+| Code | Description | Resolution |
+| --- | --- | --- |
+| `NOT_FOUND` | Resource does not exist | Verify the ID or slug |
+| `CONFLICT` | Operation conflicts with current state | e.g., revoking an already-revoked key |
+| `REVIEW_REQUIRED` | Public app needs approval for production | Run `bagdock submit` first |
+| `SERVICE_UNAVAILABLE` | Backend temporarily unavailable | Retry after a short delay |
+| `INTERNAL_ERROR` | Unexpected server error | Report to support |
+| `API_ERROR` | Generic API failure | Check the message for details |
+
+## Deploy Errors
+
+| Code | Description | Resolution |
+| --- | --- | --- |
+| `BUILD_FAILED` | Local build step failed | Check build output for errors |
+| `UPLOAD_FAILED` | CF Workers upload failed | Check script size limits and compatibility |
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Error (details in stderr) |