@indigoai-us/hq-cli 5.325.0 → 5.327.0

package/dist/utils/hq-roots.js

@@ -1,354 +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";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import { PackageRootResolutionError, } from "./package-root-diagnostics.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(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;
-}
+/** Compatibility entrypoint for the full command graph. */
+export * from "./hq-roots-core.js";
 //# sourceMappingURL=hq-roots.js.map

package/dist/utils/is-main-module.d.ts

@@ -0,0 +1,3 @@
+/** Compare executable and module paths after resolving npm-style symlinks. */
+export declare function isMainModule(moduleUrl: string, argvEntryPath?: string | undefined): boolean;
+//# sourceMappingURL=is-main-module.d.ts.map

package/dist/utils/is-main-module.js

@@ -0,0 +1,19 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Compare executable and module paths after resolving npm-style symlinks. */
+export function isMainModule(moduleUrl, argvEntryPath = process.argv[1]) {
+    if (!argvEntryPath)
+        return false;
+    const modulePath = fileURLToPath(moduleUrl);
+    const invokedPath = path.resolve(argvEntryPath);
+    try {
+        return realpathSync(modulePath) === realpathSync(invokedPath);
+    }
+    catch {
+        // Direct invocation still works if path canonicalization is unavailable;
+        // an unresolved symlink does not get treated as the module entry point.
+        return modulePath === invokedPath;
+    }
+}
+//# sourceMappingURL=is-main-module.js.map

package/dist/utils/package-root-diagnostics.d.ts

@@ -1,40 +1,10 @@
 /**
- * Bounded diagnostics for failures to locate the CLI package root.
- *
- * These values are sent to Sentry, whose general scrubber deliberately keeps
- * filesystem paths intact. Keep this module the single construction boundary
- * so a malformed install cannot turn an error report into an unbounded or
- * multi-line payload.
+ * Bounded Sentry context for failures to locate the CLI package root.
+ * The error value itself is kept in a dependency-light module for fast paths.
  */
-type PackageRootVisitOutcome = "no-manifest" | "eacces" | "eisdir" | "parse-error" | "name-mismatch" | "read-error" | "omitted";
-export type PackageRootVisit = {
-    directory: string;
-    outcome: PackageRootVisitOutcome;
-    code?: string;
-    manifestName?: string;
-};
-export type PackageRootResolutionDiagnostics = {
-    modulePath: string;
-    startDir: string;
-    strategiesTried: string[];
-    visited: PackageRootVisit[];
-    fallbackRejectedBecause: string;
-};
-type RawDiagnostics = {
-    modulePath: string;
-    startDir: string;
-    strategiesTried: string[];
-    visited: PackageRootVisit[];
-    fallbackRejectedBecause: string;
-};
-/** Replace every Unicode control character before bounding a diagnostic value. */
-export declare function boundedDiagnosticValue(value: unknown, maxBytes: number): string;
-/** An unmarked packaging fault that should remain visible in Sentry. */
-export declare class PackageRootResolutionError extends Error {
-    readonly diagnostics: PackageRootResolutionDiagnostics;
-    constructor(raw: RawDiagnostics);
-}
-export declare function isPackageRootResolutionError(err: unknown): err is PackageRootResolutionError;
+import { PackageRootResolutionError, type PackageRootResolutionDiagnostics } from "./package-root-resolution-error.js";
+export { PackageRootResolutionError, isPackageRootResolutionError, type PackageRootVisit, type PackageRootResolutionDiagnostics, } from "./package-root-resolution-error.js";
+export { boundedDiagnosticValue } from "./package-root-resolution-error.js";
 /**
  * Produce the exact Sentry contexts shape while enforcing a whole-payload cap.
  * The tail is dropped first because nearest directories contain the useful
@@ -43,5 +13,4 @@ export declare function isPackageRootResolutionError(err: unknown): err is Packa
 export declare function packageRootCaptureContext(err: PackageRootResolutionError): {
     package_root_resolution: PackageRootResolutionDiagnostics;
 };
-export {};
 //# sourceMappingURL=package-root-diagnostics.d.ts.map

package/dist/utils/package-root-diagnostics.js

@@ -1,90 +1,11 @@
 /**
- * Bounded diagnostics for failures to locate the CLI package root.
- *
- * These values are sent to Sentry, whose general scrubber deliberately keeps
- * filesystem paths intact. Keep this module the single construction boundary
- * so a malformed install cannot turn an error report into an unbounded or
- * multi-line payload.
+ * Bounded Sentry context for failures to locate the CLI package root.
+ * The error value itself is kept in a dependency-light module for fast paths.
  */
 import { beforeSend } from "../sentry-before-send.js";
-const CONTROL_CHARACTER = /[\p{C}\p{Zl}\p{Zp}]/gu;
-const REPLACEMENT = "?";
-const ELLIPSIS = "…";
-const MODULE_PATH_BYTES = 256;
-const START_DIR_BYTES = 256;
-const DIRECTORY_BYTES = 256;
-const MANIFEST_NAME_BYTES = 64;
-const CODE_BYTES = 32;
-const MESSAGE_BYTES = 2048;
+export { PackageRootResolutionError, isPackageRootResolutionError, } from "./package-root-resolution-error.js";
+export { boundedDiagnosticValue } from "./package-root-resolution-error.js";
 const CONTEXT_BYTES = 4096;
-const MAX_VISITED = 12;
-/** Replace every Unicode control character before bounding a diagnostic value. */
-export function boundedDiagnosticValue(value, maxBytes) {
-    const normalized = String(value).replace(CONTROL_CHARACTER, REPLACEMENT);
-    if (Buffer.byteLength(normalized, "utf8") <= maxBytes)
-        return normalized;
-    const markerBytes = Buffer.byteLength(ELLIPSIS, "utf8");
-    let result = "";
-    let used = 0;
-    for (const character of normalized) {
-        const bytes = Buffer.byteLength(character, "utf8");
-        if (used + bytes + markerBytes > maxBytes)
-            break;
-        result += character;
-        used += bytes;
-    }
-    return result + ELLIPSIS;
-}
-function boundedVisit(visit) {
-    return {
-        directory: boundedDiagnosticValue(visit.directory, DIRECTORY_BYTES),
-        outcome: visit.outcome,
-        ...(visit.code === undefined
-            ? {}
-            : { code: boundedDiagnosticValue(visit.code, CODE_BYTES) }),
-        ...(visit.manifestName === undefined
-            ? {}
-            : { manifestName: boundedDiagnosticValue(visit.manifestName, MANIFEST_NAME_BYTES) }),
-    };
-}
-function boundedVisits(visits) {
-    if (visits.length <= MAX_VISITED)
-        return visits.map(boundedVisit);
-    const shown = visits.slice(0, MAX_VISITED - 1).map(boundedVisit);
-    shown.push({
-        directory: `${visits.length - shown.length} more omitted`,
-        outcome: "omitted",
-    });
-    return shown;
-}
-function normalizeDiagnostics(raw) {
-    return {
-        modulePath: boundedDiagnosticValue(raw.modulePath, MODULE_PATH_BYTES),
-        startDir: boundedDiagnosticValue(raw.startDir, START_DIR_BYTES),
-        strategiesTried: raw.strategiesTried.map((strategy) => boundedDiagnosticValue(strategy, CODE_BYTES)),
-        visited: boundedVisits(raw.visited),
-        fallbackRejectedBecause: boundedDiagnosticValue(raw.fallbackRejectedBecause, DIRECTORY_BYTES),
-    };
-}
-function messageFor(diagnostics) {
-    return boundedDiagnosticValue("Could not locate the @indigoai-us/hq-cli package root from " +
-        `${diagnostics.modulePath}; manifest walk exhausted from ${diagnostics.startDir}; ` +
-        `dist-owner fallback ${diagnostics.fallbackRejectedBecause}.`, MESSAGE_BYTES);
-}
-/** An unmarked packaging fault that should remain visible in Sentry. */
-export class PackageRootResolutionError extends Error {
-    diagnostics;
-    constructor(raw) {
-        const diagnostics = normalizeDiagnostics(raw);
-        super(messageFor(diagnostics));
-        this.name = "PackageRootResolutionError";
-        this.diagnostics = diagnostics;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-export function isPackageRootResolutionError(err) {
-    return err instanceof PackageRootResolutionError;
-}
 /**
  * Produce the exact Sentry contexts shape while enforcing a whole-payload cap.
  * The tail is dropped first because nearest directories contain the useful

package/dist/utils/package-root-resolution-error.d.ts

@@ -0,0 +1,32 @@
+/** Lightweight packaging error payload; Sentry formatting lives separately. */
+type PackageRootVisitOutcome = "no-manifest" | "eacces" | "eisdir" | "parse-error" | "name-mismatch" | "read-error" | "omitted";
+export type PackageRootVisit = {
+    directory: string;
+    outcome: PackageRootVisitOutcome;
+    code?: string;
+    manifestName?: string;
+};
+export type PackageRootResolutionDiagnostics = {
+    modulePath: string;
+    startDir: string;
+    strategiesTried: string[];
+    visited: PackageRootVisit[];
+    fallbackRejectedBecause: string;
+};
+type RawDiagnostics = {
+    modulePath: string;
+    startDir: string;
+    strategiesTried: string[];
+    visited: PackageRootVisit[];
+    fallbackRejectedBecause: string;
+};
+/** Replace every Unicode control character before bounding a diagnostic value. */
+export declare function boundedDiagnosticValue(value: unknown, maxBytes: number): string;
+/** An unmarked packaging fault that should remain visible in Sentry. */
+export declare class PackageRootResolutionError extends Error {
+    readonly diagnostics: PackageRootResolutionDiagnostics;
+    constructor(raw: RawDiagnostics);
+}
+export declare function isPackageRootResolutionError(err: unknown): err is PackageRootResolutionError;
+export {};
+//# sourceMappingURL=package-root-resolution-error.d.ts.map

package/dist/utils/package-root-resolution-error.js

@@ -0,0 +1,79 @@
+/** Lightweight packaging error payload; Sentry formatting lives separately. */
+const CONTROL_CHARACTER = /[\p{C}\p{Zl}\p{Zp}]/gu;
+const REPLACEMENT = "?";
+const ELLIPSIS = "…";
+const MODULE_PATH_BYTES = 256;
+const START_DIR_BYTES = 256;
+const DIRECTORY_BYTES = 256;
+const MANIFEST_NAME_BYTES = 64;
+const CODE_BYTES = 32;
+const MESSAGE_BYTES = 2048;
+const MAX_VISITED = 12;
+/** Replace every Unicode control character before bounding a diagnostic value. */
+export function boundedDiagnosticValue(value, maxBytes) {
+    const normalized = String(value).replace(CONTROL_CHARACTER, REPLACEMENT);
+    if (Buffer.byteLength(normalized, "utf8") <= maxBytes)
+        return normalized;
+    const markerBytes = Buffer.byteLength(ELLIPSIS, "utf8");
+    let result = "";
+    let used = 0;
+    for (const character of normalized) {
+        const bytes = Buffer.byteLength(character, "utf8");
+        if (used + bytes + markerBytes > maxBytes)
+            break;
+        result += character;
+        used += bytes;
+    }
+    return result + ELLIPSIS;
+}
+function boundedVisit(visit) {
+    return {
+        directory: boundedDiagnosticValue(visit.directory, DIRECTORY_BYTES),
+        outcome: visit.outcome,
+        ...(visit.code === undefined
+            ? {}
+            : { code: boundedDiagnosticValue(visit.code, CODE_BYTES) }),
+        ...(visit.manifestName === undefined
+            ? {}
+            : { manifestName: boundedDiagnosticValue(visit.manifestName, MANIFEST_NAME_BYTES) }),
+    };
+}
+function boundedVisits(visits) {
+    if (visits.length <= MAX_VISITED)
+        return visits.map(boundedVisit);
+    const shown = visits.slice(0, MAX_VISITED - 1).map(boundedVisit);
+    shown.push({
+        directory: String(visits.length - shown.length) + " more omitted",
+        outcome: "omitted",
+    });
+    return shown;
+}
+function normalizeDiagnostics(raw) {
+    return {
+        modulePath: boundedDiagnosticValue(raw.modulePath, MODULE_PATH_BYTES),
+        startDir: boundedDiagnosticValue(raw.startDir, START_DIR_BYTES),
+        strategiesTried: raw.strategiesTried.map((strategy) => boundedDiagnosticValue(strategy, CODE_BYTES)),
+        visited: boundedVisits(raw.visited),
+        fallbackRejectedBecause: boundedDiagnosticValue(raw.fallbackRejectedBecause, DIRECTORY_BYTES),
+    };
+}
+function messageFor(diagnostics) {
+    return boundedDiagnosticValue("Could not locate the @indigoai-us/hq-cli package root from " +
+        diagnostics.modulePath + "; manifest walk exhausted from " + diagnostics.startDir +
+        "; dist-owner fallback " + diagnostics.fallbackRejectedBecause + ".", MESSAGE_BYTES);
+}
+/** An unmarked packaging fault that should remain visible in Sentry. */
+export class PackageRootResolutionError extends Error {
+    diagnostics;
+    constructor(raw) {
+        const diagnostics = normalizeDiagnostics(raw);
+        super(messageFor(diagnostics));
+        this.name = "PackageRootResolutionError";
+        this.diagnostics = diagnostics;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isPackageRootResolutionError(err) {
+    return err instanceof PackageRootResolutionError;
+}
+//# sourceMappingURL=package-root-resolution-error.js.map

package/dist/utils/staged-npm-install.js

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main-module.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const RANDOM_HEX_BYTES = 6;
 function packageRoot(prefix, platform) {
@@ -239,7 +240,7 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
             bestEffortRemove(backupPackage);
     }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === "--activate") {
+if (isMainModule(import.meta.url) && process.argv[2] === "--activate") {
     const [prefix, stagePrefix, platform] = process.argv.slice(3);
     if (!prefix || !stagePrefix) {
         console.error("usage: staged-npm-install.js --activate <prefix> <stage-prefix> [platform]");