@indigoai-us/hq-cli 5.326.0 → 5.327.0

package/dist/lib/daemon/ops/mcp.js

@@ -2,10 +2,7 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { ensureCognitoToken, isMachineIdentity } from "../../../utils/cognito-session.js";
-import { DEFAULT_VAULT_API_URL } from "../../../utils/cognito-session.js";
+import { McpEndpointError, resolveHqMcpEndpoint as resolveEndpoint } from "../mcp-endpoint.js";
 import { ensurePrivateDir, openPrivateAppend } from "../paths.js";
 export class McpOpError extends Error {
     code;
@@ -20,28 +17,28 @@ export function jsonResult(value) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: structured };
 }
 export const HQ_MCP_HTTP_TIMEOUT_MS = 30_000;
-/** Derive the hosted MCP sibling from the same hq-pro URL used by hq-cli. */
 export function resolveHqMcpEndpoint(env = process.env) {
-    const apiUrl = env.HQ_VAULT_API_URL?.trim() || DEFAULT_VAULT_API_URL;
-    let api;
     try {
-        api = new URL(apiUrl);
+        return resolveEndpoint(env);
     }
-    catch {
-        throw new McpOpError("hq_mcp_config_error", "HQ's configured API URL is invalid; check HQ_VAULT_API_URL.");
-    }
-    if (api.protocol !== "https:" || !api.hostname.startsWith("hqapi.")) {
-        throw new McpOpError("hq_mcp_config_error", "Hosted hq-mcp requires an HTTPS hqapi host in HQ_VAULT_API_URL.");
+    catch (error) {
+        if (error instanceof McpEndpointError)
+            throw new McpOpError(error.code, error.message);
+        throw error;
     }
-    api.hostname = `hq-mcp.${api.hostname.slice("hqapi.".length)}`;
-    api.pathname = "/mcp";
-    api.search = "";
-    api.hash = "";
-    return api;
 }
 async function defaultMcpToken() {
-    if (!isMachineIdentity()) {
-        throw new McpOpError("hq_mcp_auth_required", "This HQ login is not an hq-mcp audience token. Sign in to the hosted connector with its DCR plus PKCE flow; hq login tokens cannot call hq-mcp yet.");
+    const { ensureCognitoToken, resolveCognitoTokenSource } = await import("../../../utils/cognito-session.js");
+    if (resolveCognitoTokenSource() !== "machine") {
+        const { getMcpAudienceToken, McpOAuthError } = await import("../mcp-oauth.js");
+        try {
+            return await getMcpAudienceToken();
+        }
+        catch (error) {
+            if (error instanceof McpOAuthError)
+                throw new McpOpError(error.code, error.message);
+            throw new McpOpError("hq_mcp_auth_required", "Hosted MCP sign-in is required. Run `hq mcp login` and retry.");
+        }
     }
     try {
         // Send this box's existing machine token. The hosted hq-mcp audience check
@@ -82,12 +79,7 @@ export class HqMcpBridge {
             if (!tools.some((tool) => tool.name === name)) {
                 throw new McpOpError("hq_mcp_tool_unavailable", `Hosted hq-mcp does not expose ${name}.`);
             }
-            try {
-                return await client.callTool({ name, arguments: args });
-            }
-            catch (error) {
-                throw this.toSafeError(error, token);
-            }
+            return await client.callTool({ name, arguments: args });
         }, timeoutMs);
     }
     close() {
@@ -104,11 +96,17 @@ export class HqMcpBridge {
         let timeout;
         let timedOut = false;
         const abortController = new AbortController();
+        let httpErrorClass;
         try {
+            const [clientModule, httpModule] = await Promise.all([
+                import("@modelcontextprotocol/sdk/client/index.js"),
+                import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+            ]);
+            httpErrorClass = httpModule.StreamableHTTPError;
             token = await this.getToken();
             if (!token.trim())
                 throw new McpOpError("hq_mcp_auth_required", "An hq-mcp audience token is required.");
-            transport = new StreamableHTTPClientTransport(this.endpoint, {
+            transport = new httpModule.StreamableHTTPClientTransport(this.endpoint, {
                 requestInit: {
                     headers: { Authorization: `Bearer ${token}` },
                 },
@@ -117,7 +115,7 @@ export class HqMcpBridge {
                     signal: init?.signal ? AbortSignal.any([abortController.signal, init.signal]) : abortController.signal,
                 }),
             });
-            client = new Client({ name: "hqd", version: "1" }, { capabilities: {} });
+            client = new clientModule.Client({ name: "hqd", version: "1" }, { capabilities: {} });
             this.activeClients.add(client);
             timeout = setTimeout(() => {
                 timedOut = true;
@@ -133,7 +131,7 @@ export class HqMcpBridge {
             if (timedOut) {
                 throw new McpOpError("hq_mcp_timeout", `Hosted hq-mcp request did not finish within ${timeoutMs}ms.`);
             }
-            throw this.toSafeError(error, token);
+            throw this.toSafeError(error, token, httpErrorClass);
         }
         finally {
             if (timeout)
@@ -157,10 +155,12 @@ export class HqMcpBridge {
             }
         }
     }
-    toSafeError(error, token) {
+    toSafeError(error, token, StreamableHTTPErrorClass) {
         if (error instanceof McpOpError)
             return error;
-        const status = error instanceof StreamableHTTPError ? error.code : undefined;
+        if (error instanceof McpEndpointError)
+            return new McpOpError(error.code, error.message);
+        const status = StreamableHTTPErrorClass && error instanceof StreamableHTTPErrorClass ? error.code : undefined;
         if (status === 401 || status === 403) {
             return new McpOpError("hq_mcp_auth_required", "Hosted hq-mcp rejected this token. Use the DCR plus PKCE person flow or configure the hq-mcp machine client ID on this box.");
         }

package/dist/lib/process-flag-company-context-fast.d.ts

@@ -0,0 +1,4 @@
+/** Fast scope resolver; it loads manifest and HQ-root code only for slug scopes. */
+import { type ProcessFlagCompanyContext } from "./process-flag-company-context-light.js";
+export declare function resolveFastProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): Promise<ProcessFlagCompanyContext>;
+//# sourceMappingURL=process-flag-company-context-fast.d.ts.map

package/dist/lib/process-flag-company-context-fast.js

@@ -0,0 +1,20 @@
+/** Fast scope resolver; it loads manifest and HQ-root code only for slug scopes. */
+import { normalizedCompanyUid, resolveLightProcessFlagCompanyContext, } from "./process-flag-company-context-light.js";
+export async function resolveFastProcessFlagCompanyContext(env = process.env) {
+    const context = resolveLightProcessFlagCompanyContext(env);
+    let companyUid = context.companyUid;
+    if (!companyUid && context.companySlug) {
+        const [{ resolveDefaultHqRoot }, { readCompaniesManifestMap }] = await Promise.all([
+            import("../utils/hq-root-resolver.js"),
+            import("./work-context/repo-remote.js"),
+        ]);
+        const hqRoot = resolveDefaultHqRoot({ env });
+        const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
+        companyUid = typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+    }
+    return {
+        ...(companyUid ? { companyUid } : {}),
+        ...(context.companySlug ? { companySlug: context.companySlug } : {}),
+    };
+}
+//# sourceMappingURL=process-flag-company-context-fast.js.map

package/dist/lib/process-flag-company-context-light.d.ts

@@ -0,0 +1,9 @@
+/** Lightweight process company context shared by full and fast flag readers. */
+export interface ProcessFlagCompanyContext {
+    companyUid?: string;
+    companySlug?: string;
+}
+export declare function normalizedCompanyUid(value: string | undefined): string | undefined;
+/** Resolve explicit, machine, or bound-session company scope without defaults. */
+export declare function resolveLightProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): ProcessFlagCompanyContext;
+//# sourceMappingURL=process-flag-company-context-light.d.ts.map

package/dist/lib/process-flag-company-context-light.js

@@ -0,0 +1,81 @@
+/** Lightweight process company context shared by full and fast flag readers. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+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}$/;
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const DEFAULT_AGENT_IDENTITY_FILE = "/var/lib/hq-agent/identity.json";
+export function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
+function normalizedCompanySlug(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readAgentIdentity(env) {
+    const configured = env.HQ_AGENT_IDENTITY_FILE;
+    const file = configured === undefined ? DEFAULT_AGENT_IDENTITY_FILE : configured.trim();
+    if (!file)
+        return undefined;
+    try {
+        const identity = record(JSON.parse(fs.readFileSync(file, "utf8")));
+        const companyUid = normalizedCompanyUid(typeof identity?.companyUid === "string" ? identity.companyUid : undefined);
+        const companySlug = normalizedCompanySlug(typeof identity?.companySlug === "string" ? identity.companySlug : undefined);
+        return companyUid || companySlug ? {
+            ...(companyUid ? { companyUid } : {}),
+            ...(companySlug ? { companySlug } : {}),
+        } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readSessionCompany(env) {
+    const sessionId = env.HQ_SESSION_ID?.trim();
+    if (!sessionId || sessionId.includes("..") || !SESSION_ID_RE.test(sessionId))
+        return undefined;
+    const contextRoot = env.HQ_WORK_CONTEXT_ROOT?.trim() || path.join(os.homedir(), ".hq", "work-context");
+    try {
+        const sessionPath = path.join(contextRoot, "sessions", sessionId + ".json");
+        const session = record(JSON.parse(fs.readFileSync(sessionPath, "utf8")));
+        if (session?.sessionId !== sessionId ||
+            session.contextStatus !== "bound" ||
+            session.companyConfidence === "device_default")
+            return undefined;
+        const companyUid = normalizedCompanyUid(typeof session.companyUid === "string" ? session.companyUid : undefined);
+        const companySlug = normalizedCompanySlug(typeof session.companySlug === "string" ? session.companySlug : undefined);
+        return companyUid || companySlug ? {
+            ...(companyUid ? { companyUid } : {}),
+            ...(companySlug ? { companySlug } : {}),
+        } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve explicit, machine, or bound-session company scope without defaults. */
+export function resolveLightProcessFlagCompanyContext(env = process.env) {
+    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
+    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
+    if (explicitUid || explicitSlug) {
+        return { companyUid: explicitUid, companySlug: explicitSlug };
+    }
+    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
+    if (spawnValue && COMPANY_UID_RE.test(spawnValue))
+        return { companyUid: spawnValue };
+    const spawnSlug = normalizedCompanySlug(spawnValue);
+    if (spawnSlug)
+        return { companySlug: spawnSlug };
+    const identity = readAgentIdentity(env);
+    if (identity)
+        return identity;
+    return readSessionCompany(env) ?? {};
+}
+//# sourceMappingURL=process-flag-company-context-light.js.map

package/dist/lib/process-flag-company-context.d.ts

@@ -1,8 +1,6 @@
 /** Company scope shared by the full flag registry and its fast-path reader. */
-export interface ProcessFlagCompanyContext {
-    companyUid?: string;
-    companySlug?: string;
-}
+import { type ProcessFlagCompanyContext } from "./process-flag-company-context-light.js";
+export type { ProcessFlagCompanyContext } from "./process-flag-company-context-light.js";
 /** Resolve the same company identity the process-wide flag reader uses. */
 export declare function resolveProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): ProcessFlagCompanyContext;
 //# sourceMappingURL=process-flag-company-context.d.ts.map

package/dist/lib/process-flag-company-context.js

@@ -1,51 +1,7 @@
 /** Company scope shared by the full flag registry and its fast-path reader. */
-import { readMachineCompanyBinding } from "./work-context/company.js";
-import { readSessionState } from "./work-context/state.js";
-import { workContextRoot } from "./work-context/paths.js";
 import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
 import { resolveDefaultHqRoot } from "../utils/hq-root-resolver.js";
-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}$/;
-function normalizedCompanyUid(value) {
-    const candidate = value?.trim() ?? "";
-    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
-}
-function normalizedCompanySlug(value) {
-    const candidate = value?.trim() ?? "";
-    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
-}
-/** Resolve explicit, machine, or bound-session company scope without defaults. */
-function processCompanyContext(env = process.env) {
-    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
-    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
-    if (explicitUid || explicitSlug) {
-        return { companyUid: explicitUid, companySlug: explicitSlug };
-    }
-    const machine = readMachineCompanyBinding(env);
-    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
-    const spawnSlug = normalizedCompanySlug(spawnValue);
-    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
-        ? { companyUid: spawnValue }
-        : spawnSlug
-            ? { companySlug: spawnSlug }
-            : {
-                companyUid: normalizedCompanyUid(machine?.uid),
-                companySlug: normalizedCompanySlug(machine?.slug),
-            };
-    if (machineContext.companyUid || machineContext.companySlug)
-        return machineContext;
-    const sessionId = env.HQ_SESSION_ID?.trim();
-    if (!sessionId)
-        return {};
-    const session = readSessionState(sessionId, workContextRoot(undefined, env));
-    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
-        return {};
-    }
-    return {
-        companyUid: normalizedCompanyUid(session.companyUid),
-        companySlug: normalizedCompanySlug(session.companySlug),
-    };
-}
+import { normalizedCompanyUid, resolveLightProcessFlagCompanyContext, } from "./process-flag-company-context-light.js";
 function companyUidForContext(context, env = process.env) {
     if (context.companyUid)
         return context.companyUid;
@@ -57,7 +13,7 @@ function companyUidForContext(context, env = process.env) {
 }
 /** Resolve the same company identity the process-wide flag reader uses. */
 export function resolveProcessFlagCompanyContext(env = process.env) {
-    const context = processCompanyContext(env);
+    const context = resolveLightProcessFlagCompanyContext(env);
     const companyUid = companyUidForContext(context, env);
     return {
         ...(companyUid ? { companyUid } : {}),

package/dist/utils/hq-roots-core.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Root resolution for CLI-hosted HQ scaffold code.
+ *
+ * When shell that used to live inside the HQ scaffold moves into this npm
+ * package, it loses the one thing it relied on: `BASH_SOURCE`/`$0` pointed at
+ * the user's live HQ tree, so "where am I" and "where is HQ" were the same
+ * answer. Inside a globally installed package they are three different answers,
+ * and conflating any two of them silently corrupts the wrong tree.
+ *
+ *   liveRoot    The user's HQ installation — companies/, workspace/, personal/,
+ *               the installed .claude/ and core/. This is runtime state. Hidden
+ *               runtime commands operate here.
+ *
+ *   packageRoot This npm package's own directory, where bundled scaffold assets
+ *               ship. Read-only in practice: a global install may sit in a
+ *               root-owned prefix. NEVER usable as liveRoot.
+ *
+ * There is deliberately no third "source root". Release-source tooling — the
+ * linters, generators, and validators that rewrite checked-in artifacts — stays
+ * scaffold-owned, so nothing here ever needs to resolve an hq-core checkout. See
+ * the scaffold-vs-cli-code-ownership policy for why.
+ *
+ * The invariant that matters most: `resolveLiveRoot` never consults
+ * `import.meta.url`. A relocated script asking "where is HQ" must get the live
+ * tree, not the package it happens to be bundled in.
+ */
+import * as fs from "fs";
+/** Where bundled scaffold assets live, relative to the package root. */
+export declare const BUNDLED_ASSET_DIR: string;
+/**
+ * Does this directory look like an HQ tree root?
+ *
+ * `companies/` is the load-bearing marker — it is the source of truth for
+ * tenants and exists in every real install. The second clause tolerates the
+ * three shapes a tree can legitimately be in: a full install, a scaffold
+ * checkout without a personal overlay, and a personal-only overlay.
+ */
+export declare function isHqRoot(dir: string): boolean;
+export type PackageRootFs = Pick<typeof fs, "existsSync" | "readFileSync" | "realpathSync" | "statSync">;
+export type PackageRootResolverOptions = {
+    /** Directory containing the currently-running compiled module. */
+    moduleDir: string;
+    /** Full module path used only in safe diagnostic output. */
+    modulePath?: string;
+    /** Injectable filesystem seam for resolver tests. */
+    fs?: PackageRootFs;
+};
+/**
+ * Make a resolver for this package's root. It caches only a successful lookup:
+ * a concurrently replaced manifest must be retried by the next command, not
+ * converted into a permanent process failure.
+ */
+export declare function createPackageRootResolver(options: PackageRootResolverOptions): () => string;
+/**
+ * This package's installed root — the directory holding its `package.json`.
+ *
+ * Walks up from the compiled module (`dist/utils/hq-roots.js`) until it finds a
+ * `package.json` whose name matches, rather than hard-coding `..` hops, so the
+ * answer survives a change in output layout.
+ */
+export declare function packageRoot(): string;
+/**
+ * Derive this package's installed root from the running module's OWN path using
+ * STRING operations only — no `readFileSync`, `realpathSync`, or `existsSync`.
+ *
+ * {@link packageRoot} must read `<dir>/package.json` and `realpathSync` the
+ * module directory to answer, so it THROWS in exactly the situation that most
+ * needs an answer: a concurrent global install has renamed the installed
+ * package directory aside (`.hq-cli-<rand>`) and is re-extracting it file by
+ * file, so both the manifest walk and the dist-owner fallback fail on a
+ * directory that is momentarily gone. This walks the compiled module's
+ * ancestors as strings and returns the DEEPEST one whose trailing segments are
+ * `node_modules/@indigoai-us/hq-cli`, which stays correct while that directory
+ * does not exist on disk.
+ *
+ * It is a FALLBACK only — {@link packageRoot} validates the manifest name and
+ * is authoritative whenever it succeeds. Returns null for a dev checkout or any
+ * layout without that segment triple, so a caller that falls back to it can
+ * only ever degrade to today's behaviour (no resolution), never widen it.
+ *
+ * The deepest match is deliberate: a nested `node_modules/@indigoai-us/hq-cli`
+ * inside another package resolves to ITSELF (the copy the module belongs to),
+ * never an outer decoy. Case is folded only for a Windows-shaped path, matching
+ * the POSIX case-sensitivity the rest of this module assumes.
+ */
+export declare function stringDerivedPackageRoot(moduleFilePath?: string): string | null;
+export type LiveRootOptions = {
+    /** Explicit `--hq-root` value. Highest precedence. */
+    hqRoot?: string;
+    /** Start the walk-up here instead of `process.cwd()`. Tests only. */
+    cwd?: string;
+    /** Environment to read. Tests only. */
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Resolve the user's live HQ installation.
+ *
+ * Precedence: `--hq-root` → `HQ_ROOT` → `CLAUDE_PROJECT_DIR` → walk up from cwd.
+ *
+ * ## An explicit root is trusted; a discovered one must be recognized
+ *
+ * The FIRST explicit candidate present wins outright — there is no fall-through
+ * past it, because silently operating on a different tree than the caller named
+ * is the worst available outcome.
+ *
+ * That explicit candidate is checked only for the two things that are always
+ * wrong: it must be a directory, and it must not be inside {@link packageRoot}
+ * (that is this package, not anyone's HQ). It is deliberately NOT required to
+ * satisfy {@link isHqRoot}.
+ *
+ * Requiring markers here was tried and was wrong: the scripts these roots feed
+ * accepted any `HQ_ROOT` before they moved, and several callers legitimately pass
+ * a minimal tree — e.g. `rebuild-threads-index` against a fixture holding nothing
+ * but `workspace/threads/`. Enforcing markers on an explicit value turned a
+ * relocation into a silent contract change and broke those callers.
+ *
+ * The cwd walk is the opposite case: there the marker check is the only thing
+ * that can identify a root at all, so it stays mandatory.
+ */
+export declare function resolveLiveRoot(opts?: LiveRootOptions): string;
+/**
+ * Absolute path to a scaffold asset bundled in this package.
+ *
+ * Refuses to resolve outside the asset directory so a manifest entry can never
+ * be coaxed into executing an arbitrary path, and fails loudly when the asset
+ * is missing — an absent asset means the packlist dropped it, which is a
+ * packaging bug worth surfacing rather than a runtime fallback.
+ */
+export declare function resolveBundledAsset(relativePath: string): string;
+//# sourceMappingURL=hq-roots-core.d.ts.map