@zenalexa/unicli 0.224.0 → 0.225.0

package/dist/engine/cookie-refresh.js

@@ -1,71 +1,93 @@
 /**
- * Smart Cookie Refresh — automatically refresh expired cookies via CDP.
- *
- * When an adapter gets a 401/403, this module attempts to navigate Chrome
- * to the site's main page (refreshing the session), extract fresh cookies
- * via CDP, and write them to the cookie file for subsequent requests.
+ * @owner       src::engine::cookie-refresh
+ * @does        Refreshes a site's login session by navigating Chrome to it over
+ *              CDP and re-reading cookies, surfacing the real cause of a miss
+ *              (no browser / no cookies / error) instead of a bare boolean.
+ * @needs       ./cookie-extractor (saveCookies), ../browser/page (lazy),
+ *              ../browser/cdp-client (resolveCdpPort, lazy)
+ * @feeds       src::engine::runtime (maybeRefreshCookies — the auto 401/403 path)
+ * @breaks      never throws — every failure becomes a typed SessionRefreshOutcome
+ * @invariants  navigation (page.goto) happens BEFORE reading cookies so the live
+ *              server session is rebuilt; this is the navigate-then-read refresh,
+ *              deliberately distinct from cookies.ts acquireCookies(skipDisk)
+ *              which is a pure DB/CDP read with no navigation
+ * @side-effects connects to Chrome via CDP, navigates a page, persists cookies to disk
+ * @concurrency stateless; the page is opened and closed within one call
+ * @test        tests/unit/engine/cookie-refresh.test.ts
+ * @stability   stable
+ * @since       2026-05-30
  */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import { saveCookies } from "./cookie-extractor.js";
+async function defaultConnect(port) {
+    const { BrowserPage } = await import("../browser/page.js");
+    return BrowserPage.connect(port);
+}
+export const defaultSessionRefreshDeps = {
+    connect: defaultConnect,
+    persist: saveCookies,
+};
 /**
- * Attempt to refresh cookies for a site by navigating Chrome to it.
- * Returns true if cookies were refreshed, false if not possible.
+ * Attempt to refresh cookies for a site by navigating Chrome to it and reading
+ * the resulting session cookies. Returns a typed outcome; never throws.
+ *
+ * Persistence goes through the canonical writer (saveCookies) so the on-disk
+ * format always matches what the loaders expect ({name: value}); hand-rolling
+ * the write here once emitted an array format the loaders silently rejected,
+ * leaving the adapter unauthenticated after a "successful" refresh.
  */
-export async function refreshCookies(site, domain) {
+export async function refreshCookies(site, domain, deps = defaultSessionRefreshDeps) {
+    let port;
+    try {
+        const { resolveCdpPort } = await import("../browser/cdp-client.js");
+        port = resolveCdpPort();
+    }
+    catch (err) {
+        return {
+            status: "error",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    let page;
     try {
-        const { BrowserPage: BP } = await import("../browser/page.js");
-        // Try connecting to an existing Chrome instance
-        let port = 9222;
-        const rawPort = process.env.UNICLI_CDP_PORT;
-        if (rawPort) {
-            const p = parseInt(rawPort, 10);
-            if (Number.isInteger(p) && p >= 1 && p <= 65535) {
-                port = p;
-            }
+        page = await deps.connect(port);
+    }
+    catch (err) {
+        return {
+            status: "no-browser",
+            detail: `Could not connect to Chrome on CDP port ${port}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    try {
+        const targetUrl = domain ? `https://${domain}` : `https://www.${site}.com`;
+        await page.goto(targetUrl, { settleMs: 3000 });
+        const cookies = await page.cookies();
+        if (Object.keys(cookies).length === 0) {
+            return {
+                status: "no-cookies",
+                detail: `No cookies present for ${site} after navigating to ${targetUrl}`,
+            };
         }
-        let page;
+        deps.persist(site, cookies);
+        return {
+            status: "refreshed",
+            site,
+            cookieCount: Object.keys(cookies).length,
+        };
+    }
+    catch (err) {
+        return {
+            status: "error",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
         try {
-            page = await BP.connect(port);
+            await page.close();
         }
         catch {
-            // No Chrome CDP available — cannot refresh
-            return false;
+            // REASON: page close is best-effort cleanup; a close failure must not
+            // override the refresh outcome already determined above.
         }
-        try {
-            // Navigate to the site's main page to refresh session
-            const targetUrl = domain
-                ? `https://${domain}`
-                : `https://www.${site}.com`;
-            await page.goto(targetUrl, { settleMs: 3000 });
-            // Extract cookies
-            const cookies = await page.cookies();
-            if (Object.keys(cookies).length === 0) {
-                return false;
-            }
-            // Write cookies to file
-            const cookiesDir = join(homedir(), ".unicli", "cookies");
-            mkdirSync(cookiesDir, { recursive: true });
-            const cookieArray = Object.entries(cookies).map(([name, value]) => ({
-                name,
-                value,
-                domain: domain ?? `${site}.com`,
-            }));
-            const cookiePath = join(cookiesDir, `${site}.json`);
-            writeFileSync(cookiePath, JSON.stringify(cookieArray, null, 2), "utf-8");
-            return true;
-        }
-        finally {
-            try {
-                await page.close();
-            }
-            catch {
-                /* best effort */
-            }
-        }
-    }
-    catch {
-        return false;
     }
 }
 //# sourceMappingURL=cookie-refresh.js.map

package/dist/engine/cookie-refresh.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-refresh.js","sourceRoot":"","sources":["../../src/engine/cookie-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,MAAe;IAEf,IAAI,CAAC;QACH,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QAE/D,gDAAgD;QAChD,IAAI,IAAI,GAAG,IAAI,CAAC;QAChB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC5C,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAChC,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;gBAChD,IAAI,GAAG,CAAC,CAAC;YACX,CAAC;QACH,CAAC;QAED,IAAI,IAA6B,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;YAC3C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,sDAAsD;YACtD,MAAM,SAAS,GAAG,MAAM;gBACtB,CAAC,CAAC,WAAW,MAAM,EAAE;gBACrB,CAAC,CAAC,eAAe,IAAI,MAAM,CAAC;YAE9B,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAE/C,kBAAkB;YAClB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtC,OAAO,KAAK,CAAC;YACf,CAAC;YAED,wBAAwB;YACxB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YACzD,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE3C,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClE,IAAI;gBACJ,KAAK;gBACL,MAAM,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM;aAChC,CAAC,CAAC,CAAC;YAEJ,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;YACpD,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAEzE,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"cookie-refresh.js","sourceRoot":"","sources":["../../src/engine/cookie-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AA2BpD,KAAK,UAAU,cAAc,CAAC,IAAY;IACxC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAuB;IAC3D,OAAO,EAAE,cAAc;IACvB,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,MAAe,EACf,OAA2B,yBAAyB;IAEpD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;QACpE,IAAI,GAAG,cAAc,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,IAAI,IAAiB,CAAC;IACtB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,MAAM,EAAE,2CAA2C,IAAI,KACrD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE;SACH,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC,CAAC,eAAe,IAAI,MAAM,CAAC;QAC3E,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAE/C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,OAAO;gBACL,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,0BAA0B,IAAI,wBAAwB,SAAS,EAAE;aAC1E,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5B,OAAO;YACL,MAAM,EAAE,WAAW;YACnB,IAAI;YACJ,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM;SACzC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,yDAAyD;QAC3D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/engine/cookie-source.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @owner       src::engine::cookie-source
+ * @does        Multi-source cookie acquisition that surfaces the REAL cause of a
+ *              miss (keychain denied / corrupt file / v20 encryption / CDP
+ *              unavailable) as a typed outcome, instead of collapsing every
+ *              failure to null.
+ * @needs       node:fs, node:path, ./chromium-cookies (lazy), ./cookie-extractor (lazy)
+ * @feeds       src::engine::cookies (loadCookies/loadCookiesWithCDP/acquireCookies
+ *              projections), src::engine::executor (auth error detail)
+ * @breaks      never throws from loadCookiesWithDiagnostics — failures become
+ *              CookieLoadOutcome {status:"error", reasons}; readDiskCookies is total
+ * @invariants  exactly one of loaded|absent|error; "absent" ⇒ no source errored
+ *              (genuinely not logged in); "error" ⇒ ≥1 source had a real failure
+ * @side-effects readDiskCookies reads fs; default sources read browser DB / CDP
+ * @perf        disk O(file); browser tries installed browsers in order, stops on hit
+ * @concurrency stateless; sources own their own IO
+ * @test        tests/unit/engine/cookie-source.test.ts
+ * @stability   experimental
+ * @since       2026-05-30
+ */
+export type CookieSourceName = "disk" | "browser" | "cdp";
+/** A typed failure cause from one acquisition source. */
+export interface CookieReason {
+    source: CookieSourceName;
+    /** Stable code, e.g. corrupt_file | keychain_denied | encryption_unsupported | cdp_unavailable. */
+    code: string;
+    detail: string;
+}
+/**
+ * Result of trying every cookie source for a site. Discriminated so callers
+ * cannot confuse "genuinely not logged in" (absent) with "Keychain denied /
+ * file corrupt / Chrome v20" (error) — the distinction the old null collapse
+ * destroyed.
+ */
+export type CookieLoadOutcome = {
+    status: "loaded";
+    source: CookieSourceName;
+    cookies: Record<string, string>;
+} | {
+    status: "absent";
+} | {
+    status: "error";
+    reasons: CookieReason[];
+};
+/** Disk read distinguishes absent (fine) from corrupt (a real, surfaceable fault). */
+export type DiskRead = {
+    kind: "ok";
+    cookies: Record<string, string>;
+} | {
+    kind: "absent";
+} | {
+    kind: "corrupt";
+    detail: string;
+};
+/** Browser read across installed browsers: a hit, a clean miss, or real errors. */
+export type BrowserAttempt = {
+    kind: "ok";
+    cookies: Record<string, string>;
+} | {
+    kind: "none";
+} | {
+    kind: "error";
+    reasons: CookieReason[];
+};
+/**
+ * Injectable acquisition sources. The default wires the real fs / browser DB /
+ * CDP; tests pass fakes so the whole policy is verifiable without a network,
+ * Keychain, or browser.
+ */
+export interface CookieSources {
+    readDisk(site: string): DiskRead;
+    readBrowser(domain: string): Promise<BrowserAttempt>;
+    readCdp(domain: string): Promise<Record<string, string>>;
+}
+export declare function cookieDir(): string;
+/**
+ * Read the on-disk cookie file, distinguishing absent from corrupt. The old
+ * loadCookies collapsed a truncated / wrong-shaped file to null ("no auth"),
+ * hiding the real cause; this returns a typed corrupt with a detail.
+ */
+export declare function readDiskCookies(site: string): DiskRead;
+/** Resolve the cookie domain the same way the legacy loader did. */
+export declare function resolveCookieDomain(site: string, domain?: string): string;
+export declare const defaultCookieSources: CookieSources;
+/**
+ * Acquire cookies across disk → browser → CDP, collecting the real cause of
+ * each source's failure. Never throws: a miss with no underlying fault is
+ * "absent"; a miss where a source actually errored (Keychain denial, corrupt
+ * file, v20 encryption, CDP down) is "error" with the reasons.
+ *
+ * Domain precedence and the disk-first / browser / CDP order match the legacy
+ * loadCookiesWithCDP exactly, so the projection wrappers preserve behavior.
+ */
+export declare function loadCookiesWithDiagnostics(site: string, domain?: string, sources?: CookieSources, opts?: {
+    skipDisk?: boolean;
+}): Promise<CookieLoadOutcome>;
+/**
+ * Turn a non-loaded outcome into an agent-actionable message + suggestion.
+ * This is where the no-silent-failure win is spent: Keychain denial, v20
+ * encryption, and a corrupt file each get a DISTINCT next step instead of the
+ * legacy one-size-fits-all "run unicli auth setup".
+ */
+export declare function describeCookieFailure(outcome: Exclude<CookieLoadOutcome, {
+    status: "loaded";
+}>, site: string, domain?: string): {
+    message: string;
+    suggestion: string;
+    retryable: boolean;
+};
+//# sourceMappingURL=cookie-source.d.ts.map

package/dist/engine/cookie-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-source.d.ts","sourceRoot":"","sources":["../../src/engine/cookie-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;AAE1D,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,mGAAmG;IACnG,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,GACD;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC;AAEjD,sFAAsF;AACtF,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,mFAAmF;AACnF,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1D;AAID,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAyBtD;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzE;AA8CD,eAAO,MAAM,oBAAoB,EAAE,aAIlC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE,aAAoC,EAC7C,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,iBAAiB,CAAC,CA8C5B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,CAAC,iBAAiB,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC,EACzD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CA0B7D"}

package/dist/engine/cookie-source.js

@@ -0,0 +1,207 @@
+/**
+ * @owner       src::engine::cookie-source
+ * @does        Multi-source cookie acquisition that surfaces the REAL cause of a
+ *              miss (keychain denied / corrupt file / v20 encryption / CDP
+ *              unavailable) as a typed outcome, instead of collapsing every
+ *              failure to null.
+ * @needs       node:fs, node:path, ./chromium-cookies (lazy), ./cookie-extractor (lazy)
+ * @feeds       src::engine::cookies (loadCookies/loadCookiesWithCDP/acquireCookies
+ *              projections), src::engine::executor (auth error detail)
+ * @breaks      never throws from loadCookiesWithDiagnostics — failures become
+ *              CookieLoadOutcome {status:"error", reasons}; readDiskCookies is total
+ * @invariants  exactly one of loaded|absent|error; "absent" ⇒ no source errored
+ *              (genuinely not logged in); "error" ⇒ ≥1 source had a real failure
+ * @side-effects readDiskCookies reads fs; default sources read browser DB / CDP
+ * @perf        disk O(file); browser tries installed browsers in order, stops on hit
+ * @concurrency stateless; sources own their own IO
+ * @test        tests/unit/engine/cookie-source.test.ts
+ * @stability   experimental
+ * @since       2026-05-30
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const SITE_RE = /^[a-zA-Z0-9._-]+$/;
+export function cookieDir() {
+    return (process.env.UNICLI_COOKIE_DIR ??
+        join(process.env.HOME ?? "~", ".unicli", "cookies"));
+}
+/**
+ * Read the on-disk cookie file, distinguishing absent from corrupt. The old
+ * loadCookies collapsed a truncated / wrong-shaped file to null ("no auth"),
+ * hiding the real cause; this returns a typed corrupt with a detail.
+ */
+export function readDiskCookies(site) {
+    if (!SITE_RE.test(site)) {
+        return { kind: "corrupt", detail: `invalid site name "${site}"` };
+    }
+    const path = join(cookieDir(), `${site}.json`);
+    if (!existsSync(path))
+        return { kind: "absent" };
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        return {
+            kind: "corrupt",
+            detail: `cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "corrupt", detail: `${path} is not valid JSON` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { kind: "corrupt", detail: `${path} is not a {name: value} object` };
+    }
+    return { kind: "ok", cookies: parsed };
+}
+/** Resolve the cookie domain the same way the legacy loader did. */
+export function resolveCookieDomain(site, domain) {
+    let resolved = domain ?? site.replace(/_/g, ".");
+    if (!resolved.includes("."))
+        resolved = `${resolved}.com`;
+    return resolved;
+}
+async function defaultReadBrowser(domain) {
+    let mod;
+    try {
+        mod = await import("./chromium-cookies.js");
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            reasons: [
+                {
+                    source: "browser",
+                    code: "module_load_failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+    const installed = mod.detectInstalledBrowsers();
+    if (installed.length === 0)
+        return { kind: "none" };
+    const reasons = [];
+    for (const browser of installed) {
+        try {
+            const record = mod.readCookiesAsRecord({ browser, domain });
+            if (Object.keys(record).length > 0)
+                return { kind: "ok", cookies: record };
+        }
+        catch (err) {
+            const code = err instanceof mod.ChromiumCookieError
+                ? err.code
+                : "browser_read_failed";
+            reasons.push({
+                source: "browser",
+                code,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return reasons.length > 0 ? { kind: "error", reasons } : { kind: "none" };
+}
+async function defaultReadCdp(domain) {
+    const { extractCookiesViaCDP } = await import("./cookie-extractor.js");
+    return extractCookiesViaCDP(domain);
+}
+export const defaultCookieSources = {
+    readDisk: readDiskCookies,
+    readBrowser: defaultReadBrowser,
+    readCdp: defaultReadCdp,
+};
+/**
+ * Acquire cookies across disk → browser → CDP, collecting the real cause of
+ * each source's failure. Never throws: a miss with no underlying fault is
+ * "absent"; a miss where a source actually errored (Keychain denial, corrupt
+ * file, v20 encryption, CDP down) is "error" with the reasons.
+ *
+ * Domain precedence and the disk-first / browser / CDP order match the legacy
+ * loadCookiesWithCDP exactly, so the projection wrappers preserve behavior.
+ */
+export async function loadCookiesWithDiagnostics(site, domain, sources = defaultCookieSources, opts = {}) {
+    const reasons = [];
+    // Refresh-after-401 skips disk: the on-disk cookies are exactly the stale
+    // ones that just failed, so re-acquisition must go straight to the live
+    // browser / CDP sources.
+    if (!opts.skipDisk) {
+        const disk = sources.readDisk(site);
+        if (disk.kind === "ok") {
+            return { status: "loaded", source: "disk", cookies: disk.cookies };
+        }
+        if (disk.kind === "corrupt") {
+            reasons.push({
+                source: "disk",
+                code: "corrupt_file",
+                detail: disk.detail,
+            });
+        }
+    }
+    const cookieDomain = resolveCookieDomain(site, domain);
+    if (process.env.UNICLI_COOKIE_NO_BROWSER !== "1") {
+        const browser = await sources.readBrowser(cookieDomain);
+        if (browser.kind === "ok" && Object.keys(browser.cookies).length > 0) {
+            return { status: "loaded", source: "browser", cookies: browser.cookies };
+        }
+        if (browser.kind === "error")
+            reasons.push(...browser.reasons);
+    }
+    try {
+        const cdp = await sources.readCdp(cookieDomain);
+        if (Object.keys(cdp).length > 0) {
+            return { status: "loaded", source: "cdp", cookies: cdp };
+        }
+    }
+    catch (err) {
+        reasons.push({
+            source: "cdp",
+            code: "cdp_unavailable",
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return reasons.length > 0
+        ? { status: "error", reasons }
+        : { status: "absent" };
+}
+/**
+ * Turn a non-loaded outcome into an agent-actionable message + suggestion.
+ * This is where the no-silent-failure win is spent: Keychain denial, v20
+ * encryption, and a corrupt file each get a DISTINCT next step instead of the
+ * legacy one-size-fits-all "run unicli auth setup".
+ */
+export function describeCookieFailure(outcome, site, domain) {
+    const d = resolveCookieDomain(site, domain);
+    if (outcome.status === "absent") {
+        return {
+            message: `No cookies found for "${site}".`,
+            suggestion: `Sign in to https://${d} in Chrome, then run: unicli auth import ${site} --domain ${d}`,
+            retryable: false,
+        };
+    }
+    const codes = outcome.reasons.map((r) => `${r.source}:${r.code}`).join(", ");
+    const has = (code) => outcome.reasons.some((r) => r.code === code);
+    let suggestion;
+    if (has("keychain_denied")) {
+        suggestion = `Chrome cookie decryption was denied by the macOS Keychain. Grant access when prompted, or run: unicli auth import ${site} --domain ${d}`;
+    }
+    else if (has("encryption_unsupported")) {
+        suggestion = `Chrome's app-bound encryption (v20) blocks direct cookie reads. Start Chrome via "unicli browser start" (CDP path), or run: unicli auth import ${site} --domain ${d}`;
+    }
+    else if (has("corrupt_file")) {
+        suggestion = `The saved cookie file is unreadable. Re-import: unicli auth import ${site} --domain ${d}`;
+    }
+    else {
+        suggestion = `Could not acquire cookies (${codes}). Sign in to https://${d}, then run: unicli auth import ${site} --domain ${d}`;
+    }
+    return {
+        message: `Failed to load cookies for "${site}" — ${codes}.`,
+        suggestion,
+        retryable: false,
+    };
+}
+//# sourceMappingURL=cookie-source.js.map

package/dist/engine/cookie-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-source.js","sourceRoot":"","sources":["../../src/engine/cookie-source.ts"],"names":[],"mappings":"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"}

package/dist/engine/cookies.d.ts

@@ -1,12 +1,24 @@
 /**
- * Cookie file reader for authenticated adapters.
- *
- * Cookies are stored as JSON in ~/.unicli/cookies/<site>.json
- * Each file contains { "cookie_name": "value", ... }
+ * @owner       src::engine::cookies
+ * @does        Cookie front door for adapters — thin projections over the
+ *              structured acquisition core in cookie-source.ts (disk read,
+ *              header formatting, multi-source load, refresh).
+ * @needs       ./cookie-source, ./cookie-extractor (saveCookies)
+ * @feeds       adapters (loadCookiesWithCDP/formatCookieHeader), executor,
+ *              dispatch/social (refreshCookiesFromBrowser), commands/auth
+ * @breaks      loadCookies/loadCookiesWithCDP return null on miss (back-compat);
+ *              acquireCookies returns a typed CookieLoadOutcome that names the
+ *              real cause — callers that need the cause use acquireCookies
+ * @invariants  loadCookiesWithCDP cookies === acquireCookies(...).cookies on load
+ * @side-effects acquireCookies persists browser/CDP cookies to disk (best-effort)
+ * @test        tests/unit/engine/cookie-source.test.ts, cookie-refresh-format.test.ts
+ * @stability   stable
+ * @since       2026-05-30
  */
+import { type CookieLoadOutcome } from "./cookie-source.js";
 /**
- * Load cookies for a site from disk.
- * Returns null if file doesn't exist or is malformed.
+ * Load cookies for a site from disk. Returns null when the file is absent OR
+ * unreadable; callers needing to tell those apart use `acquireCookies`.
  */
 export declare function loadCookies(site: string): Record<string, string> | null;
 /**
@@ -14,32 +26,27 @@ export declare function loadCookies(site: string): Record<string, string> | null
  * Example: "SESSDATA=abc; bili_jct=def"
  */
 export declare function formatCookieHeader(cookies: Record<string, string>): string;
-/**
- * Validate that a cookie file has all required keys.
- */
+/** Validate that a cookie file has all required keys. */
 export declare function validateCookies(site: string, requiredKeys: string[]): {
     valid: boolean;
     missing: string[];
 };
+/** Get the cookie directory path (for display in auth commands). */
+export declare function getCookieDir(): string;
 /**
- * Get the cookie directory path (for display in auth commands).
+ * Acquire cookies across disk → browser → CDP, returning the structured outcome
+ * (loaded / absent / error+reasons). On a non-disk load, persists to
+ * ~/.unicli/cookies for offline reuse. This is the front door for callers that
+ * need to surface WHY acquisition failed (Keychain denial, v20 encryption,
+ * corrupt file) instead of a bare null.
  */
-export declare function getCookieDir(): string;
+export declare function acquireCookies(site: string, domain?: string, opts?: {
+    skipDisk?: boolean;
+}): Promise<CookieLoadOutcome>;
 /**
- * Load cookies with multi-source fallback.
- *
- * Precedence (each falls through silently to the next on miss):
- *   1. ~/.unicli/cookies/<site>.json       — explicit user import
- *   2. browser local DB (Chrome/Arc/Dia/…) — direct SQLite read, no browser launch
- *   3. CDP                                  — connects to Chrome debug port (legacy)
- *
- * The browser disk source is the new default for `strategy: cookie` adapters:
- * it works whether the browser is open or closed, never opens a new tab, and
- * needs neither extension nor daemon. Successful reads are persisted to
- * ~/.unicli/cookies for offline reuse.
- *
- * Set `UNICLI_COOKIE_NO_BROWSER=1` to skip the browser-disk step (e.g., in CI
- * where the macOS Keychain prompt would block).
+ * Load cookies with multi-source fallback (disk → browser DB → CDP). Returns
+ * null on any miss. Behavior-compatible with every existing adapter consumer;
+ * the structured cause is available via `acquireCookies`.
  */
 export declare function loadCookiesWithCDP(site: string, domain?: string): Promise<Record<string, string> | null>;
 export interface CookieRefreshResult {
@@ -51,5 +58,10 @@ export interface CookieRefreshResult {
     cookies?: string[];
     suggestion?: string;
 }
+/**
+ * Re-acquire cookies from the live browser / CDP after an auth failure. Skips
+ * the on-disk file (those are the stale cookies that just failed) and reports
+ * the real cause on failure rather than a generic message.
+ */
 export declare function refreshCookiesFromBrowser(site: string, domain?: string): Promise<CookieRefreshResult>;
 //# sourceMappingURL=cookies.d.ts.map

package/dist/engine/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/engine/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAmBvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAwCxC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAUD,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CA2D9B"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/engine/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAG5B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAKvC;AAED,oEAAoE;AACpE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAGxC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CA+B9B"}