@stage5/lumine 0.3.54 → 0.3.55

package/lib/admin-spending.js

@@ -0,0 +1,472 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const round = (value) => {
+  if (!Number.isFinite(value))
+    throw new Error("Invalid computed spending amount.");
+  return Number(value.toFixed(8));
+};
+const USAGE =
+  "lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--json]";
+
+function invalid(message) {
+  return Object.assign(new Error(message), {
+    code: "CLI_ADMIN_CLI_VALIDATION",
+  });
+}
+
+export function buildSpendingOperation(options) {
+  if (
+    (options.positional || []).length !== 1 ||
+    options.adminDays ||
+    options.adminDate ||
+    options.adminAll ||
+    options.adminResume
+  ) {
+    throw invalid(`Usage: ${USAGE}.`);
+  }
+  const query = new URLSearchParams();
+  const values = {
+    month: options.adminSpendingMonth,
+    from: options.adminSpendingFrom,
+    to: options.adminSpendingTo,
+  };
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !/^20\d{2}-(0[1-9]|1[0-2])$/.test(value))
+      throw invalid(`--${key} must use YYYY-MM format.`);
+    query.set(key, value);
+  }
+  if (query.has("month") && (query.has("from") || query.has("to")))
+    throw invalid("Use --month or --from/--to, not both.");
+  if (query.has("from") !== query.has("to"))
+    throw invalid("Provide both --from and --to.");
+  if (query.has("from") && query.get("from") > query.get("to"))
+    throw invalid("--from must not follow --to.");
+  const qs = query.toString();
+  return {
+    name: "spending.report",
+    method: "GET",
+    path: `/cli/admin/spending${qs ? `?${qs}` : ""}`,
+    mutates: false,
+    requiresRun: false,
+    timeoutMs: 60000,
+  };
+}
+
+async function runAws(args, { profile, region, timeoutMs }) {
+  try {
+    const { stdout } = await execFileAsync(
+      "aws",
+      [
+        ...args,
+        "--profile",
+        profile,
+        "--region",
+        region,
+        "--output",
+        "json",
+        "--no-cli-pager",
+      ],
+      {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: 8 * 1024 * 1024,
+        env: { ...process.env, AWS_PAGER: "", AWS_CLI_AUTO_PROMPT: "off" },
+      },
+    );
+    return JSON.parse(stdout);
+  } catch (error) {
+    // Do not expose subprocess stdout, credentials or arbitrary provider error
+    // payloads in a saved financial report.
+    throw new Error(
+      error.code === "ENOENT"
+        ? "AWS CLI is not installed. Install it and configure the requested profile."
+        : `AWS billing could not be read with profile ${profile}; check its authentication and Cost Explorer access.`,
+    );
+  }
+}
+
+function amount(metric) {
+  if (
+    metric?.Unit !== "USD" ||
+    metric.Amount === "" ||
+    metric.Amount == null ||
+    !Number.isFinite(Number(metric.Amount))
+  ) {
+    throw new Error(
+      "AWS returned an invalid amount or a currency other than USD.",
+    );
+  }
+  return Number(metric.Amount);
+}
+
+export function normalizeAwsSpending(pages, months) {
+  const expected = new Map(
+    months
+      .filter((m) => m.startDayKey < m.endDayKeyExclusive)
+      .map((m) => [m.startDayKey, m]),
+  );
+  const found = new Map();
+  for (const page of pages) {
+    if (!Array.isArray(page?.ResultsByTime))
+      throw new Error("AWS returned no billing periods.");
+    for (const period of page.ResultsByTime) {
+      const start = period.TimePeriod?.Start;
+      const requested = expected.get(start);
+      if (
+        !requested ||
+        period.TimePeriod?.End !== requested.endDayKeyExclusive ||
+        typeof period.Estimated !== "boolean"
+      ) {
+        throw new Error(
+          "AWS billing periods do not match the requested UTC months.",
+        );
+      }
+      let target = found.get(start);
+      if (!target) {
+        target = {
+          status: "available",
+          costUsd: 0,
+          estimated: period.Estimated,
+          services: [],
+          startDayKey: start,
+          endDayKeyExclusive: period.TimePeriod.End,
+        };
+        found.set(start, target);
+      }
+      if (
+        target.estimated !== period.Estimated ||
+        !Array.isArray(period.Groups)
+      )
+        throw new Error("Inconsistent AWS billing page.");
+      if (
+        period.Groups.length === 0 &&
+        period.Total?.UnblendedCost &&
+        amount(period.Total.UnblendedCost) !== 0
+      ) {
+        throw new Error("AWS omitted the requested service breakdown.");
+      }
+      for (const group of period.Groups) {
+        if (
+          !Array.isArray(group.Keys) ||
+          group.Keys.length !== 1 ||
+          typeof group.Keys[0] !== "string" ||
+          target.services.some((s) => s.service === group.Keys[0])
+        )
+          throw new Error("Duplicate or invalid AWS service row.");
+        const costUsd = amount(group.Metrics?.UnblendedCost);
+        target.services.push({ service: group.Keys[0], costUsd });
+        target.costUsd += costUsd;
+      }
+    }
+  }
+  if (found.size !== expected.size)
+    throw new Error("AWS billing is missing a requested month.");
+  return months.map((month) => {
+    if (month.startDayKey === month.endDayKeyExclusive)
+      return {
+        status: "no_completed_days",
+        costUsd: 0,
+        estimated: true,
+        services: [],
+        startDayKey: month.startDayKey,
+        endDayKeyExclusive: month.endDayKeyExclusive,
+      };
+    const value = found.get(month.startDayKey);
+    return {
+      ...value,
+      costUsd: round(value.costUsd),
+      services: value.services.sort((a, b) => b.costUsd - a.costUsd),
+    };
+  });
+}
+
+function validateReport(report) {
+  if (
+    report?.schemaVersion !== 1 ||
+    report.currency !== "USD" ||
+    report.timezone !== "UTC" ||
+    !Array.isArray(report.months) ||
+    !report.months.length ||
+    report.months.length > 12 ||
+    !report.sources?.aws ||
+    report.range?.includesInProgressDay !== false
+  ) {
+    throw new Error(
+      "The API did not return a supported spending report; deploy the matching API release.",
+    );
+  }
+  let expectedStart = report.range.startDayKey;
+  for (const month of report.months) {
+    const nextMonth = new Date(
+      Date.UTC(
+        Number(month.monthKey?.slice(0, 4)),
+        Number(month.monthKey?.slice(5, 7)),
+        1,
+      ),
+    )
+      .toISOString()
+      .slice(0, 10);
+    if (
+      !/^20\d{2}-(0[1-9]|1[0-2])$/.test(month.monthKey) ||
+      month.startDayKey !== `${month.monthKey}-01` ||
+      month.startDayKey !== expectedStart ||
+      !/^20\d{2}-\d{2}-\d{2}$/.test(month.endDayKeyExclusive) ||
+      month.endDayKeyExclusive < month.startDayKey ||
+      month.endDayKeyExclusive > nextMonth ||
+      (month.status === "closed" && month.endDayKeyExclusive !== nextMonth) ||
+      (month !== report.months.at(-1) &&
+        month.endDayKeyExclusive !== nextMonth) ||
+      new Date(`${month.endDayKeyExclusive}T00:00:00Z`)
+        .toISOString()
+        .slice(0, 10) !== month.endDayKeyExclusive
+    ) {
+      throw new Error("The API spending report has invalid month boundaries.");
+    }
+    expectedStart = nextMonth;
+    // An available source must supply its amounts. In particular, null paid
+    // totals must never be coerced to zero when combined with operating costs.
+    const required = [
+      ...(month.ai ? [month.ai.grossUsd] : []),
+      ...(month.reimbursements
+        ? [
+            month.reimbursements.aiServiceUsd,
+            month.reimbursements.infrastructureUsd,
+            month.reimbursements.totalUsd,
+          ]
+        : []),
+    ];
+    if (
+      required.some(
+        (value) => typeof value !== "number" || !Number.isFinite(value),
+      )
+    )
+      throw new Error("The API spending report has incomplete source amounts.");
+    for (const value of [
+      month.ai?.grossUsd,
+      month.ai?.creditUsd,
+      month.ai?.estimatedCashUsd,
+      month.reimbursements?.aiServiceUsd,
+      month.reimbursements?.infrastructureUsd,
+      month.reimbursements?.totalUsd,
+    ]) {
+      if (
+        value != null &&
+        (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+      )
+        throw new Error("Invalid spending source amount.");
+    }
+  }
+  if (
+    report.months.at(-1).endDayKeyExclusive !== report.range.endDayKeyExclusive
+  )
+    throw new Error("The API spending report has incomplete month coverage.");
+}
+
+export async function completeSpendingReport(receipt, options, aws = runAws) {
+  if (receipt?.ok !== true) return receipt;
+  const report = receipt.data?.spending;
+  validateReport(report);
+  const warnings = [...(report.warnings || [])];
+  const source = report.sources.aws;
+  const profile = options.adminAwsProfile || source.defaultProfile;
+  if (typeof profile !== "string" || !profile.trim())
+    throw invalid("--aws-profile must name an AWS CLI profile.");
+  let awsMonths = null;
+  let awsError = null;
+  try {
+    const settings = {
+      profile,
+      region: source.region,
+      timeoutMs: Math.max(
+        1000,
+        Math.min(60000, Number(options.timeoutMs) || 30000),
+      ),
+    };
+    const hasCompletedDays =
+      report.range.startDayKey < report.range.endDayKeyExclusive;
+    const pages = [];
+    if (hasCompletedDays) {
+      const identity = await aws(["sts", "get-caller-identity"], settings);
+      if (
+        identity?.Account !== source.accountId ||
+        identity?.Arn !== source.principalArn
+      ) {
+        throw new Error(
+          "AWS identity does not match the Twinkle billing principal. No Cost Explorer query was sent.",
+        );
+      }
+      let token;
+      const seen = new Set();
+      do {
+        if (pages.length >= 100)
+          throw new Error("AWS billing exceeded the pagination limit.");
+        const page = await aws(
+          [
+            "ce",
+            "get-cost-and-usage",
+            "--time-period",
+            `Start=${report.range.startDayKey},End=${report.range.endDayKeyExclusive}`,
+            "--granularity",
+            "MONTHLY",
+            "--metrics",
+            "UnblendedCost",
+            "--group-by",
+            "Type=DIMENSION,Key=SERVICE",
+            "--no-paginate",
+            ...(token ? ["--next-page-token", token] : []),
+          ],
+          settings,
+        );
+        pages.push(page);
+        token = page.NextPageToken;
+        if (token && (typeof token !== "string" || seen.has(token)))
+          throw new Error("AWS billing pagination did not advance.");
+        if (token) seen.add(token);
+      } while (token);
+    }
+    awsMonths = normalizeAwsSpending(pages, report.months);
+  } catch (error) {
+    awsError = error.message;
+    warnings.push(awsError);
+  }
+  const months = report.months.map((month, i) => {
+    const billing = awsMonths?.[i] ?? null;
+    const overlap = month.ai?.awsOverlapDetected === true;
+    if (overlap)
+      warnings.push(
+        `${month.monthKey}: AWS-billed AI detected; combined totals require overlap reconciliation.`,
+      );
+    const operating =
+      month.ai?.estimatedCashUsd != null && billing && !overlap
+        ? round(month.ai.estimatedCashUsd + billing.costUsd)
+        : null;
+    return {
+      ...month,
+      aws: billing,
+      providerOperatingCostUsd: operating,
+      totalIncludingReimbursementsUsd:
+        operating !== null && month.reimbursements
+          ? round(operating + month.reimbursements.totalUsd)
+          : null,
+    };
+  });
+  const complete = months.every(
+    (m) => m.totalIncludingReimbursementsUsd !== null,
+  );
+  const sum = (select) =>
+    months.every((m) => select(m) != null)
+      ? round(months.reduce((n, m) => n + select(m), 0))
+      : null;
+  return {
+    ...receipt,
+    status: complete ? "success" : "partial",
+    data: {
+      ...receipt.data,
+      spending: {
+        ...report,
+        complete,
+        months,
+        warnings,
+        sources: {
+          ...report.sources,
+          aws: {
+            ...source,
+            profile,
+            status: awsMonths ? "available" : "unavailable",
+            error: awsError,
+          },
+        },
+        totals: {
+          aiEstimatedCashUsd: sum((m) => m.ai?.estimatedCashUsd),
+          awsUsd: sum((m) => m.aws?.costUsd),
+          reimbursementsUsd: sum((m) => m.reimbursements?.totalUsd),
+          totalIncludingReimbursementsUsd: sum(
+            (m) => m.totalIncludingReimbursementsUsd,
+          ),
+        },
+      },
+    },
+  };
+}
+
+export function formatSpending(report) {
+  const money = (value) =>
+    value == null
+      ? "Unavailable"
+      : `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  const lines = [
+    `Twinkle spending · USD · UTC · ${report.complete ? "complete sources" : "INCOMPLETE SOURCES"}`,
+  ];
+  const rows = [
+    ["Category", ...report.months.map((m) => m.monthKey)],
+    [
+      "AI after credits",
+      ...report.months.map((m) => money(m.ai?.estimatedCashUsd)),
+    ],
+    ["AWS (including tax)", ...report.months.map((m) => money(m.aws?.costUsd))],
+    [
+      "Reimbursements",
+      ...report.months.map((m) => money(m.reimbursements?.totalUsd)),
+    ],
+    [
+      "TOTAL incl. reimbursements",
+      ...report.months.map((m) => money(m.totalIncludingReimbursementsUsd)),
+    ],
+    ["", ...report.months.map(() => "")],
+    ["AI before credits", ...report.months.map((m) => money(m.ai?.grossUsd))],
+    ["Promotional credit", ...report.months.map((m) => money(m.ai?.creditUsd))],
+    [
+      "Reimbursement: AI service",
+      ...report.months.map((m) => money(m.reimbursements?.aiServiceUsd)),
+    ],
+    [
+      "Reimbursement: infrastructure",
+      ...report.months.map((m) => money(m.reimbursements?.infrastructureUsd)),
+    ],
+  ];
+  const widths = rows[0].map((_, i) =>
+    Math.max(...rows.map((row) => row[i].length)),
+  );
+  lines.push(
+    ...rows.map((row) =>
+      row
+        .map((cell, i) =>
+          i ? cell.padStart(widths[i]) : cell.padEnd(widths[i]),
+        )
+        .join(" | "),
+    ),
+  );
+  for (const month of report.months) {
+    if (month.status === "in_progress")
+      lines.push(
+        `${month.monthKey} AI/AWS: ${month.throughDayKey ? `through ${month.throughDayKey} UTC` : "no completed UTC days"}; current usage day excluded.`,
+      );
+    if (month.aws?.estimated)
+      lines.push(
+        `${month.monthKey} AWS is provisional and may change with billing updates.`,
+      );
+  }
+  lines.push(
+    `Selected-period total: ${money(report.totals.totalIncludingReimbursementsUsd)}`,
+  );
+  lines.push(
+    "AI is a usage-based estimate after credits. AWS estimated flags and service details are in JSON.",
+  );
+  lines.push(
+    "Reimbursements are gross paid amounts by payment date, before refunds/fees; included once in the total above.",
+  );
+  if (report.sources.reimbursements?.includesCurrentDay)
+    lines.push(
+      `Reimbursements include today's settled payments through ${new Date((report.sources.reimbursements.endAtExclusive - 1) * 1000).toISOString()}.`,
+    );
+  if (report.inProgressDay)
+    lines.push(
+      `${report.inProgressDay.dayKey} partial AI usage: ${money(report.inProgressDay.ai?.grossUsd)} before credits, excluded.`,
+    );
+  for (const warning of report.warnings || [])
+    lines.push(`Unavailable: ${warning}`);
+  return lines.join("\n");
+}

package/lib/admin.js

@@ -44,6 +44,7 @@ import {
   printOwnerTrace,
 } from "./admin-owner-trace.js";
 import { buildRolesOperation, printRoles } from "./admin-roles.js";
+import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
 import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
 import {
@@ -1545,7 +1546,10 @@ export async function adminCommand(options) {
         recommendationContentTypes,
         viewFilter,
       });
-    if (operation.featuredWorkflow) {
+    if (operation.name === "spending.report") {
+      result = await completeSpendingReport(await fetchOperation(), options);
+      if (result.status === "partial") process.exitCode = 1;
+    } else if (operation.featuredWorkflow) {
       result = await runFeaturedWorkflow({
         options,
         operation,
@@ -1624,6 +1628,11 @@ export async function adminCommand(options) {
     // private evidence is printed, never kept in the receipt file
     mutationIntent?.confirm(receiptToKeep(operation, result));
   } catch (error) {
+    if (operation.name === "spending.report" && error.status === 404) {
+      error.message = "The spending report API is not deployed yet. Deploy the matching API before using this CLI command.";
+      error.code = "CLI_ADMIN_SPENDING_NOT_DEPLOYED";
+      error.data = { ok: false, status: "unavailable", error: { code: error.code, message: error.message, details: null } };
+    }
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
       error.message =
@@ -4474,6 +4483,8 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "spending") return buildSpendingOperation(options);
+
   if (namespace === "ai-costs") {
     if (action === "monthly" && !target && !extra) {
       if (options.adminDays) {
@@ -7360,6 +7371,10 @@ function printAiBucketRuleResult({ operation, data }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "spending.report" && data.spending) {
+    console.log(formatSpending(data.spending));
+    return;
+  }
   if (operation.name === "math-lab.queue") {
     console.log(`Math Lab: published artifact ${data.publishedArtifactVersionId}, review ${data.reviewId}, day ${data.dayKey} UTC.`);
     for (const grade of data.grades || []) console.log(grade.available

package/lib/commands.js

@@ -2562,6 +2562,13 @@ export function parseArgs(args) {
         );
     }
   }
+  if (command === "admin" && positional[0] === "spending") {
+    const allowed = new Set(["help", "month", "from", "to", "awsProfile", "output", "json",
+      "apiUrl", "siteUrl", "authFile", "authToken", "clientName", "timeoutMs", "noUpdateCheck"]);
+    for (const key of Object.keys(raw)) {
+      if (!allowed.has(key)) throw new Error(`Unsupported spending option --${key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}.`);
+    }
+  }
   const suggestionInboxActions = new Set([
     "list",
     "merge",
@@ -2805,6 +2812,10 @@ export function parseArgs(args) {
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
     adminDays: raw.days ? String(raw.days) : "",
+    adminSpendingMonth: raw.month,
+    adminSpendingFrom: raw.from,
+    adminSpendingTo: raw.to,
+    adminAwsProfile: raw.awsProfile,
     adminMaxStep: raw.maxStep ? String(raw.maxStep) : "",
     adminBuild: raw.build ? String(raw.build) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
@@ -3325,6 +3336,7 @@ export function printHelp() {
     (with both a comment session and a daily run active, comment draft/reply/post/edit need --via session|run)
   lumine admin comment edit <comment-id> --file <comment.md> [--review-receipt <review.json> | --reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--json]
   lumine admin brief [--days <1..30>] [--json]
+  lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--output <file.json>] [--json] (owner spending: AI, AWS, reimbursements; no active run required)
   lumine admin ai-costs monthly [--output <file.json>] [--json] (no active run required)
   lumine admin ai-costs day <YYYY-MM-DD> [--json]
   lumine admin media-costs monthly [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.54",
+  "version": "0.3.55",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -3886,6 +3886,61 @@ input snapshots as described below.
 See `twinkle-api/JEV_PILOT.md` for configuration,
 the synthetic evaluation step and release checks.
 
+### Spending by calendar month
+
+```bash
+lumine admin spending --from 2026-08 --to 2026-10
+lumine admin spending --month 2026-09 --json --output work/spending-september.json
+lumine admin spending --aws-profile <profile> --json
+```
+
+This owner-only read needs no delegated run. With no dates, it reports the
+previous and current UTC calendar months. Use `--month` for one month, or both
+`--from` and `--to` for an inclusive range of up to 12 months. Future months
+are refused. Current-month AI and AWS usage ends at today's UTC midnight;
+today's partial AI usage is returned separately and excluded from totals.
+Paid reimbursements include today's settled payments through the report time.
+Their separate cutoff is explicit in the table and JSON.
+
+The default output is a table separating AI costs after promotional credits,
+AWS infrastructure including tax, and reimbursements, with a combined total.
+It also shows gross AI usage, credits, and AI-service versus infrastructure
+reimbursements. JSON includes provider and AWS-service details and the paid
+invoice references and dates. AI is a usage-based estimate. Credits follow
+the server's private billing policy and account for usage earlier in the same
+credit cycle, even when that usage predates the requested calendar month.
+
+The API supplies the canonical AI ledger and paid reimbursement history.
+Reimbursements use settlement dates, including old invoices paid later, and
+include all known subscription histories and invoice pages. They are gross
+paid amounts, not Stripe fee/refund or bank-payout reconciliation. Failed,
+expired and pending attempts are excluded; no payment or subscription action
+is performed. Reimbursements are a separate category included in the total;
+`providerOperatingCostUsd` also provides AI plus AWS without reimbursements.
+
+AWS reads use the installed AWS CLI and the existing billing profile, or
+`--aws-profile`. The command checks the required account and principal before
+querying Cost Explorer, paginates service groups, validates exact UTC periods
+and USD currency, and preserves provisional billing status. It never changes
+AWS credentials or infrastructure. Cost Explorer's ordinary query fees apply.
+AWS authentication stays local; it is not uploaded to Twinkle.
+
+`data.spending` is versioned with `schemaVersion: 1`. `months` contains each
+month's `ai`, `aws`, `reimbursements`, `providerOperatingCostUsd`, and
+`totalIncludingReimbursementsUsd`; `totals` sums the selected period. Missing
+sources are `null`, never zero. A partial report preserves available data,
+sets `complete: false` and receipt `status: "partial"`, saves with `--output`,
+and exits nonzero. Unknown provider attribution or AWS-billed AI can make a
+combined total unavailable until the credit/overlap is reconciled. Zero usage
+on the first UTC day means no completed days, not a full-month forecast;
+reimbursements paid on that day still contribute to the total.
+
+This report does not replace the existing AI run-rate projections or AWS
+remaining-period forecast required for a full daily-management review.
+Release dependency: deploy the owner-authorized `/cli/admin/spending` API
+before publishing the CLI that calls it. No new database migration, npm
+dependency or server-side AWS permission is required.
+
 ### Application AI calendar-month cost (standing duty, every full daily review)
 
 Run `lumine admin ai-costs monthly --json` during every full daily management