@optima-chat/dev-skills 0.7.35 → 0.7.37

package/.claude/skills/discount-codes/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "discount-codes"
+description: "当用户请求创建优惠码、发优惠码、生成折扣码、promo code、discount code、批量生成优惠码、停用优惠码、查看优惠码时，使用此技能。支持 Stage、Prod 两个环境。"
+allowed-tools: ["Bash"]
+---
+
+# 优惠码管理
+
+为 billing 结账（技能包 / 会员）创建和管理百分比优惠码。
+
+## 执行方式：使用 CLI 工具
+
+无论用户用 `/discount-codes` 还是直接请求，都使用 `optima-discount` CLI（thin HTTP client，调 billing admin 端点）：
+
+```bash
+optima-discount <subcommand> [options]
+```
+
+## 子命令
+
+```bash
+# 建共享码：LAUNCH20 = 8 折，限 scout，6/30 截止，最多核销 100 次
+optima-discount create   --code LAUNCH20 --percent 20 --products scout --ends 2026-06-30 --max 100 --env prod
+
+# 批量唯一码（每码用一次）—— 码写入本地文件，不打屏
+optima-discount generate --count 100 --percent 50 --campaign partner-q3 --products scout --env prod
+#   → ./discount-codes-partner-q3-<ts>.txt
+
+# 查看（按 campaign / code 过滤）
+optima-discount list     --campaign partner-q3 --env prod
+
+# 停用
+optima-discount disable  --code LAUNCH20 --env prod
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--code` | 优惠码（存为大写） |
+| `--percent` | 折扣百分比 1-100 |
+| `--products` | 逗号分隔的 productKey；省略 = 所有商品 |
+| `--starts` / `--ends` | 有效期（`YYYY-MM-DD` 或 ISO datetime） |
+| `--max` | 总核销上限（省略 = 不限；`1` = 一次性） |
+| `--campaign` | 分组标签（generate 时也是码前缀） |
+| `--count` | generate 生成数量 1-1000 |
+| `--limit` | list 返回上限（默认 500，最大 1000） |
+| `--env` | `stage` / `prod`（默认 `stage`） |
+| `--yes` | 跳过 prod 二次确认 |
+
+## 安全提醒
+
+1. **Stage 优先**：默认 `stage`。
+2. **Prod 谨慎**：`create` / `generate` / `disable` 在 prod 会要求输入 "yes" 确认（`--yes` 跳过）。
+3. **唯一码写文件**：`generate` 的码写入当前目录文件（`mode 0600`），不打屏——避免复制时被终端 padding 破坏。
+4. 依赖 billing 已部署对应环境（admin 端点存在）。越界值（如 `--percent 0`）由 billing 服务端校验返 400。
+
+## 相关
+
+- `optima-product` — 管理付费商品（优惠码作用于其结账）
+- `optima-query-db` — 查 `discount_codes` / `discount_redemptions` 表核对

package/AGENTS.md

@@ -13,6 +13,7 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-grant-balance <email> --amount <usd> [options]`
 - `optima-product <create|update|add-channel|toggle-channel|show> [options]` — manage paid-plugin marketplace Products + Stripe channels (Wave 1.5 admin endpoints; stage default)
 - `optima-entitlement <grant|revoke|list> [options]` — admin-grant / revoke / list paid-plugin entitlements (refuses revoke of PAYMENT / PARTNER source)
+- `optima-plugin <show|set-paid|set-default> [options]` — flip a plugin's skills-side paid/free state (isPaid) + defaultForUser (the user-facing gate; pairs with optima-product for the billing side)
 
 For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
 

package/README.md

@@ -42,6 +42,7 @@ Optima Dev Skills 让 Claude Code 能够直接在 **CI、Stage、Prod** 三个
 - **generate-test-token** - 生成测试 Access Token 用于 API 测试
 - **use-commerce-cli** - 使用 Commerce CLI 管理电商店铺
 - **read-code** - 阅读 Optima-Chat 组织下任意仓库的代码
+- **discount-codes** - 创建/生成/查看/停用 billing 优惠码（Stage/Prod）
 
 ## 👤 用户故事
 
@@ -103,6 +104,7 @@ Claude:
 | `optima-query-db` | 数据库查询工具 | `optima-query-db user-auth "SELECT COUNT(*) FROM users" prod` |
 | `optima-show-env` | 查看服务环境变量 | `optima-show-env commerce-backend stage --filter DATABASE` |
 | `optima-generate-test-token` | 生成测试 token | `optima-generate-test-token --business-name "测试店铺"` |
+| `optima-discount` | 优惠码管理 | `optima-discount create --code LAUNCH20 --percent 20 --env stage` |
 
 **特点**：
 - ✅ 支持 CI、Stage、Prod 三个环境（query-db）

package/bin/helpers/billing-http.ts

@@ -43,6 +43,7 @@ const DEV_SKILLS_CLIENT_SECRET_KEY = 'DEV_SKILLS_OAUTH_CLIENT_SECRET';
 //     retry; any transient failure surfaces immediately. Re-run the CLI.
 const tokenCache: Record<string, string> = {};
 const billingUrlCache: Record<string, string> = {};
+const skillsUrlCache: Record<string, string> = {};
 
 function getBillingUrl(env: string): string {
   if (billingUrlCache[env]) return billingUrlCache[env];
@@ -51,6 +52,13 @@ function getBillingUrl(env: string): string {
   return url;
 }
 
+function getSkillsUrl(env: string): string {
+  if (skillsUrlCache[env]) return skillsUrlCache[env];
+  const url = fetchInfisicalSecret(env, '/shared-secrets/domain-urls', 'SKILLS_REGISTRY_URL');
+  skillsUrlCache[env] = url;
+  return url;
+}
+
 export function getServiceToken(env: string): string {
   if (tokenCache[env]) return tokenCache[env];
 
@@ -89,7 +97,7 @@ interface BillingErrorEnvelope {
   code?: string;
 }
 
-function formatBillingError(status: number, statusText: string, body: string): string {
+function formatServiceError(status: number, statusText: string, body: string): string {
   let parsed: BillingErrorEnvelope | null = null;
   try { parsed = JSON.parse(body); } catch { /* non-JSON */ }
 
@@ -114,24 +122,25 @@ function formatBillingError(status: number, statusText: string, body: string): s
   return `❌ Error [${status}] ${statusText}\n   Response body (first 500 bytes): ${body.slice(0, 500)}`;
 }
 
-// ───── Public: callBilling ──────────────────────────────────────────────────
-export interface BillingResponse<T> {
+// ───── Public: callService / callBilling / callSkills ───────────────────────
+export interface ServiceResponse<T> {
   status: number;
   body: T;
 }
 
 /**
- * Make an authenticated call to optima-billing. Returns `{status, body}` on
- * 2xx; throws Error with formatted message on non-2xx. Single retry on 5xx
- * (one-shot — no exponential backoff; admin CLI doesn't justify it).
+ * Authenticated call to an Optima service (billing or skills — same dev-skills
+ * M2M token works for both). Returns `{status, body}` on 2xx; throws Error with
+ * formatted message on non-2xx. Single retry on 5xx (no backoff — admin CLI).
  */
-export async function callBilling<T = unknown>(
+async function callService<T>(
+  baseUrl: string,
   env: string,
   method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
   path: string,
   body?: object,
-): Promise<BillingResponse<T>> {
-  const url = `${getBillingUrl(env)}${path}`;
+): Promise<ServiceResponse<T>> {
+  const url = `${baseUrl}${path}`;
   const token = getServiceToken(env);
 
   const doFetch = async () => fetch(url, {
@@ -145,18 +154,38 @@ export async function callBilling<T = unknown>(
 
   let res = await doFetch();
   if (res.status >= 500) {
-    // One retry on 5xx
     res = await doFetch();
   }
   const text = await res.text();
   if (!res.ok) {
-    throw new Error(formatBillingError(res.status, res.statusText, text));
+    throw new Error(formatServiceError(res.status, res.statusText, text));
   }
   let parsed: T;
   try {
     parsed = text ? (JSON.parse(text) as T) : (undefined as unknown as T);
   } catch {
-    throw new Error(`Billing returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+    throw new Error(`Service returned non-JSON 2xx body: ${text.slice(0, 200)}`);
   }
   return { status: res.status, body: parsed };
 }
+
+/** Kept as an alias for billing-side callers that reference the response type. */
+export interface BillingResponse<T> extends ServiceResponse<T> {}
+
+export async function callBilling<T = unknown>(
+  env: string,
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: object,
+): Promise<ServiceResponse<T>> {
+  return callService<T>(getBillingUrl(env), env, method, path, body);
+}
+
+export async function callSkills<T = unknown>(
+  env: string,
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: object,
+): Promise<ServiceResponse<T>> {
+  return callService<T>(getSkillsUrl(env), env, method, path, body);
+}

package/bin/helpers/discount/create.ts

@@ -0,0 +1,79 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface CreateArgs {
+  code: string;
+  percentOff: number;
+  productKeys?: string[];
+  startsAt?: string;
+  endsAt?: string;
+  maxRedemptions?: number;
+  campaign?: string;
+  env: string;
+  yes: boolean;
+}
+
+/** Normalize a date/datetime arg to a full ISO datetime string (billing requires z.iso.datetime). */
+function toIso(v: string): string {
+  const d = new Date(v);
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${v} (use YYYY-MM-DD or ISO datetime)`);
+  return d.toISOString();
+}
+
+function parseArgs(argv: string[]): CreateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount create --code <CODE> --percent <1-100> [options]
+
+Required:
+  --code <CODE>            Promo code (stored uppercased)
+  --percent <1-100>        Percentage off
+
+Optional:
+  --products <a,b,...>     Limit to these productKeys (default: all)
+  --starts <date>          Valid-from (YYYY-MM-DD or ISO; default: immediately)
+  --ends <date>            Valid-until
+  --max <N>                Max total redemptions (default: unlimited; 1 = single-use)
+  --campaign <label>       Grouping label
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<CreateArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--code': out.code = next; i++; break;
+      case '--percent': out.percentOff = parseInt(next, 10); i++; break;
+      case '--products': if (!next) throw new Error('--products requires a value'); out.productKeys = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--starts': out.startsAt = toIso(next); i++; break;
+      case '--ends': out.endsAt = toIso(next); i++; break;
+      case '--max': out.maxRedemptions = parseInt(next, 10); i++; break;
+      case '--campaign': out.campaign = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.code) throw new Error('--code required');
+  if (out.percentOff === undefined || isNaN(out.percentOff)) throw new Error('--percent required (1-100)');
+  return out as CreateArgs;
+}
+
+export async function runCreate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Create discount code ${args.code.toUpperCase()} (${args.percentOff}% off)`, args.yes);
+
+  const body: Record<string, unknown> = { code: args.code, percentOff: args.percentOff };
+  if (args.productKeys) body.productKeys = args.productKeys;
+  if (args.startsAt) body.startsAt = args.startsAt;
+  if (args.endsAt) body.endsAt = args.endsAt;
+  if (args.maxRedemptions !== undefined) body.maxRedemptions = args.maxRedemptions;
+  if (args.campaign) body.campaign = args.campaign;
+
+  console.log(`\n🎟️  Creating discount code on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/discount-codes', body);
+  console.log(`✓ Created (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount/disable.ts

@@ -0,0 +1,44 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface DisableArgs {
+  code: string;
+  env: string;
+  yes: boolean;
+}
+
+function parseArgs(argv: string[]): DisableArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount disable --code <CODE> [options]
+
+Required:
+  --code <CODE>
+
+Optional:
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<DisableArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--code': out.code = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.code) throw new Error('--code required');
+  return out as DisableArgs;
+}
+
+export async function runDisable(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Disable discount code ${args.code.toUpperCase()}`, args.yes);
+  const res = await callBilling(args.env, 'PATCH', `/api/billing/admin/discount-codes/${encodeURIComponent(args.code)}`, { status: 'DISABLED' });
+  console.log(`✓ Disabled (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount/generate.ts

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface GenArgs {
+  count: number;
+  percentOff: number;
+  campaign: string;
+  productKeys?: string[];
+  startsAt?: string;
+  endsAt?: string;
+  env: string;
+  yes: boolean;
+}
+
+function toIso(v: string): string {
+  const d = new Date(v);
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${v} (use YYYY-MM-DD or ISO datetime)`);
+  return d.toISOString();
+}
+
+function parseArgs(argv: string[]): GenArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount generate --count <N> --percent <1-100> --campaign <label> [options]
+
+Generates N unique single-use codes (maxRedemptions=1). Codes are written to a
+local file (NOT printed) to keep them copy-paste clean.
+
+Required:
+  --count <N>              How many codes (1-1000)
+  --percent <1-100>        Percentage off
+  --campaign <label>       Grouping label (also the code prefix)
+
+Optional:
+  --products <a,b,...>     Limit to these productKeys
+  --starts <date>          Valid-from (YYYY-MM-DD or ISO)
+  --ends <date>            Valid-until
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<GenArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--count': out.count = parseInt(next, 10); i++; break;
+      case '--percent': out.percentOff = parseInt(next, 10); i++; break;
+      case '--campaign': out.campaign = next; i++; break;
+      case '--products': if (!next) throw new Error('--products requires a value'); out.productKeys = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--starts': out.startsAt = toIso(next); i++; break;
+      case '--ends': out.endsAt = toIso(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (out.count === undefined || isNaN(out.count)) throw new Error('--count required (1-1000)');
+  if (out.percentOff === undefined || isNaN(out.percentOff)) throw new Error('--percent required (1-100)');
+  if (!out.campaign) throw new Error('--campaign required');
+  return out as GenArgs;
+}
+
+export async function runGenerate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Generate ${args.count} unique discount codes (${args.percentOff}% off, campaign ${args.campaign})`, args.yes);
+
+  const body: Record<string, unknown> = { count: args.count, percentOff: args.percentOff, campaign: args.campaign };
+  if (args.productKeys) body.productKeys = args.productKeys;
+  if (args.startsAt) body.startsAt = args.startsAt;
+  if (args.endsAt) body.endsAt = args.endsAt;
+
+  console.log(`\n🎟️  Generating ${args.count} codes on ${args.env.toUpperCase()}...`);
+  const res = await callBilling<{ codes: string[] }>(args.env, 'POST', '/api/billing/admin/discount-codes/batch', body);
+  const codes = res.body.codes ?? [];
+
+  const safeCampaign = args.campaign.replace(/[^A-Za-z0-9_-]/g, '');
+  const file = `./discount-codes-${safeCampaign}-${Date.now()}.txt`;
+  // mode 0o600: single-use codes are sensitive-ish; written to the operator's CWD.
+  fs.writeFileSync(file, codes.join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });
+  console.log(`✓ Generated ${codes.length} codes (HTTP ${res.status}). Written to: ${file}`);
+  console.log(`  (codes are in the file, not printed, to keep them copy-paste clean)`);
+}

package/bin/helpers/discount/list.ts

@@ -0,0 +1,46 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ListArgs {
+  campaign?: string;
+  code?: string;
+  limit?: number;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ListArgs {
+  if (argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount list [options]
+
+Optional:
+  --campaign <label>       Filter by campaign
+  --code <CODE>            Filter by exact code
+  --limit <N>              Max rows (default 500, max 1000)
+  --env stage|prod         (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<ListArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--campaign': out.campaign = next; i++; break;
+      case '--code': out.code = next; i++; break;
+      case '--limit': { const n = parseInt(next, 10); if (isNaN(n)) throw new Error('--limit requires a number'); out.limit = n; i++; break; }
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  return out as ListArgs;
+}
+
+export async function runList(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const qs = new URLSearchParams();
+  if (args.campaign) qs.set('campaign', args.campaign);
+  if (args.code) qs.set('code', args.code);
+  if (args.limit !== undefined) qs.set('limit', String(args.limit));
+  const suffix = qs.toString() ? `?${qs.toString()}` : '';
+  const res = await callBilling(args.env, 'GET', `/api/billing/admin/discount-codes${suffix}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { runCreate } from './discount/create';
+import { runGenerate } from './discount/generate';
+import { runList } from './discount/list';
+import { runDisable } from './discount/disable';
+
+function printHelp() {
+  console.log(`Usage: optima-discount <subcommand> [options]
+
+Subcommands:
+  create     Create one discount code (shared or single-use)
+  generate   Generate N unique single-use codes (written to a file)
+  list       List discount codes (filter by campaign/code)
+  disable    Disable a discount code
+
+Run 'optima-discount <subcommand> --help' for subcommand-specific options.`);
+}
+
+async function main() {
+  const [, , subcommand, ...rest] = process.argv;
+  if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+    printHelp();
+    process.exit(0);
+  }
+  switch (subcommand) {
+    case 'create': await runCreate(rest); break;
+    case 'generate': await runGenerate(rest); break;
+    case 'list': await runList(rest); break;
+    case 'disable': await runDisable(rest); break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/bin/helpers/plugin/set-default.ts

@@ -0,0 +1,65 @@
+import { callSkills, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface SetDefaultArgs {
+  slug: string;
+  default: boolean;
+  yes: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): SetDefaultArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin set-default --slug <slug> --default true|false [options]
+
+Required:
+  --slug <slug>
+  --default true|false   Sets Plugin.defaultForUser
+
+Optional:
+  --yes                  Skip prod confirmation prompt (no-op on stage)
+  --env stage|prod       (default: stage)
+
+Note: no skill-sync broadcast — changes what NEW user syncs receive; does not
+retroactively add/remove the plugin for existing users until their next sync.`);
+    process.exit(0);
+  }
+  const out: Partial<SetDefaultArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--default':
+        if (next !== 'true' && next !== 'false') throw new Error('--default must be true or false');
+        out.default = next === 'true'; i++; break;
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  if (out.default === undefined) throw new Error('--default required (true|false)');
+  return out as SetDefaultArgs;
+}
+
+export async function runSetDefault(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  await confirmIfProd(
+    args.env,
+    `Action: set defaultForUser=${args.default} on plugin '${args.slug}' (${args.env.toUpperCase()})`,
+    args.yes,
+  );
+
+  console.log(`\n🔧 Setting defaultForUser=${args.default} on ${args.slug} (${args.env.toUpperCase()})...`);
+  const res = await callSkills(
+    args.env,
+    'PATCH',
+    `/api/admin/plugins/${encodeURIComponent(args.slug)}`,
+    { defaultForUser: args.default },
+  );
+  console.log(`✓ Updated plugin (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/plugin/set-paid.ts

@@ -0,0 +1,69 @@
+import { callSkills, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface SetPaidArgs {
+  slug: string;
+  paid: boolean;
+  yes: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): SetPaidArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin set-paid --slug <slug> --paid true|false [options]
+
+Required:
+  --slug <slug>
+  --paid true|false    Sets Plugin.isPaid (the user-facing paid/free gate)
+
+Optional:
+  --yes                Skip prod confirmation prompt (no-op on stage)
+  --env stage|prod     (default: stage)
+
+Note: salesUrl is NOT settable here (skills PATCH is strict; salesUrl is
+publish-time-only via plugin.json metadata). When isPaid=true and salesUrl is
+null, the 402 falls back to sales.optima.onl.`);
+    process.exit(0);
+  }
+  const out: Partial<SetPaidArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--paid':
+        if (next !== 'true' && next !== 'false') throw new Error('--paid must be true or false');
+        out.paid = next === 'true'; i++; break;
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  if (out.paid === undefined) throw new Error('--paid required (true|false)');
+  return out as SetPaidArgs;
+}
+
+export async function runSetPaid(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  await confirmIfProd(
+    args.env,
+    `Action: set isPaid=${args.paid} on plugin '${args.slug}' (${args.env.toUpperCase()})`,
+    args.yes,
+  );
+
+  console.log(`\n💰 Setting isPaid=${args.paid} on ${args.slug} (${args.env.toUpperCase()})...`);
+  const res = await callSkills(
+    args.env,
+    'PATCH',
+    `/api/admin/plugins/${encodeURIComponent(args.slug)}`,
+    { isPaid: args.paid },
+  );
+  console.log(`✓ Updated plugin (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+  if (args.paid) {
+    console.log(`\nℹ️  Reminder: ensure a billing Product + channel exists for '${args.slug}' (optima-product) or users will 402 with no purchase path. salesUrl is publish-time-only (currently shown above).`);
+  }
+}

package/bin/helpers/plugin/show.ts

@@ -0,0 +1,42 @@
+import { callSkills, validateEnv } from '../billing-http';
+
+interface ShowArgs {
+  slug: string;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ShowArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin show --slug <slug> [options]
+
+Required:
+  --slug <slug>
+
+Optional:
+  --env stage|prod   (default: stage)
+
+Note: reads the public GET /api/plugins/:slug — shows isPaid, salesUrl, and
+descriptive fields, but NOT defaultForUser / status / trustLevel (public
+endpoint omits them). Returns 404 for non-ACTIVE plugins.`);
+    process.exit(0);
+  }
+  const out: Partial<ShowArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  return out as ShowArgs;
+}
+
+export async function runShow(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const res = await callSkills(args.env, 'GET', `/api/plugins/${encodeURIComponent(args.slug)}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}