@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/plan-limit-nag.js

@@ -5,28 +5,83 @@
  * some 2xx JSON response bodies (US-012). This module:
  *
  *   1. Best-effort records the last-seen status from decoded JSON bodies
- *      (`recordPlanLimitStatus`).
+ *      (`recordPlanLimitStatus`), and prints the one-time threshold notice
+ *      right there — see below.
  *   2. Emits a stderr nag at command completion (`emitPlanLimitNag`):
  *      - entries present, none over (≥80% warning): one-line yellow warning,
  *        once per process session
- *      - any resource over: boxed notice, at most once per day (persisted in
- *        `~/.hq/plan-limit-nag.json`) and once per session
+ *      - any resource over: one-line notice, at most once every 6 hours
+ *        (persisted in `~/.hq/plan-limit-nag.json`) and once per session
+ *
+ * The one-time threshold notice (US-035) is the third surface and the only one
+ * that does NOT wait for command completion. hq-pro attaches
+ * `thresholdCrossings: [{ resource, band, firstSeenAt, used, limit }]` beside
+ * `planLimits`, populated from the server's own threshold state, and this
+ * module prints each `{resource}:{band}` exactly once per EPISODE — persisted
+ * in `~/.hq/plan-limit-nag.json` under `notifiedThresholds`. It prints from the
+ * record path so a session that is already running surfaces the notice on its
+ * next API call rather than on its next launch, which is the whole point of
+ * carrying the crossing on the wire instead of recomputing it locally.
+ *
+ * "Once per episode", not once per lifetime: the stored value is the server's
+ * `firstSeenAt`, so a dimension that drops back under the threshold and climbs
+ * again arrives with a new timestamp and notifies again. The server decides
+ * when an episode ends; this module only remembers what it has printed.
  *
  * Additive only — never throws, never touches `process.exitCode`, never
- * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
+ * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1` silences all
+ * three surfaces, the threshold notice included.
  */
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-export const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
-const DAY_MS = 24 * 60 * 60 * 1000;
+import { resolveProcessFlagCompanyContext } from "./flag-registry.js";
+import { isCliLimitResourceKind, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
+import { planLimitUpgradeFallbackUrl, selectPlanLimitUpgradeUrl, } from "./billing/plan-limit-upgrade-url.js";
+export const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
+/**
+ * Cadence of the over-limit per-turn line (US-036). Was once a day; the nag
+ * model wants it more often than that and still not on every turn, so the
+ * window is six hours — up to four lines in a day for someone working all day,
+ * and one for someone who runs a single command.
+ */
+export const OVER_NAG_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/**
+ * Plain-English name for each plan-limit resource key, so a nag line says which
+ * dimension is tight rather than only the wire key. The key itself stays in the
+ * copy — hooks and support transcripts match on it — and the label is appended
+ * only when it differs. An unknown key (a resource this CLI predates) renders
+ * as the bare key rather than a guess.
+ */
+export const PLAN_LIMIT_DIMENSION_LABELS = {
+    users: "members",
+    integrations: "integrations",
+    secrets: "secrets",
+    agents: "agents",
+    deployments: "deployments",
+    storageBytes: "storage",
+};
+function dimensionSuffix(key) {
+    const label = PLAN_LIMIT_DIMENSION_LABELS[key];
+    return label && label !== key ? ` (${label})` : "";
+}
+/** The two bands hq-pro reports. Anything else on the wire is ignored. */
+export const PLAN_LIMIT_BANDS = ["warn", "over"];
 /** Module-level last-seen cell — overwritten by each successful parse. */
 let lastSeen = null;
 /** Session dedupe for the ≥80% one-line warning. */
 let warningShownThisSession = false;
-/** Session dedupe for the over-limit boxed notice. */
+/** Session dedupe for the over-limit line. */
 let overShownThisSession = false;
+/**
+ * `"{resource}:{band}"` → `firstSeenAt` already printed in THIS process.
+ *
+ * The persisted file is the durable dedupe; this map exists so a process that
+ * cannot write `~/.hq` (read-only home, sandboxed agent) still prints each
+ * crossing once rather than on every single API call.
+ */
+const thresholdsShownThisSession = new Map();
 function defaultStatePath() {
     return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
 }
@@ -58,9 +113,24 @@ function parseEntry(value) {
     }
     return { used: rec.used, limit: rec.limit, over: rec.over };
 }
+/** Validate the server-provided optional upgrade URL without throwing. */
+function parseUpgradeUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = new URL(value);
+        // hq-pro permits an environment-configured console base URL, so stages
+        // cannot use a production-host allowlist. HTTPS is the trust boundary.
+        return parsed.protocol === "https:" ? parsed.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Defensively parse a decoded JSON body for a well-formed top-level
- * `planLimits` object. Malformed or absent → null. Never throws.
+ * `planLimits` object and its optional `upgradeUrl`. Malformed or absent →
+ * null. Never throws.
  */
 function parsePlanLimits(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body)) {
@@ -81,20 +151,101 @@ function parsePlanLimits(body) {
         out[key] = entry;
         anyValid = true;
     }
-    return anyValid ? out : null;
+    return anyValid
+        ? {
+            limits: out,
+            upgradeUrl: parseUpgradeUrl(planLimits.upgradeUrl),
+        }
+        : null;
+}
+function parseNestedUpgradeUrl(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return null;
+    }
+    const planLimits = body.planLimits;
+    if (planLimits === null ||
+        typeof planLimits !== "object" ||
+        Array.isArray(planLimits)) {
+        return null;
+    }
+    return parseUpgradeUrl(planLimits.upgradeUrl);
+}
+/**
+ * Defensively parse the top-level `thresholdCrossings` array.
+ *
+ * Every field is validated and a malformed ROW is dropped rather than failing
+ * the whole array — an older CLI must stay useful against a newer server that
+ * has added a band or a field. An unrecognised band is dropped for the same
+ * reason it is not guessed at: printing "you have reached critical of your
+ * secrets" is worse than printing nothing.
+ */
+function parseThresholdCrossings(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return [];
+    }
+    const raw = body.thresholdCrossings;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            continue;
+        }
+        const rec = value;
+        if (typeof rec.resource !== "string" || rec.resource.length === 0)
+            continue;
+        if (typeof rec.band !== "string" ||
+            !PLAN_LIMIT_BANDS.includes(rec.band)) {
+            continue;
+        }
+        if (typeof rec.firstSeenAt !== "string" || rec.firstSeenAt.length === 0) {
+            continue;
+        }
+        if (typeof rec.used !== "number" || !Number.isFinite(rec.used))
+            continue;
+        if (typeof rec.limit !== "number" || !Number.isFinite(rec.limit))
+            continue;
+        out.push({
+            resource: rec.resource,
+            band: rec.band,
+            firstSeenAt: rec.firstSeenAt,
+            used: rec.used,
+            limit: rec.limit,
+        });
+    }
+    return out;
 }
 /**
  * Record plan-limit status from a decoded JSON response body.
  * Never throws. Overwrites the last-seen cell when a well-formed
  * `planLimits` object is present; ignores malformed / absent payloads.
  */
-export function recordPlanLimitStatus(body) {
+export function recordPlanLimitStatus(body, opts = {}) {
     try {
-        const limits = parsePlanLimits(body);
-        if (limits === null)
-            return;
-        const anyOver = Object.values(limits).some((e) => e.over);
-        lastSeen = { limits, anyOver };
+        const status = parsePlanLimits(body);
+        const crossings = parseThresholdCrossings(body);
+        let resolvedUpgradeUrl = null;
+        if (status !== null || crossings.length > 0) {
+            const bodyRecord = body !== null && typeof body === "object" && !Array.isArray(body)
+                ? body
+                : null;
+            const topLevelUpgradeUrl = parseUpgradeUrl(bodyRecord?.upgradeUrl);
+            const nestedUpgradeUrl = parseNestedUpgradeUrl(body);
+            const companySlug = resolveProcessFlagCompanyContext().companySlug;
+            resolvedUpgradeUrl = selectPlanLimitUpgradeUrl(companySlug, {
+                topLevelUrl: topLevelUpgradeUrl,
+                nestedUrl: nestedUpgradeUrl,
+                legacyUrl: status?.upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL,
+            });
+        }
+        if (status !== null) {
+            const anyOver = Object.values(status.limits).some((e) => e.over);
+            lastSeen = { ...status, anyOver, upgradeUrl: resolvedUpgradeUrl };
+        }
+        // Independent of `planLimits`: the server can announce a crossing on a
+        // response whose nag map this CLI could not parse, and the notice is the
+        // one surface that must land inside a session that is already running.
+        emitPlanLimitThresholdNotice(crossings, resolvedUpgradeUrl, opts);
     }
     catch {
         // Never throw from record path.
@@ -122,46 +273,190 @@ function formatPct(entry) {
     return `${Math.round((entry.used / entry.limit) * 100)}%`;
 }
 function formatEntryLine(key, entry) {
-    return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})`;
+    return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})${dimensionSuffix(key)}`;
 }
-function readShownAt(statePath) {
+/**
+ * Read the whole state file. A missing, unreadable or malformed file is an
+ * empty state — the nag re-arms rather than being silenced by a bad write.
+ */
+function readNagState(statePath) {
     try {
         const raw = fs.readFileSync(statePath, "utf-8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.shownAt !== "number" || !Number.isFinite(parsed.shownAt)) {
-            return null;
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
+        }
+        const rec = parsed;
+        const state = {};
+        if (typeof rec.shownAt === "number" && Number.isFinite(rec.shownAt)) {
+            state.shownAt = rec.shownAt;
+        }
+        if (rec.notifiedThresholds !== null &&
+            typeof rec.notifiedThresholds === "object" &&
+            !Array.isArray(rec.notifiedThresholds)) {
+            const entries = Object.entries(rec.notifiedThresholds).filter((pair) => typeof pair[1] === "string");
+            if (entries.length > 0) {
+                state.notifiedThresholds = Object.fromEntries(entries);
+            }
         }
-        return parsed.shownAt;
+        return state;
     }
     catch {
-        return null;
+        return {};
     }
 }
-function writeShownAt(statePath, shownAt) {
+/**
+ * Merge `patch` into the state file and write it back.
+ *
+ * Read-modify-write rather than overwrite, so the over-limit box's `shownAt`
+ * and the threshold notice's `notifiedThresholds` — written by different
+ * surfaces at different moments — cannot erase each other.
+ */
+function updateNagState(statePath, patch) {
     try {
+        const current = readNagState(statePath);
+        const next = {
+            ...current,
+            ...patch,
+            ...(patch.notifiedThresholds
+                ? {
+                    notifiedThresholds: {
+                        ...current.notifiedThresholds,
+                        ...patch.notifiedThresholds,
+                    },
+                }
+                : {}),
+        };
         fs.mkdirSync(path.dirname(statePath), { recursive: true });
-        const payload = { shownAt };
-        fs.writeFileSync(statePath, JSON.stringify(payload));
+        fs.writeFileSync(statePath, JSON.stringify(next));
     }
     catch {
         // best-effort; never break the CLI on cache write failure
     }
 }
-function withinDayWindow(shownAt, nowMs) {
-    return nowMs - shownAt < DAY_MS;
+function readShownAt(statePath) {
+    return readNagState(statePath).shownAt ?? null;
+}
+function writeShownAt(statePath, shownAt) {
+    updateNagState(statePath, { shownAt });
+}
+function withinNagWindow(shownAt, nowMs) {
+    return nowMs - shownAt < OVER_NAG_INTERVAL_MS;
+}
+/**
+ * The over-limit per-turn line (US-036 §2.2). One line, not the old box: it
+ * now repeats up to four times a day, and a multi-line box at that cadence
+ * reads as breakage rather than as a nag. It states the two paused things and
+ * never claims the workspace has stopped working.
+ */
+export function buildOverLine(overEntries, upgradeUrl) {
+    const facts = overEntries
+        .map(([key, entry]) => `${PLAN_LIMIT_DIMENSION_LABELS[key] ?? key} ${entry.used} of ${entry.limit}`)
+        .join(", ");
+    return (`⚠ HQ Starter: ${facts}. New files and new secrets are paused. ` +
+        `Upgrade: ${upgradeUrl}`);
+}
+// ---------------------------------------------------------------------------
+// Individual-plan feature notice (US-054)
+// ---------------------------------------------------------------------------
+/**
+ * My Telemetry is an Individual-plan feature on a personal scope (owner
+ * decision 9 / us-044-individual-plan-design.md §11). When hq-pro refuses it,
+ * the CLI prints this notice INSTEAD of telemetry output.
+ *
+ * It lives beside the nag copy so plan wording stays in one file, but it is
+ * NOT part of the nag model: no persistence, no throttle, no episode state. It
+ * is rendered once, on the spot, by whoever received the refusal. The refusal
+ * is a plan fact, so it neither counts toward the nag bands nor is silenced by
+ * the nag cadence.
+ *
+ * Copy names the plan and its price only — no Outposts, no bot pricing (owner
+ * decisions 10 and 11).
+ */
+export const INDIVIDUAL_PLAN_NAME = "Individual";
+export const INDIVIDUAL_PRICE_LABEL = "$50/mo";
+/** Human names for the features a personal scope can be refused. */
+const PERSONAL_FEATURE_LABELS = {
+    telemetry: "My Telemetry",
+};
+/**
+ * The notice a personal feature refusal prints. `upgradeUrl` is the server's
+ * own checkout target; an older hq-pro sends none, and the line then names the
+ * plan without a link rather than inventing one.
+ */
+export function renderPersonalPlanFeatureNotice(feature, upgradeUrl) {
+    const label = PERSONAL_FEATURE_LABELS[feature] ?? feature;
+    const headline = `${label} is included with the HQ ${INDIVIDUAL_PLAN_NAME} plan (${INDIVIDUAL_PRICE_LABEL}).`;
+    const action = typeof upgradeUrl === "string" && upgradeUrl.trim().length > 0
+        ? `Upgrade: ${upgradeUrl.trim()}`
+        : "Upgrade in your HQ billing settings.";
+    return `${headline} Your personal account is on the free tier. ${action}`;
+}
+/** `"{resource}:{band}"` — the persisted key, matching the server's own. */
+function crossingKey(crossing) {
+    return `${crossing.resource}:${crossing.band}`;
 }
-function buildOverBox(overEntries) {
-    const title = "⚠ HQ plan limit exceeded";
-    const upgrade = `Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
-    const resourceLines = overEntries.map(([key, entry]) => `  ${key}: ${entry.used}/${entry.limit}`);
-    const contentLines = [title, "", ...resourceLines, "", upgrade];
-    const innerWidth = Math.max(...contentLines.map((l) => l.length), 40);
-    const top = `┌${"─".repeat(innerWidth + 2)}┐`;
-    const bot = `└${"─".repeat(innerWidth + 2)}┘`;
-    const mid = contentLines
-        .map((l) => `│ ${l.padEnd(innerWidth)} │`)
-        .join("\n");
-    return `${top}\n${mid}\n${bot}`;
+/** Human dimension name, falling back to the wire key for an unknown resource. */
+function dimensionName(resource) {
+    return PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource;
+}
+/**
+ * One line per crossing.
+ *
+ * The copy states the fact and the exit, nothing else. It deliberately does
+ * not describe consequences that have not shipped: the hard stops arrive with
+ * their own story, and a notice that announces a pause nobody is experiencing
+ * reads as a bug.
+ */
+export function renderThresholdNotice(crossing, upgradeUrl) {
+    const name = dimensionName(crossing.resource);
+    const counts = `${crossing.used} of ${crossing.limit}`;
+    const headline = crossing.band === "over"
+        ? `HQ Starter: you are past your ${name} limit (${counts}).`
+        : `HQ Starter: you have reached 80% of your ${name} (${counts}).`;
+    return `${headline} Upgrade: ${upgradeUrl}`;
+}
+/**
+ * Print every crossing this machine has not already printed for this episode.
+ *
+ * Called from the record path, so a session already running prints on its next
+ * API call. Never throws; a state file it cannot read or write degrades to
+ * per-process dedupe rather than to silence or to repetition.
+ */
+export function emitPlanLimitThresholdNotice(crossings, upgradeUrl, opts = {}) {
+    try {
+        if (!isPlanLimitNagEnabled())
+            return;
+        if (crossings.length === 0)
+            return;
+        const write = opts.write ?? ((s) => process.stderr.write(s));
+        const statePath = opts.statePath ?? defaultStatePath();
+        const stored = readNagState(statePath).notifiedThresholds ?? {};
+        const resolvedUpgradeUrl = upgradeUrl ??
+            planLimitUpgradeFallbackUrl(resolveProcessFlagCompanyContext().companySlug, PLAN_LIMIT_UPGRADE_URL);
+        const printed = {};
+        for (const crossing of crossings) {
+            const key = crossingKey(crossing);
+            // A DIFFERENT firstSeenAt is a different episode and prints again; the
+            // same one has already been said.
+            if (stored[key] === crossing.firstSeenAt)
+                continue;
+            if (thresholdsShownThisSession.get(key) === crossing.firstSeenAt)
+                continue;
+            thresholdsShownThisSession.set(key, crossing.firstSeenAt);
+            printed[key] = crossing.firstSeenAt;
+            write(chalk.yellow(renderThresholdNotice(crossing, resolvedUpgradeUrl)) + "\n");
+            if (isCliLimitResourceKind(crossing.resource)) {
+                queueCliLimitNoticeExposure(crossing.resource, "advisory");
+            }
+        }
+        if (Object.keys(printed).length > 0) {
+            updateNagState(statePath, { notifiedThresholds: printed });
+        }
+    }
+    catch {
+        // Never throw from the notice path.
+    }
 }
 /**
  * Emit a plan-limit nag to stderr at command completion.
@@ -178,7 +473,9 @@ export function emitPlanLimitNag(opts = {}) {
         const write = opts.write ?? ((s) => process.stderr.write(s));
         const now = opts.now ?? (() => new Date());
         const statePath = opts.statePath ?? defaultStatePath();
-        const { limits, anyOver } = lastSeen;
+        const { limits, anyOver, upgradeUrl } = lastSeen;
+        const resolvedUpgradeUrl = upgradeUrl ??
+            planLimitUpgradeFallbackUrl(resolveProcessFlagCompanyContext().companySlug, PLAN_LIMIT_UPGRADE_URL);
         const entries = Object.entries(limits);
         if (entries.length === 0)
             return;
@@ -187,12 +484,16 @@ export function emitPlanLimitNag(opts = {}) {
                 return;
             const nowMs = now().getTime();
             const prev = readShownAt(statePath);
-            if (prev !== null && withinDayWindow(prev, nowMs))
+            if (prev !== null && withinNagWindow(prev, nowMs))
                 return;
             overShownThisSession = true;
             const overEntries = entries.filter(([, e]) => e.over);
-            const box = buildOverBox(overEntries);
-            write(chalk.yellow(box) + "\n");
+            const line = buildOverLine(overEntries, resolvedUpgradeUrl);
+            write(chalk.yellow(line) + "\n");
+            const resourceKind = overEntries[0]?.[0];
+            if (resourceKind && isCliLimitResourceKind(resourceKind)) {
+                queueCliLimitNoticeExposure(resourceKind, "advisory");
+            }
             writeShownAt(statePath, nowMs);
             return;
         }
@@ -203,8 +504,11 @@ export function emitPlanLimitNag(opts = {}) {
         if (worst === null)
             return;
         warningShownThisSession = true;
-        const line = `⚠ HQ free plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
+        const line = `⚠ HQ Starter: ${formatEntryLine(worst.key, worst.entry)}. Add headroom before you hit the cap: ${resolvedUpgradeUrl}`;
         write(chalk.yellow(line) + "\n");
+        if (isCliLimitResourceKind(worst.key)) {
+            queueCliLimitNoticeExposure(worst.key, "advisory");
+        }
     }
     catch {
         // Never throw from emit path.
@@ -215,5 +519,6 @@ export function _resetForTests() {
     lastSeen = null;
     warningShownThisSession = false;
     overShownThisSession = false;
+    thresholdsShownThisSession.clear();
 }
 //# sourceMappingURL=plan-limit-nag.js.map

package/dist/lib/policy-validator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Load-time validation: reject policy files that cannot participate in the
+ * trigger system. Authoring-only hard-policy constraints remain in the hook.
+ */
+export declare function policyLoadDiagnostic(content: string, filePath: string): string | undefined;
+export declare function policyValidatorDiagnostic(content: string, filePath: string, env: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=policy-validator.d.ts.map