@autofleet/cli 2.23.0 → 2.25.0

package/dist/claude-marketplace/README.md

@@ -9,7 +9,9 @@ TBD (Future: Jira, GitHub, Figma with automated API key setup)
 
 ### Skills
 - **db-modeling** - Database schema understanding and Sequelize model guidance
+- **dev-workflow** - Autofleet development workflows: sim/staging deployments, debugging, architecture overview
 - **js-ts-standards** - JavaScript/TypeScript coding standards and best practices
+- **node-test-runner** - Run Jest tests locally with Docker dependencies and test DB setup
 - **pr-standards** - Pull request description templates and conventions
 - **python-standards** - Python coding standards for Autofleet projects
 
@@ -20,28 +22,33 @@ TBD (Future: Jira, GitHub, Figma with automated API key setup)
 
 ## Installation
 
-### From Git (Recommended)
+The plugin is installed automatically when you install or update `@autofleet/cli`:
 
 ```bash
-# Add marketplace from Git
-claude plugin marketplace add https://github.com/Autofleet/autorepo.git#packages/claude-marketplace
+npm install -g @autofleet/cli
+```
+
+The `postinstall` hook runs `autofleet claudeInit`, which registers the marketplace and installs/updates the plugin automatically.
+
+### Manual Installation
 
-# Install the plugin
-claude plugin install autofleet@Autofleet
+If needed, you can run the setup manually:
+
+```bash
+autofleet claudeInit
 ```
 
 ### From Local Path (Development)
 
-If you have the monorepo cloned locally:
+If you want to work on the marketplace locally without rebuilding the CLI, symlink the dist directory to the source:
 
 ```bash
-# Add marketplace from local path
-claude plugin marketplace add file:///path/to/autorepo/packages/claude-marketplace
-
-# Install the plugin
-claude plugin install autofleet@Autofleet
+ln -sf ~/work/autorepo/packages/cli/bin/commands/base/claude-init/claude-marketplace \
+  $(npm root -g)/@autofleet/cli/dist/claude-marketplace
 ```
 
+Then run `autofleet claudeInit` to pick up the changes.
+
 ## Verification
 
 After installation, verify the setup:
@@ -49,54 +56,61 @@ After installation, verify the setup:
 ```bash
 # List installed marketplaces
 claude plugin marketplace list
-# Should show "Autofleet"
+# Should show "autofleet"
 
 # List installed plugins
 claude plugin list
-# Should show "autofleet@Autofleet"
+# Should show "autofleet@autofleet"
 ```
 
-Restart Claude Code to activate the MCP servers and skills.
+Restart Claude Code to activate the skills.
 
 ## Usage
 
-
-### Skills
-
 Skills are automatically available when relevant:
+- **dev-workflow** - Activated when discussing deployments, debugging, or architecture
 - **js-ts-standards** - Applied during code writing and review
+- **node-test-runner** - Activated when running tests on a Node.js microservice locally
 - **python-standards** - Applied when working with Python code
 - **db-modeling** - Activated when discussing database schemas or models
 - **pr-standards** - Enforced when creating pull requests
 
 ## Updating
 
-To update to the latest version:
+Users receive plugin updates automatically when they update the CLI:
 
 ```bash
-claude plugin update autofleet@Autofleet
+npm install -g @autofleet/cli
 ```
 
+The `postinstall` hook bumps the plugin version and reinstalls it on every CLI update.
+
 ## Development
 
 ### Structure
 
 ```
-packages/claude-marketplace/
-├── index.json              # Marketplace plugin list
+packages/cli/bin/commands/base/claude-init/claude-marketplace/
 ├── plugins/
 │   └── autofleet/
 │       ├── .claude-plugin/
-│       │   └── plugin.json  # Plugin metadata
+│       │   └── plugin.json   # Plugin metadata + version
 │       └── skills/
-│           ├── code-quality/SKILL.md
-│           └── pr-standards/SKILL.md
+│           ├── code-review/SKILL.md
+│           ├── db-modeling/SKILL.md
+│           ├── dev-workflow/SKILL.md
+│           ├── js-ts-standarts/SKILL.md
+│           ├── node-test-runner/SKILL.md
+│           ├── pr-standards/SKILL.md
+│           └── python-standards/SKILL.md
 └── README.md
 ```
 
 ### Publishing Changes
 
-1. Make changes to plugin files
+1. Add or edit skill files under `plugins/autofleet/skills/`
 2. Commit and push to the monorepo
-3. Team members run `claude plugin update autofleet@Autofleet` to update
-   (Note: Considering adding postinstall hook to CLI for automatic updates)
+3. Bump the CLI version (`packages/cli/package.json`) and publish
+4. Users get the update automatically on their next `npm install -g @autofleet/cli`
+
+> **Note:** `plugin.json` version is managed automatically by `claudeInit` — do not bump it manually.

package/dist/claude-marketplace/plugins/autofleet/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "autofleet",
   "description": "Autofleet company standards, MCP servers, and development skills",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "author": {
     "name": "Autofleet",
     "email": "emil@autofleet.io"

package/dist/claude-marketplace/plugins/autofleet/skills/add-endpoint/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: add-endpoint
+description: Guides adding a new API endpoint in an Autofleet microservice — REST
+  conventions, HTTP method selection, response codes, validation layers, pagination,
+  and registering the endpoint in the API gateway. Use when the user wants to add
+  a new route, register an endpoint, design a REST API, or understand Autofleet API
+  standards.
+version: 1.0.0
+userInvocable: true
+---
+
+# Adding a New Endpoint
+
+## Gateway Rule
+
+Register an endpoint in the API gateway **only if** it is called from a frontend or an external client. Endpoints called only between microservices (server-to-server) bypass the gateway and do not need to be registered.
+
+---
+
+## Step 1 — Implement the endpoint in the microservice
+
+### Path Format
+
+`/api/v{n}/{resource-name}` — kebab-case, plural nouns
+
+Examples: `/api/v1/vehicle-assignments`, `/api/v2/fleet-operators/:id/settings`
+
+### HTTP Method Selection
+
+| Method | When to use |
+|--------|-------------|
+| GET | Retrieval; use PUT if request body is too large for query params |
+| POST | Non-idempotent creation or actions |
+| PUT | Idempotent create-or-replace |
+| PATCH | Partial updates |
+| DELETE | Removal |
+
+### Response Codes
+
+| Code | When |
+|------|------|
+| 200 | Success with body |
+| 204 | Success with no body (DELETE) |
+| 400 | Validation error |
+| 403 | Forbidden (missing permission) |
+| 404 | Resource not found |
+| 500 | Unexpected server error |
+
+> 401 and 429 are handled by the gateway — do not return them from microservices.
+
+### Response Body Rules
+
+- All field names: **camelCase**
+- Never return a raw array — wrap in `{ items: [...] }`
+- Serialize explicitly — never return a raw DB model instance
+- Error format: `{ "errors": ["message"] }`
+
+### Pagination
+
+When returning lists, support `page` + `pageSize` query params (max 100). See **examples.md → Pagination Response** for the response shape.
+
+### Validation Layers (in order)
+
+1. **Syntax** — framework-level (JSON parse, content-type)
+2. **Schema** — validate shape and types (Joi/Zod)
+3. **Business logic** — domain rules in the service layer
+
+See the [REST APIs at Autofleet](https://www.notion.so/autofleet/REST-APIs-at-Autofleet) Notion guide for full examples.
+
+### Error Handling with `@autofleet/errors`
+
+Use the shared error classes instead of throwing plain errors or manually setting status codes.
+
+```typescript
+import {
+  BadRequest,
+  ResourceNotFoundError,
+  UnauthorizedError,
+  UnexpectedError,
+  handleError,          // Express
+  handleErrorFastify,   // Fastify — register as a plugin
+} from '@autofleet/errors';
+```
+
+**Error classes and their HTTP status codes:**
+
+| Class | Status | When to use |
+|-------|--------|-------------|
+| `BadRequest` | 400 | Validation / schema errors |
+| `UnauthorizedError` | 403* | Missing or insufficient permissions |
+| `ResourceNotFoundError` | 404 | Entity not found |
+| `UnexpectedError` | 500 | Unexpected/unhandled errors |
+| `ServiceUnavailableError` | 503 | Downstream dependency unavailable |
+| `DatabaseLockedEntityError` | 423 | Optimistic lock conflict |
+
+> *`UnauthorizedError` defaults to 403 for backwards compatibility. Pass `{ useForbiddenStatusCode: false }` to get 401.
+
+See **examples.md → Error Handling** for Express and Fastify usage patterns.
+
+---
+
+## Step 2 — Register it in api-gateway-ms (if needed)
+
+**Only required if** the endpoint will be called from a frontend or an external client. Server-to-server calls between microservices bypass the gateway entirely — skip this step.
+
+Add/edit the service's config file at:
+```
+api-gateway-ms/src/config/server-api/apis/<service-name>.json
+```
+
+See **examples.md → API Gateway Registration** for the JSON format.
+
+### Permission values
+
+| Value | Who can call |
+|-------|-------------|
+| `"public"` | No auth required |
+| `"*"` or `"authenticated"` | Any logged-in user |
+| `"resource:action"` | Specific permission (e.g. `"vehicle:write"`) |
+| `"admin"` | Admin users only |
+
+---
+
+## Common Issues
+
+### 401 returned from microservice
+The gateway handles authentication — microservices should return 403 (forbidden) or 404, not 401.
+
+### Endpoint works locally but returns 404 in simulation
+The endpoint is not registered in `api-gateway-ms`. Add it to the service's JSON config and deploy api-gateway-ms.
+
+### Raw array returned instead of `{ items }`
+Clients break when the shape changes from object to array. Always wrap: `{ items: result }`.
+
+### Throwing plain `new Error()` instead of `@autofleet/errors` classes
+Plain errors are caught by `handleError` but always produce a 500. Use the specific class so the correct status code is returned automatically.

package/dist/claude-marketplace/plugins/autofleet/skills/add-endpoint/examples.md

@@ -0,0 +1,77 @@
+# Add Endpoint Examples
+
+## API Gateway Registration
+
+Config file: `api-gateway-ms/src/config/server-api/apis/<service-name>.json`
+
+```json
+{
+  "endpoints": [
+    {
+      "path": "/api/v1/my-resource/:id",
+      "methods": {
+        "get": {
+          "requestedPermissions": ["public"]
+        },
+        "post": {
+          "requestedPermissions": ["my-resource:write"],
+          "qps": 100,
+          "qpm": 1000
+        }
+      }
+    }
+  ]
+}
+```
+
+## Pagination Response
+
+```json
+{
+  "page": 1,
+  "pageSize": 20,
+  "total": 150,
+  "items": []
+}
+```
+
+## Error Handling — Express
+
+```typescript
+import { BadRequest, ResourceNotFoundError, handleError } from '@autofleet/errors';
+
+router.get('/vehicles/:id', async (req, res) => {
+  try {
+    const vehicle = await vehicleService.findById(req.params.id);
+    if (!vehicle) throw new ResourceNotFoundError('Vehicle not found');
+    res.json(vehicle);
+  } catch (err) {
+    handleError(err, res, { logger, message: 'GET /vehicles/:id failed' });
+  }
+});
+
+// BadRequest takes an array of Error objects
+throw new BadRequest([new Error('vehicleId is required')]);
+```
+
+## Error Handling — Fastify
+
+```typescript
+import { handleErrorFastify, ResourceNotFoundError } from '@autofleet/errors';
+
+// Register once at app startup
+fastify.register(handleErrorFastify);
+
+// Then throw anywhere — the plugin handles status codes and response shape
+fastify.get('/vehicles/:id', async (request) => {
+  const vehicle = await vehicleService.findById(request.params.id);
+  if (!vehicle) throw new ResourceNotFoundError('Vehicle not found');
+  return vehicle;
+});
+```
+
+## Error Response Shape
+
+```json
+{ "status": "ERROR", "errors": ["Vehicle not found"] }
+```

package/dist/claude-marketplace/plugins/autofleet/skills/dev-workflow/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: dev-workflow
+description: >-
+  Guides Autofleet development workflows — deploying to simulation/staging,
+  running services locally against simulation, debugging with GCP logs and mirrord,
+  adding API endpoints, and orchestrating E2E testing cycles. Use when the git
+  remote contains `github.com/Autofleet/`, the package.json name starts with
+  `@autofleet/`, or the directory ends in `-ms` — load at session start without
+  waiting for the user to ask.
+version: 1.0.0
+userInvocable: true
+---
+
+# Autofleet Development Workflow
+
+## Environment Types
+
+This skill covers simulation and staging only. **Never touch production.**
+
+| Name | Cluster Keys | Purpose |
+|------|-------------|---------|
+| **Simulation (dev)** | `expManager` (default), `dev1`, `e2eManager` | Personal dev sandbox, isolated per variation |
+| **Staging** | `staging`, `loadTest` | Shared pre-production environment |
+
+**Default simulation cluster is `expManager`** — use `dev1` or `e2eManager` only when explicitly required.
+
+Each simulation environment is isolated by a `variationId` (UUID). This becomes the Kubernetes namespace, database name suffix, and password component.
+
+**Default test account on simulation:**
+- Email: `tester@autofleet.io`
+- Password: `123456`
+
+---
+
+## Architecture Overview
+
+```
+Frontends: Control Center · Ordering · Web-Booker · Partner-Admin (React, Vite)
+       ↓  all /api/v1/* and /api/v2/* calls
+API Gateway MS (Express, port 8085)
+  - Adds x-trace-id to every request
+  - Authenticates via JWT (@autofleet/zehut)
+  - Rate limits, permission checks
+  - Proxies to target microservice
+       ↓
+Individual Microservices (TypeScript/Node.js)
+       ↓
+PostgreSQL / Redis / RabbitMQ
+```
+
+### Key repos
+- **api-gateway-ms** — entry point for all API traffic
+- **control-center** — React frontend (main)
+- **cli** — `@autofleet/cli` package inside `autorepo`; the `autofleet` command for cluster ops, proxying, deployments
+
+---
+
+## Adding a New Endpoint
+
+For full REST conventions, HTTP method selection, response codes, validation layers, and gateway registration details, use the **`add-endpoint` skill**.
+
+**Quick reference:**
+- Path: `/api/v{n}/{resource-name}` — kebab-case, plural nouns
+- Endpoints called from frontends or external clients → must be registered in api-gateway-ms
+- Endpoints called only between microservices → no gateway registration needed
+- Config file: `api-gateway-ms/src/config/server-api/apis/<service-name>.json`
+
+---
+
+## Development Workflows
+
+See **examples.md → Development Workflow Commands** for full bash commands.
+
+### Option A: Run service locally, wire to simulation
+
+Best for active backend development with hot reload. Steps: forward the sim DB, run the service locally, optionally intercept traffic via mirrord.
+
+### Option B: Deploy service to simulation, run a frontend locally
+
+Best for frontend development. Steps: `autofleet updateExp` to deploy the service, then wire the frontend to the sim gateway.
+
+- **Control Center:** `autofleet localDev` handles the wiring automatically, then `pnpm start control-center`
+- **Other frontends (ordering, web-booker, partner-admin):** set env vars manually — see the **`frontend-dev` skill** for per-app instructions
+
+### Useful cluster operations
+
+Use `autofleet switchCluster`, `forwardService`, `getIps`, and `dockerInit` for common cluster tasks. See examples.md for commands.
+
+---
+
+## Debugging
+
+### Tracing requests with x-trace-id
+
+Every request through the API gateway gets a unique `x-trace-id` header:
+- Generated by `shortid` in api-gateway-ms
+- Forwarded to all downstream microservices in the proxy headers
+- Included in error responses returned to the client
+- Logged alongside all service-level logs in GCP
+
+**When debugging network issues:**
+1. Use browser automation (Chrome) to test directly in the browser — click buttons, check checkbox state, trigger requests
+2. In Chrome DevTools → Network, find the failing request and check:
+   - The `x-trace-id` response header (to query GCP logs)
+   - The response payload (often contains a specific error message pointing to root cause)
+3. Replay the request with curl or intercept the auth token via the browser console — see **examples.md → Debugging**
+4. Query GCP logs filtering by that trace ID — see **examples.md → Querying GCP logs**
+
+### GCP project names by cluster
+- `dev1` → `dev1-experiment-manager`
+- `expManager` → `af-experiment-manager`
+- `e2eManager` → `e2e-project-1`
+- `staging` → `autofleet-staging`
+
+### Mirrord debugging (intercept live traffic locally)
+
+`mirrord` lets you run a service locally while it intercepts real traffic from the simulation cluster — no full deploy needed. It disables liveness/readiness probes on the running pod and restores them on exit (Ctrl+C). See **examples.md → Mirrord** for commands.
+
+### DB access
+
+Use `autofleet forwardDb` to port-forward PostgreSQL to localhost:5432. Credentials follow the pattern `postgres / afpass_<variationId>`, DB name is `<service>_<variationId>` (hyphens → underscores). See **examples.md → DB access**.
+
+---
+
+## Frontend Development
+
+All four Autofleet frontends (control-center, ordering, web-booker, partner-admin) share: React + Vite + TypeScript, dev server on port 3000, and proxy `/api` traffic to the API gateway.
+
+For full frontend wiring instructions, per-app setup, and common issues, use the **`frontend-dev` skill**.
+
+**Quick reference:** Option B in Development Workflows above uses `autofleet localDev` which is Control Center specific. For other frontends, set the gateway env var manually (see `frontend-dev` skill).
+
+---
+
+## Common Patterns
+
+### Error correlation flow
+1. User reports error in UI
+2. Open browser DevTools → Network → find failing request
+3. Copy x-trace-id from response headers
+4. Query GCP logs with that trace ID to find root cause across services
+
+### NPM packages
+
+Autofleet uses private `@autofleet/*` npm packages. Two things are required:
+
+**1. `NPM_TOKEN` env var** — needed for Docker builds (`updateExp`). If not set, the build will fail with a 401/404 on `@autofleet/*` packages. Always check this is set before running `autofleet updateExp`. See **examples.md → NPM Token Setup** for how to find and export the token.
+
+**2. npm install locally** — the token might be in `~/.npmrc` (used automatically) or may need to be set. If you get a 404 on `@autofleet/*` during local install, ask the user to check their token or run `npm login`.
+
+---
+
+## Common Issues
+
+### mirrord exits unexpectedly
+Liveness probes are restored on Ctrl+C; if killed abruptly, run `autofleet mirrordConfig` to check state.
+
+### npm audit fix breaks build
+Only use `--force` if the user explicitly approves — it may introduce breaking changes.
+
+### `@autofleet/*` package 401/404 during Docker build
+`NPM_TOKEN` is not set — see NPM packages section above and **examples.md → NPM Token Setup**.
+
+### Frontend can't reach backend
+See the **`frontend-dev` skill** → Common Issues.
+
+---
+
+## npm audit fix
+
+Before any of the following, ask the user if they'd like to run `npm audit fix` on the affected services:
+- Running unit tests
+- Deploying to simulation/staging
+- Opening or merging a PR
+
+> "Would you like to run `npm audit fix` on the changed services first? It fixes known dependency vulnerabilities — better to catch these now than have them flagged during QA or code review."
+
+Only use `--force` if the user explicitly approves — it may introduce breaking changes.
+
+---
+
+## End-of-Session Testing Flow
+
+After finishing a coding session, **always ask the user how they want to test** before proceeding. Summarize what was changed so they can make an informed choice.
+
+### Step 1 — Summarize what was changed
+
+Before asking, present a brief summary:
+- Which services were modified (e.g. `automation-ms`, `api-gateway-ms`)
+- Whether any frontend was changed
+- What the change does and what flow needs to be verified
+
+### Step 2 — Ask the user which testing mode they prefer
+
+Present the four options (see **examples.md → End-of-Session Testing Options** for commands):
+
+- **Option A** — Deploy changed backend services to simulation, run a frontend locally. Best when backend changes are the main thing to verify.
+- **Option B** — Run everything locally, wire to simulation DB/infra. Best when iterating on both frontend and backend simultaneously.
+- **Option C** — Run frontend locally, backend in simulation if needed. Best when only frontend was changed.
+- **Option D** — Deploy everything to simulation. Best for full integration test or handing off to QA.
+
+### Step 3 — Confirm what to verify
+
+After the user picks a mode, remind them what to test based on the changes made:
+- Navigate to the relevant page
+- Perform the action that triggers the new/changed behavior
+- Check browser DevTools for the new API call and verify the response
+- If something fails, grab the `x-trace-id` from the response and query GCP logs