@indigoai-us/hq-cli 5.325.0 → 5.327.0

package/dist/lib/mcp/tools.js

@@ -0,0 +1,82 @@
+/**
+ * Tool surface of `hq mcp serve` (hq-anywhere US-011).
+ *
+ * The hq-mcp tools come from src/lib/mcp/hq-mcp-tools.generated.ts, which
+ * scripts/generate-hq-mcp-tools.mjs builds from repos/public/hq-mcp. The four
+ * daemon-native tools are defined here. Names use underscores because
+ * Anthropic and OpenAI tool names reject dots (hq.resolve_company is exposed
+ * as hq_resolve_company).
+ *
+ * hqd answers every one of these through the `mcp.call` op, so a subagent
+ * without MCP can call the same tool with
+ * `hq daemon call mcp.call --json '{"name":"hq_journal_append","arguments":{...}}'`.
+ */
+import { HQ_MCP_TOOLS } from "./hq-mcp-tools.generated.js";
+import { HOSTED_SEARCH_FETCH_TOOLS } from "./hosted-search-tools.js";
+const companyProp = { type: "string", description: "Company slug. Defaults to the company linked to cwd." };
+const cwdProp = { type: "string", description: "Directory to resolve the company from. Defaults to the server's working directory." };
+export const HQD_NATIVE_TOOLS = [
+    {
+        name: "hq_resolve_company",
+        description: "Returns the HQ company linked to a directory (registry from `hq link`), with the matched repo path.",
+        inputSchema: { type: "object", properties: { cwd: cwdProp }, additionalProperties: false },
+    },
+    {
+        name: "hq_policy_check",
+        description: "Runs the HQ policy engine for a proposed tool call and returns allow/block plus any policy context to inject. Fails closed when the engine errors.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tool: { type: "string", description: "Tool name the policy is checked for, e.g. Bash or Write" },
+                input: { type: "object", description: "The tool input, e.g. {\"command\": \"git push\"}" },
+                event: { type: "string", description: "Hook event, default PreToolUse" },
+                company: companyProp,
+                cwd: cwdProp,
+                sessionId: { type: "string" },
+            },
+            required: ["tool"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "hq_journal_append",
+        description: "Appends a line to a project's active HQ journal under a section heading.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: { type: "string", description: "Project slug under companies/<company>/projects" },
+                section: { type: "string", enum: ["decisions", "open", "findings", "rejected"], description: "Journal section" },
+                text: { type: "string", description: "The line to append" },
+                company: companyProp,
+                cwd: cwdProp,
+            },
+            required: ["project", "section", "text"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "hq_run_worker",
+        description: "Dispatches an HQ worker skill through the /run command in a detached headless session. Returns the pid and log path; it does not wait for the worker to finish.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                worker: { type: "string", description: "Worker id from core/workers/registry.yaml or a company registry" },
+                skill: { type: "string", description: "Skill name on that worker" },
+                args: { type: "string", description: "Free-text arguments passed to the skill" },
+                company: companyProp,
+                cwd: cwdProp,
+            },
+            required: ["worker"],
+            additionalProperties: false,
+        },
+    },
+];
+export const HQD_NATIVE_TOOL_NAMES = new Set(HQD_NATIVE_TOOLS.map((t) => t.name));
+/** Every tool `hq mcp serve` lists: the four native tools, then the hq-mcp set. */
+export const HQ_MCP_HOSTED_TOOLS = [...HQ_MCP_TOOLS, ...HOSTED_SEARCH_FETCH_TOOLS];
+export const MCP_TOOLS = [
+    ...HQD_NATIVE_TOOLS,
+    ...HQ_MCP_HOSTED_TOOLS.filter((t) => !HQD_NATIVE_TOOL_NAMES.has(t.name)),
+];
+export const HQ_MCP_TOOL_NAMES = new Set(HQ_MCP_HOSTED_TOOLS.map((t) => t.name));
+//# sourceMappingURL=tools.js.map

package/dist/lib/mcp/types.d.ts

@@ -0,0 +1,6 @@
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/mcp/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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