@indigoai-us/hq-cli 5.273.0-alpha.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