@optima-chat/dev-skills 0.7.32 → 0.7.35

package/bin/helpers/product/create.ts

@@ -0,0 +1,96 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface CreateArgs {
+  key: string;
+  plugins: string[];
+  type: string;
+  name?: string;
+  description?: string;
+  refundWindowDays?: number;
+  refundProrateMaxDays?: number;
+  bundledPlanId?: string;
+  bundledDurationDays?: number;
+  revokeBundledOnRefund?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): CreateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product create --key <productKey> --plugins <slug1,slug2,...> --type <ProductType> [options]
+
+Required:
+  --key <productKey>             Unique slug
+  --plugins <slug1,slug2,...>    Comma-separated, >=1 plugin slug
+  --type <ProductType>           Only ONE_SHOT_SKILL accepted by v1 CLI policy
+
+Optional:
+  --name "..."                   Convenience flag, folded into metadata.name
+  --description "..."            Convenience flag, folded into metadata.description
+  --refund-window-days N
+  --refund-prorate-max-days N
+  --bundled-plan-id <planId>     (joint with --bundled-duration-days)
+  --bundled-duration-days N
+  --revoke-bundled-on-refund true|false
+  --metadata '<json>'            JSON object stored in product.metadata
+  --env stage|prod               (default: stage)`);
+    process.exit(0);
+  }
+
+  const out: Partial<CreateArgs> = { env: 'stage', revokeBundledOnRefund: undefined };
+  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 '--plugins': out.plugins = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--type': out.type = next; i++; break;
+      case '--name': out.name = next; i++; break;
+      case '--description': out.description = next; i++; break;
+      case '--refund-window-days': out.refundWindowDays = parseInt(next, 10); i++; break;
+      case '--refund-prorate-max-days': out.refundProrateMaxDays = parseInt(next, 10); i++; break;
+      case '--bundled-plan-id': out.bundledPlanId = next; i++; break;
+      case '--bundled-duration-days': out.bundledDurationDays = parseInt(next, 10); i++; break;
+      case '--revoke-bundled-on-refund': out.revokeBundledOnRefund = 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.plugins || out.plugins.length === 0) throw new Error('--plugins required (>=1 slug)');
+  if (!out.type) throw new Error('--type required');
+  if (out.type !== 'ONE_SHOT_SKILL') {
+    throw new Error(`v1 CLI accepts only --type ONE_SHOT_SKILL (got ${out.type}). See spec §5.1.`);
+  }
+  if ((out.bundledPlanId == null) !== (out.bundledDurationDays == null)) {
+    throw new Error('--bundled-plan-id and --bundled-duration-days must be set together');
+  }
+  return out as CreateArgs;
+}
+
+export async function runCreate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  const body: Record<string, unknown> = {
+    productKey: args.key,
+    type: args.type,
+    pluginSlugs: args.plugins,
+  };
+  if (args.name !== undefined) body.name = args.name;
+  if (args.description !== undefined) body.description = args.description;
+  if (args.refundWindowDays !== undefined) body.refundWindowDays = args.refundWindowDays;
+  if (args.refundProrateMaxDays !== undefined) body.refundProrateMaxDays = args.refundProrateMaxDays;
+  if (args.bundledPlanId !== undefined) body.bundledPlanId = args.bundledPlanId;
+  if (args.bundledDurationDays !== undefined) body.bundledDurationDays = args.bundledDurationDays;
+  if (args.revokeBundledOnRefund !== undefined) body.revokeBundledOnRefund = args.revokeBundledOnRefund;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  console.log(`\n🎁 Creating product ${args.key} (${args.plugins.length} plugin(s)) on ${args.env.toUpperCase()}...`);
+
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/products', body);
+  console.log(`✓ Created Product (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/show.ts

@@ -0,0 +1,43 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ShowArgs {
+  key: string;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ShowArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product show --key <productKey> [options]
+
+Required:
+  --key <productKey>
+
+Optional:
+  --env stage|prod                 (default: stage)
+
+Note: returns the bare Product row only — productPlugins and channels arrays
+are NOT included (billing's GET /api/internal/products/:key is a plain
+findUnique with no include). To inspect channels/plugins today, query the DB
+directly via optima-query-db. Tracked as follow-up in spec §7.`);
+    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 '--key': out.key = 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');
+  return out as ShowArgs;
+}
+
+export async function runShow(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const res = await callBilling(args.env, 'GET', `/api/internal/products/${encodeURIComponent(args.key)}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

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

@@ -0,0 +1,56 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ToggleArgs {
+  key: string;
+  provider: string;
+  enabled: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ToggleArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product toggle-channel --key <productKey> --provider STRIPE --enabled true|false [options]
+
+Required:
+  --key <productKey>
+  --provider STRIPE                v1 CLI accepts only STRIPE
+  --enabled true|false
+
+Optional:
+  --env stage|prod                 (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<ToggleArgs> = { 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 '--enabled':
+        if (next !== 'true' && next !== 'false') throw new Error('--enabled must be true or false');
+        out.enabled = next === 'true'; 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.enabled === undefined) throw new Error('--enabled required');
+  return out as ToggleArgs;
+}
+
+export async function runToggleChannel(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  console.log(`\n🔁 Setting ${args.provider} channel enabled=${args.enabled} on ${args.key} (${args.env.toUpperCase()})...`);
+  const res = await callBilling(
+    args.env,
+    'PATCH',
+    `/api/billing/admin/products/${encodeURIComponent(args.key)}/channels/${args.provider}`,
+    { enabled: args.enabled },
+  );
+  console.log(`✓ Channel updated (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/update.ts

@@ -0,0 +1,72 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface UpdateArgs {
+  key: string;
+  refundWindowDays?: number | null;
+  refundProrateMaxDays?: number | null;
+  bundledPlanId?: string | null;
+  bundledDurationDays?: number | null;
+  revokeBundledOnRefund?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): UpdateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product update --key <productKey> [options]
+
+Required:
+  --key <productKey>
+
+Optional (PATCH — only included fields are updated):
+  --refund-window-days N | null
+  --refund-prorate-max-days N | null
+  --bundled-plan-id <planId> | null    (joint with --bundled-duration-days)
+  --bundled-duration-days N | null
+  --revoke-bundled-on-refund true|false
+  --metadata '<json>'                   FULL REPLACE — Prisma does not deep-merge JSON
+  --env stage|prod                      (default: stage)
+
+Note: productKey, type, and pluginSlugs are immutable post-create. To change plugin
+membership, create a new Product with a new key.`);
+    process.exit(0);
+  }
+  const out: Partial<UpdateArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    const parseNullable = (v: string): number | null => v === 'null' ? null : parseInt(v, 10);
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--refund-window-days': out.refundWindowDays = parseNullable(next); i++; break;
+      case '--refund-prorate-max-days': out.refundProrateMaxDays = parseNullable(next); i++; break;
+      case '--bundled-plan-id': out.bundledPlanId = next === 'null' ? null : next; i++; break;
+      case '--bundled-duration-days': out.bundledDurationDays = parseNullable(next); i++; break;
+      case '--revoke-bundled-on-refund': out.revokeBundledOnRefund = 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');
+  return out as UpdateArgs;
+}
+
+export async function runUpdate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const body: Record<string, unknown> = {};
+  if (args.refundWindowDays !== undefined) body.refundWindowDays = args.refundWindowDays;
+  if (args.refundProrateMaxDays !== undefined) body.refundProrateMaxDays = args.refundProrateMaxDays;
+  if (args.bundledPlanId !== undefined) body.bundledPlanId = args.bundledPlanId;
+  if (args.bundledDurationDays !== undefined) body.bundledDurationDays = args.bundledDurationDays;
+  if (args.revokeBundledOnRefund !== undefined) body.revokeBundledOnRefund = args.revokeBundledOnRefund;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  if (Object.keys(body).length === 0) throw new Error('At least one updatable field must be passed');
+
+  console.log(`\n✏️  Updating product ${args.key} on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(args.env, 'PATCH', `/api/billing/admin/products/${encodeURIComponent(args.key)}`, body);
+  console.log(`✓ Updated Product (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { runCreate } from './product/create';
+import { runUpdate } from './product/update';
+import { runAddChannel } from './product/add-channel';
+import { runToggleChannel } from './product/toggle-channel';
+import { runShow } from './product/show';
+
+const SUBCOMMANDS = ['create', 'update', 'add-channel', 'toggle-channel', 'show'] as const;
+
+function printHelp() {
+  console.log(`Usage: optima-product <subcommand> [options]
+
+Subcommands:
+  create           Create a Product bundling 1+ plugin slugs
+  update           Patch refund policy / metadata on an existing Product
+  add-channel      Attach a payment channel (Stripe Price ID) to a Product
+  toggle-channel   Enable/disable an existing channel
+  show             Show a Product's bare row (note: does NOT include plugins/channels)
+
+Run 'optima-product <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 'update': await runUpdate(rest); break;
+    case 'add-channel': await runAddChannel(rest); break;
+    case 'toggle-channel': await runToggleChannel(rest); break;
+    case 'show': await runShow(rest); break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/dist/bin/helpers/billing-http.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnv = validateEnv;
+exports.getServiceToken = getServiceToken;
+exports.callBilling = callBilling;
+const child_process_1 = require("child_process");
+const infisical_secrets_1 = require("./infisical-secrets");
+const db_utils_1 = require("./db-utils");
+const USER_AUTH_URLS = {
+    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.
+ */
+function validateEnv(env) {
+    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 = {};
+const billingUrlCache = {};
+function getBillingUrl(env) {
+    if (billingUrlCache[env])
+        return billingUrlCache[env];
+    const url = (0, infisical_secrets_1.fetchInfisicalSecret)(env, '/shared-secrets/domain-urls', 'BILLING_URL');
+    billingUrlCache[env] = url;
+    return url;
+}
+function getServiceToken(env) {
+    if (tokenCache[env])
+        return tokenCache[env];
+    const cfg = (0, db_utils_1.getInfisicalConfig)();
+    const tok = (0, db_utils_1.getInfisicalToken)(cfg);
+    // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
+    const clientId = (0, infisical_secrets_1.fetchInfisicalSecret)(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_ID_KEY, cfg, tok);
+    const clientSecret = (0, infisical_secrets_1.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 = (0, child_process_1.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;
+    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;
+}
+function formatBillingError(status, statusText, body) {
+    let parsed = 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.code ?? 'UNKNOWN';
+        const msg = parsed.error.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)}`;
+}
+/**
+ * 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).
+ */
+async function callBilling(env, method, path, body) {
+    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;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        throw new Error(`Billing returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+    }
+    return { status: res.status, body: parsed };
+}

package/dist/bin/helpers/confirm-prompt.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmIfProd = confirmIfProd;
+const readline = __importStar(require("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.
+ */
+async function confirmIfProd(env, actionDescription, skipFlag) {
+    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((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/dist/bin/helpers/db-utils.js

@@ -92,17 +92,50 @@ function parseDatabaseUrl(url) {
     return { user: decodeURIComponent(match[1]), password: decodeURIComponent(match[2]), host: match[3], port: parseInt(match[4], 10), database: match[5] };
 }
 // ─── SSH tunnel ─────────────────────────────────────────────────────────────
+// 端口被占不等于 tunnel 还能转发：AWS bastion idle 断连后，本地 ssh 进程还活着、
+// 端口还 LISTEN，但流量过不去，所有后续查询会 hang 到客户端 timeout。
+// 用 pg_isready 真去 ping postgres，超时就当 zombie，杀掉重建。
+function isTunnelHealthy(localPort) {
+    try {
+        (0, child_process_1.execSync)(`pg_isready -h localhost -p ${localPort} -t 3 -q`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function killOrphanTunnel(localPort) {
+    try {
+        const pids = (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { encoding: 'utf-8' }).trim();
+        if (pids)
+            (0, child_process_1.execSync)(`kill -9 ${pids.split(/\s+/).join(' ')}`, { stdio: 'ignore' });
+    }
+    catch { /* nothing to kill */ }
+}
 function setupSSHTunnel(dbHost, localPort) {
+    let portInUse = false;
     try {
         (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { stdio: 'ignore' });
-        return;
+        portInUse = true;
+    }
+    catch { /* free */ }
+    if (portInUse) {
+        if (isTunnelHealthy(localPort))
+            return;
+        console.log(`! SSH tunnel on port ${localPort} not responding (zombie), replacing...`);
+        killOrphanTunnel(localPort);
     }
-    catch { /* need tunnel */ }
     const sshKeyPath = `${process.env.HOME}/.ssh/optima-ec2-key`;
     if (!fs.existsSync(sshKeyPath))
         throw new Error(`SSH key not found: ${sshKeyPath}. Please obtain optima-ec2-key from xbfool.`);
     console.log(`Creating SSH tunnel: localhost:${localPort} -> ${EC2_HOST} -> ${dbHost}:5432`);
-    (0, child_process_1.execSync)(`ssh -i ${sshKeyPath} -f -N -o StrictHostKeyChecking=no -L ${localPort}:${dbHost}:5432 ec2-user@${EC2_HOST}`, { stdio: 'inherit' });
+    // ServerAliveInterval/CountMax: 服务端 30s 没回应就让 ssh 自己退出（不留 zombie）
+    // ExitOnForwardFailure: 端口绑定失败立刻退出（不会黑悄悄继续跑）
+    // ConnectTimeout: 10s 不通就放弃（业界 ssh 默认 120s 太宽）
+    (0, child_process_1.execSync)(`ssh -i ${sshKeyPath} -f -N -o StrictHostKeyChecking=no ` +
+        `-o ServerAliveInterval=30 -o ServerAliveCountMax=3 ` +
+        `-o ExitOnForwardFailure=yes -o ConnectTimeout=10 ` +
+        `-L ${localPort}:${dbHost}:5432 ec2-user@${EC2_HOST}`, { stdio: 'inherit' });
 }
 // ─── psql ───────────────────────────────────────────────────────────────────
 function findPsqlPath() {

package/dist/bin/helpers/entitlement/grant.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGrant = runGrant;
+const billing_http_1 = require("../billing-http");
+const confirm_prompt_1 = require("../confirm-prompt");
+const db_utils_1 = require("../db-utils");
+function parseArgs(argv) {
+    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 = { 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;
+}
+async function runGrant(argv) {
+    const args = parseArgs(argv);
+    (0, billing_http_1.validateEnv)(args.env);
+    const cfg = (0, db_utils_1.getInfisicalConfig)();
+    const token = (0, db_utils_1.getInfisicalToken)(cfg);
+    const userId = await (0, db_utils_1.resolveUserId)(args.email, args.env, cfg, token);
+    await (0, confirm_prompt_1.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 (0, billing_http_1.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));
+}