@optima-chat/dev-skills 0.7.33 → 0.7.36

package/docs/superpowers/specs/2026-05-24-marketplace-admin-cli-design.md

@@ -0,0 +1,324 @@
+# Marketplace Admin CLI — Design Spec
+
+**Status**: draft for review
+**Date**: 2026-05-24
+**Author**: Jerry (via Claude collaborative spec)
+**Tracking**: Optima-Chat/optima-dev-skills (to be filed)
+
+## 1. Purpose
+
+Give the Optima team a CLI surface to manage the paid-plugin marketplace (Wave 1.5) **before any admin UI exists**:
+
+1. Create a `Product` bundling 1+ plugin slugs and set its refund policy.
+2. Attach a payment `Channel` to a `Product` so it becomes self-purchaseable.
+3. Toggle a channel on/off.
+4. Inspect a `Product`'s current state (channels + plugins).
+5. Grant a `Product` entitlement to a user (admin-grant, no payment).
+6. Revoke an admin-granted entitlement.
+7. List a user's entitlements (used by `revoke` internally and exposed standalone).
+
+CLI ships inside the existing `@optima-chat/dev-skills` npm package as two new bin entries: `optima-product` and `optima-entitlement`, each with subcommands.
+
+## 2. Background
+
+Wave 1.5 (deployed to stage 2026-05-21, prod pending — see [optima-billing#43](https://github.com/Optima-Chat/optima-billing/issues/43)) shipped a full set of billing admin HTTP endpoints under `/api/billing/admin/*` plus the `Product` / `ProductPlugin` / `ProductChannel` / `Entitlement` data model. The service layer (`product.service.ts`, `entitlement.service.ts`) already encodes:
+
+- N:1 Plugin↔Product mapping with `pluginSlugs` ≥ 1 invariant
+- Concurrent grant race handling (partial unique index `entitlements_one_active`)
+- Outbox event creation (`entitlement.granted` / `entitlement.revoked`) with set-difference semantics on revoke (a plugin only appears in `lostPluginSlugs` if no other ACTIVE entitlement covers it)
+- Stripe refund cascade (PAYMENT source) vs no-op for ADMIN_GRANT / PARTNER sources (`EntitlementSource` enum is `PAYMENT | ADMIN_GRANT | PARTNER`)
+- Bundled subscription cascade per spec §6.2/§6.3
+
+**Implication for this CLI**: the heavy logic is already centralized in billing. The CLI must NOT reimplement any of it. It is a thin HTTP client that collects arguments, calls the admin endpoint, and surfaces the response/error verbatim.
+
+## 3. Non-goals
+
+- **Stripe Dashboard automation**: operator creates the Stripe `Product`+`Price` in the Stripe Dashboard by hand, then passes the resulting `price_xxx` ID to `optima-product add-channel`. No Stripe SDK dependency in this CLI.
+- **prod usage**: prod billing main is still on pre-Wave-1.5 schema ([optima-billing#48](https://github.com/Optima-Chat/optima-billing/pull/48) revert). The CLI accepts `--env prod` but will get 404/error responses until Wave 1.5 lands on prod. That's a billing rollout concern, not a CLI concern.
+- **Revoking PAYMENT or PARTNER-source entitlements**: only `ADMIN_GRANT`-source entitlements may be revoked via this CLI. `PAYMENT` revokes belong to the customer-facing Stripe refund flow (Stripe API + accounting); `PARTNER` revokes (3rd-party-issued grants) need their own out-of-band reversal — neither belongs in an admin convenience CLI.
+- **Listing all products**: no `optima-product list` subcommand. The required endpoint `GET /api/billing/admin/products` does not exist — see [optima-billing#58](https://github.com/Optima-Chat/optima-billing/issues/58). When that endpoint ships, add the subcommand in a follow-up.
+- **Admin UI**: this CLI is the bridge until a web admin UI exists. It is not a replacement.
+
+## 4. Architecture
+
+```
+                       ┌──── Infisical (BILLING_URL + client_secret)
+                       │
+operator's shell ──────┼──── user-auth /api/v1/oauth/token (grant_type=client_credentials)
+$ optima-product       │     → service JWT (type=service, clientId=dev-skills-ubd3qz6n)
+$ optima-entitlement   │
+                       ▼
+                  ┌─────────────────────────────────────┐    SQL    ┌─────────────┐
+                  │  optima-billing (stage)             │ ────────► │  billing DB │
+                  │  POST /api/billing/admin/products   │           │             │
+                  │  POST /api/billing/admin/           │           └─────────────┘
+                  │       grant-entitlement                                │
+                  │  POST /api/billing/admin/                              │ same tx
+                  │       refund-entitlement                               ▼
+                  │  GET  /api/billing/admin/entitlements           outbox_events
+                  │  GET  /api/internal/products/:key                      │
+                  └─────────────────────────────────────┘                  │
+                                                                           │ async dispatch
+                                                                           ▼
+                                                            optima-skills (existing)
+                                                            entitlement.granted → UserPlugin upsert
+                                                            entitlement.revoked → UserPlugin deleteMany
+```
+
+Three external dependencies per invocation: Infisical (config + secret lookup), user-auth (M2M token mint), optima-billing (admin endpoint).
+
+Components:
+
+- **CLI bin** (`bin/cli.js`): top-level dispatcher for `product` / `entitlement` subcommands. Mirrors how existing bins route flags.
+- **Subcommand handlers** (`bin/helpers/product/*.ts`, `bin/helpers/entitlement/*.ts`): one file per subcommand, each does arg parsing → token acquisition → HTTP call → JSON pretty-print or `BillingError` surface.
+- **Shared HTTP module** (`bin/helpers/billing-http.ts`, new): wraps `fetch` with: auth header injection, base URL resolution per env, response envelope unwrap, error formatting. Mirrors `db-utils.ts`'s role for DB.
+- **Auth module** (`bin/helpers/m2m-auth.ts`, new): `getServiceToken(env)` → Infisical fetch of OAuth credentials → `POST /api/v1/oauth/token` with `grant_type=client_credentials` → cache token in memory for the process lifetime.
+
+Dependencies on existing infra:
+
+- `db-utils.getInfisicalConfig` / `getInfisicalToken` — reused as-is to authenticate to Infisical.
+- No new npm dependencies. `fetch` is Node 18+ native; `package.json` `engines.node` is currently `">=14.0.0"`. Implementation plan T1 bumps it to `">=18.0.0"` (current install confirmed on Node 22 per `/home/jerry/.nvm/versions/node/v22.13.0/lib/node_modules/@optima-chat/dev-skills`; `>=18` is a safety floor, not a tightening of the runtime).
+
+## 5. Command surface
+
+All commands accept `--env stage|prod` (default `stage`) and `-h`/`--help`.
+
+### 5.1 `optima-product`
+
+```
+optima-product create
+  --key <productKey>                 required, unique slug; matches Wave 1.5 productKey rules
+  --plugins <slug1,slug2,...>        required, comma-separated, ≥1 plugin slug; CLI passes through verbatim (duplicates rejected server-side as INVALID_PLUGIN_SLUGS)
+  --type <ProductType>               required. Schema enum (`prisma/schema.prisma`) supports `SUBSCRIPTION_PLAN | ONE_SHOT_SKILL`. **v1 CLI policy: accept only ONE_SHOT_SKILL** because the grant path (`entitlement.service.ts` grant() check) hard-rejects other types with "Only ONE_SHOT_SKILL grants supported", and there's no roadmap to introduce SUBSCRIPTION_PLAN products via CLI before an admin UI lands. If that changes, widen this flag — server `createProduct` itself accepts both.
+  [--name "..."]                     optional; convenience flag — folded into product.metadata.name by billing service (Product schema has no name column)
+  [--description "..."]              optional; convenience flag — folded into product.metadata.description
+  [--refund-window-days N]           optional
+  [--refund-prorate-max-days N]      optional
+  [--bundled-plan-id <planId>]       optional; for products that also grant a subscription
+  [--bundled-duration-days N]        optional; required iff --bundled-plan-id given
+  [--revoke-bundled-on-refund true|false]   optional, defaults to billing's default (true)
+  [--metadata <json-string>]         optional, JSON object stored in product.metadata; merged with --name/--description if both supplied (--name/--description take precedence per service:79-82)
+  [--env stage|prod]
+
+POST /api/billing/admin/products
+Body: { productKey, type, pluginSlugs: [...], name?, description?, refundWindowDays?, refundProrateMaxDays?,
+        bundledPlanId?, bundledDurationDays?, revokeBundledOnRefund?, metadata? }
+```
+
+Output (success): the created `Product` row pretty-printed as JSON, plus a one-line summary.
+
+```
+optima-product update
+  --key <productKey>                 required
+  [--refund-window-days N]           optional
+  [--refund-prorate-max-days N]      optional
+  [--bundled-plan-id <planId>]       optional (joint constraint with --bundled-duration-days)
+  [--bundled-duration-days N]        optional
+  [--revoke-bundled-on-refund true|false]   optional
+  [--metadata <json-string>]         optional (full-replace; PATCH endpoint does not merge nested keys)
+  [--env stage|prod]
+
+PATCH /api/billing/admin/products/:key
+```
+
+Note: `productKey`, `type`, and `pluginSlugs` are immutable post-create (not in `UpdateProductInput`). To change plugin membership, create a new Product with a new key.
+
+```
+optima-product add-channel
+  --key <productKey>                 required
+  --provider STRIPE                  required; today only STRIPE supported by this CLI
+                                     (ALIPAY/WECHAT_PAY/AIRWALLEX exist in schema but operator flow differs — no auto-create endpoint per provider)
+  --stripe-price-id <price_xxx>      required; pre-created in Stripe Dashboard. Wire-mapped to body field `externalProductId` (provider-neutral name in billing schema)
+  --price-cents N                    required; MUST be > 0 (server rejects 0/negative with INVALID_PRICE). Should match the Stripe Price's unit_amount — operator's responsibility; billing does NOT call Stripe to verify
+  --currency USD                     required; should match the Stripe Price's currency (also not server-verified against Stripe)
+  [--enabled true|false]             optional; defaults to true (channel goes immediately live). Use `--enabled false` to create a disabled channel (saves a `toggle-channel` round-trip when staging a future launch)
+  [--metadata <json-string>]         optional
+  [--env stage|prod]
+
+POST /api/billing/admin/products/:key/channels
+Body: { provider, externalProductId, priceCents, currency, enabled?, metadata? }
+```
+
+```
+optima-product toggle-channel
+  --key <productKey>                 required
+  --provider STRIPE                  required
+  --enabled true|false               required
+  [--env stage|prod]
+
+PATCH /api/billing/admin/products/:key/channels/:provider
+Body: { enabled }
+```
+
+```
+optima-product show
+  --key <productKey>                 required
+  [--env stage|prod]
+
+GET /api/internal/products/:key
+```
+
+Note on auth: despite the `/api/internal/` path prefix (vs `/api/billing/admin/`), this endpoint still requires a valid service-client M2M token (`extractAnyServiceAuth`, admin-products.ts:138). Same auth flow as the admin routes — no special handling.
+
+Output: bare `Product` row (productKey, type, refund fields, metadata, timestamps). **Does NOT include `productPlugins` or `channels` arrays** — `getProductByKey` in `product.service.ts:234` is a plain `findUnique` with no `include`. For the full picture, operator must also call `optima-entitlement list` (for grants) or query the DB directly for channels/plugins. A follow-up will request billing to add `?include=plugins,channels` or expose a richer admin endpoint — see §7.
+
+### 5.2 `optima-entitlement`
+
+```
+optima-entitlement grant
+  --email <user-email>               required; CLI resolves to userId via user-auth (see §6.2)
+  --product-key <productKey>         required
+  --justification "..."              required; billing returns 400 without it; stored on entitlement.justification (free-text audit)
+  [--yes]                            skip the prod confirmation prompt (see §6.6); no-op on --env stage
+  [--env stage|prod]
+
+POST /api/billing/admin/grant-entitlement
+```
+
+Body: `{ userId, productKey, justification }`. The endpoint hardcodes `source=ADMIN_GRANT`, `priceCents=0`, `currency=USD`, and `grantedBy=<clientId from auth>`. CLI only forwards the three user-supplied fields.
+
+```
+optima-entitlement revoke
+  --email <user-email>               required
+  --product-key <productKey>         required
+  --reason "..."                     required; billing returns 400 without it; stored on entitlement.refundReason
+  [--yes]                            skip the prod confirmation prompt (see §6.6); no-op on --env stage
+  [--env stage|prod]
+
+Internal flow:
+  1. **Fetch** GET /api/billing/admin/entitlements?userId=<resolved> → response shape `{ entitlements: [...] }`. Endpoint returns all statuses (ACTIVE, REFUNDED) — CLI filters client-side.
+  2. **Filter** for status=ACTIVE AND productKey=<arg>.
+  3. **Validate count** — expect exactly 0 or 1 match (DB partial unique `entitlements_one_active` enforces ≤1 ACTIVE per (user, productKey)).
+       0 → exit 1 with "no active entitlement for (user, product)"
+       1 → take entitlementId
+  4. **Validate source** — refuse if source ≠ ADMIN_GRANT.
+       Exit 1 with source-specific message:
+         source=PAYMENT  → "refusing to revoke a PAYMENT-source entitlement via CLI; this would leave the customer charged but unentitled. Use the Stripe refund flow which calls Stripe refund API + records refundedAmountCents + emits webhook. Manual psql is the escape hatch if absolutely necessary."
+         source=PARTNER  → "refusing to revoke a PARTNER-source entitlement via CLI; PARTNER grants are issued out-of-band and must be reversed via the partner contract / process that issued them. Manual psql is the escape hatch if absolutely necessary."
+  5. **Refund** POST /api/billing/admin/refund-entitlement with `{ entitlementId, refundReason }`.
+
+Race window note: between step 1 and step 5 two scenarios are possible:
+- **PAYMENT lands concurrently**: blocked by partial unique index `entitlements_one_active` while the ADMIN_GRANT row is still ACTIVE; can only land after our refund flips status to REFUNDED. No corruption.
+- **Two operators racing concurrent revokes**: both list the same ACTIVE entitlementId in step 1. First refund wins (status → REFUNDED). Second refund hits billing with a stale id; billing's `entSvc.revoke` either no-ops (idempotent on REFUNDED) or returns an error — either way the CLI surfaces it as a clear failure and exits 1.
+
+A future server-side `POST /admin/refund-by-product` (atomic lookup + refund under `FOR UPDATE`) could close both windows, but neither is a real risk for an infrequent admin CLI.
+```
+
+```
+optima-entitlement list
+  --email <user-email>               required
+  [--env stage|prod]
+
+GET /api/billing/admin/entitlements?userId=<resolved>
+```
+
+Response shape: `{ entitlements: Entitlement[] }`. Output: table of entitlements, newest first, columns: `id | productKey | status | source | purchasedAt | refundedAt`.
+
+## 6. Implementation notes
+
+### 6.1 Environment resolution
+
+- **`BILLING_URL`**: read from Infisical at `secretPath=/shared-secrets/domain-urls`. Indirect evidence the secret exists on **stage**: billing's `BILLING_PUBLIC_URL` env is configured as `${staging.shared-secrets.domain-urls.BILLING_URL}` (visible in `optima-show-env billing stage` output) — Infisical resolves the substitution at injection time, so the underlying secret must exist. Direct verification (Universal-Auth fetch of the path itself) and prod-side existence are deferred to T1 — see §10. No existing dev-skills helper reads from `/shared-secrets/domain-urls`, so implementation extends `db-utils` (or adds a sibling helper). Note the env-name mismatch: billing's runtime env var is `BILLING_PUBLIC_URL`, but the Infisical secret name is just `BILLING_URL` — CLI uses the Infisical secret name.
+- **OAuth credentials**: dev-skills client is `clientId=dev-skills-ubd3qz6n` (existing OAuth client, already on billing's `ADMIN_SERVICE_ALLOWLIST` via the `dev-skills-<suffix>` prefix rule). The `client_secret` location in Infisical is **the one blocking open question** (see §10) — T1 of the implementation plan must locate or add it.
+
+### 6.2 Email → userId resolution
+
+Reuse `db-utils.resolveUserId(email, env, infisicalConfig, token)` (4-arg signature, see `bin/helpers/db-utils.ts:169`). Caller must already have `infisicalConfig` + Infisical access token in hand from §6.1's lookup — these are passed through to `resolveUserId`. No new helper code needed.
+
+### 6.3 M2M token acquisition
+
+```ts
+POST {USER_AUTH_URL}/api/v1/oauth/token
+  Content-Type: application/x-www-form-urlencoded
+  Body: grant_type=client_credentials
+        &client_id=dev-skills-ubd3qz6n
+        &client_secret=<secret>
+```
+
+Response: `{ access_token, token_type, expires_in }`. The JWT must contain `type: "service"` claim — billing's `extractAnyServiceAuth` (auth.ts ~340) hard-rejects tokens without it with 403 FORBIDDEN. T1 verifies via a smoke `curl` that user-auth's `client_credentials` grant actually sets this claim (the billing comment at auth.ts ~322 implies it does, but the verify-response shape doesn't carry it back, so the JWT itself must be decoded to confirm).
+
+**Token lifecycle**: the M2M auth module exposes `getServiceToken(env)` which memoizes within the process. Each CLI invocation calls it once at startup, and every HTTP call thereafter reuses the same token — important for multi-call flows like `revoke` (list + refund = 2 calls) or compound smoke tests. **No cross-invocation cache** (every fresh CLI process re-mints) — adequate since token TTLs (typically ≥1 hour) far exceed any single CLI invocation.
+
+### 6.4 Error handling
+
+Billing's dominant envelope is the flat shape `{ error: "CODE_STRING", message: "..." }` (emitted by the global error handler at `src/app.ts:99-118` for all BillingError throws + validation + internal errors — verified during plan R1). A nested shape `{ error: { code, message } }` appears on a few inline returns (e.g. admin-products.ts toggle-channel 400/404). CLI handles both; printed format collapses to:
+
+```
+❌ Error [<HTTP status>] <code>: <message>
+```
+
+and **always exits 1** on any error (auth failure, validation failure, server error, network failure — all collapse to exit 1; matches existing `grant-subscription` etc. precedent). No retries on 4xx; one retry on 5xx (billing already has its own idempotency story for grant via `idempotencyKey`).
+
+**Non-envelope fallback**: if a response is non-2xx but the body isn't valid JSON or lacks the `{error: {code, message}}` shape (e.g. raw 502 from an upstream load balancer, plain-text 500 from a crashed handler before the error middleware runs), CLI prints:
+
+```
+❌ Error [<HTTP status>] <status text>
+   Response body (first 500 bytes): <truncated body>
+```
+
+So operators always see SOMETHING actionable on failure.
+
+### 6.5 Output format
+
+Default: human-readable summary lines + the response object pretty-printed.
+Future: `--json` flag for machine-readable output. **Not in initial scope** — add when first consumer requires it.
+
+### 6.6 Safety rails
+
+- Default `--env stage`. To run against prod, operator must type `--env prod` explicitly.
+- `optima-entitlement revoke` MUST refuse non-`ADMIN_GRANT` sources (`PAYMENT`, `PARTNER`) with a source-specific message (see §5.2). **No `--force` escape** — operator drops to psql if they truly need to bypass (logged + auditable that way). Rationale: PAYMENT revoke via CLI without Stripe-side refund would leave the customer charged but unentitled; PARTNER revoke without partner-process reversal violates the issuance contract — both strictly worse than the manual escape hatch.
+- **prod safety prompt**: when `--env prod`, `grant` and `revoke` print the resolved action (`userId + productKey + source + new status`) and require typing `yes` to confirm. `--yes` flag bypasses the prompt (for scripted ops with prior verification). Stage stays no-prompt for ergonomic iteration. Rationale: typo'd `--email` that happens to match a different real user would silently affect the wrong account; one-time human-in-the-loop is cheap insurance for prod-only operations.
+- `optima-product create` does NOT auto-add a channel. A product without a channel is admin-grant-only; making it self-purchaseable is a deliberate second step.
+
+## 7. Out-of-scope follow-ups
+
+| Item | Why deferred |
+|---|---|
+| `optima-product list` subcommand | Endpoint missing — see [optima-billing#58](https://github.com/Optima-Chat/optima-billing/issues/58). Add CLI side once endpoint ships. |
+| `optima-product show` returning plugins + channels | Endpoint `getProductByKey` is bare `findUnique` with no `include`. File billing issue to add `?include=plugins,channels` or expose `/api/billing/admin/products/:key` (admin-richer view). Until then, `show` returns the bare Product row only. |
+| `optima-entitlement show <id>` | Billing has no fetch-by-id endpoint; list-by-userId is the only path. File billing issue to add `GET /api/billing/admin/entitlements/:id`. Until then, use `optima-entitlement list` and grep by id. |
+| Auto-create Stripe Product+Price | Requires Stripe SDK + per-env Stripe key wiring. Manual Dashboard creation is fine for the small initial paid-plugin catalog. |
+| Non-STRIPE channel providers (ALIPAY, WECHAT_PAY, AIRWALLEX) | Each has its own out-of-band registration flow (or none at all). Add per-provider subcommand only when a real product needs it. |
+| `--json` flag for machine-readable output | Add when first scripted consumer requires it. |
+| Rotation of `dev-skills-ubd3qz6n` OAuth secret | Tracked by Wave 1.5 plan T10 step 8 ([optima-billing#43](https://github.com/Optima-Chat/optima-billing/issues/43)). Independent. |
+| `optima-product delete` subcommand | No `DELETE /api/billing/admin/products/:key` endpoint exists (verified). Wave 1.5 spec §2.7 is append-only — products are never deleted, only channels disabled via `toggle-channel`. Listed here for completeness; not anticipated. |
+| `--verify-sync` flag on grant/revoke (poll skills UserPlugin after) | Nice-to-have closing the cross-service async loop without operator dropping to `optima-query-db`. Low cost (one query). Add when first operator hits the gap. |
+| `optima-product show --with-db-verify` (parallel ProductPlugin + ProductChannel DB queries to fill the gap from bare `getProductByKey`) | Reasonable workaround for the §7 enrichment gap, but adds SSH tunnel + SQL overhead per show. Wait until billing endpoint enriches OR the gap actually bites in practice. |
+| Bulk grant / revoke (e.g. CSV of emails) | YAGNI until a real campaign needs it. |
+| prod billing deploy of Wave 1.5 | Out of this repo's control. CLI is forward-compatible. Prod main reverted via [optima-billing#48](https://github.com/Optima-Chat/optima-billing/pull/48); integration→main PR gated on Wave 1.5 tracker [optima-billing#43](https://github.com/Optima-Chat/optima-billing/issues/43). |
+
+## 8. Testing approach
+
+- **No unit tests** for the HTTP wrapper / arg parsing. Pattern matches existing `grant-subscription` etc.
+- **Stage smoke** is the primary verification:
+  1. `optima-product create --key smoke-cli-1 --plugins skillify --type ONE_SHOT_SKILL --env stage` → 201
+  2. `optima-product show --key smoke-cli-1 --env stage` → returns Product with 1 plugin, 0 channels
+  3. `optima-entitlement grant --email pro.xu.optima@gmail.com --product-key smoke-cli-1 --env stage` → 201
+  4. `optima-entitlement list --email pro.xu.optima@gmail.com --env stage` → includes the new entitlement, status=ACTIVE, source=ADMIN_GRANT
+  5. Verify outbox + skills sync:
+     a. `optima-query-db billing "SELECT id, event_type, status, payload FROM outbox_events WHERE event_type='entitlement.granted' ORDER BY created_at DESC LIMIT 1" stage` → DELIVERED row. (Verify column case at smoke time — billing tables in this area are snake_case `outbox_events.event_type` per Wave 1.5 migrations; column quoting may need adjustment if Prisma generated camelCase columns. Outbox `payload` column may carry a billing-internal envelope rather than the verbatim wire shape; implementer pins the exact field path during T-final smoke.)
+     b. `optima-query-db skills "SELECT up.\"userId\", p.slug FROM \"UserPlugin\" up JOIN \"Plugin\" p ON p.id = up.\"pluginId\" WHERE up.\"userId\"='<resolved>' AND p.slug='skillify'" stage` → exactly 1 row. Skills schema: `UserPlugin` is `(userId, pluginId, installedAt)` with **no status column** (`optima-skills/prisma/schema.prisma:153`); grants `upsert` a row, revokes `deleteMany` it. Post-revoke step 7 asserts the row is absent, not that any status flipped.
+  6. `optima-entitlement revoke --email pro.xu.optima@gmail.com --product-key smoke-cli-1 --env stage` → 200
+  7. `optima-entitlement list --email pro.xu.optima@gmail.com --env stage` → status=REFUNDED, refundedAt set. Also re-run step 5b query → 0 rows (UserPlugin row deleted by skills revoke handler).
+  8. (Optional) `optima-product add-channel --key smoke-cli-1 --provider STRIPE --stripe-price-id <fresh test Price> --price-cents 100 --currency USD --env stage` → 201, then `optima-product show` reflects the channel
+- **Clean up**: leave stage Product rows in place (Wave 1.5 spec §2.7 append-only convention) but disable the test channel via `toggle-channel --enabled false`.
+
+## 9. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Stage Infisical `ADMIN_SERVICE_ALLOWLIST` overridden to not include `dev-skills` | Verified 2026-05-24: not overridden; falls back to default `"sales-page,dev-skills"`. If broken later, the 403 message names the offending clientId for fast diagnosis. |
+| `dev-skills-ubd3qz6n` client secret location in Infisical not yet known | Implementation plan first task is to locate or set up the secret path; spec proceeds. |
+| Operator confuses ADMIN_GRANT for free trial / runs revoke on a PAYMENT or PARTNER entitlement | Revoke refuses non-ADMIN_GRANT source with a source-specific message (§5.2 step 4); grant is explicit (no implicit "free trial" mode). |
+| Typo'd `--email` on prod silently affects wrong real user | §6.6 prod-only confirmation prompt prints resolved userId before action; `--yes` bypass exists for scripted ops with prior verification. |
+| `dev-skills-ubd3qz6n` OAuth client is shared with other test infra (test-token minting, smoke scripts) — concurrent CLI ops + ambient test traffic share the same client's token-mint quota and rate limits | Single-action CLI runs are infrequent enough that contention is unlikely in practice. If hit, error surfaces as user-auth 429/5xx with a clear retry path. Real fix (if it ever bites): mint a dedicated `dev-skills-admin-cli` OAuth client at impl time. Listed here so the trade-off is explicit. |
+| Billing service layer changes break wire contract | CLI calls public admin endpoints; any breaking change to those would be a billing release concern surfaced at call time as a clear HTTP error. |
+| prod usage attempt before Wave 1.5 lands prod | Billing returns 404/500 with clear error; CLI passes it through. Documented in §3 non-goals. |
+
+## 10. Open questions
+
+1. **[BLOCKING for implementation T1]** Where in Infisical does `dev-skills-ubd3qz6n`'s `client_secret` live? Candidates: `/services/dev-skills/CLIENT_SECRET`, `/shared-secrets/oauth/dev-skills/CLIENT_SECRET`, or it may need to be added fresh. T1 of the implementation plan must locate or create this path on both stage AND prod Infisical envs before any HTTP code is written.
+
+2. **[BLOCKING for implementation T1]** Does Infisical's `/shared-secrets/domain-urls/BILLING_URL` exist on **prod**? Verified to exist on stage (billing's own `BILLING_PUBLIC_URL` references it). If prod is missing, T1 also adds it (CLI uses `--env prod` would otherwise fail at URL lookup before reaching billing).
+
+3. **[VERIFY in T1, not blocking design]** Does user-auth's `client_credentials` grant actually mint a JWT with `type: "service"` claim? Inferred from billing's `extractAnyServiceAuth` comments but never observed directly. A 30-second `curl` smoke will confirm.

package/docs/superpowers/specs/2026-05-25-optima-plugin-cli-design.md

@@ -0,0 +1,156 @@
+# optima-plugin CLI — Design Spec
+
+**Status**: draft for review
+**Date**: 2026-05-25
+**Author**: Jerry (via Claude collaborative spec)
+**Repo**: `@optima-chat/dev-skills`
+
+## 1. Purpose
+
+Add the **skills-side admin command that the marketplace-admin-cli ([#11](https://github.com/Optima-Chat/optima-dev-skills/pull/11)) missed**.
+
+The shipped `optima-product` / `optima-entitlement` CLIs manage only the **billing half** of a paid plugin (Product, Channel, Entitlement). But the flag that actually makes a plugin paid/free to users — `Plugin.isPaid` — lives in **optima-skills**, and it is the real access gate:
+
+```ts
+// optima-skills src/routes/plugins.ts:132 (GET /:slug/download-url) + user-plugins.ts:96 (install)
+// NOTE: this gate is on the install/download paths, NOT the plain detail read
+// GET /:slug (line 72) that `show` uses — so `show` is unaffected by isPaid.
+if (plugin.isPaid) {
+  const ok = await hasEntitlement({ userId, pluginId, isPaid: true }); // REAL billing HTTP call
+  if (!ok) throw 402 PAYMENT_REQUIRED  // → plugin.salesUrl (fallback: sales.optima.onl)
+}
+```
+
+(`hasEntitlement` is the real implementation — `entitlement-checker.ts` calls billing's `checkEntitlement` with caching + fail-mode. The stale `// stub for Phase 0` comment at `plugins.ts:128` is outdated; Wave 1.5 wired the real call.)
+
+Because no plugin currently has `isPaid=true` (the Wave 1/1.5 testing sessions exercised billing only, never flipped the skills flag), **every plugin including scout is effectively free regardless of its billing Product**. There is no CLI to flip this. The skills admin endpoint exists and its auth middleware comment explicitly says it is "callable by the dev-skills CLI" — but the command was never built.
+
+`optima-plugin` closes that gap.
+
+## 2. Background — verified facts (2026-05-25)
+
+- **Endpoint**: `PATCH /api/admin/plugins/:slug` (optima-skills `src/routes/admin-plugins.ts:19-31`). **`.strict()`** zod body — accepts ONLY `{ trustLevel?, status?, category?, tags?, readme?, defaultForUser?, isPaid? }`. **`salesUrl` is NOT accepted** (verified: `.strict()` → any extra key incl. `salesUrl` → ZodError 400). `salesUrl` is writable **only at publish time** from `pluginJson.metadata.salesUrl` (`plugin-publish-persister.ts:71`). Returns the full updated Plugin row.
+- **Auth**: `requireAdminService` = `tryM2mAuth` + `requireAdminServiceClient` (`src/middleware/admin-service.ts`). Same model as billing: verified service JWT (`type: "service"`) + clientId on `ADMIN_SERVICE_ALLOWLIST` (default `'sales-page,dev-skills'`, prefix match). **Verified live**: minted a dev-skills M2M token via the existing `billing-http.getServiceToken('stage')` and a no-op `PATCH /api/admin/plugins/scout {}` returned 200 with scout's row. dev-skills token works against skills admin unchanged.
+- **Skills base URL**: Infisical `/shared-secrets/domain-urls/SKILLS_REGISTRY_URL`. Stage = `https://skills.stage.optima.onl` (verified). Prod value to confirm in impl T1 — **note skills IS deployed to prod** (skills.optima.onl, marketplace-v2 Option A), so `--env prod` may actually be functional for plugin commands, unlike `optima-product` (billing prod is pre-Wave-1.5).
+- **Read path**: public `GET /api/plugins/:slug` exposes `{slug, name, description, version, isPaid, salesUrl, category, tags, components, author, updatedAt}` — enough to verify isPaid/salesUrl, but **NOT** `defaultForUser` / `status` / `trustLevel` (no admin GET-single endpoint exists).
+- **Error envelope**: skills uses the **nested** `{error: {code, message}}` shape (e.g. admin-service.ts 401/403). billing's shared `formatBillingError` already handles both nested and flat, so it is reusable as-is for skills responses.
+
+## 3. Non-goals
+
+- **No new auth/token work**: reuse `billing-http.getServiceToken(env)` verbatim (same dev-skills M2M client serves both billing and skills).
+- **No auto-coupling of isPaid ↔ defaultForUser**: operator sets each independently. (A typical free plugin is `isPaid=false, defaultForUser=true`, but the CLI does not enforce or auto-apply that — explicit is safer for an admin tool.)
+- **No general `patch` escape hatch**: only the three scoped verbs below. The skills PATCH also accepts trustLevel/status/category/tags/readme, but those are out of scope (use a future command or psql if ever needed).
+- **No write of `defaultForUser` read-back in `show`**: `show` uses the public GET (no defaultForUser field). Reading defaultForUser back is deferred to a skills follow-up (admin GET-single).
+- **No marketplace re-publish / version management**: that is the existing publish flow's job.
+
+## 4. Architecture
+
+New bin `optima-plugin` → dispatcher → subcommand handlers, mirroring `optima-product`'s structure.
+
+```
+optima-plugin <subcommand> → bin/helpers/plugin.ts (dispatcher)
+                              → bin/helpers/plugin/show.ts
+                              → bin/helpers/plugin/set-paid.ts
+                              → bin/helpers/plugin/set-default.ts
+```
+
+**Shared HTTP refactor** (low-risk, on freshly-shipped code): generalize `billing-http.ts`'s call core so both billing and skills reuse the fetch + 5xx-retry + envelope-format + token logic.
+
+- Extract the existing `callBilling` body into a private `callService(baseUrl, env, method, path, body?)` that takes a resolved base URL. **The `getServiceToken(env)` mint moves INTO `callService`** (currently inside `callBilling`); the 5xx single-retry + non-JSON-2xx guard move verbatim too.
+- `callBilling(env, method, path, body?)` → `callService(getBillingUrl(env), env, ...)` (unchanged behavior + signature — billing path stays byte-identical).
+- Add `getSkillsUrl(env)` (Infisical `SKILLS_REGISTRY_URL`, memoized like `getBillingUrl`) + `callSkills(env, method, path, body?)` → `callService(getSkillsUrl(env), env, ...)`.
+- `getServiceToken`, `formatBillingError` (rename → `formatServiceError`, keep behavior), caches: shared. **Genericize the one hardcoded string** `"Billing returned non-JSON 2xx body"` → `"Service returned non-JSON 2xx body"` (it now also covers skills).
+
+Reuse unchanged: `confirmIfProd` (prod prompt), `validateEnv` (stage|prod gate), `fetchInfisicalSecret`.
+
+## 5. Command surface
+
+All commands: `--env stage|prod` (default `stage`), `-h`/`--help`, validated via `validateEnv` at entry.
+
+### 5.1 `optima-plugin show`
+
+```
+optima-plugin show --slug <slug> [--env stage|prod]
+
+GET /api/plugins/:slug   (public; no auth needed but token injection is harmless)
+```
+
+Output: pretty-printed `{slug, name, version, isPaid, salesUrl, category, tags, ...}`. **Does NOT include defaultForUser / status / trustLevel** — public endpoint omits them (documented gap; skills follow-up to add admin GET-single). One-line note printed when shown.
+
+**Limitation**: `GET /api/plugins/:slug` returns 404 for non-ACTIVE plugins (`plugins.ts:78` rejects `status !== 'ACTIVE'`). `show` therefore only works for ACTIVE plugins; a BETA/DEPRECATED plugin surfaces as `404 NOT_FOUND`. Acceptable — scout/skillify are ACTIVE. (The same admin GET-single follow-up in §7 would lift this.)
+
+### 5.2 `optima-plugin set-paid`
+
+```
+optima-plugin set-paid --slug <slug> --paid true|false [--env stage|prod] [--yes]
+
+PATCH /api/admin/plugins/:slug
+Body: { isPaid: <bool> }
+```
+
+- `--paid` required (`true`|`false`); maps to `isPaid`.
+- **No `--sales-url` flag** — the skills PATCH `.strict()` schema rejects `salesUrl` (§2). salesUrl is publish-time-only (`metadata.salesUrl`). When `--paid true` and the plugin's salesUrl is null, the 402 falls back to `sales.optima.onl`. Setting a custom sales page requires either a re-publish with `metadata.salesUrl`, or a skills follow-up to add `salesUrl` to patchSchema (§7). **Reminder printed** on `--paid true`: "ensure a billing Product + channel exists (optima-product) or users will 402 with no purchase path; salesUrl is publish-time-only."
+- prod confirm prompt (resolved action: slug + isPaid + env), `--yes` bypass.
+- Output: pretty-print the returned updated Plugin row (skills PATCH returns full row incl isPaid, salesUrl, defaultForUser).
+
+### 5.3 `optima-plugin set-default`
+
+```
+optima-plugin set-default --slug <slug> --default true|false
+                          [--env stage|prod] [--yes]
+
+PATCH /api/admin/plugins/:slug
+Body: { defaultForUser: <bool> }
+```
+
+- `--default` required (`true`|`false`); maps to `defaultForUser`.
+- prod confirm prompt, `--yes` bypass.
+- Output: pretty-print returned row.
+- **Note**: the PATCH is a plain `prisma.plugin.update` with no skill-sync broadcast (matches the rollback handler's documented Phase 0 behavior). Flipping `defaultForUser` changes what NEW user syncs receive; it does not retroactively push/remove the plugin for existing users until their next session/sync boundary.
+
+## 6. Implementation notes
+
+- **Token**: `getServiceToken(env)` reused. Skills admin uses the same dev-skills client (stage `dev-skills-ubd3qz6n`, prod `dev-skills-hinxa0rs`) already on skills' `ADMIN_SERVICE_ALLOWLIST` (default includes `dev-skills`).
+- **Error handling**: `callSkills` reuses the shared `formatServiceError` → `❌ Error [<status>] <code>: <message>`, non-envelope fallback for non-JSON. Exit 1 on any error (matches house convention).
+- **404 on unknown slug**: skills returns 404 `{error:{code:'NOT_FOUND',...}}` (`Errors.notFound('Plugin')`). Surfaces via formatter.
+- **`show` token**: public endpoint needs no auth; `callSkills` injects the Bearer anyway (harmless). Keeps one code path.
+- **prod**: unlike `optima-product`, `--env prod` for `optima-plugin` may be functional (skills prod is live). T1 confirms prod `SKILLS_REGISTRY_URL` + prod dev-skills client on prod skills allowlist.
+
+## 7. Out-of-scope follow-ups
+
+| Item | Why deferred |
+|---|---|
+| skills `GET /api/admin/plugins/:slug` (admin read with defaultForUser/status/trustLevel, any status) | No admin GET-single exists; public GET is ACTIVE-only + omits admin fields. File optima-skills issue. Until then `show` reads the public listing (isPaid/salesUrl, ACTIVE-only). |
+| skills patchSchema: add `salesUrl` (so `set-paid --sales-url` becomes possible) | Currently salesUrl is publish-time-only; `.strict()` PATCH rejects it. If operators need to set custom sales pages without re-publishing, file an optima-skills issue to add `salesUrl: z.string().nullable().optional()` to patchSchema, then add `--sales-url` to set-paid. |
+| `optima-plugin` verbs for trustLevel/status/category/tags/readme | PATCH supports them but no current need. Add when required. |
+| Auto-set `defaultForUser=true` when making a plugin free | Deliberate non-goal — operator controls independently (§3). |
+
+## 8. Testing approach
+
+Smoke-only (matches all existing dev-skills helpers; no unit tests).
+
+Stage smoke (use `scout` — the real plugin we want paid, and `skillify` — should stay free):
+
+1. `optima-plugin show --slug scout --env stage` → isPaid=false, salesUrl=null (current state)
+2. `optima-plugin set-paid --slug scout --paid true --env stage` → 200, returned row isPaid=true (salesUrl stays whatever publish set — likely null; 402 falls back to sales.optima.onl)
+3. `optima-plugin show --slug scout --env stage` → isPaid=true reflected
+4. `optima-plugin set-default --slug scout --default false --env stage` → 200, returned row defaultForUser=false (verify via the returned PATCH body since show can't read it)
+5. `optima-plugin set-paid --slug skillify --paid false --env stage` → 200, isPaid=false (confirms idempotent / skillify stays free)
+6. Negative: `optima-plugin set-paid --slug nonexistent-xyz --paid true --env stage` → exit 1, 404 NOT_FOUND surfaced cleanly
+
+**State note**: this smoke deliberately flips real stage plugin state (scout → paid). That is the intended end state per the operator's goal, not throwaway test data — leave scout paid after smoke (or coordinate with the separate "make scout paid" task). skillify set-paid false is a no-op (already false).
+
+## 9. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Shared HTTP refactor breaks the just-shipped billing path | `callBilling` keeps its exact signature + behavior (delegates to `callService` with billing URL). Smoke billing once post-refactor (`optima-entitlement list`) to confirm no regression. |
+| skills prod allowlist missing dev-skills | T1 verifies; default includes `dev-skills` so likely fine. 403 message names the client if not. |
+| `show` can't display defaultForUser | Documented; `set-default` output (returned PATCH row) is the read-back path until the admin GET-single follow-up lands. |
+| Operator flips isPaid=true but no billing Product/channel exists → users hit 402 with no way to buy | Out of CLI's enforcement scope, but `set-paid --paid true` prints a reminder: "ensure a billing Product + channel exists (optima-product) or users will 402 with no purchase path." |
+
+## 10. Open questions
+
+1. **[T1]** prod `SKILLS_REGISTRY_URL` value + prod dev-skills client (`dev-skills-hinxa0rs`) on prod skills `ADMIN_SERVICE_ALLOWLIST`?
+
+(Resolved during spec review: public `GET /api/plugins/:slug` rejects non-ACTIVE plugins with 404 — `plugins.ts:78`. `show` is ACTIVE-only; documented in §5.1. `salesUrl` is not PATCH-settable — `set-paid` drops `--sales-url`; documented in §2/§5.2/§7.)

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.7.33",
+  "version": "0.7.36",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
     "optima-dev-skills": "bin/cli.js",
-    "optima-query-db": "dist/bin/helpers/query-db.js",
+    "optima-entitlement": "dist/bin/helpers/entitlement.js",
     "optima-generate-test-token": "dist/bin/helpers/generate-test-token.js",
-    "optima-show-env": "dist/bin/helpers/show-env.js",
+    "optima-grant-balance": "dist/bin/helpers/grant-balance.js",
     "optima-grant-subscription": "dist/bin/helpers/grant-subscription.js",
-    "optima-grant-balance": "dist/bin/helpers/grant-balance.js"
+    "optima-plugin": "dist/bin/helpers/plugin.js",
+    "optima-product": "dist/bin/helpers/product.js",
+    "optima-query-db": "dist/bin/helpers/query-db.js",
+    "optima-show-env": "dist/bin/helpers/show-env.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",
@@ -36,7 +39,7 @@
   },
   "homepage": "https://github.com/Optima-Chat/optima-dev-skills#readme",
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     ".claude",