@optima-chat/dev-skills 0.7.33 → 0.7.35

package/AGENTS.md

@@ -11,6 +11,8 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-generate-test-token [options]`
 - `optima-grant-subscription <email> [options]`
 - `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)
 
 For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
 

package/bin/helpers/billing-http.ts

@@ -0,0 +1,162 @@
+import { execSync } from 'child_process';
+import { fetchInfisicalSecret } from './infisical-secrets';
+import { getInfisicalConfig, getInfisicalToken } from './db-utils';
+
+const USER_AUTH_URLS: Record<string, string> = {
+  stage: 'https://auth.stage.optima.onl',
+  prod: 'https://auth.optima.onl',
+};
+
+/**
+ * Validate the --env flag value at command entry, before any I/O.
+ *
+ * Without this, a typo like `--env staging` flows downstream and surfaces as
+ * a confusing error: entitlement subcommands hit resolveUserId first (SSH
+ * tunnel to RDS_HOSTS[undefined] → cryptic ssh failure), product subcommands
+ * reach getServiceToken (USER_AUTH_URLS[undefined] → "Unknown env"). All
+ * fail-closed (no wrong-env write), but the UX diverges per subcommand.
+ * Every runX handler calls this first so the error is uniform and immediate.
+ */
+export function validateEnv(env: string): 'stage' | 'prod' {
+  if (env !== 'stage' && env !== 'prod') {
+    throw new Error(`--env must be "stage" or "prod" (got: ${env})`);
+  }
+  return env;
+}
+
+// T1 discovered: client_id differs per env (stage=dev-skills-ubd3qz6n,
+// prod=dev-skills-hinxa0rs). Both stored in Infisical alongside the
+// secret at /shared-secrets/oauth-clients/.
+const DEV_SKILLS_OAUTH_PATH = '/shared-secrets/oauth-clients';
+const DEV_SKILLS_CLIENT_ID_KEY = 'DEV_SKILLS_OAUTH_CLIENT_ID';
+const DEV_SKILLS_CLIENT_SECRET_KEY = 'DEV_SKILLS_OAUTH_CLIENT_SECRET';
+
+// ───── Cache (process-lifetime) ─────────────────────────────────────────────
+// One CLI invocation does at most a handful of HTTP calls. We mint the M2M
+// token once and reuse it. Cross-invocation re-mint is fine — JWT TTL is
+// typically ≥1h, far longer than any single CLI run.
+//
+// NOT handled (acceptable for admin CLI):
+//   * Token expiry mid-invocation — a long-stalled revoke (list call + 5min
+//     pause + refund call) could in theory expire. Operator can retry.
+//   * Infisical 5xx retry — getInfisicalToken is sync execSync curl with no
+//     retry; any transient failure surfaces immediately. Re-run the CLI.
+const tokenCache: Record<string, string> = {};
+const billingUrlCache: Record<string, string> = {};
+
+function getBillingUrl(env: string): string {
+  if (billingUrlCache[env]) return billingUrlCache[env];
+  const url = fetchInfisicalSecret(env, '/shared-secrets/domain-urls', 'BILLING_URL');
+  billingUrlCache[env] = url;
+  return url;
+}
+
+export function getServiceToken(env: string): string {
+  if (tokenCache[env]) return tokenCache[env];
+
+  const cfg = getInfisicalConfig();
+  const tok = getInfisicalToken(cfg);
+  // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
+  const clientId = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_ID_KEY, cfg, tok);
+  const clientSecret = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_SECRET_KEY, cfg, tok);
+
+  const authUrl = USER_AUTH_URLS[env];
+  if (!authUrl) throw new Error(`Unknown env: ${env}`);
+
+  const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}`;
+  const response = execSync(
+    `curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`,
+    { encoding: 'utf-8' },
+  );
+
+  let parsed: { access_token?: string; error?: string };
+  try {
+    parsed = JSON.parse(response);
+  } catch {
+    throw new Error(`user-auth token endpoint returned non-JSON (${env}): ${response.slice(0, 200)}`);
+  }
+  if (!parsed.access_token) {
+    throw new Error(`user-auth token mint failed (${env}): ${response.slice(0, 200)}`);
+  }
+  tokenCache[env] = parsed.access_token;
+  return parsed.access_token;
+}
+
+// ───── Error envelope ───────────────────────────────────────────────────────
+interface BillingErrorEnvelope {
+  error?: { code?: string; message?: string } | string;
+  message?: string;
+  code?: string;
+}
+
+function formatBillingError(status: number, statusText: string, body: string): string {
+  let parsed: BillingErrorEnvelope | null = null;
+  try { parsed = JSON.parse(body); } catch { /* non-JSON */ }
+
+  // Dominant Wave 1.5 envelope: flat { error: "CODE_STRING", message: "..." }
+  // emitted by billing's global error handler (app.ts:99-118) for ALL
+  // BillingError throws + validation errors + internal errors. Most inline
+  // route returns also use this shape (admin-products.ts:110,144,184-185,etc).
+  if (parsed && typeof parsed.error === 'string') {
+    return `❌ Error [${status}] ${parsed.error}: ${parsed.message ?? '(no message)'}`;
+  }
+  // Less-common nested envelope: { error: { code, message } } — used by a
+  // few inline 400/404 returns in admin-products.ts toggle-channel handler
+  // (lines 92-93, 100-101, 114-117). Possibly extends to other routes
+  // post-Wave-1.5 as standardization lands.
+  if (parsed && typeof parsed.error === 'object' && parsed.error !== null) {
+    const code = (parsed.error as { code?: string }).code ?? 'UNKNOWN';
+    const msg = (parsed.error as { message?: string }).message ?? '(no message)';
+    return `❌ Error [${status}] ${code}: ${msg}`;
+  }
+  // Non-envelope fallback (raw 502 from upstream LB, crashed handler before
+  // error middleware, plain-text body, etc.)
+  return `❌ Error [${status}] ${statusText}\n   Response body (first 500 bytes): ${body.slice(0, 500)}`;
+}
+
+// ───── Public: callBilling ──────────────────────────────────────────────────
+export interface BillingResponse<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).
+ */
+export async function callBilling<T = unknown>(
+  env: string,
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: object,
+): Promise<BillingResponse<T>> {
+  const url = `${getBillingUrl(env)}${path}`;
+  const token = getServiceToken(env);
+
+  const doFetch = async () => fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  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));
+  }
+  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)}`);
+  }
+  return { status: res.status, body: parsed };
+}

package/bin/helpers/confirm-prompt.ts

@@ -0,0 +1,23 @@
+import * as readline from 'readline';
+
+/**
+ * On prod, print the resolved action and require typing "yes" to proceed.
+ * No-op on stage or when --yes was passed. Exits 1 if user declines.
+ */
+export async function confirmIfProd(
+  env: string,
+  actionDescription: string,
+  skipFlag: boolean,
+): Promise<void> {
+  if (env !== 'prod' || skipFlag) return;
+
+  console.log(`\n⚠️  About to perform on PROD:\n${actionDescription}\n`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>((resolve) => {
+    rl.question('Type "yes" to confirm: ', (a) => { rl.close(); resolve(a.trim()); });
+  });
+  if (answer !== 'yes') {
+    console.error('❌ Aborted by user.');
+    process.exit(1);
+  }
+}

package/bin/helpers/entitlement/grant.ts

@@ -0,0 +1,70 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
+
+interface GrantArgs {
+  email: string;
+  productKey: string;
+  justification: string;
+  yes: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): GrantArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-entitlement grant --email <user> --product-key <slug> --justification "..." [options]
+
+Required:
+  --email <user-email>             Resolved to userId via user-auth DB
+  --product-key <productKey>
+  --justification "..."            Required by billing (400 otherwise); stored on entitlement.justification
+
+Optional:
+  --yes                            Skip prod confirmation prompt (no-op on stage)
+  --env stage|prod                 (default: stage)
+
+Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
+    process.exit(0);
+  }
+  const out: Partial<GrantArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--email': out.email = next; i++; break;
+      case '--product-key': out.productKey = next; i++; break;
+      case '--justification': out.justification = next; i++; break;
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.email) throw new Error('--email required');
+  if (!out.productKey) throw new Error('--product-key required');
+  if (!out.justification) throw new Error('--justification required (billing returns 400 otherwise)');
+  return out as GrantArgs;
+}
+
+export async function runGrant(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  const cfg = getInfisicalConfig();
+  const token = getInfisicalToken(cfg);
+  const userId = await resolveUserId(args.email, args.env, cfg, token);
+
+  await confirmIfProd(
+    args.env,
+    `Action: GRANT product '${args.productKey}' to user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`,
+    args.yes,
+  );
+
+  console.log(`\n🎁 Granting ${args.productKey} to ${args.email}...`);
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/grant-entitlement', {
+    userId,
+    productKey: args.productKey,
+    justification: args.justification,
+  });
+  console.log(`✓ Granted entitlement (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/entitlement/list.ts

@@ -0,0 +1,77 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
+
+interface ListArgs {
+  email: string;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ListArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-entitlement list --email <user-email> [options]
+
+Required:
+  --email <user-email>             Resolved to userId via user-auth DB
+
+Optional:
+  --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 '--email': out.email = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.email) throw new Error('--email required');
+  return out as ListArgs;
+}
+
+interface EntitlementRow {
+  id: string;
+  productKey: string;
+  status: string;
+  source: string;
+  purchasedAt: string;
+  refundedAt: string | null;
+}
+
+export async function runList(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  const cfg = getInfisicalConfig();
+  const token = getInfisicalToken(cfg);
+  const userId = await resolveUserId(args.email, args.env, cfg, token);
+
+  const res = await callBilling<{ entitlements: EntitlementRow[] }>(
+    args.env,
+    'GET',
+    `/api/billing/admin/entitlements?userId=${encodeURIComponent(userId)}`,
+  );
+
+  const rows = res.body.entitlements ?? [];
+  if (rows.length === 0) {
+    console.log(`(no entitlements for ${args.email} on ${args.env})`);
+    return;
+  }
+  // Newest first per spec
+  rows.sort((a, b) => b.purchasedAt.localeCompare(a.purchasedAt));
+  console.log(`${rows.length} entitlement(s) for ${args.email}:\n`);
+  console.log('id'.padEnd(38) + ' | ' + 'productKey'.padEnd(32) + ' | ' + 'status'.padEnd(9) + ' | ' + 'source'.padEnd(12) + ' | purchasedAt              | refundedAt');
+  console.log('-'.repeat(140));
+  for (const r of rows) {
+    console.log(
+      r.id.padEnd(38) + ' | ' +
+      r.productKey.padEnd(32) + ' | ' +
+      r.status.padEnd(9) + ' | ' +
+      r.source.padEnd(12) + ' | ' +
+      r.purchasedAt.padEnd(24) + ' | ' +
+      (r.refundedAt ?? ''),
+    );
+  }
+}

package/bin/helpers/entitlement/revoke.ts

@@ -0,0 +1,116 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+import { getInfisicalConfig, getInfisicalToken, resolveUserId } from '../db-utils';
+
+interface RevokeArgs {
+  email: string;
+  productKey: string;
+  reason: string;
+  yes: boolean;
+  env: string;
+}
+
+interface EntitlementRow {
+  id: string;
+  productKey: string;
+  status: string;
+  source: string;
+}
+
+function parseArgs(argv: string[]): RevokeArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-entitlement revoke --email <user> --product-key <slug> --reason "..." [options]
+
+Required:
+  --email <user-email>             Resolved to userId via user-auth DB
+  --product-key <productKey>
+  --reason "..."                   Required by billing (400 otherwise); stored on entitlement.refundReason
+
+Optional:
+  --yes                            Skip prod confirmation prompt (no-op on stage)
+  --env stage|prod                 (default: stage)
+
+Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
+error pointing to the right reversal flow.`);
+    process.exit(0);
+  }
+  const out: Partial<RevokeArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--email': out.email = next; i++; break;
+      case '--product-key': out.productKey = next; i++; break;
+      case '--reason': out.reason = next; i++; break;
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.email) throw new Error('--email required');
+  if (!out.productKey) throw new Error('--product-key required');
+  if (!out.reason) throw new Error('--reason required (billing returns 400 otherwise)');
+  return out as RevokeArgs;
+}
+
+const PAYMENT_REFUSAL = `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.`;
+
+const PARTNER_REFUSAL = `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.`;
+
+export async function runRevoke(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  const cfg = getInfisicalConfig();
+  const token = getInfisicalToken(cfg);
+  const userId = await resolveUserId(args.email, args.env, cfg, token);
+
+  // Step 1: Fetch user's entitlements
+  const listRes = await callBilling<{ entitlements: EntitlementRow[] }>(
+    args.env,
+    'GET',
+    `/api/billing/admin/entitlements?userId=${encodeURIComponent(userId)}`,
+  );
+  const all = listRes.body.entitlements ?? [];
+
+  // Step 2: Filter for ACTIVE + matching productKey
+  const matches = all.filter((e) => e.status === 'ACTIVE' && e.productKey === args.productKey);
+
+  // Step 3: Validate count (partial unique index enforces ≤1 ACTIVE)
+  if (matches.length === 0) {
+    throw new Error(`no active entitlement for (user=${args.email}, product=${args.productKey}) on ${args.env}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`unexpected: ${matches.length} ACTIVE entitlements for (user, product) — partial unique constraint should prevent this. Inspect with: optima-entitlement list --email ${args.email}`);
+  }
+  const target = matches[0];
+
+  // Step 4: Validate source
+  if (target.source === 'PAYMENT') throw new Error(PAYMENT_REFUSAL);
+  if (target.source === 'PARTNER') throw new Error(PARTNER_REFUSAL);
+  if (target.source !== 'ADMIN_GRANT') throw new Error(`unknown entitlement source: ${target.source}`);
+
+  await confirmIfProd(
+    args.env,
+    `Action: REVOKE entitlement ${target.id} (productKey=${target.productKey}) for user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nReason: ${args.reason}`,
+    args.yes,
+  );
+
+  // Step 5: Refund
+  // refundAmountCents=0 is always correct for ADMIN_GRANT (priceCents=0,
+  // no upstream charge). Pass explicitly so billing's auto-compute
+  // (which requires refundWindowDays on the Product) doesn't 400 with
+  // MANUAL_REFUND_AMOUNT_REQUIRED for products that lack a refund policy.
+  // PAYMENT/PARTNER sources are already refused in step 4 above, so
+  // this branch only ever runs for ADMIN_GRANT (priceCents=0) — Stripe
+  // refund path in billing (admin-products.ts:296-307) is gated on
+  // source=PAYMENT and won't trigger here.
+  console.log(`\n♻️  Revoking entitlement ${target.id} for ${args.email}...`);
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/refund-entitlement', {
+    entitlementId: target.id,
+    refundReason: args.reason,
+    refundAmountCents: 0,
+  });
+  console.log(`✓ Revoked entitlement (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/entitlement.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { runGrant } from './entitlement/grant';
+import { runList } from './entitlement/list';
+import { runRevoke } from './entitlement/revoke';
+
+function printHelp() {
+  console.log(`Usage: optima-entitlement <subcommand> [options]
+
+Subcommands:
+  grant      Admin-grant a product entitlement to a user
+  revoke     Revoke an admin-granted entitlement (refuses PAYMENT / PARTNER sources)
+  list       List a user's entitlements, newest first
+
+Run 'optima-entitlement <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 'list': await runList(rest); break;
+    case 'grant': await runGrant(rest); break;
+    case 'revoke': await runRevoke(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/infisical-secrets.ts

@@ -0,0 +1,41 @@
+import { execSync } from 'child_process';
+import { getInfisicalConfig, getInfisicalToken, InfisicalConfig } from './db-utils';
+
+/**
+ * Fetch a single secret value from Infisical given env + path + name.
+ *
+ * env mapping: 'stage' → Infisical env slug 'staging'; 'prod' → 'prod'
+ * (matches dev-skills convention documented at
+ *  ~/.claude/projects/-mnt-d-work-projects-optima/memory/optima_infisical_env_naming.md).
+ *
+ * Returns the raw secretValue string. Throws if the secret is missing.
+ */
+export function fetchInfisicalSecret(
+  env: string,
+  secretPath: string,
+  secretName: string,
+  config?: InfisicalConfig,
+  token?: string,
+): string {
+  const cfg = config ?? getInfisicalConfig();
+  const tok = token ?? getInfisicalToken(cfg);
+  const envSlug = env === 'stage' ? 'staging' : env;
+  const encodedPath = encodeURIComponent(secretPath);
+  const encodedName = encodeURIComponent(secretName);
+
+  const response = execSync(
+    `curl -s "${cfg.url}/api/v3/secrets/raw/${encodedName}?workspaceId=${cfg.projectId}&environment=${envSlug}&secretPath=${encodedPath}" -H "Authorization: Bearer ${tok}"`,
+    { encoding: 'utf-8' },
+  );
+
+  let parsed: { secret?: { secretValue?: string }; message?: string };
+  try {
+    parsed = JSON.parse(response);
+  } catch {
+    throw new Error(`Infisical raw secret fetch returned non-JSON for ${secretPath}/${secretName} (${envSlug}): ${response.slice(0, 200)}`);
+  }
+  if (!parsed.secret?.secretValue) {
+    throw new Error(`Infisical secret not found: env=${envSlug} path=${secretPath} name=${secretName} (response: ${response.slice(0, 200)})`);
+  }
+  return parsed.secret.secretValue;
+}

package/bin/helpers/product/add-channel.ts

@@ -0,0 +1,78 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface AddChannelArgs {
+  key: string;
+  provider: string;
+  stripePriceId: string;
+  priceCents: number;
+  currency: string;
+  enabled?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): AddChannelArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product add-channel --key <productKey> --provider STRIPE --stripe-price-id <price_xxx> --price-cents N --currency USD [options]
+
+Required:
+  --key <productKey>
+  --provider STRIPE                v1 CLI accepts only STRIPE (schema supports more)
+  --stripe-price-id <price_xxx>    Pre-created in Stripe Dashboard; wire-mapped to externalProductId
+  --price-cents N                  MUST be > 0; should match Stripe Price's unit_amount (NOT verified)
+  --currency USD                   Should match Stripe Price's currency (NOT verified)
+
+Optional:
+  --enabled true|false             default: true
+  --metadata '<json>'
+  --env stage|prod                 (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<AddChannelArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--provider': out.provider = next; i++; break;
+      case '--stripe-price-id': out.stripePriceId = next; i++; break;
+      case '--price-cents': out.priceCents = parseInt(next, 10); i++; break;
+      case '--currency': out.currency = next; i++; break;
+      case '--enabled': out.enabled = next === 'true'; i++; break;
+      case '--metadata': out.metadata = JSON.parse(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.key) throw new Error('--key required');
+  if (!out.provider) throw new Error('--provider required');
+  if (out.provider !== 'STRIPE') throw new Error(`v1 CLI accepts only --provider STRIPE (got ${out.provider})`);
+  if (!out.stripePriceId) throw new Error('--stripe-price-id required');
+  if (out.priceCents === undefined || !Number.isFinite(out.priceCents)) throw new Error('--price-cents required (integer)');
+  if (out.priceCents <= 0) throw new Error('--price-cents must be > 0');
+  if (!out.currency) throw new Error('--currency required');
+  return out as AddChannelArgs;
+}
+
+export async function runAddChannel(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const body: Record<string, unknown> = {
+    provider: args.provider,
+    externalProductId: args.stripePriceId,
+    priceCents: args.priceCents,
+    currency: args.currency,
+  };
+  if (args.enabled !== undefined) body.enabled = args.enabled;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  console.log(`\n💳 Adding ${args.provider} channel to ${args.key} on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(
+    args.env,
+    'POST',
+    `/api/billing/admin/products/${encodeURIComponent(args.key)}/channels`,
+    body,
+  );
+  console.log(`✓ Created Channel (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}