@indigoai-us/hq-cli 5.273.0 → 5.274.0

package/dist/lib/first-sync-next-step.js

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resolveProcessFlagGate } from "./flag-registry.js";
+import { cognitoSubjectKey, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
+export const CLI_FIRST_SYNC_NEXT_STEP_FLAG = "cli.first-sync-next-step";
+export const FIRST_SYNC_NEXT_STEP_COPY = "Save a file in your HQ folder, then run `hq sync push`.";
+export const FIRST_SYNC_CONFIRMATION_COPY = "Your first work sync is complete.";
+const AUTOMATION_ENV_MARKERS = [
+    "CI",
+    "HQ_E2E",
+    "HQ_TEST",
+    "HQ_AUTOMATED",
+    "HQ_PROBE",
+    "HQ_AGENT_DIR",
+];
+const pendingOutcomes = [];
+export function shouldShowFirstSyncNextStep(input) {
+    return (input.flagEnabled &&
+        input.interactive &&
+        !input.alreadyShown &&
+        !input.alreadyCompleted);
+}
+export function shouldConfirmFirstWorkBearingSync(input) {
+    return (input.flagEnabled &&
+        input.interactive &&
+        !input.alreadyCompleted &&
+        input.workBearing);
+}
+export function isWorkBearingSyncResult(result) {
+    if (result.aborted === true)
+        return false;
+    return [
+        result.filesUploaded,
+        result.filesDownloaded,
+        result.sessionLogUploadedCount,
+        result.filesDeleted,
+        result.tombstonedCount,
+    ].some((count) => typeof count === "number" && Number.isFinite(count) && count > 0);
+}
+function isNonAutomatedHumanCliProcess(input) {
+    if (input.machineIdentity || input.env.NODE_ENV === "test")
+        return false;
+    return !AUTOMATION_ENV_MARKERS.some((name) => Boolean(input.env[name]?.trim()));
+}
+export function isHumanInteractiveCliSession(input) {
+    if (!input.stdoutIsTTY || !isNonAutomatedHumanCliProcess(input))
+        return false;
+    if (input.argv.some((arg) => ["--json", "--help", "-h", "--version", "-V"].includes(arg))) {
+        return false;
+    }
+    return true;
+}
+function markerDirectory(home) {
+    return path.join(home, ".hq", "first-sync-next-step");
+}
+export function firstSyncStepMarkerPaths(identity, home = process.env.HOME?.trim() || os.homedir()) {
+    const identityHash = createHash("sha256").update(identity).digest("hex");
+    const directory = markerDirectory(home);
+    return {
+        shown: path.join(directory, `${identityHash}.shown`),
+        completed: path.join(directory, `${identityHash}.completed`),
+    };
+}
+function reportMarkerError(action, err) {
+    const code = typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : err instanceof Error
+            ? err.name
+            : "unknown error";
+    console.error(`hq: Could not ${action} first-sync state (${code}).`);
+}
+function firstSyncStepMarkerExists(kind, identity) {
+    try {
+        const paths = firstSyncStepMarkerPaths(identity);
+        return fs.existsSync(paths[kind]);
+    }
+    catch (err) {
+        reportMarkerError("read", err);
+        return false;
+    }
+}
+export function claimFirstSyncStepMarker(kind, identity, home = process.env.HOME?.trim() || os.homedir()) {
+    const paths = firstSyncStepMarkerPaths(identity, home);
+    const hqDirectory = path.join(home, ".hq");
+    try {
+        // Do not create ~/.hq on a signed-out machine. Authenticated CLI sessions
+        // already have it, and this state belongs only to the cached person.
+        if (!fs.existsSync(hqDirectory))
+            return false;
+        fs.mkdirSync(path.dirname(paths[kind]), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(paths[kind], `${new Date().toISOString()}\n`, {
+            flag: "wx",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") {
+            return false;
+        }
+        reportMarkerError("write", err);
+        return false;
+    }
+}
+export function firstSyncStepTelemetryProperties(outcome) {
+    return {
+        step: "first_sync_next_step",
+        outcome,
+        flagKey: CLI_FIRST_SYNC_NEXT_STEP_FLAG,
+    };
+}
+export function isFirstSyncNextStepEnabled() {
+    return resolveProcessFlagGate(CLI_FIRST_SYNC_NEXT_STEP_FLAG, { fallback: false }, () => false);
+}
+function currentPersonIdentity() {
+    return cognitoSubjectKey(loadCachedTokens());
+}
+function isCurrentSessionEligible() {
+    return isHumanInteractiveCliSession({
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        argv: process.argv,
+        env: process.env,
+        machineIdentity: isMachineIdentity(),
+    });
+}
+function queueOutcome(outcome) {
+    if (!pendingOutcomes.includes(outcome))
+        pendingOutcomes.push(outcome);
+}
+/** Called once after the first completed CLI action, before process finalization. */
+export function maybeShowFirstSyncNextStep() {
+    // Keep the cheap eligibility/gate checks ahead of identity and filesystem
+    // reads; neither an automated invocation nor a flag-off session needs state.
+    if (!isCurrentSessionEligible() || !isFirstSyncNextStepEnabled())
+        return false;
+    const identity = currentPersonIdentity();
+    if (!identity)
+        return false;
+    const shouldShow = shouldShowFirstSyncNextStep({
+        flagEnabled: true,
+        interactive: true,
+        alreadyShown: firstSyncStepMarkerExists("shown", identity),
+        alreadyCompleted: firstSyncStepMarkerExists("completed", identity),
+    });
+    if (!shouldShow || !claimFirstSyncStepMarker("shown", identity))
+        return false;
+    console.log(FIRST_SYNC_NEXT_STEP_COPY);
+    queueOutcome("shown");
+    return true;
+}
+/** Capture the first positive CLI sync result without changing transfer logic. */
+export function recordFirstWorkBearingSync(result) {
+    if (!isWorkBearingSyncResult(result))
+        return false;
+    if (!isNonAutomatedHumanCliProcess({
+        env: process.env,
+        machineIdentity: isMachineIdentity(),
+    }))
+        return false;
+    const identity = currentPersonIdentity();
+    if (!identity)
+        return false;
+    const alreadyCompleted = firstSyncStepMarkerExists("completed", identity);
+    if (alreadyCompleted || !claimFirstSyncStepMarker("completed", identity))
+        return false;
+    // Persist completion even while the rollout is off so enabling the flag later
+    // cannot prompt a person who already completed a work-bearing sync. JSON and
+    // other non-interactive human syncs count too; only the message is TTY-gated.
+    if (!isCurrentSessionEligible())
+        return false;
+    if (!shouldConfirmFirstWorkBearingSync({
+        flagEnabled: isFirstSyncNextStepEnabled(),
+        interactive: true,
+        alreadyCompleted: false,
+        workBearing: true,
+    }))
+        return false;
+    console.log(FIRST_SYNC_CONFIRMATION_COPY);
+    if (firstSyncStepMarkerExists("shown", identity))
+        queueOutcome("followed");
+    return true;
+}
+/** Drain outcomes once so each shown/followed event is sent at most once per run. */
+export function takeFirstSyncStepOutcomes() {
+    return pendingOutcomes.splice(0, pendingOutcomes.length);
+}
+//# sourceMappingURL=first-sync-next-step.js.map

package/dist/main.js

@@ -43,7 +43,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { emitCliFirstSyncNextStepOutcome, emitCliSessionStarted, takeFirstSyncStepOutcomes, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -275,6 +275,7 @@ export async function runCli() {
             return;
         }
         await program.parseAsync();
+        maybeShowFirstSyncNextStep();
     }
     catch (err) {
         await handleTopLevelError(err);
@@ -292,9 +293,11 @@ export async function runCli() {
             // lifecycle boundary for this invocation. The budget reserves this 500 ms
             // slice even when the command itself was long-running.
             const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+            const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
             await settleWithin([
                 refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
                 Sentry.flush(releaseHealthTimeoutMs),
+                ...firstSyncOutcomeFlushes,
             ], releaseHealthTimeoutMs);
         });
         // Last, so it wins over anything the (skipped) command path would have

package/dist/utils/cli-telemetry.d.ts

@@ -1,9 +1,13 @@
+import { type FirstSyncStepOutcome } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, type FirstSyncStepOutcome, } from "../lib/first-sync-next-step.js";
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Wording matches the event body: CLI version + timestamp only.
+ * `--json`. Keep this notice and its marker stable for the default telemetry
+ * path; first-sync fields have a separate opt-in disclosure below.
  */
 export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export declare const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
  * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
@@ -25,4 +29,6 @@ export declare function maybeDiscloseCliTelemetry(stderr?: {
  * This deliberately never refreshes a session or opens a browser.
  */
 export declare function emitCliSessionStarted(timeoutMs?: number): Promise<void>;
+/** Emit one authenticated measurement for a first-sync prompt outcome. */
+export declare function emitCliFirstSyncNextStepOutcome(outcome: FirstSyncStepOutcome, timeoutMs?: number): Promise<void>;
 //# sourceMappingURL=cli-telemetry.d.ts.map

package/dist/utils/cli-telemetry.js

@@ -4,14 +4,19 @@ import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
+import { firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Wording matches the event body: CLI version + timestamp only.
+ * `--json`. Keep this notice and its marker stable for the default telemetry
+ * path; first-sync fields have a separate opt-in disclosure below.
  */
 export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
 const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
+const FIRST_SYNC_DISCLOSURE_MARKER = "cli-telemetry-disclosed-first-sync-v1";
 let cliSessionStartedPromise;
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
@@ -30,27 +35,30 @@ function hqConfigDir() {
 export function telemetryDisclosureMarkerPath() {
     return path.join(hqConfigDir(), DISCLOSURE_MARKER);
 }
+function firstSyncTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), FIRST_SYNC_DISCLOSURE_MARKER);
+}
 function wantsJsonOutput(argv = process.argv) {
     return argv.includes("--json");
 }
 function canPrintDisclosure(stdout = process.stdout, argv = process.argv) {
     return Boolean(stdout.isTTY) && !wantsJsonOutput(argv);
 }
-function hasShownDisclosure() {
+function hasShownDisclosure(markerPath) {
     try {
-        return fs.existsSync(telemetryDisclosureMarkerPath());
+        return fs.existsSync(markerPath);
     }
     catch {
         return false;
     }
 }
-function recordDisclosureShown() {
+function recordDisclosureShown(markerPath) {
     try {
         const dir = hqConfigDir();
         // Do not create ~/.hq. Signed-in runs already have it (cached tokens).
         if (!fs.existsSync(dir))
             return;
-        fs.writeFileSync(telemetryDisclosureMarkerPath(), `${new Date().toISOString()}\n`);
+        fs.writeFileSync(markerPath, `${new Date().toISOString()}\n`);
     }
     catch {
         // Marker write is best effort; a repeat print is better than crashing.
@@ -62,17 +70,23 @@ function recordDisclosureShown() {
  * non-TTY stdout skip the print and do not record the marker.
  */
 export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
-    if (hasShownDisclosure())
+    return maybeDiscloseTelemetry(TELEMETRY_DISCLOSURE_LINE, telemetryDisclosureMarkerPath(), stderr, stdout, argv);
+}
+function maybeDiscloseFirstSyncTelemetry() {
+    return maybeDiscloseTelemetry(FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE, firstSyncTelemetryDisclosureMarkerPath());
+}
+function maybeDiscloseTelemetry(line, markerPath, stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    if (hasShownDisclosure(markerPath))
         return true;
     if (!canPrintDisclosure(stdout, argv))
         return false;
     try {
-        stderr.write(`${TELEMETRY_DISCLOSURE_LINE}\n`);
+        stderr.write(`${line}\n`);
     }
     catch {
         return false;
     }
-    recordDisclosureShown();
+    recordDisclosureShown(markerPath);
     return true;
 }
 /**
@@ -131,4 +145,66 @@ async function emitCachedCliSessionStarted(timeoutMs) {
         // Cached-token reads are also best effort (for example, a malformed cache).
     }
 }
+/** Emit one authenticated measurement for a first-sync prompt outcome. */
+export async function emitCliFirstSyncNextStepOutcome(outcome, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        if (!isFirstSyncNextStepEnabled())
+            return;
+        const cached = loadCachedTokens();
+        const machineIdentity = isMachineIdentity();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            }))
+            return;
+        const token = cached.accessToken;
+        if (!token)
+            return;
+        const consentBasis = maybeDiscloseFirstSyncTelemetry() ? "disclosed" : "no-consent";
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "cli_session_started",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis,
+                            schemaVersion: 1,
+                            properties: {
+                                version: CLI_VERSION,
+                                ...firstSyncStepTelemetryProperties(outcome),
+                            },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                return;
+        }
+        catch {
+            // Telemetry is best effort and must never affect or follow as an error
+            // after the completed CLI command.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Cached-token reads are also best effort (for example, a malformed cache).
+    }
+}
 //# sourceMappingURL=cli-telemetry.js.map

package/dist/utils/contribution-table.d.ts

@@ -99,5 +99,5 @@ export declare const CONTRIBUTION_KEYS: ContributionKey[];
  */
 export declare function payloadFor(key: ContributionKey, item: string): string;
 /** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
-export declare const SYMLINK_KEYS: ("workers" | "mcp" | "skills" | "knowledge" | "commands" | "hooks" | "policies" | "scripts")[];
+export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "skills" | "knowledge" | "hooks" | "policies" | "scripts")[];
 //# sourceMappingURL=contribution-table.d.ts.map

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

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

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

@@ -0,0 +1,28 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export function forbiddenFastPathModules(loadedModules, distDirectory) {
+    const dist = path.resolve(distDirectory);
+    const main = path.join(dist, "main.js");
+    const commands = `${path.join(dist, "commands")}${path.sep}`;
+    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))
+        .sort();
+}
+export function assertFastPathStaysCommandGraphFree(loadedModules, distDirectory) {
+    const forbidden = forbiddenFastPathModules(loadedModules, distDirectory);
+    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,21 @@
+export type SiblingAssetReference = {
+    referringAsset: string;
+    targetAsset: string;
+};
+export 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;
+//# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.273.0",
+  "version": "5.274.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {