feat: add coding plan usage

packages/cli/src/commands.ts

@@ -46,6 +46,7 @@ import {
   usageStats,
   usageSummary,
   usageTokenPlan,
+  usageCodingPlan,
   pipelineRun,
   pipelineValidate,
   advisorRecommend,
@@ -166,6 +167,7 @@ export const commands: Record<string, AnyCommand> = {
   "usage stats": usageStats,
   "usage summary": usageSummary,
   "usage token-plan": usageTokenPlan,
+  "usage coding-plan": usageCodingPlan,
   "pipeline run": pipelineRun,
   "pipeline validate": pipelineValidate,
   "advisor recommend": advisorRecommend,

packages/commands/src/commands/usage/coding-plan.ts

@@ -0,0 +1,132 @@
+import { defineCommand, detectOutputFormat, unwrapResponse } from "bailian-cli-core";
+import { emitResult } from "bailian-cli-runtime";
+import { printQuotaBox, readNumber, type QuotaSection } from "./quota-box.ts";
+import { formatNumber } from "./shared.ts";
+
+const CODING_PLAN_USAGE_API =
+  "zeldaEasy.broadscope-bailian.codingPlan.queryCodingPlanInstanceInfoV2";
+
+const COMMODITY_CODES: Record<string, string> = {
+  domestic: "sfm_codingplan_public_cn",
+  international: "sfm_codingplan_public_intl",
+};
+
+interface CodingPlanWindow {
+  usedQuota?: number;
+  totalQuota?: number;
+  /** Usage ratio in [0, 1]; absent when the window has no positive total or no used value. */
+  percentage?: number;
+  resetTime?: number;
+}
+
+interface CodingPlanUsage {
+  instanceType?: string;
+  per5Hour: CodingPlanWindow;
+  perWeek: CodingPlanWindow;
+  perBillMonth: CodingPlanWindow;
+}
+
+function readWindow(
+  quotaInfo: Record<string, unknown> | undefined,
+  fieldPrefix: string,
+): CodingPlanWindow {
+  const window: CodingPlanWindow = {};
+  if (!quotaInfo) return window;
+
+  const usedQuota = readNumber(quotaInfo[`${fieldPrefix}UsedQuota`]);
+  if (usedQuota !== undefined) window.usedQuota = usedQuota;
+  const totalQuota = readNumber(quotaInfo[`${fieldPrefix}TotalQuota`]);
+  if (totalQuota !== undefined) window.totalQuota = totalQuota;
+  const resetTime = readNumber(quotaInfo[`${fieldPrefix}QuotaNextRefreshTime`]);
+  if (resetTime !== undefined) window.resetTime = resetTime;
+
+  // Console rule: the usage rate only exists with a positive total and a used value.
+  if (usedQuota !== undefined && totalQuota !== undefined && totalQuota > 0) {
+    window.percentage = usedQuota / totalQuota;
+  }
+  return window;
+}
+
+/** Pick the first VALID instance's quota info, mirroring the Coding Plan console. */
+function readUsage(result: unknown): CodingPlanUsage | undefined {
+  const response = unwrapResponse(result as Record<string, unknown>);
+  const instances = Array.isArray(response.codingPlanInstanceInfos)
+    ? (response.codingPlanInstanceInfos as Record<string, unknown>[])
+    : [];
+  const validInstance = instances.find((instance) => instance.status === "VALID");
+  if (!validInstance) return undefined;
+
+  const quotaInfo = validInstance.codingPlanQuotaInfo as Record<string, unknown> | undefined;
+  const usage: CodingPlanUsage = {
+    per5Hour: readWindow(quotaInfo, "per5Hour"),
+    perWeek: readWindow(quotaInfo, "perWeek"),
+    perBillMonth: readWindow(quotaInfo, "perBillMonth"),
+  };
+  if (typeof validInstance.instanceType === "string" && validInstance.instanceType) {
+    usage.instanceType = validInstance.instanceType;
+  }
+  return usage;
+}
+
+function toSection(label: string, window: CodingPlanWindow): QuotaSection {
+  const section: QuotaSection = {
+    label,
+    emptyMessage: "No quota data for this window; verify in the Bailian Coding Plan console.",
+    percentage: window.percentage,
+    resetTime: window.resetTime,
+  };
+  if (window.usedQuota !== undefined && window.totalQuota !== undefined) {
+    section.detail = `Used: ${formatNumber(window.usedQuota)} / ${formatNumber(window.totalQuota)}`;
+  }
+  return section;
+}
+
+function printView(usage: CodingPlanUsage, generatedAt: number): void {
+  const planSuffix = usage.instanceType ? ` (${usage.instanceType})` : "";
+  printQuotaBox(
+    `Coding Plan Usage${planSuffix}`,
+    [
+      toSection("5-hour quota", usage.per5Hour),
+      toSection("1-week quota", usage.perWeek),
+      toSection("Monthly quota", usage.perBillMonth),
+    ],
+    generatedAt,
+  );
+}
+
+export default defineCommand({
+  description: "Show Coding Plan quota usage",
+  auth: "console",
+  usageArgs: "[flags]",
+  exampleArgs: ["", "--output json"],
+  async run(ctx) {
+    const { settings } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const requestData = {
+      queryCodingPlanInstanceInfoRequest: {
+        commodityCode: COMMODITY_CODES[settings.consoleSite ?? "domestic"],
+        onlyLatestOne: true,
+      },
+    };
+
+    if (settings.dryRun) {
+      emitResult({ api: CODING_PLAN_USAGE_API, data: requestData }, format);
+      return;
+    }
+
+    const result = await ctx.client.console(CODING_PLAN_USAGE_API, requestData);
+    const usage = readUsage(result);
+
+    if (format === "json") {
+      emitResult(usage ?? {}, format);
+      return;
+    }
+
+    if (!usage) {
+      process.stdout.write("No active Coding Plan subscription found.\n");
+      return;
+    }
+
+    printView(usage, Date.now());
+  },
+});

packages/commands/src/commands/usage/quota-box.ts

@@ -0,0 +1,91 @@
+import {
+  ansi,
+  displayWidth,
+  renderGauge,
+  type GaugeCell,
+  type TextStyle,
+} from "bailian-cli-runtime";
+import { formatDateTime } from "./shared.ts";
+
+const BOX_WIDTH = 76;
+
+/** One quota window rendered inside the box: a label + usage ratio + reset time. */
+export interface QuotaSection {
+  label: string;
+  /** Shown instead of the gauge when the usage ratio is absent. */
+  emptyMessage: string;
+  /** Usage ratio in [0, 1]; absent means no data (possibly unlimited). */
+  percentage?: number;
+  resetTime?: number;
+  /** Optional dim line under the gauge, e.g. "Used: 38 / 100". */
+  detail?: string;
+}
+
+/** Accept only finite numbers; anything else counts as absent (possibly unlimited). */
+export function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** Match the `usage free` gauge label style: 0.1% precision, no trailing zeros. */
+function formatPercentage(ratio: number): string {
+  const percent = Math.round(ratio * 1000) / 10;
+  return `${Number.isInteger(percent) ? percent : percent.toFixed(1)}%`;
+}
+
+function formatRemainingTime(resetTime: number, now: number): string {
+  const remainingMs = Math.max(0, resetTime - now);
+  const totalMinutes = Math.floor(remainingMs / 60_000);
+  if (totalMinutes === 0) return "now";
+
+  const days = Math.floor(totalMinutes / (24 * 60));
+  const hours = Math.floor((totalMinutes % (24 * 60)) / 60);
+  const minutes = totalMinutes % 60;
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0 || parts.length === 0) parts.push(`${minutes}m`);
+  return parts.join(" ");
+}
+
+/** Print a bordered quota box with a title line and one gauge per section. */
+export function printQuotaBox(title: string, sections: QuotaSection[], generatedAt: number): void {
+  const color = ansi(process.stdout);
+  const writeLine = (text = "", style?: TextStyle) => {
+    const padding = Math.max(0, BOX_WIDTH - displayWidth(` ${text}`));
+    process.stdout.write(`│ ${style ? style(text) : text}${" ".repeat(padding)}│\n`);
+  };
+  // Pre-colored gauge cell: pad from the plain variant so ANSI escapes never shift the border.
+  const writeGaugeLine = (cell: GaugeCell) => {
+    const padding = Math.max(0, BOX_WIDTH - displayWidth(` ${cell.plain}`));
+    process.stdout.write(`│ ${cell.colored}${" ".repeat(padding)}│\n`);
+  };
+  const writeQuota = (section: QuotaSection) => {
+    writeLine(section.label, color.bold);
+    if (section.percentage === undefined) {
+      writeLine(section.emptyMessage, color.dim);
+      return;
+    }
+
+    const gaugeLabel = `${formatPercentage(section.percentage)} used`;
+    writeGaugeLine(renderGauge(section.percentage * 100, gaugeLabel));
+    if (section.detail) {
+      writeLine(section.detail, color.dim);
+    }
+    if (section.resetTime === undefined) {
+      writeLine("Resets: not applicable (no usage yet)", color.dim);
+      return;
+    }
+
+    const resetText = `Resets: ${formatDateTime(section.resetTime)}  (in ${formatRemainingTime(section.resetTime, generatedAt)})`;
+    writeLine(resetText, color.dim);
+  };
+
+  process.stdout.write(`┌${"─".repeat(BOX_WIDTH)}┐\n`);
+  writeLine(title, color.cyan);
+  writeLine(`Generated at: ${formatDateTime(generatedAt)} (local time)`, color.dim);
+  for (const section of sections) {
+    process.stdout.write(`├${"─".repeat(BOX_WIDTH)}┤\n`);
+    writeQuota(section);
+  }
+  process.stdout.write(`└${"─".repeat(BOX_WIDTH)}┘\n`);
+}

packages/commands/src/commands/usage/token-plan.ts

@@ -1,16 +1,8 @@
 import { defineCommand, detectOutputFormat, unwrapResponse } from "bailian-cli-core";
-import {
-  ansi,
-  displayWidth,
-  emitResult,
-  type AnsiStyles,
-  type TextStyle,
-} from "bailian-cli-runtime";
-import { formatDateTime } from "./shared.ts";
+import { emitResult } from "bailian-cli-runtime";
+import { printQuotaBox, readNumber } from "./quota-box.ts";
 
 const TOKEN_PLAN_USAGE_API = "zeldaHttp.apikeyMgr./tokenplan/personal/api/v2/usage";
-const BOX_WIDTH = 76;
-const PROGRESS_WIDTH = 32;
 
 interface TokenPlanUsage {
   per5HourPercentage?: number;
@@ -19,16 +11,6 @@ interface TokenPlanUsage {
   per1WeekResetTime?: number;
 }
 
-interface QuotaWindow {
-  percentage?: number;
-  resetTime?: number;
-}
-
-/** Accept only finite numbers; anything else counts as absent (possibly unlimited). */
-function readNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
 function readUsage(result: unknown): TokenPlanUsage {
   const response = unwrapResponse(result as Record<string, unknown>);
   const usage: TokenPlanUsage = {};
@@ -45,78 +27,27 @@ function readUsage(result: unknown): TokenPlanUsage {
   return usage;
 }
 
-function formatPercentage(ratio: number): string {
-  return `${(ratio * 100).toFixed(2)}%`;
-}
-
-function formatRemainingTime(resetTime: number, now: number): string {
-  const remainingMs = Math.max(0, resetTime - now);
-  const totalMinutes = Math.floor(remainingMs / 60_000);
-  if (totalMinutes === 0) return "now";
-
-  const days = Math.floor(totalMinutes / (24 * 60));
-  const hours = Math.floor((totalMinutes % (24 * 60)) / 60);
-  const minutes = totalMinutes % 60;
-  const parts: string[] = [];
-  if (days > 0) parts.push(`${days}d`);
-  if (hours > 0) parts.push(`${hours}h`);
-  if (minutes > 0 || parts.length === 0) parts.push(`${minutes}m`);
-  return parts.join(" ");
-}
-
-function progressBar(ratio: number): string {
-  const clampedRatio = Math.min(1, Math.max(0, ratio));
-  const filled = Math.round(clampedRatio * PROGRESS_WIDTH);
-  return `[${"█".repeat(filled)}${"░".repeat(PROGRESS_WIDTH - filled)}]`;
-}
-
-function progressStyle(percentage: number, color: AnsiStyles): TextStyle {
-  if (percentage >= 0.9) return color.red;
-  if (percentage >= 0.75) return color.yellow;
-  return color.green;
-}
-
 function printView(usage: TokenPlanUsage, generatedAt: number): void {
-  const color = ansi(process.stdout);
-  const writeLine = (text = "", style?: TextStyle) => {
-    const padding = Math.max(0, BOX_WIDTH - displayWidth(` ${text}`));
-    process.stdout.write(`│ ${style ? style(text) : text}${" ".repeat(padding)}│\n`);
-  };
-  const writeQuota = (label: string, unlimitedMessage: string, window: QuotaWindow) => {
-    writeLine(label, color.bold);
-    if (window.percentage === undefined) {
-      writeLine(unlimitedMessage, color.dim);
-      return;
-    }
-
-    const percentageText = formatPercentage(window.percentage);
-    const bar = progressBar(window.percentage);
-    writeLine(`${percentageText} used   ${bar}`, progressStyle(window.percentage, color));
-    if (window.resetTime === undefined) {
-      writeLine("Resets: not applicable (no usage yet)", color.dim);
-      return;
-    }
-
-    const resetText = `Resets: ${formatDateTime(window.resetTime)}  (in ${formatRemainingTime(window.resetTime, generatedAt)})`;
-    writeLine(resetText, color.dim);
-  };
-
-  process.stdout.write(`┌${"─".repeat(BOX_WIDTH)}┐\n`);
-  writeLine("Token Plan Usage", color.cyan);
-  writeLine(`Generated at: ${formatDateTime(generatedAt)} (local time)`, color.dim);
-  process.stdout.write(`├${"─".repeat(BOX_WIDTH)}┤\n`);
-  writeQuota(
-    "5-hour quota",
-    "The 5-hour limit may be unlimited; verify in the Bailian Token Plan console.",
-    { percentage: usage.per5HourPercentage, resetTime: usage.per5HourResetTime },
-  );
-  process.stdout.write(`├${"─".repeat(BOX_WIDTH)}┤\n`);
-  writeQuota(
-    "1-week quota",
-    "The 1-week limit may be unlimited; verify in the Bailian Token Plan console.",
-    { percentage: usage.per1WeekPercentage, resetTime: usage.per1WeekResetTime },
+  printQuotaBox(
+    "Token Plan Usage",
+    [
+      {
+        label: "5-hour quota",
+        emptyMessage:
+          "The 5-hour limit may be unlimited; verify in the Bailian Token Plan console.",
+        percentage: usage.per5HourPercentage,
+        resetTime: usage.per5HourResetTime,
+      },
+      {
+        label: "1-week quota",
+        emptyMessage:
+          "The 1-week limit may be unlimited; verify in the Bailian Token Plan console.",
+        percentage: usage.per1WeekPercentage,
+        resetTime: usage.per1WeekResetTime,
+      },
+    ],
+    generatedAt,
   );
-  process.stdout.write(`└${"─".repeat(BOX_WIDTH)}┘\n`);
 }
 
 export default defineCommand({

packages/commands/src/index.ts

@@ -49,6 +49,7 @@ export { default as usageFreetier } from "./commands/usage/freetier.ts";
 export { default as usageStats } from "./commands/usage/stats.ts";
 export { default as usageSummary } from "./commands/usage/summary.ts";
 export { default as usageTokenPlan } from "./commands/usage/token-plan.ts";
+export { default as usageCodingPlan } from "./commands/usage/coding-plan.ts";
 export { default as pipelineRun } from "./commands/pipeline/run.ts";
 export { default as pipelineValidate } from "./commands/pipeline/validate.ts";
 export { default as advisorRecommend } from "./commands/advisor/recommend.ts";