@indigoai-us/hq-cli 5.122.2 → 5.123.1

package/dist/commands/whoami.js

@@ -5,7 +5,7 @@ import chalk from 'chalk';
 import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
 import { ensureCognitoToken, loadMachineCachedTokens, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
-import { colorizePlanLimitNotice, fetchPlanLockStatus, renderPlanLine, renderPlanLimitNotice, } from "../lib/billing/plan-lock.js";
+import { colorizePlanLimitNotice, fetchPlanLimitStatus, renderPlanLine, renderPlanLimitNotice, } from "../lib/billing/plan-lock.js";
 /**
  * Resolves the person represented by an ID token without pairing a delegated
  * email with the token subject of the delegating machine.
@@ -42,27 +42,27 @@ function peekIdToken(idToken) {
     };
 }
 /**
- * starter-plan-hard-limits / US-011 — read the workspace plan lock for
- * `--company <slug>`.
+ * starter-plan-hard-limits / US-011 — read the workspace plan-limit nag for
+ * `--company <slug>` (the bind notice).
  *
- * hq-pro owns the decision (`planLock` on GET /membership/me); this only reads
- * it. Best-effort by construction: no session, a network failure, an older
- * backend that sends no `planLock`, or a company the caller is not a member of
- * all resolve to null — reported as UNKNOWN and rendered as nothing, never as
- * a guessed lock or a guessed all-clear, and never as a command failure. The
- * command exists to answer "who am I"; the plan line is decoration on top.
+ * hq-pro owns the numbers (`GET /v1/billing/usage-limits`); this only reads
+ * them. Best-effort by construction: no session, a network failure, or a
+ * company the caller is not a member of all resolve to null — reported as
+ * UNKNOWN and rendered as nothing, never as a guessed over-limit or a guessed
+ * all-clear, and never as a command failure. The command exists to answer
+ * "who am I"; the plan line is decoration on top.
  */
-async function readPlanLock(company) {
+async function readPlanLimits(company) {
     const slug = company?.trim();
     if (!slug)
         return null;
     try {
         // NEVER interactive: this runs inside `--json` (before the authenticated
-        // check) and inside hq-core's per-turn plan-lock refresh hook. With the
+        // check) and inside hq-core's per-turn plan-limit refresh hook. With the
         // default `interactive: true`, a box with no cached session would launch a
         // browser sign-in and block the caller instead of resolving to UNKNOWN.
         const token = await ensureCognitoToken({ interactive: false });
-        return await fetchPlanLockStatus(token, slug);
+        return await fetchPlanLimitStatus(token, slug);
     }
     catch {
         return null;
@@ -74,13 +74,13 @@ async function readPlanLock(company) {
  * orientation when it is Starter and healthy, and nothing at all otherwise.
  */
 export function renderWhoamiPlanBlock(status) {
-    if (status.lock.locked) {
+    if (status.over) {
         return colorizePlanLimitNotice(renderPlanLimitNotice(status));
     }
     return renderPlanLine(status);
 }
 async function printPlanBlock(company) {
-    const status = await readPlanLock(company);
+    const status = await readPlanLimits(company);
     if (!status)
         return;
     const block = renderWhoamiPlanBlock(status);
@@ -92,7 +92,7 @@ export function registerWhoamiCommand(program) {
         .command('whoami')
         .description('Show the currently authenticated user')
         .option('--json', 'Output identity metadata as JSON (never tokens)')
-        .option('--company <slug>', 'Also report this company\'s workspace plan state (Starter lock)')
+        .option('--company <slug>', 'Also report this company\'s workspace plan state (Starter nag)')
         .action(async (opts) => {
         try {
             // Effective source (same as auth status / ensureCognitoToken): env
@@ -115,9 +115,8 @@ export function registerWhoamiCommand(program) {
                 const agentUid = machineCreds?.entityUid !== undefined
                     ? (machineCreds.entityUid.startsWith('agt_') ? machineCreds.entityUid : null)
                     : boundLegacyAgent;
-                // planLock is additive: absent-or-null means UNKNOWN, which is what
-                // every consumer already sees from a backend that predates it.
-                const planLock = await readPlanLock(opts.company);
+                // planLimits is additive: absent-or-null means UNKNOWN.
+                const planLimits = await readPlanLimits(opts.company);
                 console.log(JSON.stringify({
                     schemaVersion: 1,
                     authenticated: machine ? Boolean(machineCreds) : Boolean(cached && !isExpiring(cached, 0)),
@@ -126,7 +125,7 @@ export function registerWhoamiCommand(program) {
                     personUid: !machine && identity.entityType === 'person' ? identity.entityUid ?? null : null,
                     agentUid,
                     username: machineCreds?.username ?? null,
-                    planLock,
+                    planLimits,
                 }, null, 2));
                 return;
             }

package/dist/lib/billing/plan-lock.d.ts

@@ -1,65 +1,58 @@
 /**
- * `plan-lock` (starter-plan-hard-limits / US-011, rewritten for US-036) — the
- * CLI-side read + render of a workspace's Starter plan-limit state.
+ * CLI-side read + render of a workspace's Starter plan-limit nag
+ * (starter-plan-hard-limits / US-011, rewritten for US-036, then US-040).
  *
  * Starter (free) workspaces are capped on members, integrations, secrets and
  * agents (deployments and storage nag but never arm a stop). Going over does
  * NOT stop the workspace working (US-033 owner decision 12): everything that
  * exists keeps working, and the only two things that pause are adding new
  * files to the vault and adding new secrets (owner decision 13). Every string
- * this module renders is a nag, never a claim that HQ has stopped. The state
- * is NOT decided here — hq-pro is the single source of truth and ships the
- * answer on `GET /membership/me` as a per-company `planLock` object. This
- * module only reads that field and renders it.
+ * this module renders is a nag, never a claim that HQ has stopped.
+ *
+ * US-040: hq-pro no longer attaches `planLock` on `/membership/me` or
+ * `/v1/billing/usage-limits`. This module reads the nag payload from
+ * usage-limits (`planLimits` resource rows, top-level `freeMonth`,
+ * `upgradeUrl`) and never a lock object.
  *
  * Copy rule (US-036): no string a customer reads may contain "locked" or
  * "read-only". `plan-lock.test.ts` scans every rendered string for both.
  *
- * Member counts are decoration, never a second opinion: the count comes from
- * `GET /v1/billing/usage-limits` on a best-effort basis and its absence only
- * removes the "n of 5" detail from the notice. An absent field is UNKNOWN, so
- * nothing here ever infers a lock (or an unlock) from missing data
- * (hq-absent-field-never-means-constraining-value).
+ * An absent field is UNKNOWN, so nothing here ever infers over-limit from
+ * missing data (hq-absent-field-never-means-constraining-value).
  */
 /**
- * Mirror of hq-pro's `PlanLockReason`. Owner decision 7 (2026-09-17) fixes the
- * nagging set at these four: `deployments` and `storageBytes` are nag-only and
- * never appear here. An unrecognised reason is dropped by `parsePlanLock`, so a
- * server that adds a fifth dimension renders as the generic line rather than as
- * a false claim about members.
+ * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
+ * fixes the nagging set at these four: `deployments` and `storageBytes` are
+ * nag-only and never appear here.
  */
+export declare const PLAN_LIMIT_REASONS: readonly ["users", "integrations", "secrets", "agents"];
+/** @deprecated US-040 — alias of {@link PLAN_LIMIT_REASONS}. */
 export declare const PLAN_LOCK_REASONS: readonly ["users", "integrations", "secrets", "agents"];
-export type PlanLockReason = (typeof PLAN_LOCK_REASONS)[number];
-/** Mirror of hq-pro's `PlanLock` wire shape (see src/billing/plan-lock.ts). */
-export interface PlanLock {
-    locked: boolean;
-    reasons: PlanLockReason[];
-    upgradeUrl: string;
-    fixOptions: PlanLockFixOptions;
-}
-/**
- * The remedies hq-pro ships with the lock. The two original fields are always
- * present (defaulted when the server omits them) because shipped copy reads
- * them unconditionally; every dimension added since is optional, so an older
- * server simply leaves it absent and the renderer quotes the Starter cap.
- */
-export interface PlanLockFixOptions {
-    removeMembersTo: number;
-    disconnectIntegrations: boolean;
-    disconnectIntegrationsTo?: number;
-    removeSecretsTo?: number;
-    deprovisionAgentsTo?: number;
-}
+export type PlanLimitReason = (typeof PLAN_LIMIT_REASONS)[number];
+/** @deprecated US-040 — alias of {@link PlanLimitReason}. */
+export type PlanLockReason = PlanLimitReason;
 /** Optional member decoration for the notice ("7 of 5 members"). */
-export interface PlanLockMembers {
+export interface PlanLimitMembers {
     used: number;
     limit: number;
 }
-export interface PlanLockStatus {
+/** @deprecated US-040 — alias of {@link PlanLimitMembers}. */
+export type PlanLockMembers = PlanLimitMembers;
+export interface PlanLimitFreeMonth {
+    eligible: boolean;
+    trialDays?: number;
+    url?: string;
+}
+export interface PlanLimitStatus {
     companySlug: string;
     companyUid?: string;
-    lock: PlanLock;
-    members?: PlanLockMembers;
+    /** True when any named dimension is over its cap. */
+    over: boolean;
+    reasons: PlanLimitReason[];
+    members?: PlanLimitMembers;
+    usages: Partial<Record<PlanLimitReason, PlanLimitMembers>>;
+    upgradeUrl: string;
+    freeMonth?: PlanLimitFreeMonth;
     /**
      * Resolved plan id, when the usage endpoint answered. UNKNOWN (absent) when
      * it did not — surfaces that gate on "is this Starter?" must then stay
@@ -68,51 +61,53 @@ export interface PlanLockStatus {
     plan?: "free" | "paid" | "enterprise";
     checkedAt: string;
 }
-/** Starter member cap quoted when the server did not send `removeMembersTo`. */
+/** @deprecated US-040 — alias of {@link PlanLimitStatus}. */
+export type PlanLockStatus = PlanLimitStatus;
+/** Starter member cap quoted when the server did not send a users.limit. */
 export declare const STARTER_MEMBER_TARGET = 5;
 /**
- * Starter integration cap quoted when the server did not send
- * `disconnectIntegrationsTo`. One: Starter includes a single integration
- * (US-020 owner decision 11, 2026-09-17 — it was zero before that).
+ * Starter integration cap quoted when the server did not send a limit.
+ * One: Starter includes a single integration (US-020 owner decision 11).
  */
 export declare const STARTER_INTEGRATION_TARGET = 1;
-/** Starter secret cap quoted when the server did not send `removeSecretsTo`. */
+/** Starter secret cap quoted when the server did not send a secrets.limit. */
 export declare const STARTER_SECRET_TARGET = 10;
-/** Starter agent cap quoted when the server did not send `deprovisionAgentsTo`. */
+/** Starter agent cap quoted when the server did not send an agents.limit. */
 export declare const STARTER_AGENT_TARGET = 0;
 /** Upgrade destination quoted when the server did not send one. */
 export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
-/** The paid plan the lock wall sends owners to. Copy lives in ONE place. */
+/** The paid plan the nag sends owners to. Copy lives in ONE place. */
 export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
-/**
- * Defensively parse a `planLock` payload. Anything malformed returns null —
- * the caller then behaves exactly as if the server had sent nothing, which is
- * "unknown", not "locked".
- */
-export declare function parsePlanLock(value: unknown): PlanLock | null;
+export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
- * `/membership/me` body and return its parsed lock. No matching row — or no
- * `planLock` on it — is UNKNOWN, so this returns null rather than guessing.
+ * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.
  */
-export declare function selectPlanLock(body: unknown, companyRef: string): {
-    lock: PlanLock;
+export declare function selectCompanyMembership(body: unknown, companyRef: string): {
     companyUid?: string;
 } | null;
 /** Parse the resolved plan id out of a usage-limits body. Absent → null. */
 export declare function selectPlan(body: unknown): "free" | "paid" | "enterprise" | null;
 /** Parse the `users` dimension out of a usage-limits body. Absent → null. */
-export declare function selectMemberUsage(body: unknown): PlanLockMembers | null;
+export declare function selectMemberUsage(body: unknown): PlanLimitMembers | null;
+/**
+ * Read over-limit dimensions from a usage-limits body. `planLimits` nested
+ * map is preferred when present; otherwise the top-level resource rows.
+ */
+export declare function selectOverReasons(body: unknown): PlanLimitReason[];
+export declare function selectUsages(body: unknown): Partial<Record<PlanLimitReason, PlanLimitMembers>>;
 /**
- * Read the live lock for one company: `planLock` from `/membership/me`, plus a
- * best-effort member count for the notice. Returns null when the server did not
- * answer with a lock for this company — callers must then say nothing.
+ * Read the live nag for one company from usage-limits. `/membership/me` is
+ * used only to resolve slug → companyUid. Returns null when the server did
+ * not answer for this company — callers must then say nothing.
  */
-export declare function fetchPlanLockStatus(token: string, companyRef: string, opts?: {
+export declare function fetchPlanLimitStatus(token: string, companyRef: string, opts?: {
     timeoutMs?: number;
-}): Promise<PlanLockStatus | null>;
+}): Promise<PlanLimitStatus | null>;
+/** @deprecated US-040 — alias of {@link fetchPlanLimitStatus}. */
+export declare const fetchPlanLockStatus: typeof fetchPlanLimitStatus;
 /** Why the workspace is over, one clause per reason. */
-export declare function reasonLabel(reason: PlanLockReason): string;
+export declare function reasonLabel(reason: PlanLimitReason): string;
 /**
  * The one sentence every over-limit surface says about the two hard stops
  * (US-033 §3.3). Written once so the CLI, the console and the emails cannot
@@ -124,22 +119,22 @@ export declare const HARD_STOP_SENTENCE: string;
  * against the cap, and the ways out. Plain text — colour is applied by the
  * caller so scripts capturing stdout get a clean block.
  *
- * Every line is derived from `lock.reasons`. A workspace over on secrets is
+ * Every line is derived from `status.reasons`. A workspace over on secrets is
  * never told it has too many members, and an empty reason list (a server
  * dimension this CLI does not know) renders a generic line rather than a claim
  * about a dimension nobody measured.
  */
-export declare function renderPlanLimitNotice(status: PlanLockStatus): string;
+export declare function renderPlanLimitNotice(status: PlanLimitStatus): string;
 /**
  * The one-line form injected on every turn while the workspace stays over.
  * Kept to a single line on purpose — it repeats each turn.
  */
-export declare function renderPlanLimitLine(status: PlanLockStatus): string;
+export declare function renderPlanLimitLine(status: PlanLimitStatus): string;
 /**
  * The `Plan: …` orientation line. Starter only: a paid or enterprise
  * workspace — and an UNKNOWN plan — gets no line at all.
  */
-export declare function renderPlanLine(status: PlanLockStatus): string | null;
+export declare function renderPlanLine(status: PlanLimitStatus): string | null;
 /**
  * Colourised block for interactive output. Yellow, not red: this is a nag, and
  * an error colour would read as "HQ has stopped working", which is the exact