@optima-chat/dev-skills 0.16.6 → 0.16.7

package/bin/helpers/entitlement/grant.ts

@@ -1,12 +1,14 @@
 import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 import { resolveTargetUser } from '../grant-subscription';
+import { operatorActorId } from '../operator';
 
 interface GrantArgs {
   identifier: string;
   productKey: string;
   justification: string;
   yes: boolean;
+  operator?: string;
   env: string;
 }
 
@@ -21,6 +23,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
@@ -35,6 +38,7 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
       case '--product-key': out.productKey = next; i++; break;
       case '--justification': out.justification = next; i++; break;
       case '--yes': out.yes = true; break;
+      case '--operator': out.operator = next; i++; break;
       case '--env': out.env = next; i++; break;
       default:
         if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
@@ -67,6 +71,7 @@ export async function runGrant(argv: string[]): Promise<void> {
     userId,
     productKey: args.productKey,
     justification: args.justification,
+    actorUserId: operatorActorId(args.operator ?? null),
   });
   console.log(`✓ Granted entitlement (HTTP ${res.status}):`);
   console.log(JSON.stringify(res.body, null, 2));

package/bin/helpers/entitlement/revoke.ts

@@ -1,12 +1,14 @@
 import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
 import { resolveTargetUser } from '../grant-subscription';
+import { operatorActorId } from '../operator';
 
 interface RevokeArgs {
   identifier: string;
   productKey: string;
   reason: string;
   yes: boolean;
+  operator?: string;
   env: string;
 }
 
@@ -28,6 +30,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
@@ -43,6 +46,7 @@ error pointing to the right reversal flow.`);
       case '--product-key': out.productKey = next; i++; break;
       case '--reason': out.reason = next; i++; break;
       case '--yes': out.yes = true; break;
+      case '--operator': out.operator = next; i++; break;
       case '--env': out.env = next; i++; break;
       default:
         if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
@@ -111,6 +115,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
     entitlementId: target.id,
     refundReason: args.reason,
     refundAmountCents: 0,
+    actorUserId: operatorActorId(args.operator ?? null),
   });
   console.log(`✓ Revoked entitlement (HTTP ${res.status}):`);
   console.log(JSON.stringify(res.body, null, 2));

package/bin/helpers/grant-credits.ts

@@ -10,6 +10,7 @@
 import { basename } from 'path';
 import { randomUUID } from 'crypto';
 import { callBilling, validateEnvCnProd } from './billing-http';
+import { operatorActorId } from './operator';
 import { resolveTargetUser } from './grant-subscription';
 
 const CREDITS_PER_USD = 700;
@@ -19,6 +20,7 @@ interface Parsed {
   credits: number | null;
   amountUsd: number | null;
   description: string | null;
+  operator: string | null;
   env: string;
 }
 
@@ -36,6 +38,7 @@ Options:
   --credits <n>         Credits to grant (integer >= 1). Primary unit.
   --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
   --description <text>  Description for audit trail (optional)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help            Show this help
 
@@ -50,12 +53,14 @@ Examples:
   let credits: number | null = null;
   let amountUsd: number | null = null;
   let description: string | null = null;
+  let operator: string | null = null;
   let env = 'stage';
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--credits' && args[i + 1]) { credits = parseInt(args[++i], 10); }
     else if (args[i] === '--amount' && args[i + 1]) { amountUsd = parseFloat(args[++i]); }
     else if (args[i] === '--description' && args[i + 1]) { description = args[++i]; }
+    else if (args[i] === '--operator' && args[i + 1]) { operator = args[++i]; }
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
@@ -74,7 +79,7 @@ Examples:
   }
   validateEnvCnProd(env);
 
-  return { identifier, credits, amountUsd, description, env };
+  return { identifier, credits, amountUsd, description, operator, env };
 }
 
 async function main() {
@@ -83,7 +88,7 @@ async function main() {
     console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
   }
 
-  const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+  const { identifier, credits, amountUsd, description, operator, env } = parseArgs(process.argv.slice(2));
 
   const creditsDisplay = credits ?? Math.round((amountUsd as number) * CREDITS_PER_USD);
   console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
@@ -105,6 +110,7 @@ async function main() {
       userId,
       ...amountField,
       description: description ?? undefined,
+      actorUserId: operatorActorId(operator),
       idempotencyKey: `dev-skills-grant:${randomUUID()}`,
     },
   );

package/bin/helpers/grant-subscription.ts

@@ -11,6 +11,7 @@ import {
   getUserById,
   validateEnvCnProd,
 } from './billing-http';
+import { operatorActorId } from './operator';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -76,7 +77,7 @@ const PLANS_BY_ENV: Record<string, string[]> = {
   'cn-stage': ['trial', 'starter', 'pro', 'enterprise', 'free'],
 };
 
-function parseArgs(args: string[]): { identifier: string; plan: string; months: number; env: string } {
+function parseArgs(args: string[]): { identifier: string; plan: string; months: number; operator: string | null; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     console.log(`Usage: optima-grant-subscription <email|phone|userId> [options]
 
@@ -85,6 +86,7 @@ Options:
                     cn-prod/cn-stage additionally allow: free
                     (legacy *-cn ids are accepted and normalized to canonical)
   --months <n>      Duration in months (default: 1)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>       Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help        Show this help`);
     process.exit(0);
@@ -93,11 +95,13 @@ Options:
   const identifier = args[0];
   let plan: string | null = null;
   let months = 1;
+  let operator: string | null = null;
   let env = 'stage';
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--plan' && args[i + 1]) { plan = args[++i]; }
     else if (args[i] === '--months' && args[i + 1]) { months = parseInt(args[++i], 10); }
+    else if (args[i] === '--operator' && args[i + 1]) { operator = args[++i]; }
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
@@ -113,7 +117,7 @@ Options:
   }
   if (months < 1) { console.error('Months must be >= 1'); process.exit(1); }
 
-  return { identifier, plan, months, env };
+  return { identifier, plan, months, operator, env };
 }
 
 /**
@@ -181,7 +185,7 @@ export async function resolveTargetUser(
 }
 
 async function main() {
-  const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
+  const { identifier, plan, months, operator, env } = parseArgs(process.argv.slice(2));
 
   console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${classifyIdentifier(identifier)}) for ${months} month(s) [${env.toUpperCase()}]\n`);
 
@@ -198,7 +202,7 @@ async function main() {
     weeklyTokenLimit: number;
     expiresAt: string;
     warning?: string;
-  }>(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months });
+  }>(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months, actorUserId: operatorActorId(operator) });
 
   console.log(`✓ Subscription ${body.subscriptionId} (${body.planId})`);
   console.log(`✓ Credits: ${body.credits.toLocaleString()} (expires ${body.expiresAt})`);

package/bin/helpers/operator.ts

@@ -0,0 +1,9 @@
+import { userInfo } from 'os';
+
+// #429（Owner 拍板 3）：CLI 发放族自报操作者——informational，billing 信任 allowlist client
+// 自述（actor 不参与授权）；不带 --operator 时回退本机用户名。缺省链最终兜底在 billing
+// 侧（channel=client_id）。格式：dev-skills:<name>。
+export function operatorActorId(operatorFlag?: string | null): string {
+  const name = (operatorFlag ?? '').trim() || userInfo().username;
+  return `dev-skills:${name}`;
+}

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

@@ -4,6 +4,7 @@ exports.runGrant = runGrant;
 const billing_http_1 = require("../billing-http");
 const confirm_prompt_1 = require("../confirm-prompt");
 const grant_subscription_1 = require("../grant-subscription");
+const operator_1 = require("../operator");
 function parseArgs(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.log(`Usage: optima-entitlement grant <email|phone|userId> --product-key <slug> --justification "..." [options]
@@ -15,6 +16,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
@@ -40,6 +42,10 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
             case '--yes':
                 out.yes = true;
                 break;
+            case '--operator':
+                out.operator = next;
+                i++;
+                break;
             case '--env':
                 out.env = next;
                 i++;
@@ -72,6 +78,7 @@ async function runGrant(argv) {
         userId,
         productKey: args.productKey,
         justification: args.justification,
+        actorUserId: (0, operator_1.operatorActorId)(args.operator ?? null),
     });
     console.log(`✓ Granted entitlement (HTTP ${res.status}):`);
     console.log(JSON.stringify(res.body, null, 2));

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

@@ -4,6 +4,7 @@ exports.runRevoke = runRevoke;
 const billing_http_1 = require("../billing-http");
 const confirm_prompt_1 = require("../confirm-prompt");
 const grant_subscription_1 = require("../grant-subscription");
+const operator_1 = require("../operator");
 function parseArgs(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.log(`Usage: optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..." [options]
@@ -15,6 +16,7 @@ Required:
 
 Optional:
   --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
@@ -41,6 +43,10 @@ error pointing to the right reversal flow.`);
             case '--yes':
                 out.yes = true;
                 break;
+            case '--operator':
+                out.operator = next;
+                i++;
+                break;
             case '--env':
                 out.env = next;
                 i++;
@@ -102,6 +108,7 @@ async function runRevoke(argv) {
         entitlementId: target.id,
         refundReason: args.reason,
         refundAmountCents: 0,
+        actorUserId: (0, operator_1.operatorActorId)(args.operator ?? null),
     });
     console.log(`✓ Revoked entitlement (HTTP ${res.status}):`);
     console.log(JSON.stringify(res.body, null, 2));

package/dist/bin/helpers/grant-credits.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = require("path");
 const crypto_1 = require("crypto");
 const billing_http_1 = require("./billing-http");
+const operator_1 = require("./operator");
 const grant_subscription_1 = require("./grant-subscription");
 const CREDITS_PER_USD = 700;
 function parseArgs(args) {
@@ -27,6 +28,7 @@ Options:
   --credits <n>         Credits to grant (integer >= 1). Primary unit.
   --amount <usd>        Alt: grant by USD ($1 = ${CREDITS_PER_USD} credits). Provide exactly one of --credits / --amount.
   --description <text>  Description for audit trail (optional)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>           Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help            Show this help
 
@@ -40,6 +42,7 @@ Examples:
     let credits = null;
     let amountUsd = null;
     let description = null;
+    let operator = null;
     let env = 'stage';
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--credits' && args[i + 1]) {
@@ -51,6 +54,9 @@ Examples:
         else if (args[i] === '--description' && args[i + 1]) {
             description = args[++i];
         }
+        else if (args[i] === '--operator' && args[i + 1]) {
+            operator = args[++i];
+        }
         else if (args[i] === '--env' && args[i + 1]) {
             env = args[++i];
         }
@@ -69,14 +75,14 @@ Examples:
         process.exit(1);
     }
     (0, billing_http_1.validateEnvCnProd)(env);
-    return { identifier, credits, amountUsd, description, env };
+    return { identifier, credits, amountUsd, description, operator, env };
 }
 async function main() {
     // Deprecation notice when invoked via the legacy alias `optima-grant-balance`.
     if ((0, path_1.basename)(process.argv[1] || '').includes('grant-balance')) {
         console.warn('⚠️  optima-grant-balance 已更名为 optima-grant-credits（P15 钱包退役后回归积分）。请改用 `optima-grant-credits --credits <n>`；本别名仍可用，后续弃用。\n');
     }
-    const { identifier, credits, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+    const { identifier, credits, amountUsd, description, operator, env } = parseArgs(process.argv.slice(2));
     const creditsDisplay = credits ?? Math.round(amountUsd * CREDITS_PER_USD);
     console.log(`\n🎁 Granting ${creditsDisplay} credits${amountUsd !== null ? ` ($${amountUsd.toFixed(2)})` : ''} to ${identifier} [${env.toUpperCase()}]\n`);
     if (description)
@@ -93,6 +99,7 @@ async function main() {
         userId,
         ...amountField,
         description: description ?? undefined,
+        actorUserId: (0, operator_1.operatorActorId)(operator),
         idempotencyKey: `dev-skills-grant:${(0, crypto_1.randomUUID)()}`,
     });
     console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);

package/dist/bin/helpers/grant-subscription.js

@@ -10,6 +10,7 @@ exports.resolveTargetUser = resolveTargetUser;
 // 业务体：supersede 旧授予 + 实得 credits + token quota，重试双发不双倍）。
 const db_utils_1 = require("./db-utils");
 const billing_http_1 = require("./billing-http");
+const operator_1 = require("./operator");
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Auto-detect what kind of identifier the operator passed. gateway#923: a
@@ -79,6 +80,7 @@ Options:
                     cn-prod/cn-stage additionally allow: free
                     (legacy *-cn ids are accepted and normalized to canonical)
   --months <n>      Duration in months (default: 1)
+  --operator <name>       Operator self-report for billing audit (default: local username)
   --env <env>       Environment: stage, prod, cn-prod, cn-stage (default: stage)
   -h, --help        Show this help`);
         process.exit(0);
@@ -86,6 +88,7 @@ Options:
     const identifier = args[0];
     let plan = null;
     let months = 1;
+    let operator = null;
     let env = 'stage';
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--plan' && args[i + 1]) {
@@ -94,6 +97,9 @@ Options:
         else if (args[i] === '--months' && args[i + 1]) {
             months = parseInt(args[++i], 10);
         }
+        else if (args[i] === '--operator' && args[i + 1]) {
+            operator = args[++i];
+        }
         else if (args[i] === '--env' && args[i + 1]) {
             env = args[++i];
         }
@@ -112,7 +118,7 @@ Options:
         console.error('Months must be >= 1');
         process.exit(1);
     }
-    return { identifier, plan, months, env };
+    return { identifier, plan, months, operator, env };
 }
 /**
  * Resolve a CLI identifier (`<email|phone|userId>`) to a userId + verified
@@ -167,12 +173,12 @@ async function resolveTargetUser(env, identifier) {
     return { userId, kind, identity: { phone: null, email: identifier } };
 }
 async function main() {
-    const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
+    const { identifier, plan, months, operator, env } = parseArgs(process.argv.slice(2));
     console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${classifyIdentifier(identifier)}) for ${months} month(s) [${env.toUpperCase()}]\n`);
     // Shared resolver: classify → resolve → reverse-verify echo → phone-assert
     // (cn-prod/cn-stage), or email-only via SSH tunnel (AWS). See resolveTargetUser.
     const { userId, identity } = await resolveTargetUser(env, identifier);
-    const { body } = await (0, billing_http_1.callBilling)(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months });
+    const { body } = await (0, billing_http_1.callBilling)(env, 'POST', '/api/billing/admin/grant-subscription', { userId, planId: plan, months, actorUserId: (0, operator_1.operatorActorId)(operator) });
     console.log(`✓ Subscription ${body.subscriptionId} (${body.planId})`);
     console.log(`✓ Credits: ${body.credits.toLocaleString()} (expires ${body.expiresAt})`);
     console.log(`✓ Token limits: session ${body.sessionTokenLimit.toLocaleString()} / weekly ${body.weeklyTokenLimit.toLocaleString()}`);

package/dist/bin/helpers/operator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorActorId = operatorActorId;
+const os_1 = require("os");
+// #429（Owner 拍板 3）：CLI 发放族自报操作者——informational，billing 信任 allowlist client
+// 自述（actor 不参与授权）；不带 --operator 时回退本机用户名。缺省链最终兜底在 billing
+// 侧（channel=client_id）。格式：dev-skills:<name>。
+function operatorActorId(operatorFlag) {
+    const name = (operatorFlag ?? '').trim() || (0, os_1.userInfo)().username;
+    return `dev-skills:${name}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.16.6",
+  "version": "0.16.7",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {