@optima-chat/dev-skills 0.8.1 → 0.9.0

package/bin/helpers/logs.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * optima-logs —— 一条命令直取服务日志,四环境统一,用 --env 区分。
+ *
+ *   stage / prod     : AWS CloudWatch(`aws logs tail /ecs/<svc>-<env>`)
+ *   cn-prod / cn-stage: 阿里云 SLS 直连(`aliyun sls GetLogs`)
+ *
+ * cn 的关键改进:旧流程要 SSH 进 buildbox 再调 SAE `DescribeInstanceLog`,
+ * 只能看实例**当前缓冲**(重启即丢、不能检索)。现在 cn-prod/cn-stage 全部
+ * 服务已接 SLS,GetLogs 是公网控制面 API,本机 `aliyun-optima` profile 直连即可:
+ *   - 免 buildbox 跳板
+ *   - 支持时间窗(--since)+ 关键词检索(--grep)+ 历史(重启不丢)
+ *
+ * 前置:
+ *   AWS  → 已配 aws CLI 凭证(ap-southeast-1)
+ *   cn   → 已配 aliyun CLI profile `aliyun-optima`(cn-beijing)
+ *
+ * 用法:
+ *   optima-logs gateway-core                       # 默认 cn-prod,最近 1h,100 行
+ *   optima-logs gateway-core --env cn-stage
+ *   optima-logs user-auth --env prod --since 2h
+ *   optima-logs commerce-backend --grep error -n 200
+ *   optima-logs gateway-core --since 30m --json     # 机器可读
+ *
+ * service == SLS logstore == AWS 日志组 `/ecs/<svc>-<env>` 的 <svc>(同名)。
+ */
+import { execFileSync } from 'child_process';
+
+const ALIYUN_ACCOUNT = '1911493506120573';
+const ALIYUN_PROFILE = 'aliyun-optima';
+const ALIYUN_REGION = 'cn-beijing';
+const AWS_REGION = 'ap-southeast-1';
+
+const AWS_ENVS = ['stage', 'prod'] as const;
+const CN_ENVS = ['cn-prod', 'cn-stage'] as const;
+type Env = (typeof AWS_ENVS)[number] | (typeof CN_ENVS)[number];
+const ALL_ENVS: Env[] = [...AWS_ENVS, ...CN_ENVS];
+
+const C = { g: '\x1b[32m', y: '\x1b[33m', b: '\x1b[34m', d: '\x1b[2m', n: '\x1b[0m' };
+
+interface Args {
+  service: string;
+  env: Env;
+  lines: number;
+  since: string; // 原样字符串,如 1h / 30m / 2d
+  grep?: string;
+  json: boolean;
+}
+
+const HELP = `Usage: optima-logs <service> [options]
+
+四环境统一查日志,cn 直连阿里云 SLS(免 buildbox),AWS 走 CloudWatch。
+
+Required:
+  <service>                服务名(== SLS logstore == /ecs/<svc>-<env> 的 <svc>)
+
+Optional:
+  --env <e>                stage | prod | cn-prod | cn-stage   (default: cn-prod)
+  --lines, -n <N>          返回行数                            (default: 100)
+  --since <dur>            时间窗,如 30m / 2h / 1d / 3600(秒)  (default: 1h)
+  --grep <kw>              关键词检索(cn=SLS query / aws=filter-pattern)
+  --json                   原始 JSON 输出(接管道)
+  --help, -h               显示本帮助
+
+Examples:
+  optima-logs gateway-core
+  optima-logs user-auth --env prod --since 2h
+  optima-logs commerce-backend --env cn-prod --grep error -n 200`;
+
+/** 把 30m / 2h / 1d / 纯秒 解析成秒数;同时回填给 aws 用的带单位字符串。 */
+function parseSince(raw: string): { sec: number; awsStr: string } {
+  const m = raw.match(/^(\d+)([smhdw]?)$/);
+  if (!m) throw new Error(`--since 格式非法: ${raw}(用 30m / 2h / 1d / 纯秒)`);
+  const n = parseInt(m[1], 10);
+  const unit = m[2] || 's';
+  const mult: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+  return { sec: n * mult[unit], awsStr: `${n}${unit}` };
+}
+
+function parseArgs(argv: string[]): Args {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const out: Partial<Args> = { env: 'cn-prod', lines: 100, since: '1h', json: false };
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--env': out.env = next as Env; i++; break;
+      case '--lines': case '-n': {
+        const v = parseInt(next, 10);
+        if (isNaN(v) || v <= 0) throw new Error('--lines 需要正整数');
+        out.lines = v; i++; break;
+      }
+      case '--since': out.since = next; i++; break;
+      case '--grep': out.grep = next; i++; break;
+      case '--json': out.json = true; break;
+      default:
+        if (a.startsWith('-')) throw new Error(`未知参数: ${a}`);
+        positional.push(a);
+    }
+  }
+  if (positional.length === 0) throw new Error('缺少 <service>(见 --help)');
+  if (positional.length > 1) throw new Error(`多余参数: ${positional.slice(1).join(' ')}`);
+  out.service = positional[0];
+  if (!ALL_ENVS.includes(out.env as Env)) {
+    throw new Error(`--env 非法: ${out.env}(可选 ${ALL_ENVS.join(' | ')})`);
+  }
+  return out as Args;
+}
+
+function run(cmd: string, args: string[]): string {
+  return execFileSync(cmd, args, { encoding: 'utf-8', maxBuffer: 128 * 1024 * 1024 });
+}
+
+/** AWS CloudWatch:aws logs tail /ecs/<svc>-<env>。 */
+function fetchAws(args: Args): void {
+  const group = `/ecs/${args.service}-${args.env}`;
+  const { awsStr } = parseSince(args.since);
+  const cmd = ['logs', 'tail', group, '--since', awsStr, '--region', AWS_REGION, '--format', args.json ? 'json' : 'short'];
+  if (args.grep) cmd.push('--filter-pattern', args.grep);
+  process.stderr.write(`${C.d}# AWS CloudWatch ${group} (since ${awsStr}${args.grep ? `, grep "${args.grep}"` : ''})${C.n}\n`);
+  try {
+    process.stdout.write(run('aws', cmd));
+  } catch (e: any) {
+    if (/ResourceNotFoundException/.test(e.stderr || e.message || '')) {
+      throw new Error(`日志组不存在: ${group}\n  确认服务名/环境对,或该服务未部署在 ${args.env}。`);
+    }
+    throw new Error(e.stderr || e.message);
+  }
+}
+
+/** 阿里云 SLS:aliyun sls GetLogs,project=optima-<env>-<account>,logstore=service。 */
+function fetchCn(args: Args): void {
+  const project = `optima-${args.env}-${ALIYUN_ACCOUNT}`;
+  const { sec } = parseSince(args.since);
+  const now = Math.floor(Date.now() / 1000);
+  const from = now - sec;
+  const cmd = [
+    'sls', 'GetLogs',
+    '--project', project,
+    '--logstore', args.service,
+    '--from', String(from),
+    '--to', String(now),
+    '--line', String(args.lines),
+    '--reverse', 'true', // 先拿最新 N 条
+    '--region', ALIYUN_REGION,
+    '--profile', ALIYUN_PROFILE,
+  ];
+  if (args.grep) { cmd.push('--query', args.grep); }
+  process.stderr.write(`${C.d}# 阿里云 SLS ${project}/${args.service} (since ${args.since}${args.grep ? `, query "${args.grep}"` : ''})${C.n}\n`);
+
+  let raw: string;
+  try {
+    raw = run('aliyun', cmd);
+  } catch (e: any) {
+    const msg = e.stderr || e.message || '';
+    if (/LogStoreNotExist|ProjectNotExist/.test(msg)) {
+      throw new Error(`SLS logstore 不存在: ${project}/${args.service}\n  确认服务名对,或该服务未接 SLS。列全部:\n  aliyun sls ListLogStores --project ${project} --region ${ALIYUN_REGION} --profile ${ALIYUN_PROFILE}`);
+    }
+    throw new Error(msg);
+  }
+
+  const rows: Array<Record<string, string>> = JSON.parse(raw || '[]');
+  // reverse=true 取到的是新→旧,翻回旧→新便于阅读
+  rows.reverse();
+  if (args.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (rows.length === 0) {
+    process.stderr.write(`${C.y}(无日志:该时间窗内 ${args.service} 无输出,或 --grep 没命中)${C.n}\n`);
+    return;
+  }
+  for (const r of rows) {
+    // SLS 存的 content 已含容器时间戳 + stream(stdout/stderr)前缀,直接打印即可
+    process.stdout.write((r.content ?? JSON.stringify(r)) + '\n');
+  }
+}
+
+function main(): void {
+  let args: Args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (e: any) {
+    console.error(`${C.y}✗ ${e.message}${C.n}`);
+    process.exit(1);
+  }
+  try {
+    if (CN_ENVS.includes(args.env as any)) fetchCn(args);
+    else fetchAws(args);
+  } catch (e: any) {
+    console.error(`${C.y}✗ ${e.message}${C.n}`);
+    process.exit(1);
+  }
+}
+
+main();

package/dist/bin/helpers/account.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// optima-account：以用户为中心的运营 admin 操作。
+//  · status — 只读聚合（订阅 + 权益）。M2M。
+//  · ban / unban — user-auth 账号禁用/恢复。需 admin-用户 token（非 M2M）。
+//
+// 标识符 <email|phone|userId>：cn-prod/cn-stage 支持三种，AWS stage/prod 仅 email
+// （见 resolveTargetUser）。两个生产环境（prod/cn-prod）ban/unban 前会要求确认。
+const grant_subscription_1 = require("./grant-subscription");
+const billing_http_1 = require("./billing-http");
+const confirm_prompt_1 = require("./confirm-prompt");
+function parseArgs(argv, opts = {}) {
+    const out = { env: 'stage', reason: null, yes: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+        if (a === '--env') {
+            out.env = next;
+            i++;
+        }
+        else if (a === '--reason') {
+            out.reason = next;
+            i++;
+        }
+        else if (a === '--yes') {
+            out.yes = true;
+        }
+        else if (a.startsWith('--')) {
+            throw new Error(`Unknown arg: ${a}`);
+        }
+        else if (out.identifier) {
+            throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        }
+        else {
+            out.identifier = a;
+        }
+    }
+    if (!out.identifier)
+        throw new Error('target user required: <email|phone|userId>');
+    (0, billing_http_1.validateEnvCnProd)(out.env);
+    if (opts.reason && !out.reason)
+        throw new Error('--reason required for ban');
+    return out;
+}
+async function runStatus(argv) {
+    const { identifier, env } = parseArgs(argv);
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    // 订阅（membership-status，M2M；路径前缀 /api/internal 经 billing base URL）
+    let sub = '(读取失败)';
+    try {
+        const { body } = await (0, billing_http_1.callBilling)(env, 'GET', `/api/internal/users/${encodeURIComponent(userId)}/membership-status`);
+        sub = `active=${body.active} plan=${body.planId} status=${body.status}`;
+    }
+    catch (e) {
+        sub = `(读取失败: ${e.message})`;
+    }
+    // 权益（admin/entitlements，M2M）
+    let ents = '(读取失败)';
+    try {
+        const { body } = await (0, billing_http_1.callBilling)(env, 'GET', `/api/billing/admin/entitlements?userId=${encodeURIComponent(userId)}`);
+        const rows = body.entitlements ?? [];
+        ents = rows.length ? rows.map((r) => `${r.productKey}(${r.status})`).join(', ') : '(无)';
+    }
+    catch (e) {
+        ents = `(读取失败: ${e.message})`;
+    }
+    console.log(`\n=== 账号状态 [${env.toUpperCase()}] ===`);
+    console.log(`userId : ${userId}`);
+    console.log(`手机   : ${identity.phone || '(无)'}`);
+    console.log(`email  : ${identity.email || '(无)'}`);
+    console.log(`订阅   : ${sub}`);
+    console.log(`权益   : ${ents}`);
+    console.log(`禁用态/credits 余额: 暂未纳入（banned_at 与 credits 无 M2M 读取端点，见 optima-dev-skills#36）\n`);
+}
+async function runBan(argv) {
+    const { identifier, env, reason, yes } = parseArgs(argv, { reason: true });
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    await (0, confirm_prompt_1.confirmIfProd)(env, `Action: BAN userId=${userId} (手机=${identity.phone || '(无)'} email=${identity.email || '(无)'}) on ${env.toUpperCase()}\nReason: ${reason}`, yes);
+    console.log(`\n🚫 Banning ${identifier} (userId=${userId})...`);
+    const res = await (0, billing_http_1.callUserAuthAsAdmin)(env, 'POST', `/api/v1/admin/users/${encodeURIComponent(userId)}/ban`, { reason });
+    console.log(`✓ Banned (HTTP ${res.status})`);
+    console.log('⚠️  注意：ban 仅置 is_active=false——挡新登录/刷新，但**不会立即失效已签发的 access token**（活跃会话到 token 过期才失效）。即时踢会话需 user-auth 后续支持。\n');
+}
+async function runUnban(argv) {
+    const { identifier, env, yes } = parseArgs(argv);
+    const { userId, identity } = await (0, grant_subscription_1.resolveTargetUser)(env, identifier);
+    await (0, confirm_prompt_1.confirmIfProd)(env, `Action: UNBAN userId=${userId} (手机=${identity.phone || '(无)'} email=${identity.email || '(无)'}) on ${env.toUpperCase()}`, yes);
+    console.log(`\n♻️  Unbanning ${identifier} (userId=${userId})...`);
+    const res = await (0, billing_http_1.callUserAuthAsAdmin)(env, 'POST', `/api/v1/admin/users/${encodeURIComponent(userId)}/unban`);
+    console.log(`✓ Unbanned (HTTP ${res.status})\n`);
+}
+function printHelp() {
+    console.log(`Usage: optima-account <subcommand> <email|phone|userId> [options]
+
+Subcommands:
+  status   只读聚合：订阅(membership) + 权益(entitlements)
+  ban      禁用账号（user-auth is_active=false）。需 --reason
+  unban    恢复账号
+
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
+Options:
+  --reason "..."   Ban reason (required for ban; stored on the user)
+  --yes            Skip prod/cn-prod confirmation prompt
+  --env <env>      Environment: stage, prod, cn-prod, cn-stage (default: stage)
+
+Notes:
+  · ban/unban 用 admin-用户 token（Infisical /shared-secrets/credentials）。
+  · ban 非即时踢会话：仅挡新登录/刷新，活跃 token 过期后失效。
+  · 禁用原因/banned_at 与 credits 余额暂不在 status 显示（见 #36）。
+
+Examples:
+  optima-account status 18898654855 --env cn-prod
+  optima-account ban user@example.com --reason "abuse" --env prod
+  optima-account unban 18898654855 --env cn-prod`);
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+        printHelp();
+        process.exit(0);
+    }
+    switch (subcommand) {
+        case 'status':
+            await runStatus(rest);
+            break;
+        case 'ban':
+            await runBan(rest);
+            break;
+        case 'unban':
+            await runUnban(rest);
+            break;
+        default:
+            console.error(`Unknown subcommand: ${subcommand}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+main().catch((err) => { console.error('\n❌ Error:', err.message); process.exit(1); });

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

@@ -5,8 +5,9 @@ exports.validateEnvCnProd = validateEnvCnProd;
 exports.getServiceToken = getServiceToken;
 exports.callBilling = callBilling;
 exports.callSkills = callSkills;
+exports.getAdminUserToken = getAdminUserToken;
+exports.callUserAuthAsAdmin = callUserAuthAsAdmin;
 exports.resolveUserIdByEmail = resolveUserIdByEmail;
-exports.resolveUserIdByEmailAnyEnv = resolveUserIdByEmailAnyEnv;
 exports.resolveUserIdByPhone = resolveUserIdByPhone;
 exports.getUserById = getUserById;
 const child_process_1 = require("child_process");
@@ -220,6 +221,103 @@ async function callBilling(env, method, path, body) {
 async function callSkills(env, method, path, body) {
     return callService(getSkillsUrl(env), env, method, path, body);
 }
+// ───── Admin-USER token (ROPC password grant) ───────────────────────────────
+// Distinct from getServiceToken (M2M client_credentials): user-auth's /admin/*
+// endpoints gate on get_current_admin_user — a real role=ADMIN *user* — which an
+// M2M token (no user_id) can't satisfy. So ban/unban mint a password-grant token
+// for the seeded admin account. Per-env ROPC client = the same public client
+// generate-test-token uses; admin email/password live in Infisical
+// /shared-secrets/credentials. Cached separately from the M2M tokenCache.
+const adminTokenCache = {};
+const ADMIN_ROPC_CLIENT = {
+    stage: 'commerce-cli-stage-ihbbwplz',
+    prod: 'commerce-cli-ecs-pro-i2r5of1h',
+    'cn-prod': 'dev-skill-cli-cn-pro-acvkmcuq',
+    'cn-stage': 'dev-skill-cli-cn-sta-3dvsxzdo',
+};
+const ADMIN_CREDS_PATH = '/shared-secrets/credentials';
+async function getAdminUserToken(env) {
+    if (adminTokenCache[env])
+        return adminTokenCache[env];
+    let email;
+    let password;
+    if (env === 'cn-prod' || env === 'cn-stage') {
+        // cn Infisical (separate instance; needs INFISICAL_CN_EMAIL/PASSWORD at runtime).
+        const cnTok = (0, db_utils_1.getCnInfisicalToken)();
+        const creds = (0, db_utils_1.getCnSecrets)(cnTok, ADMIN_CREDS_PATH, false, env === 'cn-stage' ? 'staging' : 'prod');
+        email = creds['USER_AUTH_ADMIN_EMAIL'];
+        password = creds['USER_AUTH_ADMIN_PASSWORD'];
+    }
+    else {
+        const cfg = (0, db_utils_1.getInfisicalConfig)();
+        const tok = (0, db_utils_1.getInfisicalToken)(cfg);
+        email = (0, infisical_secrets_1.fetchInfisicalSecret)(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_EMAIL', cfg, tok);
+        password = (0, infisical_secrets_1.fetchInfisicalSecret)(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_PASSWORD', cfg, tok);
+    }
+    if (!email || !password) {
+        throw new Error(`admin 凭证缺失（Infisical ${ADMIN_CREDS_PATH} 的 USER_AUTH_ADMIN_EMAIL/PASSWORD，env=${env}）`);
+    }
+    const clientId = ADMIN_ROPC_CLIENT[env];
+    const authUrl = USER_AUTH_URLS[env];
+    if (!clientId || !authUrl)
+        throw new Error(`Unknown env: ${env}`);
+    // fetch (not execSync curl) so the password never lands in a shell command line.
+    const form = new URLSearchParams({
+        grant_type: 'password',
+        username: email,
+        password,
+        client_id: clientId,
+    });
+    const res = await fetch(`${authUrl}/api/v1/oauth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: form,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`user-auth admin token endpoint returned non-JSON (${env}): ${text.slice(0, 200)}`);
+    }
+    if (!parsed.access_token) {
+        throw new Error(`admin-user token mint failed (${env}): ${text.slice(0, 200)}`);
+    }
+    adminTokenCache[env] = parsed.access_token;
+    return parsed.access_token;
+}
+/**
+ * Authenticated call to user-auth as the admin USER (role=ADMIN), for the
+ * /api/v1/admin/* endpoints that getServiceToken's M2M token can't reach
+ * (ban/unban). Mirrors callService's shape; single retry on 5xx.
+ */
+async function callUserAuthAsAdmin(env, method, path, body) {
+    const authUrl = USER_AUTH_URLS[env];
+    if (!authUrl)
+        throw new Error(`Unknown env: ${env}`);
+    const token = await getAdminUserToken(env);
+    const doFetch = async () => fetch(`${authUrl}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    let res = await doFetch();
+    if (res.status >= 500)
+        res = await doFetch();
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(formatServiceError(res.status, res.statusText, text));
+    }
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        throw new Error(`user-auth admin returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+    }
+    return { status: res.status, body: parsed };
+}
 /**
  * Resolve a user's id by email via user-auth's internal lookup endpoint
  * (POST /api/v1/internal/users/lookup). cn-prod only: AWS envs resolve via
@@ -257,24 +355,6 @@ async function resolveUserIdByEmail(env, email) {
     console.log(`✓ Found user: ${parsed.user_id}`);
     return parsed.user_id;
 }
-/**
- * Resolve email → userId across all envs, picking the path that exists for
- * each cloud. AWS (stage/prod) reaches the database over the RDS SSH tunnel
- * (db-utils.resolveUserId). cn-prod / cn-stage have no tunnel into the Aliyun
- * VPC-internal RDS, so they resolve via user-auth's internal HTTP lookup
- * (resolveUserIdByEmail) — the cn dev-skills token carries the
- * internal:users:write scope that endpoint requires. Lets the entitlement
- * subcommands support cn the same way grant-subscription already does, without
- * each call site re-implementing the branch.
- */
-async function resolveUserIdByEmailAnyEnv(env, email) {
-    if (env === 'cn-prod' || env === 'cn-stage') {
-        return resolveUserIdByEmail(env, email);
-    }
-    const cfg = (0, db_utils_1.getInfisicalConfig)();
-    const token = (0, db_utils_1.getInfisicalToken)(cfg);
-    return (0, db_utils_1.resolveUserId)(email, env, cfg, token);
-}
 /**
  * Resolve a user's id by phone via user-auth's internal lookup endpoint
  * (POST /api/v1/internal/users/lookup with {phone}). Mirrors

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

@@ -3,18 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runGrant = runGrant;
 const billing_http_1 = require("../billing-http");
 const confirm_prompt_1 = require("../confirm-prompt");
+const grant_subscription_1 = require("../grant-subscription");
 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]
+        console.log(`Usage: optima-entitlement grant <email|phone|userId> --product-key <slug> --justification "..." [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
   --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|cn-prod|cn-stage  (default: stage)
+  --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
         process.exit(0);
@@ -25,9 +26,9 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
         const next = argv[i + 1];
         switch (a) {
             case '--email':
-                out.email = next;
+                out.identifier = next;
                 i++;
-                break;
+                break; // back-compat alias for the positional identifier
             case '--product-key':
                 out.productKey = next;
                 i++;
@@ -43,11 +44,16 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
                 out.env = next;
                 i++;
                 break;
-            default: throw new Error(`Unknown arg: ${a}`);
+            default:
+                if (a.startsWith('--'))
+                    throw new Error(`Unknown arg: ${a}`);
+                if (out.identifier)
+                    throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+                out.identifier = a;
         }
     }
-    if (!out.email)
-        throw new Error('--email required');
+    if (!out.identifier)
+        throw new Error('target user required (<email|phone|userId> positional, or --email)');
     if (!out.productKey)
         throw new Error('--product-key required');
     if (!out.justification)
@@ -57,9 +63,11 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
 async function runGrant(argv) {
     const args = parseArgs(argv);
     (0, billing_http_1.validateEnvCnProd)(args.env);
-    const userId = await (0, billing_http_1.resolveUserIdByEmailAnyEnv)(args.env, args.email);
-    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}...`);
+    // Shared resolver: accepts email/phone/userId, reverse-verifies + phone-asserts
+    // on cn-prod, email-only via SSH tunnel on AWS (gateway#923).
+    const { userId } = await (0, grant_subscription_1.resolveTargetUser)(args.env, args.identifier);
+    await (0, confirm_prompt_1.confirmIfProd)(args.env, `Action: GRANT product '${args.productKey}' to ${args.identifier} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`, args.yes);
+    console.log(`\n🎁 Granting ${args.productKey} to ${args.identifier}...`);
     const res = await (0, billing_http_1.callBilling)(args.env, 'POST', '/api/billing/admin/grant-entitlement', {
         userId,
         productKey: args.productKey,

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

@@ -2,15 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runList = runList;
 const billing_http_1 = require("../billing-http");
+const grant_subscription_1 = require("../grant-subscription");
 function parseArgs(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-        console.log(`Usage: optima-entitlement list --email <user-email> [options]
+        console.log(`Usage: optima-entitlement list <email|phone|userId> [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
 
 Optional:
-  --env stage|prod|cn-prod|cn-stage  (default: stage)`);
+  --env stage|prod|cn-prod|cn-stage   (default: stage)`);
         process.exit(0);
     }
     const out = { env: 'stage' };
@@ -19,33 +20,38 @@ Optional:
         const next = argv[i + 1];
         switch (a) {
             case '--email':
-                out.email = next;
+                out.identifier = next;
                 i++;
-                break;
+                break; // back-compat alias for the positional identifier
             case '--env':
                 out.env = next;
                 i++;
                 break;
-            default: throw new Error(`Unknown arg: ${a}`);
+            default:
+                if (a.startsWith('--'))
+                    throw new Error(`Unknown arg: ${a}`);
+                if (out.identifier)
+                    throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+                out.identifier = a;
         }
     }
-    if (!out.email)
-        throw new Error('--email required');
+    if (!out.identifier)
+        throw new Error('target user required (<email|phone|userId> positional, or --email)');
     return out;
 }
 async function runList(argv) {
     const args = parseArgs(argv);
     (0, billing_http_1.validateEnvCnProd)(args.env);
-    const userId = await (0, billing_http_1.resolveUserIdByEmailAnyEnv)(args.env, args.email);
+    const { userId } = await (0, grant_subscription_1.resolveTargetUser)(args.env, args.identifier);
     const res = await (0, billing_http_1.callBilling)(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})`);
+        console.log(`(no entitlements for ${args.identifier} 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(`${rows.length} entitlement(s) for ${args.identifier}:\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) {