@indigoai-us/hq-cli 5.326.0 → 5.328.0

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

package/dist/utils/hq-roots-core.js

@@ -0,0 +1,354 @@
+/**
+ * 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";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { PackageRootResolutionError, } from "./package-root-resolution-error.js";
+/** This package's name, used to identify its root when walking upward. */
+const CLI_PACKAGE_NAME = "@indigoai-us/hq-cli";
+/**
+ * A root that cannot be resolved is the caller's state — a wrong `--hq-root`, or a
+ * command run from outside any HQ tree. Marking
+ * these `expected` makes the top-level handler print the message and skip Sentry;
+ * an unmarked error there prints NOTHING and only ships a crash report, which is
+ * the worst possible outcome for a misconfiguration the user can fix.
+ *
+ * Deliberately not used for packaging faults — a missing bundled asset IS a
+ * defect and should reach Sentry.
+ */
+function rootError(message) {
+    const err = new Error(message);
+    err.expected = true;
+    return err;
+}
+/** Where bundled scaffold assets live, relative to the package root. */
+export const BUNDLED_ASSET_DIR = path.join("assets", "scaffold");
+/**
+ * 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 function isHqRoot(dir) {
+    return (fs.existsSync(path.join(dir, "companies")) &&
+        (fs.existsSync(path.join(dir, ".claude")) ||
+            fs.existsSync(path.join(dir, "core")) ||
+            fs.existsSync(path.join(dir, "personal"))));
+}
+function realpathOrResolve(p, fileSystem = fs) {
+    try {
+        return fileSystem.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function errorCode(err) {
+    if (err && typeof err === "object" && "code" in err) {
+        const code = err.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+function failureOutcome(code) {
+    if (code === "ENOENT")
+        return "no-manifest";
+    if (code === "EACCES")
+        return "eacces";
+    if (code === "EISDIR")
+        return "eisdir";
+    return "read-error";
+}
+/**
+ * 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 function createPackageRootResolver(options) {
+    const fileSystem = options.fs ?? fs;
+    const modulePath = options.modulePath ?? options.moduleDir;
+    let cachedPackageRoot;
+    return () => {
+        if (cachedPackageRoot !== undefined)
+            return cachedPackageRoot;
+        const visited = [];
+        let dir = options.moduleDir;
+        for (;;) {
+            const manifest = path.join(dir, "package.json");
+            try {
+                const parsed = JSON.parse(fileSystem.readFileSync(manifest, "utf8"));
+                if (parsed.name === CLI_PACKAGE_NAME) {
+                    cachedPackageRoot = realpathOrResolve(dir, fileSystem);
+                    return cachedPackageRoot;
+                }
+                visited.push({
+                    directory: dir,
+                    outcome: "name-mismatch",
+                    manifestName: String(parsed.name),
+                });
+            }
+            catch (err) {
+                const code = errorCode(err);
+                if (code) {
+                    visited.push({ directory: dir, outcome: failureOutcome(code), code });
+                }
+                else {
+                    visited.push({ directory: dir, outcome: "parse-error" });
+                }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        let fallbackRejectedBecause = "no dist-owner ancestor";
+        try {
+            const resolvedModuleDir = fileSystem.realpathSync(options.moduleDir);
+            let candidate = resolvedModuleDir;
+            for (;;) {
+                const relativeModulePath = path.relative(candidate, resolvedModuleDir);
+                if (relativeModulePath.split(path.sep)[0] === "dist") {
+                    const assetDir = path.join(candidate, BUNDLED_ASSET_DIR);
+                    try {
+                        if (fileSystem.existsSync(assetDir) && fileSystem.statSync(assetDir).isDirectory()) {
+                            cachedPackageRoot = candidate;
+                            return cachedPackageRoot;
+                        }
+                        fallbackRejectedBecause =
+                            "deepest dist-owner lacks assets/scaffold";
+                    }
+                    catch (err) {
+                        fallbackRejectedBecause =
+                            `could not inspect deepest dist-owner assets/scaffold (${errorCode(err) ?? "unknown"})`;
+                    }
+                    // Never climb to a shallower dist owner after the nearest owner fails.
+                    break;
+                }
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    break;
+                candidate = parent;
+            }
+        }
+        catch (err) {
+            fallbackRejectedBecause =
+                `could not realpath module directory (${errorCode(err) ?? "unknown"})`;
+        }
+        throw new PackageRootResolutionError({
+            modulePath,
+            startDir: options.moduleDir,
+            strategiesTried: ["manifest-walk", "dist-owner-fallback"],
+            visited,
+            fallbackRejectedBecause,
+        });
+    };
+}
+const currentModulePath = fileURLToPath(new URL("./hq-roots.js", import.meta.url));
+const defaultPackageRootResolver = createPackageRootResolver({
+    moduleDir: path.dirname(currentModulePath),
+    modulePath: currentModulePath,
+});
+/**
+ * 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 function packageRoot() {
+    return defaultPackageRootResolver();
+}
+/**
+ * The trailing path segments that mark an installed copy of this package:
+ * `node_modules` followed by the package name's own segments (for
+ * `@indigoai-us/hq-cli`, that is `node_modules/@indigoai-us/hq-cli`).
+ */
+const INSTALLED_ROOT_SEGMENTS = ["node_modules", ...CLI_PACKAGE_NAME.split("/")];
+/** A Windows-shaped absolute path (drive letter or UNC), regardless of host OS. */
+function looksWin32Path(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+/**
+ * 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 function stringDerivedPackageRoot(moduleFilePath = currentModulePath) {
+    if (typeof moduleFilePath !== "string" || moduleFilePath.length === 0) {
+        return null;
+    }
+    const wanted = INSTALLED_ROOT_SEGMENTS;
+    const caseInsensitive = looksWin32Path(moduleFilePath);
+    const sameSegment = (a, b) => caseInsensitive ? a.toLowerCase() === b.toLowerCase() : a === b;
+    // Tokenise into segments with each one's end offset in the ORIGINAL string,
+    // so the returned root keeps the source path's leading root and separators
+    // verbatim (a leading `/`, or a `C:\` drive) rather than a rejoined guess.
+    const segments = [];
+    const segmentPattern = /[^\\/]+/g;
+    let match;
+    while ((match = segmentPattern.exec(moduleFilePath)) !== null) {
+        segments.push({ text: match[0], end: match.index + match[0].length });
+    }
+    if (segments.length < wanted.length)
+        return null;
+    // Scan from the deepest segment upward; the first (deepest) leaf whose
+    // preceding segments complete the triple wins.
+    for (let leaf = segments.length - 1; leaf >= wanted.length - 1; leaf--) {
+        let matched = true;
+        for (let k = 0; k < wanted.length; k++) {
+            if (!sameSegment(segments[leaf - (wanted.length - 1) + k].text, wanted[k])) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched)
+            return moduleFilePath.slice(0, segments[leaf].end);
+    }
+    return null;
+}
+/**
+ * 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 function resolveLiveRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const candidates = [];
+    if (opts.hqRoot) {
+        candidates.push({ value: opts.hqRoot, source: "--hq-root" });
+    }
+    if (env.HQ_ROOT) {
+        candidates.push({ value: env.HQ_ROOT, source: "$HQ_ROOT" });
+    }
+    if (env.CLAUDE_PROJECT_DIR) {
+        candidates.push({
+            value: env.CLAUDE_PROJECT_DIR,
+            source: "$CLAUDE_PROJECT_DIR",
+        });
+    }
+    const explicit = candidates[0];
+    if (explicit) {
+        const resolved = realpathOrResolve(explicit.value);
+        if (isWithinPackage(resolved)) {
+            throw rootError(`${explicit.source} points inside the ${CLI_PACKAGE_NAME} package ` +
+                `(${resolved}). That is the CLI's own install directory, not an HQ tree.`);
+        }
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+            throw rootError(`${explicit.source} is not a directory: ${resolved}`);
+        }
+        return resolved;
+    }
+    // Walk up from cwd. Unlike the explicit tiers this is a guess, so failing to
+    // find a root here is reported as "run this from inside HQ" rather than as a
+    // bad value.
+    let dir = realpathOrResolve(opts.cwd ?? process.cwd());
+    for (;;) {
+        if (isHqRoot(dir) && !isWithinPackage(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw rootError("Could not find your HQ installation. Run this from inside your HQ " +
+        "directory, or pass --hq-root <path> / set $HQ_ROOT.");
+}
+function isWithinPackage(candidate) {
+    let root;
+    try {
+        root = packageRoot();
+    }
+    catch {
+        // If we cannot locate our own package we cannot be inside it either.
+        return false;
+    }
+    const rel = path.relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * 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 function resolveBundledAsset(relativePath) {
+    const assetDir = path.join(packageRoot(), BUNDLED_ASSET_DIR);
+    const resolved = path.resolve(assetDir, relativePath);
+    const rel = path.relative(assetDir, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`Bundled asset path escapes ${BUNDLED_ASSET_DIR}: ${relativePath}`);
+    }
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Bundled asset is missing from the installed package: ${BUNDLED_ASSET_DIR}/${relativePath}\n` +
+            "This is a packaging fault — the file exists in source but was not published.");
+    }
+    return resolved;
+}
+//# sourceMappingURL=hq-roots-core.js.map

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

@@ -1,130 +1,3 @@
-/**
- * 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;
+/** Compatibility entrypoint for the full command graph. */
+export * from "./hq-roots-core.js";
 //# sourceMappingURL=hq-roots.d.ts.map