@bagdock/cli 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bagdock/cli",
-  "version": "0.2.0",
+  "version": "0.4.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,208 @@
+{
+  "skill": "bagdock-cli",
+  "version": "0.4.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"
+    },
+    {
+      "id": "validate-before-submit",
+      "description": "Agent should validate before submitting",
+      "input": "Check if my adapter is ready to submit to the marketplace",
+      "expected_commands": ["bagdock validate --json"],
+      "expected_behavior": "Runs local checks on bagdock.json and bundle, returns pass/warn/fail"
+    },
+    {
+      "id": "submission-list",
+      "description": "Agent should list submissions",
+      "input": "Show me all my marketplace submissions for this app",
+      "expected_commands": ["bagdock submission list --json"],
+      "expected_behavior": "Lists submission history with IDs, versions, and dates"
+    },
+    {
+      "id": "submission-status",
+      "description": "Agent should check submission status",
+      "input": "What's the review status of submission iadpv_abc123?",
+      "expected_commands": ["bagdock submission status iadpv_abc123 --json"],
+      "expected_behavior": "Returns detailed review state including status, reason, and timestamps"
+    },
+    {
+      "id": "submission-withdraw",
+      "description": "Agent should withdraw a pending submission",
+      "input": "Withdraw my pending submission iadpv_abc123, I found a bug",
+      "expected_commands": ["bagdock submission withdraw iadpv_abc123"],
+      "expected_behavior": "Cancels submission, sets review_status back to draft"
+    },
+    {
+      "id": "open-dashboard",
+      "description": "Agent should open project in dashboard",
+      "input": "Open my adapter in the Bagdock dashboard",
+      "expected_commands": ["bagdock open"],
+      "expected_behavior": "Opens browser to dashboard URL for the current project"
+    },
+    {
+      "id": "inspect-app",
+      "description": "Agent should inspect app deployment details",
+      "input": "Show me the deployment details for smart-entry",
+      "expected_commands": ["bagdock inspect smart-entry --json"],
+      "expected_behavior": "Returns app details including worker URL, version, review status"
+    },
+    {
+      "id": "env-pull",
+      "description": "Agent should pull env vars for local development",
+      "input": "Pull the env var keys from my deployed adapter to a local .env file",
+      "expected_commands": ["bagdock env pull .env.local"],
+      "expected_behavior": "Creates .env.local with keys and empty values, warns that values need filling"
+    },
+    {
+      "id": "link-project",
+      "description": "Agent should link directory to a project",
+      "input": "Link this directory to my smart-entry adapter",
+      "expected_commands": ["bagdock link --slug smart-entry"],
+      "expected_behavior": "Creates .bagdock/link.json with slug, other commands use it as fallback"
+    }
+  ]
+}

package/skills/bagdock-cli/SKILL.md

@@ -0,0 +1,161 @@
+# 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 |
+| `env pull [file]` | Pull remote env var keys to local .env file |
+| `keys create` | Create a new API key (raw key shown once) |
+| `keys list` | List API keys |
+| `keys delete <id>` | Revoke an API key |
+| `validate` | Run local pre-submission checks on bagdock.json and bundle |
+| `submission list` | List marketplace submission history |
+| `submission status <id>` | Fetch detailed review state for a submission |
+| `submission withdraw <id>` | Cancel a pending submission |
+| `open [slug]` | Open project in Bagdock dashboard |
+| `inspect [slug]` | Show deployment details and status |
+| `link` | Link directory to a Bagdock app or edge |
+| `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.
+
+### Validate before submitting
+
+```bash
+bagdock validate
+bagdock submit
+```
+
+### Check submission status
+
+```bash
+bagdock submission list --json
+bagdock submission status iadpv_xxx
+```
+
+### Link a directory and inspect
+
+```bash
+bagdock link --slug my-adapter
+bagdock inspect
+bagdock open
+```
+
+### Pull env vars for local dev
+
+```bash
+bagdock env pull .env.local
+```
+
+## 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`
+- **Marketplace submission lifecycle** → `references/marketplace.md`
+- **App management (open, inspect, link)** → `references/app-management.md`

package/skills/bagdock-cli/references/app-management.md

@@ -0,0 +1,63 @@
+# App Management Commands
+
+Commands for managing the relationship between your local directory and a Bagdock app or edge.
+
+## `bagdock link`
+
+Links the current directory to a Bagdock app or edge. Once linked, other commands (deploy, env, open, inspect, submission) use the linked slug as a fallback — no `bagdock.json` required.
+
+```bash
+# Interactive: select from your apps
+bagdock link
+
+# Non-interactive (CI/agents)
+bagdock link --slug my-adapter
+```
+
+Stores the link in `.bagdock/link.json`:
+
+```json
+{
+  "slug": "my-adapter",
+  "linkedAt": "2026-04-05T00:00:00.000Z"
+}
+```
+
+### Slug Resolution Order
+
+1. Explicit `--slug` or `--app` argument
+2. `bagdock.json` in current directory
+3. `.bagdock/link.json` (linked app)
+
+## `bagdock open [slug]`
+
+Opens the project in the Bagdock dashboard. Uses the slug resolution order above.
+
+```bash
+bagdock open
+bagdock open my-adapter
+```
+
+In JSON mode, returns the URL instead of opening the browser:
+
+```bash
+bagdock open --json
+# => {"url":"https://dashboard.bagdock.com/developer/apps/my-adapter","slug":"my-adapter"}
+```
+
+## `bagdock inspect [slug]`
+
+Shows deployment details for an app.
+
+```bash
+bagdock inspect
+bagdock inspect my-adapter --json
+```
+
+Displays:
+- Name, slug, ID
+- Type, category
+- Version, maintainer, visibility
+- Review status
+- Worker URL, namespace
+- Created, updated, published timestamps

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 }
+  }
+}
+```