@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/utils/redact-url.js

@@ -0,0 +1,218 @@
+/** Marker used when a value claims to be a URL but cannot be parsed safely. */
+export const REDACTED_URL = "[REDACTED]";
+const EXACT_SECRET_PARAMETER_NAMES = new Set([
+    "key",
+    "apikey",
+    "api_key",
+    "x-api-key",
+    "xmcpkey",
+    "token",
+    "access_token",
+    "refresh_token",
+    "secret",
+    "client_secret",
+    "password",
+    "pass",
+    "pwd",
+    "auth",
+    "authorization",
+    "sig",
+    "signature",
+    "session",
+    "code",
+    "credential",
+    "credentials",
+    "authcode",
+    "authorizationcode",
+    "oauthcode",
+    "clientcode",
+    "verificationcode",
+    "confirmationcode",
+    "resetcode",
+    "activationcode",
+    "invitecode",
+    "devicecode",
+    "pairingcode",
+    "onetimecode",
+    "otpcode",
+    "auth_code",
+    "authorization_code",
+    "oauth_code",
+    "client_code",
+    "verification_code",
+    "confirmation_code",
+    "reset_code",
+    "activation_code",
+    "invite_code",
+    "device_code",
+    "pairing_code",
+    "one_time_code",
+    "otp_code",
+]);
+const UNAMBIGUOUS_SECRET_PARAMETER_SUFFIXES = [
+    "key",
+    "token",
+    "secret",
+    "password",
+    "signature",
+    "credential",
+    "credentials",
+];
+const AMBIGUOUS_SECRET_PARAMETER_SUFFIXES = ["pass", "pwd", "sig", "auth", "session"];
+const SECRET_PATH_LABEL = /^(?:access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|x?mcpkey|client[_-]?secret|token|key|secret|password|pass|pwd|auth|authorization|sig|signature|credential|credentials|session)[=_-].+$/i;
+function hasParameterBoundaryBeforeSuffix(name, suffix) {
+    const suffixStart = name.length - suffix.length;
+    if (suffixStart <= 0)
+        return true;
+    return /[-_.]/.test(name[suffixStart - 1]) || /[A-Z]/.test(name[suffixStart]);
+}
+function isSecretParameterName(name) {
+    const normalized = name.toLowerCase();
+    return (EXACT_SECRET_PARAMETER_NAMES.has(normalized) ||
+        UNAMBIGUOUS_SECRET_PARAMETER_SUFFIXES.some((suffix) => normalized.endsWith(suffix)) ||
+        AMBIGUOUS_SECRET_PARAMETER_SUFFIXES.some((suffix) => normalized.endsWith(suffix) && hasParameterBoundaryBeforeSuffix(name, suffix)));
+}
+function isOpaqueCapabilitySegment(segment) {
+    if (SECRET_PATH_LABEL.test(segment))
+        return true;
+    const length = segment.length;
+    const hasLetter = /[A-Za-z]/.test(segment);
+    const hasDigit = /\d/.test(segment);
+    const isLongHex = length >= 24 && /^[A-Fa-f0-9]+$/.test(segment);
+    const isLongBase64Url = length >= 32 &&
+        /^[A-Za-z0-9_-]+$/.test(segment) &&
+        hasLetter &&
+        (hasDigit || /[A-Z_-]/.test(segment));
+    return (length >= 20 && hasLetter && hasDigit) || isLongHex || isLongBase64Url;
+}
+/** Mask opaque credential-like path segments while keeping ordinary routes. */
+function redactPathSegments(pathname) {
+    const segments = pathname.split("/");
+    const redacted = segments.map((segment) => {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch (error) {
+            if (error instanceof URIError)
+                return null;
+            throw error;
+        }
+        return isOpaqueCapabilitySegment(decoded) ? "REDACTED" : segment;
+    });
+    return redacted.some((segment) => segment === null) ? null : redacted.join("/");
+}
+/**
+ * Redact the values of secret-looking URL parameters while retaining URL
+ * structure and safe query values. An invalid URL or malformed encoded
+ * parameter name is replaced in full because its secret boundaries are
+ * unknowable.
+ */
+export function redactSensitiveUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            return REDACTED_URL;
+        throw error;
+    }
+    const hasUserinfo = url.username !== "" || url.password !== "";
+    url.username = "";
+    url.password = "";
+    const pathname = redactPathSegments(url.pathname);
+    if (pathname === null)
+        return REDACTED_URL;
+    url.pathname = pathname;
+    const query = redactParameterList(url.search.slice(1));
+    if (query === null)
+        return REDACTED_URL;
+    url.search = query === "" ? "" : `?${query}`;
+    const fragment = redactFragment(url.hash.slice(1));
+    if (fragment === null)
+        return REDACTED_URL;
+    url.hash = fragment === "" ? "" : `#${fragment}`;
+    const serialized = url.toString();
+    if (!hasUserinfo)
+        return serialized;
+    const authorityStart = serialized.indexOf("://");
+    if (authorityStart === -1)
+        return serialized;
+    const hostStart = authorityStart + 3;
+    return `${serialized.slice(0, hostStart)}***@${serialized.slice(hostStart)}`;
+}
+/** Redact secret parameters in an ampersand-separated query or fragment. */
+function redactParameterList(raw) {
+    if (raw === "")
+        return "";
+    const parts = raw.split("&");
+    const redacted = [];
+    for (const part of parts) {
+        const equalsAt = part.indexOf("=");
+        const encodedName = equalsAt === -1 ? part : part.slice(0, equalsAt);
+        let name;
+        try {
+            name = decodeURIComponent(encodedName.replace(/\+/g, " "));
+        }
+        catch (error) {
+            if (error instanceof URIError)
+                return null;
+            throw error;
+        }
+        if (isSecretParameterName(name)) {
+            redacted.push(`${encodedName}=REDACTED`);
+        }
+        else {
+            redacted.push(part);
+        }
+    }
+    return redacted.join("&");
+}
+/** Redact query-like fields in both `#access_token=...` and `#/route?...`. */
+function redactFragment(fragment) {
+    if (fragment === "")
+        return "";
+    const queryStart = fragment.indexOf("?");
+    if (queryStart !== -1) {
+        const query = redactParameterList(fragment.slice(queryStart + 1));
+        return query === null ? null : `${fragment.slice(0, queryStart + 1)}${query}`;
+    }
+    if (fragment.includes("="))
+        return redactParameterList(fragment);
+    return fragment;
+}
+const URL_IN_TEXT = /\b[a-z][a-z\d+.-]*:\/\/[^\s<>"'`]+/gi;
+const TRAILING_SENTENCE_PUNCTUATION = /[),.;!?]+$/;
+/** Redact URLs embedded in an error or human-readable sentence. */
+export function redactUrlsInText(text) {
+    return text.replace(URL_IN_TEXT, (candidate) => {
+        const punctuation = TRAILING_SENTENCE_PUNCTUATION.exec(candidate)?.[0] ?? "";
+        const url = punctuation ? candidate.slice(0, -punctuation.length) : candidate;
+        return `${redactSensitiveUrl(url)}${punctuation}`;
+    });
+}
+const URL_PROPERTY = /(?:^|[-_.])(?:url|uri|endpoint)$/i;
+const CAMEL_URL_PROPERTY = /(?:Url|Uri|Endpoint)$/;
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:\/\//i;
+function isUrlProperty(key) {
+    return URL_PROPERTY.test(key) || CAMEL_URL_PROPERTY.test(key);
+}
+/** Clone a JSON-like value with all URL-valued fields and embedded URLs safe. */
+export function redactSensitiveUrls(value) {
+    if (typeof value === "string")
+        return redactUrlsInText(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactSensitiveUrls(item));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        typeof item === "string" && isUrlProperty(key)
+            ? ABSOLUTE_URL.test(item)
+                ? redactSensitiveUrl(item)
+                : redactUrlsInText(item)
+            : redactSensitiveUrls(item),
+    ]));
+}
+//# sourceMappingURL=redact-url.js.map

package/dist/utils/run-bundled-script.d.ts

@@ -50,10 +50,16 @@ export type RunBundledScriptOptions = {
     hqRoot?: string;
     /** Extra environment for the child, applied last. */
     env?: Record<string, string | undefined>;
+    /** Capture stdout and stderr as bytes instead of inheriting those streams. */
+    captureOutput?: boolean;
 };
 export type RunBundledScriptResult = {
     /** The child's exit code, or 128+signal if it was terminated by one. */
     code: number;
+    /** Present when captureOutput is true. */
+    stdout?: Buffer;
+    /** Present when captureOutput is true. */
+    stderr?: Buffer;
 };
 /**
  * Execute a bundled scaffold script and return its exit code.

package/dist/utils/run-bundled-script.js

@@ -29,6 +29,7 @@
  *     script needs to see termination, not a success code.
  */
 import { spawnSync } from "child_process";
+import * as fs from "node:fs";
 import * as path from "path";
 import { resolveBundledAsset } from "./hq-roots.js";
 /**
@@ -41,6 +42,93 @@ export function interpreterFor(asset) {
     const ext = path.extname(asset).toLowerCase();
     return ext === ".mjs" || ext === ".js" || ext === ".cjs" ? "node" : "bash";
 }
+function envValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+}
+function isFile(file, lookupErrors) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch (error) {
+        // Missing PATH candidates are expected during lookup; retain the cause so
+        // the final actionable error can expose why no interpreter was resolved.
+        lookupErrors.push(error);
+        return false;
+    }
+}
+function isWithinWindowsDirectory(file, directory) {
+    const normalizedFile = path.win32.resolve(file).toLowerCase();
+    const normalizedDirectory = path.win32.resolve(directory).toLowerCase();
+    return (normalizedFile === normalizedDirectory ||
+        normalizedFile.startsWith(`${normalizedDirectory}${path.win32.sep}`));
+}
+function isExcludedWindowsBash(file, env) {
+    if (path.win32.basename(file).toLowerCase() !== "bash.exe")
+        return false;
+    const windowsDir = envValue(env, "SystemRoot") ?? envValue(env, "WINDIR") ?? "C:\\Windows";
+    const systemBash = path.win32.resolve(windowsDir, "System32", "bash.exe");
+    if (path.win32.resolve(file).toLowerCase() === systemBash.toLowerCase())
+        return true;
+    const localAppData = envValue(env, "LOCALAPPDATA");
+    return Boolean(localAppData &&
+        isWithinWindowsDirectory(file, path.win32.resolve(localAppData, "Microsoft", "WindowsApps")));
+}
+function findOnWindowsPath(executable, env, lookupErrors) {
+    const pathValue = envValue(env, "PATH") ?? "";
+    const extensions = executable.includes(".")
+        ? [""]
+        : (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD")
+            .split(";")
+            .filter(Boolean)
+            .map((ext) => ext.toLowerCase());
+    for (const entry of pathValue.split(";").filter(Boolean)) {
+        const directory = entry.trim().replace(/^"|"$/g, "");
+        for (const extension of extensions) {
+            const candidate = path.win32.join(directory, `${executable}${extension}`);
+            if (!isExcludedWindowsBash(candidate, env) && isFile(candidate, lookupErrors))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function resolveWindowsBash(env) {
+    const lookupErrors = [];
+    const configured = envValue(env, "CLAUDE_CODE_GIT_BASH_PATH");
+    if (configured && !isExcludedWindowsBash(configured, env) && isFile(configured, lookupErrors)) {
+        return { executable: configured, cause: lookupErrors.at(-1) };
+    }
+    const pathBash = findOnWindowsPath("bash", env, lookupErrors);
+    if (pathBash)
+        return { executable: pathBash, cause: lookupErrors.at(-1) };
+    const gitExe = findOnWindowsPath("git.exe", env, lookupErrors);
+    if (gitExe) {
+        const derived = path.win32.resolve(path.win32.dirname(gitExe), "..", "bin", "bash.exe");
+        if (!isExcludedWindowsBash(derived, env) && isFile(derived, lookupErrors)) {
+            return { executable: derived, cause: lookupErrors.at(-1) };
+        }
+    }
+    const programFiles = envValue(env, "ProgramFiles") ?? "C:\\Program Files";
+    const localAppData = envValue(env, "LOCALAPPDATA");
+    const standardPaths = [
+        path.win32.join(programFiles, "Git", "bin", "bash.exe"),
+        ...(localAppData ? [path.win32.join(localAppData, "Programs", "Git", "bin", "bash.exe")] : []),
+    ];
+    const executable = standardPaths.find((candidate) => !isExcludedWindowsBash(candidate, env) && isFile(candidate, lookupErrors));
+    return {
+        executable,
+        cause: lookupErrors.at(-1) ??
+            Object.assign(new Error("Bash was not found (ENOENT)"), { code: "ENOENT" }),
+    };
+}
+function bashNotFoundError(asset, cause) {
+    const isHandoff = asset.replaceAll("\\", "/").endsWith("core/scripts/handoff-finalize.sh");
+    const recovery = isHandoff
+        ? "The handoff was not saved; rerun the command."
+        : "The script did not run; rerun this command.";
+    return new Error(`Bash was not found to run bundled script ${asset}. Install Git for Windows or ` +
+        `set CLAUDE_CODE_GIT_BASH_PATH. ${recovery}`, { cause });
+}
 /**
  * Execute a bundled scaffold script and return its exit code.
  *
@@ -56,14 +144,30 @@ export function runBundledScript(opts) {
         env.CLAUDE_PROJECT_DIR = opts.hqRoot;
     }
     Object.assign(env, opts.env ?? {});
-    const result = spawnSync(interpreterFor(opts.asset), [script, ...(opts.args ?? [])], {
+    const interpreter = interpreterFor(opts.asset);
+    const windowsBash = process.platform === "win32" && interpreter === "bash"
+        ? resolveWindowsBash(env)
+        : undefined;
+    const executable = windowsBash?.executable ?? interpreter;
+    if (windowsBash && !windowsBash.executable) {
+        throw bashNotFoundError(opts.asset, windowsBash.cause);
+    }
+    const result = spawnSync(executable, [script, ...(opts.args ?? [])], {
         cwd: opts.cwd,
         env,
-        stdio: "inherit",
+        stdio: opts.captureOutput ? ["inherit", "pipe", "pipe"] : "inherit",
+        ...(opts.captureOutput ? { maxBuffer: Number.MAX_SAFE_INTEGER } : {}),
     });
     if (result.error) {
+        const spawnError = result.error;
+        if (process.platform === "win32" &&
+            interpreter === "bash" &&
+            spawnError.code === "ENOENT") {
+            throw bashNotFoundError(opts.asset, spawnError);
+        }
         throw new Error(`Failed to run bundled script ${opts.asset}: ${result.error.message}`);
     }
+    let code;
     if (result.signal) {
         // Conventional shell encoding, so a caller checking for termination sees it.
         const signals = {
@@ -73,8 +177,17 @@ export function runBundledScript(opts) {
             SIGKILL: 9,
             SIGTERM: 15,
         };
-        return { code: 128 + (signals[result.signal] ?? 0) };
+        code = 128 + (signals[result.signal] ?? 0);
+    }
+    else {
+        code = result.status ?? 0;
     }
-    return { code: result.status ?? 0 };
+    return {
+        code,
+        ...(opts.captureOutput ? {
+            stdout: result.stdout ?? Buffer.alloc(0),
+            stderr: result.stderr ?? Buffer.alloc(0),
+        } : {}),
+    };
 }
 //# sourceMappingURL=run-bundled-script.js.map

package/dist/utils/sandbox-runner-client.d.ts

@@ -1,4 +1,4 @@
-export type SandboxRunnerState = "queued" | "running" | "succeeded" | "failed";
+type SandboxRunnerState = "queued" | "running" | "succeeded" | "failed";
 export interface SandboxRunnerStartRequest {
     companyUid: string;
     secretNames: string[];
@@ -45,4 +45,5 @@ export declare class SandboxRunnerClient {
     getJob(token: string, jobId: string): Promise<SandboxRunnerJob>;
     pollJob(token: string, jobId: string, options?: SandboxRunnerPollOptions): Promise<SandboxRunnerJob>;
 }
+export {};
 //# sourceMappingURL=sandbox-runner-client.d.ts.map

package/dist/utils/scaffold-fast-import-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function assertFastPathStaysCommandGraphFree(loadedModules: readonly string[], distDirectory: string, allowedCommandModules?: readonly string[]): void;
+//# sourceMappingURL=scaffold-fast-import-guard.d.ts.map

package/dist/utils/scaffold-fast-import-guard.js

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+function forbiddenFastPathModules(loadedModules, distDirectory, allowedCommandModules = []) {
+    const dist = path.resolve(distDirectory);
+    const main = path.join(dist, "main.js");
+    const commands = `${path.join(dist, "commands")}${path.sep}`;
+    const flagRegistry = path.join(dist, "lib", "flag-registry.js");
+    const coreCommand = path.join(dist, "commands", "core.js");
+    const fullNetworkCompat = path.join(dist, "node-network-compat.js");
+    const sentryEntrypoint = path.join(dist, "sentry.js");
+    const allowedCommands = new Set(allowedCommandModules.map((module) => path.resolve(module)));
+    return [...new Set(loadedModules.map((loaded) => {
+            if (loaded.startsWith("file:")) {
+                try {
+                    return fileURLToPath(loaded);
+                }
+                catch {
+                    return loaded;
+                }
+            }
+            return path.resolve(loaded);
+        }))]
+        .filter((loaded) => path.resolve(loaded) === main ||
+        path.resolve(loaded).startsWith(commands) ||
+        path.resolve(loaded) === flagRegistry ||
+        path.resolve(loaded) === coreCommand ||
+        path.resolve(loaded) === fullNetworkCompat ||
+        path.resolve(loaded) === sentryEntrypoint ||
+        path.resolve(loaded).includes(`${path.sep}node_modules${path.sep}@sentry${path.sep}`))
+        .filter((loaded) => !allowedCommands.has(path.resolve(loaded)) ||
+        path.resolve(loaded) === main || path.resolve(loaded) === coreCommand)
+        .sort();
+}
+export function assertFastPathStaysCommandGraphFree(loadedModules, distDirectory, allowedCommandModules = []) {
+    const forbidden = forbiddenFastPathModules(loadedModules, distDirectory, allowedCommandModules);
+    if (forbidden.length > 0) {
+        throw new Error(`fast core loaded forbidden command modules:\n${forbidden.join("\n")}`);
+    }
+}
+//# sourceMappingURL=scaffold-fast-import-guard.js.map

package/dist/utils/scaffold-packlist-guard.d.ts

@@ -0,0 +1,7 @@
+export type ScaffoldPacklistCheck = {
+    missingAssets: string[];
+    forbiddenTestData: string[];
+};
+export declare function checkScaffoldPacklist(listedAssets: readonly string[], packedPaths: ReadonlySet<string>, assetPrefix: string): ScaffoldPacklistCheck;
+export declare function assertScaffoldPacklist(listedAssets: readonly string[], packedPaths: ReadonlySet<string>, assetPrefix: string): void;
+//# sourceMappingURL=scaffold-packlist-guard.d.ts.map

package/dist/utils/scaffold-packlist-guard.js

@@ -0,0 +1,23 @@
+export function checkScaffoldPacklist(listedAssets, packedPaths, assetPrefix) {
+    const prefix = assetPrefix.replace(/\/$/, "");
+    const missingAssets = listedAssets
+        .map((asset) => `${prefix}/${asset}`)
+        .filter((assetPath) => !packedPaths.has(assetPath))
+        .sort();
+    const forbiddenTestData = [...packedPaths]
+        .filter((packedPath) => packedPath === "test/differential" ||
+        packedPath.startsWith("test/differential/") ||
+        packedPath.split("/").some((part) => /corpus/i.test(part)))
+        .sort();
+    return { missingAssets, forbiddenTestData };
+}
+export function assertScaffoldPacklist(listedAssets, packedPaths, assetPrefix) {
+    const check = checkScaffoldPacklist(listedAssets, packedPaths, assetPrefix);
+    const failures = [
+        ...check.missingAssets.map((asset) => `missing listed asset ${asset}`),
+        ...check.forbiddenTestData.map((file) => `test data leaked into packlist: ${file}`),
+    ];
+    if (failures.length > 0)
+        throw new Error(failures.join("\n"));
+}
+//# sourceMappingURL=scaffold-packlist-guard.js.map

package/dist/utils/scaffold-sibling-references.d.ts

@@ -0,0 +1,22 @@
+type SiblingAssetReference = {
+    referringAsset: string;
+    targetAsset: string;
+};
+type HqRootAssetReference = {
+    referringAsset: string;
+    reference: string;
+};
+export type ScaffoldReferenceScan = {
+    missing: SiblingAssetReference[];
+    allowedHqRoot: HqRootAssetReference[];
+};
+/**
+ * Scan every asset below assets/scaffold for local file loads. Node source is
+ * identified by extension or shebang; unknown text assets use shell scanning.
+ * `${HQ_ROOT}/...` paths stay rooted in the live HQ tree and are returned as
+ * allowed references for review instead of being mistaken for package assets.
+ */
+export declare function scanScaffoldSiblingReferences(scaffoldRoot: string): ScaffoldReferenceScan;
+export declare function assertNoMissingScaffoldSiblings(scan: ScaffoldReferenceScan): void;
+export {};
+//# sourceMappingURL=scaffold-sibling-references.d.ts.map

package/dist/utils/scaffold-sibling-references.js

@@ -0,0 +1,156 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+const SCRIPT_ROOT_TOKENS = /(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)/g;
+const BASH_SOURCE_TOKEN = String.raw `(?:\$\{BASH_SOURCE\[0\](?::-\$0)?\}|\$\{?0\}?)`;
+function relativePath(root, target) {
+    return path.relative(root, target).split(path.sep).join("/") || ".";
+}
+function filesBelow(root) {
+    const files = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!current)
+            continue;
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(fullPath);
+            else if (entry.isFile())
+                files.push(fullPath);
+        }
+    }
+    return files.sort();
+}
+function shellLocationAliases(contents) {
+    // Asset-relative values point into the package. HQ-root values are live-tree
+    // paths, so keep them visible as allowed references instead of package deps.
+    const aliases = new Map([
+        ["SCRIPT_DIR", { kind: "asset", baseDirectory: "." }],
+        ["HQ_ROOT", { kind: "hq-root", baseDirectory: "." }],
+    ]);
+    for (const line of contents.split(/\r?\n/)) {
+        const assignment = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!assignment)
+            continue;
+        const [, name, value] = assignment;
+        if (name === "HQ_ROOT" || /\$\{?(?:HQ_ROOT|CLAUDE_PROJECT_DIR)(?:\}|(?=[:/}]))/.test(value)) {
+            aliases.set(name, { kind: "hq-root", baseDirectory: "." });
+            continue;
+        }
+        SCRIPT_ROOT_TOKENS.lastIndex = 0;
+        const scriptRoot = SCRIPT_ROOT_TOKENS.exec(value);
+        if (scriptRoot) {
+            const suffix = value.slice(scriptRoot.index + scriptRoot[0].length)
+                .match(/^\/([^"'`\s;|&)}]+)/)?.[1] ?? ".";
+            aliases.set(name, { kind: "asset", baseDirectory: path.posix.normalize(suffix) });
+            continue;
+        }
+        const dirname = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)]+)?`).exec(value);
+        if (dirname) {
+            const suffix = dirname[1]?.replace(/^\/+/, "") ?? ".";
+            aliases.set(name, { kind: "asset", baseDirectory: path.posix.normalize(suffix) });
+        }
+    }
+    return aliases;
+}
+function isNodeAsset(file, contents) {
+    if ([".js", ".mjs", ".cjs"].includes(path.extname(file).toLowerCase()))
+        return true;
+    const shebang = contents.split(/\r?\n/, 1)[0] ?? "";
+    return /^#!.*(?:[\s/])node(?:js)?(?:\s|$)/.test(shebang);
+}
+/**
+ * Scan every asset below assets/scaffold for local file loads. Node source is
+ * identified by extension or shebang; unknown text assets use shell scanning.
+ * `${HQ_ROOT}/...` paths stay rooted in the live HQ tree and are returned as
+ * allowed references for review instead of being mistaken for package assets.
+ */
+export function scanScaffoldSiblingReferences(scaffoldRoot) {
+    const root = path.resolve(scaffoldRoot);
+    const bundledFiles = filesBelow(root);
+    const bundledPaths = new Set(bundledFiles.map((file) => relativePath(root, file)));
+    const missing = [];
+    const allowedHqRoot = new Map();
+    const missingSet = new Set();
+    const recordRelative = (sourceFile, specifier, baseDirectory = ".") => {
+        const referringAsset = relativePath(root, sourceFile);
+        const targetPath = path.resolve(path.dirname(sourceFile), baseDirectory, specifier.replace(/^\/+/, ""));
+        const targetAsset = relativePath(root, targetPath);
+        if (bundledPaths.has(targetAsset))
+            return;
+        const key = `${referringAsset}\0${targetAsset}`;
+        if (missingSet.has(key))
+            return;
+        missingSet.add(key);
+        missing.push({ referringAsset, targetAsset });
+    };
+    for (const sourceFile of bundledFiles) {
+        const contents = fs.readFileSync(sourceFile, "utf8");
+        const referringAsset = relativePath(root, sourceFile);
+        for (const line of contents.split(/\r?\n/)) {
+            if (/^\s*#/.test(line))
+                continue;
+            for (const match of line.matchAll(/\$\{HQ_ROOT(?::-[^}]*)?\}\/([^"'`\s;|&)]+)/g)) {
+                const reference = "${HQ_ROOT}/" + match[1];
+                allowedHqRoot.set(`${referringAsset}\0${reference}`, { referringAsset, reference });
+            }
+            for (const match of line.matchAll(/\$HQ_ROOT\/([^"'`\s;|&)]+)/g)) {
+                const reference = `$HQ_ROOT/${match[1]}`;
+                allowedHqRoot.set(`${referringAsset}\0${reference}`, { referringAsset, reference });
+            }
+        }
+        if (isNodeAsset(sourceFile, contents)) {
+            const nodePatterns = [
+                /new\s+URL\(\s*(['"])(\.\.?\/[^'"]+)\1\s*,\s*import\.meta\.url\s*\)/g,
+                /path\.join\(\s*__dirname\s*,\s*(['"])(\.\.?\/[^'"]+|[^.'"/][^'"]*)\1\s*\)/g,
+            ];
+            for (const pattern of nodePatterns) {
+                for (const match of contents.matchAll(pattern))
+                    recordRelative(sourceFile, match[2]);
+            }
+            continue;
+        }
+        const aliases = shellLocationAliases(contents);
+        const commandLines = contents.split(/\r?\n/).filter((line) => !/^\s*#/.test(line) &&
+            (/\b(?:source|exec|bash|sh|node)\b/.test(line) || /^\s*\.\s+/.test(line)));
+        for (const line of commandLines) {
+            SCRIPT_ROOT_TOKENS.lastIndex = 0;
+            for (const match of line.matchAll(/(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)\/([^"'`\s;|&)}]+)/g)) {
+                recordRelative(sourceFile, match[1]);
+            }
+            const dirnamePath = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)}]+)`, "g");
+            for (const match of line.matchAll(dirnamePath))
+                recordRelative(sourceFile, match[1]);
+            for (const [alias, location] of aliases) {
+                const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                const aliasPath = new RegExp(String.raw `(?:\$\{${escapedAlias}\}|\$${escapedAlias})\/([^"'\x60\s;|&)}]+)`, "g");
+                for (const match of line.matchAll(aliasPath)) {
+                    if (location.kind === "hq-root") {
+                        const reference = match[0];
+                        allowedHqRoot.set(`${referringAsset}\0${reference}`, { referringAsset, reference });
+                    }
+                    else {
+                        recordRelative(sourceFile, match[1], location.baseDirectory);
+                    }
+                }
+            }
+            const relativeCommand = /(?:\b(?:source|exec|bash|sh|node)\s+|^\s*\.\s+)(?:"(\.\.?\/[^"]+)"|'(\.\.?\/[^']+)'|(\.\.?\/[^\s;|&)]+))/g;
+            for (const match of line.matchAll(relativeCommand)) {
+                recordRelative(sourceFile, match[1] ?? match[2] ?? match[3]);
+            }
+        }
+    }
+    return {
+        missing: missing.sort((a, b) => `${a.referringAsset}\0${a.targetAsset}`.localeCompare(`${b.referringAsset}\0${b.targetAsset}`)),
+        allowedHqRoot: [...allowedHqRoot.values()].sort((a, b) => `${a.referringAsset}\0${a.reference}`.localeCompare(`${b.referringAsset}\0${b.reference}`)),
+    };
+}
+export function assertNoMissingScaffoldSiblings(scan) {
+    if (scan.missing.length === 0)
+        return;
+    throw new Error(scan.missing
+        .map(({ referringAsset, targetAsset }) => `${referringAsset} references missing ${targetAsset}`)
+        .join("\n"));
+}
+//# sourceMappingURL=scaffold-sibling-references.js.map

package/dist/utils/secret-load-availability.d.ts

@@ -0,0 +1,8 @@
+export declare class SecretLoadUnavailableError extends Error {
+    readonly serverUnavailable = true;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function isUnavailableSecretLoadHttpStatus(status: number): boolean;
+export declare function isSecretLoadUnavailable(err: unknown): boolean;
+export declare const CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE = "using cached secrets; server unavailable";
+//# sourceMappingURL=secret-load-availability.d.ts.map