@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/billing/plan-lock.js

@@ -0,0 +1,439 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * An absent field is UNKNOWN, so nothing here ever infers over-limit from
+ * missing data (hq-absent-field-never-means-constraining-value).
+ */
+import chalk from "chalk";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+import { parseFreeMonth } from "./free-month.js";
+import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
+// The free-month parser lives in a leaf module so the plan-gate 402 decoder can
+// share it without importing the HTTP layer; re-exported so existing callers
+// keep importing it from here.
+export { parseFreeMonth };
+/**
+ * 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 const PLAN_LIMIT_REASONS = [
+    "users",
+    "integrations",
+    "secrets",
+    "agents",
+];
+/** @deprecated US-040 — alias of {@link PLAN_LIMIT_REASONS}. */
+export const PLAN_LOCK_REASONS = PLAN_LIMIT_REASONS;
+/** Starter member cap quoted when the server did not send a users.limit. */
+export const STARTER_MEMBER_TARGET = 5;
+/**
+ * Starter integration cap quoted when the server did not send a limit.
+ * One: Starter includes a single integration (US-020 owner decision 11).
+ */
+export const STARTER_INTEGRATION_TARGET = 1;
+/** Starter secret cap quoted when the server did not send a secrets.limit. */
+export const STARTER_SECRET_TARGET = 10;
+/** Starter agent cap quoted when the server did not send an agents.limit. */
+export const STARTER_AGENT_TARGET = 0;
+/** Upgrade destination quoted when the server did not send one. */
+export const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
+/** The paid plan the nag sends owners to. Copy lives in ONE place. */
+export const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/** Published Starter cap for a dimension, quoted when the server sends no limit. */
+function starterCap(reason) {
+    switch (reason) {
+        case "users":
+            return STARTER_MEMBER_TARGET;
+        case "integrations":
+            return STARTER_INTEGRATION_TARGET;
+        case "secrets":
+            return STARTER_SECRET_TARGET;
+        case "agents":
+            return STARTER_AGENT_TARGET;
+    }
+}
+/**
+ * Parse one usage row. An absent or null `limit` is UNKNOWN, never zero: the
+ * renderer quotes the published Starter cap instead of "7 of 0 members"
+ * (hq-absent-field-never-means-constraining-value).
+ */
+function parseUsageRow(reason, value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return null;
+    const used = finiteNumber(rec.used);
+    if (used === null)
+        return null;
+    const limit = finiteNumber(rec.limit);
+    return { used, limit: limit ?? starterCap(reason) };
+}
+function rowIsOver(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return false;
+    if (rec.over === true)
+        return true;
+    const used = finiteNumber(rec.used);
+    const limit = finiteNumber(rec.limit);
+    return used !== null && limit !== null && used > limit;
+}
+/**
+ * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
+ * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.
+ */
+export function selectCompanyMembership(body, companyRef) {
+    const rec = asRecord(body);
+    const rows = Array.isArray(rec?.memberships) ? rec.memberships : [];
+    const ref = companyRef.trim().toLowerCase();
+    for (const raw of rows) {
+        const row = asRecord(raw);
+        if (!row)
+            continue;
+        if (typeof row.status === "string" && row.status !== "active")
+            continue;
+        const slug = typeof row.companySlug === "string" ? row.companySlug.toLowerCase() : "";
+        const uid = typeof row.companyUid === "string" ? row.companyUid.toLowerCase() : "";
+        if (slug !== ref && uid !== ref)
+            continue;
+        return {
+            companyUid: typeof row.companyUid === "string" ? row.companyUid : undefined,
+            companySlug: typeof row.companySlug === "string" ? row.companySlug : undefined,
+        };
+    }
+    return null;
+}
+/** Parse the resolved plan id out of a usage-limits body. Absent → null. */
+export function selectPlan(body) {
+    const plan = asRecord(body)?.plan;
+    return plan === "free" || plan === "paid" || plan === "enterprise"
+        ? plan
+        : null;
+}
+/** Parse the `users` dimension out of a usage-limits body. Absent → null. */
+export function selectMemberUsage(body) {
+    const users = asRecord(asRecord(body)?.users);
+    if (!users)
+        return null;
+    if (typeof users.used !== "number" || !Number.isFinite(users.used)) {
+        return null;
+    }
+    const limit = typeof users.limit === "number" && Number.isFinite(users.limit)
+        ? users.limit
+        : STARTER_MEMBER_TARGET;
+    return { used: users.used, limit };
+}
+function selectUpgradeUrl(body, companySlug) {
+    const rec = asRecord(body);
+    const nested = asRecord(rec?.planLimits);
+    const topLevelUrl = typeof rec?.upgradeUrl === "string" && rec.upgradeUrl.trim().length > 0
+        ? rec.upgradeUrl.trim()
+        : undefined;
+    const nestedUrl = typeof nested?.upgradeUrl === "string" && nested.upgradeUrl.trim().length > 0
+        ? nested.upgradeUrl.trim()
+        : undefined;
+    return selectPlanLimitUpgradeUrl(companySlug, {
+        topLevelUrl,
+        nestedUrl,
+        legacyUrl: topLevelUrl ?? DEFAULT_UPGRADE_URL,
+    });
+}
+/**
+ * Read over-limit dimensions from a usage-limits body. `planLimits` nested
+ * map is preferred when present; otherwise the top-level resource rows.
+ */
+export function selectOverReasons(body) {
+    const rec = asRecord(body);
+    if (!rec)
+        return [];
+    const nested = asRecord(rec.planLimits);
+    const source = nested ?? rec;
+    const reasons = [];
+    for (const key of PLAN_LIMIT_REASONS) {
+        if (rowIsOver(source[key]))
+            reasons.push(key);
+    }
+    return reasons;
+}
+export function selectUsages(body) {
+    const rec = asRecord(body);
+    if (!rec)
+        return {};
+    const nested = asRecord(rec.planLimits);
+    const source = nested ?? rec;
+    const out = {};
+    for (const key of PLAN_LIMIT_REASONS) {
+        const row = parseUsageRow(key, source[key]);
+        if (row)
+            out[key] = row;
+    }
+    return out;
+}
+function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
+    const usages = selectUsages(body);
+    const reasons = selectOverReasons(body);
+    const rec = asRecord(body);
+    const anyOverFlag = rec?.anyOver === true;
+    return {
+        companySlug,
+        companyUid,
+        over: anyOverFlag || reasons.length > 0,
+        reasons,
+        members: selectMemberUsage(body) ?? usages.users,
+        usages,
+        upgradeUrl: selectUpgradeUrl(body, upgradeCompanySlug),
+        freeMonth: parseFreeMonth(rec?.freeMonth),
+        plan: selectPlan(body) ?? undefined,
+        checkedAt: new Date().toISOString(),
+    };
+}
+/**
+ * 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 async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    const res = await vaultApiFetch({
+        token,
+        path: "/membership/me",
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok)
+        return null;
+    const selected = selectCompanyMembership(await res.json().catch(() => null), companyRef);
+    if (!selected?.companyUid)
+        return null;
+    try {
+        const usage = await vaultApiFetch({
+            token,
+            path: "/v1/billing/usage-limits",
+            query: { companyUid: selected.companyUid },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!usage.ok)
+            return null;
+        const body = await usage.json().catch(() => null);
+        if (!body)
+            return null;
+        const selectedSlug = selected.companySlug ??
+            (!companyRef.startsWith("cmp_") ? companyRef : undefined);
+        return statusFromUsage(companyRef, selected.companyUid, body, selectedSlug);
+    }
+    catch {
+        return null;
+    }
+}
+/** @deprecated US-040 — alias of {@link fetchPlanLimitStatus}. */
+export const fetchPlanLockStatus = fetchPlanLimitStatus;
+/** Why the workspace is over, one clause per reason. */
+export function reasonLabel(reason) {
+    switch (reason) {
+        case "users":
+            return "too many members";
+        case "integrations":
+            return "too many integrations";
+        case "secrets":
+            return "too many secrets";
+        case "agents":
+            return "agents are not included on Starter";
+    }
+}
+function usageTarget(reason, status) {
+    const used = status.usages[reason]?.limit;
+    if (typeof used === "number")
+        return used;
+    switch (reason) {
+        case "users":
+            return status.members?.limit ?? STARTER_MEMBER_TARGET;
+        case "integrations":
+            return STARTER_INTEGRATION_TARGET;
+        case "secrets":
+            return STARTER_SECRET_TARGET;
+        case "agents":
+            return STARTER_AGENT_TARGET;
+    }
+}
+/** The remedy sentence for one reason — what the owner does to clear it. */
+function reasonRemedy(reason, status) {
+    const target = usageTarget(reason, status);
+    switch (reason) {
+        case "users":
+            return `remove members until you are at ${target} or fewer`;
+        case "integrations":
+            return `disconnect integrations until you are at ${target} or fewer`;
+        case "secrets":
+            return `delete secrets until you are at ${target} or fewer`;
+        case "agents":
+            return target > 0
+                ? `deprovision agents until you are at ${target} or fewer`
+                : "deprovision the workspace's agents";
+    }
+}
+/** The short per-reason clause used inside the one-line turn notice. */
+function reasonDetail(reason, status) {
+    const row = status.usages[reason];
+    const target = usageTarget(reason, status);
+    switch (reason) {
+        case "users":
+            return row || status.members
+                ? `${(row ?? status.members).used} of ${target} members`
+                : `over its ${target}-member limit`;
+        case "integrations":
+            return row
+                ? `${row.used} of ${target} integrations`
+                : `over its ${target}-integration limit`;
+        case "secrets":
+            return row
+                ? `${row.used} of ${target} secrets`
+                : `over its ${target}-secret limit`;
+        case "agents":
+            return "agents are not included on Starter";
+    }
+}
+function usageLine(reason, status) {
+    const row = status.usages[reason];
+    const target = usageTarget(reason, status);
+    switch (reason) {
+        case "users": {
+            const members = row ?? status.members;
+            return members
+                ? `  Members: ${members.used} of ${target}.`
+                : `  Members allowed on Starter: ${target}.`;
+        }
+        case "integrations":
+            return row
+                ? `  Integrations: ${row.used} of ${target}.`
+                : `  Integrations allowed on Starter: ${target}.`;
+        case "secrets":
+            return row
+                ? `  Secrets: ${row.used} of ${target}.`
+                : `  Secrets allowed on Starter: ${target}.`;
+        case "agents":
+            return row
+                ? `  Agents: ${row.used} of ${target}.`
+                : `  Agents allowed on Starter: ${target}.`;
+    }
+}
+/**
+ * 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
+ * drift into three different promises.
+ */
+export const HARD_STOP_SENTENCE = "Nothing has been deleted and everything keeps working, except that new " +
+    "files and new secrets are paused until this is sorted.";
+const HARD_STOP_SENTENCE_LINES = [
+    "  Nothing has been deleted and everything keeps working, except that new",
+    "  files and new secrets are paused until this is sorted.",
+];
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/**
+ * The full over-limit block: why the workspace is over, where it stands
+ * 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 `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 function renderPlanLimitNotice(status, opts = {}) {
+    const { companySlug, freeMonth } = status;
+    const lines = [];
+    lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
+    const reasons = status.reasons.length
+        ? status.reasons.map(reasonLabel).join("; ")
+        : "over the Starter plan limits";
+    lines.push(`  Why: ${reasons}.`);
+    for (const reason of status.reasons) {
+        lines.push(usageLine(reason, status));
+    }
+    lines.push(HARD_STOP_SENTENCE_LINES[0]);
+    lines.push(HARD_STOP_SENTENCE_LINES[1]);
+    const remedy = status.reasons.length
+        ? status.reasons.map((reason) => reasonRemedy(reason, status)).join(", and ")
+        : "come back under the Starter plan limits";
+    const freeMonthUrl = freeMonth?.url;
+    const hasFreeMonth = Boolean(freeMonth?.eligible && freeMonthUrl);
+    if (hasFreeMonth) {
+        lines.push("  Three ways to sort it:");
+        lines.push(`    1. Start your free month — add a card, first month free: ${freeMonthUrl}`);
+        lines.push(`    2. ${capitalize(remedy)}.`);
+        lines.push(`    3. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
+    }
+    else {
+        lines.push("  Two ways to sort it:");
+        lines.push(`    1. ${capitalize(remedy)}.`);
+        lines.push(`    2. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
+    }
+    lines.push(`  Upgrade: ${status.upgradeUrl}`);
+    if (opts.inviteTeammateEnabled === true &&
+        status.plan === "free" &&
+        status.over &&
+        status.members?.used === 1) {
+        lines.push(`  Invite a teammate with: hq members invite <email> --company ${companySlug} --role member`);
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 function renderPlanLimitLine(status) {
+    const detail = status.reasons.length
+        ? status.reasons.map((reason) => reasonDetail(reason, status)).join("; ")
+        : "over the Starter plan limits";
+    return (`Company ${status.companySlug} is over its Starter limits (${detail}). ` +
+        `New files and new secrets are paused until this is sorted: ${status.upgradeUrl}`);
+}
+/**
+ * The `Plan: …` orientation line. Starter only: a paid or enterprise
+ * workspace — and an UNKNOWN plan — gets no line at all.
+ */
+export function renderPlanLine(status) {
+    if (status.over)
+        return "Plan: Starter — over its limits";
+    if (status.plan !== "free")
+        return null;
+    const target = status.members?.limit ?? STARTER_MEMBER_TARGET;
+    if (status.members) {
+        return `Plan: Starter — ${status.members.used} of ${target} members`;
+    }
+    return `Plan: Starter — ${target} members included`;
+}
+/**
+ * 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
+ * impression US-033 removes.
+ */
+export function colorizePlanLimitNotice(notice) {
+    return chalk.yellow(notice);
+}
+//# sourceMappingURL=plan-lock.js.map