@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/flag-registry-worker.js

@@ -2,13 +2,24 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient } from "@indigoai-us/hq-flags-client";
-const endpoint = workerData.endpoint;
+const data = workerData;
+const endpoint = data.endpoint;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 async function refresh() {
     if (!parentPort || typeof endpoint !== "string" || endpoint.trim() === "")
         return;
     try {
+        const companyUid = typeof data.companyUid === "string" && COMPANY_UID_RE.test(data.companyUid)
+            ? data.companyUid
+            : undefined;
+        const companyIdentifiers = Array.isArray(data.companyIdentifiers)
+            ? data.companyIdentifiers.filter((value) => typeof value === "string" && COMPANY_SLUG_RE.test(value))
+            : [];
         const client = createFlagClient({
             endpoint,
+            ...(companyUid ? { companyUid } : {}),
+            ...(companyIdentifiers.length ? { companyIdentifiers } : {}),
             getToken: () => loadCachedTokens()?.idToken ?? "",
             refreshIntervalMs: 0,
             onError: () => { },

package/dist/lib/flag-registry.d.ts

@@ -6,9 +6,11 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { type WorkerOptions } from "node:worker_threads";
-import { type FlagClient, type FlagLookupOptions } from "@indigoai-us/hq-flags-client";
-/** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
-export declare const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+import { createFlagClient, type FlagClient, type FlagLookupOptions, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
+type FlagRegistrySentry = Pick<typeof import("@sentry/node"), "captureException" | "withScope">;
+export { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
+export type { ProcessFlagCompanyContext } from "./process-flag-company-context.js";
+export { FLAG_REGISTRY_ENDPOINT_ENV } from "./flag-registry-endpoint.js";
 /** The synchronous capability that command gate call sites need. */
 export type FlagReader = Pick<FlagClient, "isEnabled">;
 interface WorkerLike {
@@ -18,8 +20,19 @@ interface WorkerLike {
 }
 export interface FlagRegistryDependencies {
     endpoint?: string;
-    createWorker?: (filename: URL, options: WorkerOptions) => WorkerLike;
+    createWorker?: (filename: string | URL, options: WorkerOptions) => WorkerLike;
+    sentry?: FlagRegistrySentry;
+    /** Test seam for exercising the no-source fail-open path. */
+    workerSource?: string;
+    captureWorkerFailure?: (error: Error, tags: Record<string, string>) => void;
 }
+export interface CompanyFlagGateDependencies {
+    endpoint?: string;
+    requestTimeoutMs?: number;
+    createClient?: typeof createFlagClient;
+}
+/** Create the same snapshot-backed reader used by process gates. */
+export declare function createProcessSnapshotReader(companyIdentifiers: string[], getSnapshot?: () => FlagSnapshot | null, env?: NodeJS.ProcessEnv): FlagReader;
 /**
  * Begin one registry refresh without awaiting it or retaining the CLI process.
  *
@@ -35,10 +48,17 @@ export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDep
  * `isEnabled` itself is synchronous and snapshot-only; any reader failure
  * falls through to the exact legacy predicate owned by the caller.
  */
-export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, env?: NodeJS.ProcessEnv): boolean;
+/** Resolve one explicit company's flag without relying on process-wide binding. */
+export declare function resolveCompanyFlagGate(companyUid: string, idToken: string, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, dependencies?: CompanyFlagGateDependencies): Promise<boolean>;
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export declare function currentFlagSnapshot(): FlagSnapshot | null;
 /** Test-only reset for process-global readiness state. */
 export declare function _resetFlagRegistryForTests(): void;
-export {};
 //# sourceMappingURL=flag-registry.d.ts.map

package/dist/lib/flag-registry.js

@@ -6,24 +6,48 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { Worker } from "node:worker_threads";
-import { isFlagSnapshot, resolveFlag, } from "@indigoai-us/hq-flags-client";
-/** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
-export const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+import { createFlagClient, isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
+import { resolveFlagRegistryEndpoint, } from "./flag-registry-endpoint.js";
+import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.generated.js";
+import { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
+import { writeFlagSnapshotFile } from "./flag-snapshot-file.js";
+function captureFlagRegistryException(error, tags, sentry) {
+    if (!sentry)
+        return;
+    sentry.captureException(error, { tags });
+}
+export { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
+export { FLAG_REGISTRY_ENDPOINT_ENV } from "./flag-registry-endpoint.js";
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
 let heldSnapshot = null;
 let processReader = null;
-function processSnapshotReader() {
+function processLocalOverride(flagKey, env = process.env) {
+    return readLocalOverride(flagKey, env);
+}
+function localOverrideOrFallback(flagKey, legacyFallback, env = process.env) {
+    return processLocalOverride(flagKey, env) ?? legacyFallback();
+}
+/** Create the same snapshot-backed reader used by process gates. */
+export function createProcessSnapshotReader(companyIdentifiers, getSnapshot = () => heldSnapshot, env = process.env) {
     return {
         isEnabled(flagKey, lookup = {}) {
             return resolveFlag({
                 flagKey,
-                env: process.env,
-                snapshot: heldSnapshot,
-                companyIdentifiers: [],
+                env,
+                snapshot: getSnapshot(),
+                companyIdentifiers,
                 lookup,
             }).value;
         },
     };
 }
+function processSnapshotReader(companyIdentifiers) {
+    return createProcessSnapshotReader(companyIdentifiers);
+}
 /**
  * Begin one registry refresh without awaiting it or retaining the CLI process.
  *
@@ -36,15 +60,61 @@ function processSnapshotReader() {
 export function kickFlagRegistryReadiness(dependencies = {}) {
     if (processReader)
         return processReader;
-    const endpoint = (dependencies.endpoint ?? process.env[FLAG_REGISTRY_ENDPOINT_ENV] ?? "").trim();
-    if (!endpoint)
-        return null;
-    processReader = processSnapshotReader();
+    const endpoint = resolveFlagRegistryEndpoint(dependencies.endpoint, process.env);
+    const company = resolveProcessFlagCompanyContext();
+    const sentry = dependencies.sentry;
+    const companyUid = company.companyUid;
+    const companyIdentifiers = [companyUid, company.companySlug].filter((value) => Boolean(value));
+    processReader = processSnapshotReader(companyIdentifiers);
     try {
-        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), { workerData: { endpoint } });
+        const embeddedSource = dependencies.workerSource ?? FLAG_REGISTRY_WORKER_SOURCE;
+        if (embeddedSource.length === 0) {
+            (dependencies.captureWorkerFailure ?? ((error, tags) => {
+                captureFlagRegistryException(error, tags, sentry);
+            }))(new Error("Self-contained flag-registry worker source is unavailable"), {
+                component: "flag-registry-worker-startup",
+                worker: "flag-registry",
+                flag_worker_failure: "embedded_source_unavailable",
+            });
+            return processReader;
+        }
+        // This source is embedded at build time, so it remains available while an
+        // updater replaces the installed package tree.
+        const workerOptions = {
+            workerData: {
+                endpoint,
+                ...(companyUid ? { companyUid } : {}),
+                ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
+            },
+            eval: true,
+        };
+        // The SDK's child-process integration captures every Worker error unless
+        // its process-wide captureWorkerErrors option is disabled. Scope only this
+        // worker so the reporting boundary can classify its startup errors without
+        // changing capture for unrelated workers.
+        const createWorker = dependencies.createWorker ??
+            ((filename, options) => new Worker(filename, options));
+        const worker = sentry
+            ? sentry.withScope((scope) => {
+                scope.setTag("worker", "flag-registry");
+                return createWorker(embeddedSource, workerOptions);
+            })
+            : createWorker(embeddedSource, workerOptions);
         worker.on("message", (value) => {
-            if (isFlagSnapshot(value))
+            if (isFlagSnapshot(value)) {
                 heldSnapshot = value;
+                if (companyUid) {
+                    try {
+                        writeFlagSnapshotFile(companyUid, value.flags);
+                    }
+                    catch (error) {
+                        captureFlagRegistryException(error instanceof Error ? error : new Error(String(error)), {
+                            component: "flag-snapshot-cache-write",
+                            company_uid_present: "true",
+                        }, sentry);
+                    }
+                }
+            }
         });
         // A failed background refresh must stay invisible to an offline CLI.
         worker.on("error", () => { });
@@ -63,20 +133,67 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
  * `isEnabled` itself is synchronous and snapshot-only; any reader failure
  * falls through to the exact legacy predicate owned by the caller.
  */
-export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
+export function resolveFlagGate(reader, flagKey, lookup, legacyFallback, env = process.env) {
     if (!reader)
-        return legacyFallback();
+        return localOverrideOrFallback(flagKey, legacyFallback, env);
     try {
         return reader.isEnabled(flagKey, lookup);
     }
     catch {
-        return legacyFallback();
+        return localOverrideOrFallback(flagKey, legacyFallback, env);
+    }
+}
+/** Resolve one explicit company's flag without relying on process-wide binding. */
+export async function resolveCompanyFlagGate(companyUid, idToken, flagKey, lookup, legacyFallback, dependencies = {}) {
+    const localOverride = processLocalOverride(flagKey);
+    if (localOverride !== null)
+        return localOverride;
+    const targetCompanyUid = normalizedCompanyUid(companyUid);
+    if (!targetCompanyUid || idToken.trim() === "") {
+        return localOverrideOrFallback(flagKey, legacyFallback);
+    }
+    let client;
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(dependencies.endpoint, process.env),
+            getToken: () => idToken,
+            companyUid: targetCompanyUid,
+            refreshIntervalMs: 0,
+            requestTimeoutMs: dependencies.requestTimeoutMs ?? 1_200,
+            onError: (error) => {
+                const errorClass = error instanceof Error ? error.name : "unknown";
+                console.error(`hq: Could not resolve a company flag (${errorClass}); using its fallback.`);
+            },
+        });
+        await client.ready();
+        return resolveFlagGate(client, flagKey, lookup, legacyFallback);
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        console.error(`hq: Could not resolve a company flag (${errorClass}); using its fallback.`);
+        return localOverrideOrFallback(flagKey, legacyFallback);
+    }
+    finally {
+        client?.close();
     }
 }
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export function resolveProcessFlagGate(flagKey, lookup, legacyFallback) {
+    // The endpoint refresh is deliberately asynchronous. Until a validated
+    // snapshot arrives, preserve each caller's exact legacy fallback.
+    if (!processReader || !heldSnapshot) {
+        return localOverrideOrFallback(flagKey, legacyFallback);
+    }
     return resolveFlagGate(processReader, flagKey, lookup, legacyFallback);
 }
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export function currentFlagSnapshot() {
+    return heldSnapshot;
+}
 /** Test-only reset for process-global readiness state. */
 export function _resetFlagRegistryForTests() {
     heldSnapshot = null;

package/dist/lib/flag-snapshot-file.d.ts

@@ -0,0 +1,20 @@
+/** Private, synchronous, offline snapshot used by the native CLI fast route. */
+export declare const FLAG_SNAPSHOT_MAX_AGE_MS: number;
+export interface PersistedFlagSnapshot {
+    company_uid: string;
+    fetched_at: string;
+    flags: Record<string, boolean>;
+}
+export declare function flagSnapshotPath(companyUid: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Write just the validated flag decisions and company scope, never auth data. */
+export declare function writeFlagSnapshotFile(companyUid: string, flags: Readonly<Record<string, unknown>>, options?: {
+    env?: NodeJS.ProcessEnv;
+    fetchedAt?: string;
+}): string;
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export declare function readFlagSnapshotFile(companyUid: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+    maxAgeMs?: number;
+}): PersistedFlagSnapshot | null;
+//# sourceMappingURL=flag-snapshot-file.d.ts.map

package/dist/lib/flag-snapshot-file.js

@@ -0,0 +1,91 @@
+/** Private, synchronous, offline snapshot used by the native CLI fast route. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const FLAG_SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+export function flagSnapshotPath(companyUid, env = process.env) {
+    if (!COMPANY_UID_RE.test(companyUid))
+        return undefined;
+    const cacheHome = env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
+    return path.join(cacheHome, "hq", "flags", `snapshot-${companyUid}.json`);
+}
+/** Write just the validated flag decisions and company scope, never auth data. */
+export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        throw new Error("Cannot persist a flag snapshot without a valid company uid");
+    const normalizedFlags = Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
+    const snapshot = {
+        company_uid: companyUid,
+        fetched_at: options.fetchedAt ?? new Date().toISOString(),
+        flags: normalizedFlags,
+    };
+    if (!Number.isFinite(Date.parse(snapshot.fetched_at))) {
+        throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
+    }
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+    const temporary = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    let fd;
+    try {
+        fd = fs.openSync(temporary, "wx", 0o600);
+        fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT")
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return file;
+}
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export function readFlagSnapshotFile(companyUid, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const value = parsed;
+    if (Object.keys(value).sort().join(",") !== "company_uid,fetched_at,flags" ||
+        value.company_uid !== companyUid ||
+        typeof value.fetched_at !== "string" ||
+        !value.flags || typeof value.flags !== "object" || Array.isArray(value.flags))
+        return null; // Expected on missing, malformed, unreadable, or cross-company cache data.
+    const fetchedAt = Date.parse(value.fetched_at);
+    const age = (options.now ?? Date.now()) - fetchedAt;
+    if (!Number.isFinite(fetchedAt) || age < 0 || age > (options.maxAgeMs ?? FLAG_SNAPSHOT_MAX_AGE_MS)) {
+        return null;
+    }
+    const flags = value.flags;
+    for (const enabled of Object.values(flags)) {
+        if (typeof enabled !== "boolean")
+            return null;
+    }
+    return {
+        company_uid: companyUid,
+        fetched_at: value.fetched_at,
+        flags: flags,
+    };
+}
+//# sourceMappingURL=flag-snapshot-file.js.map

package/dist/lib/heartbeat-identity.d.ts

@@ -0,0 +1,30 @@
+import type { CaptureContext } from "@sentry/node";
+export declare const HEARTBEAT_IDENTITY_MISMATCH_CODE = "AGENT_IDENTITY_MISMATCH";
+export declare function identityMismatchMessage(surface: "heartbeat" | "bot jobs", configuredAgentUid: string, tokenAgentUid?: string): string;
+export type HeartbeatRunner = "agent-kit" | "bot";
+export type HeartbeatAgentUidSource = "config_file" | "env" | "flag";
+export type HeartbeatCredsSource = "explicit" | "default";
+export interface HeartbeatFailure {
+    status: number;
+    code?: string;
+    message?: string;
+}
+export interface HeartbeatIdentityMismatchContext {
+    runner: HeartbeatRunner;
+    configuredAgentUid: string;
+    tokenAgentUid?: string;
+    agentUidSource: HeartbeatAgentUidSource;
+    credsSource: HeartbeatCredsSource;
+}
+export type HeartbeatIdentityMismatchReporter = (context: HeartbeatIdentityMismatchContext) => void;
+/** Parse only the bounded fields the heartbeat route uses for classification. */
+export declare function parseHeartbeatFailureBody(bodyText: string | undefined): {
+    code?: string;
+    message?: string;
+};
+/** Match the server's registered code/name, never an arbitrary 403. */
+export declare function isHeartbeatIdentityMismatch(failure: HeartbeatFailure): boolean;
+/** Read the agent uid claim for diagnostics only; this never authorizes a call. */
+export declare function tokenAgentUid(token: string): string | undefined;
+export declare function captureHeartbeatIdentityMismatch(context: HeartbeatIdentityMismatchContext, captureMessage?: (message: string, context: CaptureContext) => string): void;
+//# sourceMappingURL=heartbeat-identity.d.ts.map

package/dist/lib/heartbeat-identity.js

@@ -0,0 +1,76 @@
+import { CLI_VERSION } from "../cli-version.js";
+import { Sentry } from "../sentry.js";
+import { peekIdToken } from "../utils/id-token.js";
+export const HEARTBEAT_IDENTITY_MISMATCH_CODE = "AGENT_IDENTITY_MISMATCH";
+export function identityMismatchMessage(surface, configuredAgentUid, tokenAgentUid) {
+    return (`${surface} stopped: identity mismatch configured agentUid=${configuredAgentUid} ` +
+        `token agentUid=${tokenAgentUid ?? "unknown"}; fix the bot config to use the token agentUid, ` +
+        `or re-mint credentials for the configured agentUid.`);
+}
+const AGENT_UID_RE = /^agt_[A-Za-z0-9_-]{1,100}$/;
+function normalize(value) {
+    return (value ?? "").replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+}
+function safeAgentUid(value) {
+    return typeof value === "string" && AGENT_UID_RE.test(value) ? value : undefined;
+}
+/** Parse only the bounded fields the heartbeat route uses for classification. */
+export function parseHeartbeatFailureBody(bodyText) {
+    if (!bodyText)
+        return {};
+    try {
+        const body = JSON.parse(bodyText);
+        const code = typeof body.code === "string" ? body.code.slice(0, 120) : undefined;
+        const message = typeof body.error === "string"
+            ? body.error.slice(0, 300)
+            : typeof body.message === "string"
+                ? body.message.slice(0, 300)
+                : undefined;
+        return { ...(code ? { code } : {}), ...(message ? { message } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+/** Match the server's registered code/name, never an arbitrary 403. */
+export function isHeartbeatIdentityMismatch(failure) {
+    if (failure.status !== 403)
+        return false;
+    const code = normalize(failure.code);
+    if (code === normalize(HEARTBEAT_IDENTITY_MISMATCH_CODE) || code === "agentidentitymismatcherror")
+        return true;
+    const message = normalize(failure.message);
+    return (message.includes("heartbeatmustbereportedbytheagentsownmachineidentity") ||
+        message.includes("agentidentitymismatcherror"));
+}
+/** Read the agent uid claim for diagnostics only; this never authorizes a call. */
+export function tokenAgentUid(token) {
+    const claims = peekIdToken(token);
+    return (safeAgentUid(claims["custom:entityUid"]) ??
+        safeAgentUid(claims.entityUid) ??
+        safeAgentUid(claims.sub));
+}
+function diagnosticUid(value) {
+    return safeAgentUid(value) ?? "unknown";
+}
+function captureHeartbeatIdentityMismatchMessage(message, context) {
+    return Sentry.captureMessage(message, context);
+}
+export function captureHeartbeatIdentityMismatch(context, captureMessage = captureHeartbeatIdentityMismatchMessage) {
+    const options = {
+        level: "warning",
+        fingerprint: ["heartbeat-identity-mismatch"],
+        tags: {
+            agent_uid_source: context.agentUidSource,
+            creds_source: context.credsSource,
+            runner: context.runner,
+            hq_cli_version: CLI_VERSION,
+        },
+        extra: {
+            configured_agent_uid: diagnosticUid(context.configuredAgentUid),
+            ...(context.tokenAgentUid ? { token_agent_uid: diagnosticUid(context.tokenAgentUid) } : {}),
+        },
+    };
+    captureMessage("heartbeat identity mismatch", options);
+}
+//# sourceMappingURL=heartbeat-identity.js.map

package/dist/lib/index-render/companies.d.ts

@@ -1,3 +1,6 @@
 import { RenderContext, RenderResult } from "./shared.js";
-export declare function renderCompanies(context: RenderContext): RenderResult;
+export declare class CompanyIndexUserError extends Error {
+    constructor(message: string);
+}
+export declare function renderCompanies(context: RenderContext, args?: string[]): RenderResult;
 //# sourceMappingURL=companies.d.ts.map

package/dist/lib/index-render/companies.js

@@ -1,6 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
 import { basename, countImmediate, date, exists, immediateEntries, isHidden, log, projectStatus, readJson, sanitize, titleize, truncate, write } from "./shared.js";
+export class CompanyIndexUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompanyIndexUserError";
+    }
+}
 function description(root, company, name) {
     const base = `companies/${company}/${name}`;
     const nonHidden = (child) => !isHidden(child);
@@ -17,9 +23,66 @@ function description(root, company, name) {
         default: return "—";
     }
 }
-export function renderCompanies(context) {
+export function renderCompanies(context, args = []) {
+    if (args.some((arg) => arg === "--help" || arg === "-h")) {
+        (context.output ?? ((message) => process.stdout.write(message)))("Usage: hq core rebuild-index companies [--company <slug>]\n\n" +
+            "Regenerate company root INDEX.md files. Without --company, all companies are regenerated.\n" +
+            "--company <slug> regenerates only that company's index.\n" +
+            "Company-scoped writes require the cli.rebuild-index-company-scope flag.\n");
+        return { written: [] };
+    }
+    let selectedCompany;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--company") {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+            selectedCompany = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--company=")) {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            selectedCompany = arg.slice("--company=".length);
+            if (!selectedCompany)
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+        }
+        else {
+            throw new CompanyIndexUserError(`rebuild-index companies: unknown option ${arg}`);
+        }
+    }
     const written = [];
-    for (const directory of immediateEntries(context.root, "companies", "dir")) {
+    let scopedDirectories;
+    if (selectedCompany === undefined) {
+        scopedDirectories = immediateEntries(context.root, "companies", "dir");
+    }
+    else {
+        if (selectedCompany === "." || selectedCompany === ".." ||
+            selectedCompany.includes("/") || selectedCompany.includes("\\") ||
+            path.basename(selectedCompany) !== selectedCompany ||
+            selectedCompany.startsWith("_") || isHidden(selectedCompany)) {
+            throw new CompanyIndexUserError(`rebuild-index companies: invalid company slug "${selectedCompany}"`);
+        }
+        const companiesRoot = path.resolve(context.root, "companies");
+        const selectedDirectory = path.resolve(companiesRoot, selectedCompany);
+        let selectedStat;
+        try {
+            selectedStat = fs.lstatSync(selectedDirectory);
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        if (!selectedStat.isDirectory()) {
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        scopedDirectories = [selectedDirectory];
+    }
+    for (const directory of scopedDirectories) {
         const company = basename(directory);
         if (company.startsWith("_") || isHidden(company))
             continue;
@@ -40,7 +103,7 @@ export function renderCompanies(context) {
                 const parsed = readJson(prd);
                 let text = typeof parsed?.description === "string" ? parsed.description : "";
                 text = truncate(sanitize(text), 110) || "—";
-                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active")} | ${text} |`);
+                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active", prd)} | ${text} |`);
             }
         }
         else