@jitsusama/agentic-harness.core 0.1.0

package/dist/web/cookies/extract.js

@@ -0,0 +1,167 @@
+/**
+ * Cookie extraction: reads encrypted cookies from the local
+ * Chrome profile, decrypts them, and returns puppeteer-compatible
+ * cookie objects.
+ *
+ * Handles __Host- prefix cookies and correct domain matching
+ * per RFC 6265.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getDecryptionKey, isSetUp, StaleKeyError } from "./setup.js";
+/** Microseconds between 1601-01-01 and 1970-01-01. */
+const CHROME_EPOCH_OFFSET = 11644473600n * 1000000n;
+/** Length of the SHA-256 hash prefix Chrome prepends to cookie values. */
+const HASH_PREFIX_LENGTH = 32;
+function chromeDataDir() {
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "Google", "Chrome");
+    }
+    return path.join(os.homedir(), ".config", "google-chrome");
+}
+function findCookiesDb() {
+    const base = chromeDataDir();
+    const defaultDb = path.join(base, "Default", "Cookies");
+    if (fs.existsSync(defaultDb))
+        return defaultDb;
+    try {
+        const entries = fs.readdirSync(base).sort();
+        for (const entry of entries) {
+            if (entry.startsWith("Profile ")) {
+                const db = path.join(base, entry, "Cookies");
+                if (fs.existsSync(db))
+                    return db;
+            }
+        }
+    }
+    catch {
+        /* Chrome data dir unreadable: no profile found */
+    }
+    return null;
+}
+function decrypt(encryptedValue, key) {
+    if (encryptedValue.length < 4)
+        return null;
+    const prefix = encryptedValue.slice(0, 3).toString("ascii");
+    if (prefix !== "v10" && prefix !== "v11") {
+        return encryptedValue.toString("utf-8");
+    }
+    const ciphertext = encryptedValue.slice(3);
+    const iv = Buffer.alloc(16, 0x20);
+    try {
+        const decipher = crypto.createDecipheriv("aes-128-cbc", key, iv);
+        const decrypted = Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final(),
+        ]);
+        if (decrypted.length > HASH_PREFIX_LENGTH) {
+            return decrypted.slice(HASH_PREFIX_LENGTH).toString("utf-8");
+        }
+        return decrypted.toString("utf-8");
+    }
+    catch {
+        /* Decryption failed: wrong key or corrupted value */
+        return null;
+    }
+}
+function cookieHostKeys(hostname) {
+    const keys = [hostname];
+    const parts = hostname.split(".");
+    for (let i = 0; i < parts.length - 1; i++) {
+        keys.push(`.${parts.slice(i).join(".")}`);
+    }
+    return keys;
+}
+async function queryCookies(dbPath, hostKeys) {
+    const tmpDb = path.join(os.tmpdir(), `pi-chrome-cookies-${Date.now()}.db`);
+    fs.copyFileSync(dbPath, tmpDb);
+    for (const suffix of ["-wal", "-shm"]) {
+        const src = dbPath + suffix;
+        if (fs.existsSync(src)) {
+            fs.copyFileSync(src, tmpDb + suffix);
+        }
+    }
+    // We lazy-import sqlite3 because it's a native module and
+    // we only want to load it when cookies are actually needed,
+    // not on every extension load.
+    const sqlite3 = await import("sqlite3");
+    const db = new sqlite3.default.Database(tmpDb, sqlite3.default.OPEN_READONLY);
+    const placeholders = hostKeys.map(() => "?").join(", ");
+    const sql = `
+		SELECT name, encrypted_value, host_key, path,
+		       expires_utc, is_secure, is_httponly, samesite
+		FROM cookies
+		WHERE host_key IN (${placeholders})
+	`;
+    return new Promise((resolve, reject) => {
+        db.all(sql, hostKeys, (err, rows) => {
+            db.close();
+            for (const f of [tmpDb, `${tmpDb}-wal`, `${tmpDb}-shm`]) {
+                try {
+                    fs.unlinkSync(f);
+                }
+                catch {
+                    /* temp file cleanup: safe to ignore */
+                }
+            }
+            if (err)
+                reject(err);
+            else
+                resolve(rows || []);
+        });
+    });
+}
+const SAMESITE_MAP = {
+    [-1]: undefined,
+    0: "None",
+    1: "Lax",
+    2: "Strict",
+};
+/**
+ * Read Chrome cookies for a URL, decrypt them, and return in
+ * puppeteer-compatible format. Returns an empty array if the key
+ * hasn't been set up, the profile can't be found, or decryption
+ * fails.
+ */
+export async function getCookiesForUrl(url) {
+    const dbPath = findCookiesDb();
+    if (!dbPath)
+        return [];
+    const key = getDecryptionKey();
+    if (!key)
+        return [];
+    const parsed = new URL(url);
+    const hostKeys = cookieHostKeys(parsed.hostname);
+    const rows = await queryCookies(dbPath, hostKeys);
+    if (rows.length === 0)
+        return [];
+    let decryptFailures = 0;
+    const cookies = [];
+    for (const row of rows) {
+        const value = decrypt(row.encrypted_value, key);
+        if (value === null) {
+            decryptFailures++;
+            continue;
+        }
+        const expiresUtc = BigInt(row.expires_utc);
+        const expires = expiresUtc === 0n
+            ? -1
+            : Number((expiresUtc - CHROME_EPOCH_OFFSET) / 1000000n);
+        cookies.push({
+            name: row.name,
+            value,
+            domain: row.host_key,
+            path: row.path,
+            expires,
+            httpOnly: row.is_httponly === 1,
+            secure: row.is_secure === 1,
+            sameSite: SAMESITE_MAP[row.samesite],
+        });
+    }
+    if (cookies.length === 0 && decryptFailures > 0 && isSetUp()) {
+        throw new StaleKeyError();
+    }
+    return cookies;
+}

package/dist/web/cookies/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cookie module: Chrome cookie extraction, key management,
+ * and puppeteer injection.
+ */
+export type { PuppeteerCookie } from "./extract.js";
+export { getCookiesForUrl } from "./extract.js";
+export { injectCookies } from "./inject.js";
+export { isSetUp, StaleKeyError, setupChromeKey } from "./setup.js";

package/dist/web/cookies/index.js

@@ -0,0 +1,7 @@
+/**
+ * Cookie module: Chrome cookie extraction, key management,
+ * and puppeteer injection.
+ */
+export { getCookiesForUrl } from "./extract.js";
+export { injectCookies } from "./inject.js";
+export { isSetUp, StaleKeyError, setupChromeKey } from "./setup.js";

package/dist/web/cookies/inject.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cookie injection: sets Chrome session cookies on a puppeteer
+ * page before navigation. Bridges the cookie extraction and
+ * browser domains.
+ */
+import type { Page } from "puppeteer-core";
+/**
+ * Inject the user's Chrome session cookies for a URL into a
+ * puppeteer page. Best-effort: if cookies can't be read (no
+ * Chrome profile, Keychain denied, etc.) we silently continue
+ * without them.
+ */
+export declare function injectCookies(page: Page, url: string): Promise<void>;

package/dist/web/cookies/inject.js

@@ -0,0 +1,27 @@
+/**
+ * Cookie injection: sets Chrome session cookies on a puppeteer
+ * page before navigation. Bridges the cookie extraction and
+ * browser domains.
+ */
+import { getCookiesForUrl } from "./extract.js";
+import { StaleKeyError } from "./setup.js";
+/**
+ * Inject the user's Chrome session cookies for a URL into a
+ * puppeteer page. Best-effort: if cookies can't be read (no
+ * Chrome profile, Keychain denied, etc.) we silently continue
+ * without them.
+ */
+export async function injectCookies(page, url) {
+    try {
+        const cookies = await getCookiesForUrl(url);
+        if (cookies.length) {
+            await page.setCookie(...cookies);
+        }
+    }
+    catch (err) {
+        // Stale key errors need to propagate so the user gets guidance
+        if (err instanceof StaleKeyError)
+            throw err;
+        // Everything else gets a silent fallback because cookies are optional.
+    }
+}

package/dist/web/cookies/setup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cookie key management: derive, cache, and validate the Chrome
+ * cookie decryption key.
+ *
+ * On macOS, requires a one-time setupChromeKey() call that reads
+ * the password from the Keychain and caches the derived AES key.
+ * On Linux, the default password is hardcoded ("peanuts").
+ */
+/**
+ * Thrown when the cached key exists but can't decrypt any cookies,
+ * indicating Chrome was reinstalled and the key is stale.
+ */
+export declare class StaleKeyError extends Error {
+    constructor();
+}
+/**
+ * Read the cached decryption key. Returns null if the key hasn't
+ * been set up yet (on macOS) or derives it directly (on Linux).
+ */
+export declare function getDecryptionKey(): Buffer | null;
+/**
+ * One-time setup: derive the Chrome cookie decryption key from the
+ * macOS Keychain and cache it. This is the only operation that
+ * triggers a Keychain prompt.
+ *
+ * Returns true on success, false on failure. On Linux this is a
+ * no-op that always succeeds (no setup needed).
+ */
+export declare function setupChromeKey(): boolean;
+/** Check whether the cached key exists (setup has been done). */
+export declare function isSetUp(): boolean;

package/dist/web/cookies/setup.js

@@ -0,0 +1,94 @@
+/**
+ * Cookie key management: derive, cache, and validate the Chrome
+ * cookie decryption key.
+ *
+ * On macOS, requires a one-time setupChromeKey() call that reads
+ * the password from the Keychain and caches the derived AES key.
+ * On Linux, the default password is hardcoded ("peanuts").
+ */
+import { execSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Where the cached decryption key lives.
+ *
+ * Adapter-neutral rather than scoped under any one host's own
+ * config directory: the Keychain prompt this key is cached to avoid
+ * is the same prompt for every adapter driving Chrome on this
+ * machine, and re-deriving it per adapter would ask the user to
+ * approve it once per host instead of once per machine.
+ */
+const CACHED_KEY_PATH = path.join(os.homedir(), ".config", "agentic-harness", "chrome-cookie-key");
+/** Keychain query timeout in milliseconds. */
+const KEYCHAIN_TIMEOUT = 30000;
+/**
+ * Thrown when the cached key exists but can't decrypt any cookies,
+ * indicating Chrome was reinstalled and the key is stale.
+ */
+export class StaleKeyError extends Error {
+    constructor() {
+        super("Chrome cookie decryption key appears stale (Chrome may have " +
+            "been reinstalled). Ask the user to redo Chrome cookie setup " +
+            "to regenerate it.");
+        this.name = "StaleKeyError";
+    }
+}
+function deriveKey(password, iterations) {
+    return crypto.pbkdf2Sync(password, "saltysalt", iterations, 16, "sha1");
+}
+/**
+ * Read the cached decryption key. Returns null if the key hasn't
+ * been set up yet (on macOS) or derives it directly (on Linux).
+ */
+export function getDecryptionKey() {
+    if (process.platform !== "darwin") {
+        // Linux: default password is "peanuts", 1 iteration
+        return deriveKey("peanuts", 1);
+    }
+    try {
+        const encoded = fs.readFileSync(CACHED_KEY_PATH, "utf-8").trim();
+        if (!encoded)
+            return null;
+        return Buffer.from(encoded, "base64");
+    }
+    catch {
+        /* Cached key file missing or unreadable: not set up */
+        return null;
+    }
+}
+/**
+ * One-time setup: derive the Chrome cookie decryption key from the
+ * macOS Keychain and cache it. This is the only operation that
+ * triggers a Keychain prompt.
+ *
+ * Returns true on success, false on failure. On Linux this is a
+ * no-op that always succeeds (no setup needed).
+ */
+export function setupChromeKey() {
+    if (process.platform !== "darwin")
+        return true;
+    try {
+        const password = execSync("security find-generic-password -s 'Chrome Safe Storage' -a 'Chrome' -w", { encoding: "utf-8", timeout: KEYCHAIN_TIMEOUT }).trim();
+        if (!password)
+            return false;
+        const key = deriveKey(password, 1003);
+        const dir = path.dirname(CACHED_KEY_PATH);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(CACHED_KEY_PATH, key.toString("base64"), {
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        /* Keychain denied or write failed: report as failure */
+        return false;
+    }
+}
+/** Check whether the cached key exists (setup has been done). */
+export function isSetUp() {
+    if (process.platform !== "darwin")
+        return true;
+    return fs.existsSync(CACHED_KEY_PATH);
+}

package/dist/web/design/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What a page is built from, and where it drifted from itself.
+ *
+ * The inventory is pure and capture-agnostic: style samples in,
+ * dimensions and clusters out. It works as well on a stored
+ * capture or a set of design tokens as on a live page.
+ */
+export { type Cluster, COLOUR_SAMENESS, canonicalLengths, clusterUsage, coloursAreNear, DIMENSIONS, type Dimension, exactlyEqual, LENGTH_SAMENESS, lengthsAreNear, type Nearness, renderInventory, type StyleSample, takeInventory, tallyUsage, type Usage, } from "./inventory.js";
+export { inventorySource, SAMPLED_PROPERTIES } from "./probe.js";

package/dist/web/design/index.js

@@ -0,0 +1,9 @@
+/**
+ * What a page is built from, and where it drifted from itself.
+ *
+ * The inventory is pure and capture-agnostic: style samples in,
+ * dimensions and clusters out. It works as well on a stored
+ * capture or a set of design tokens as on a live page.
+ */
+export { COLOUR_SAMENESS, canonicalLengths, clusterUsage, coloursAreNear, DIMENSIONS, exactlyEqual, LENGTH_SAMENESS, lengthsAreNear, renderInventory, takeInventory, tallyUsage, } from "./inventory.js";
+export { inventorySource, SAMPLED_PROPERTIES } from "./probe.js";

package/dist/web/design/inventory.d.ts

@@ -0,0 +1,126 @@
+/**
+ * What a page is actually built from, and where it drifted.
+ *
+ * A design system is a claim about consistency, and a rendered
+ * page is the evidence for or against it. Counting distinct
+ * values is the easy half. The useful half is noticing that four
+ * of the greys differ by one step out of 255, which is not a
+ * palette but an accident that happened four times.
+ *
+ * Nothing here decides whether drift is wrong. Two blues a step
+ * apart may be a bug or may be a hover state, and this cannot
+ * tell which. It reports the cluster and the evidence; the
+ * judgment is a person's.
+ */
+/** One value found on the page, and how often. */
+export interface Usage {
+    readonly value: string;
+    readonly count: number;
+    /** A few places it was used, for finding it again. */
+    readonly examples: readonly string[];
+}
+/** Values close enough that they may have been meant as one. */
+export interface Cluster {
+    /** The most used member, which is the likely intended value. */
+    readonly leader: Usage;
+    /** The others, ordered by how often they appear. */
+    readonly nearby: readonly Usage[];
+    /** How many uses the whole cluster accounts for. */
+    readonly total: number;
+}
+/** Everything found for one property. */
+export interface Dimension {
+    readonly property: string;
+    readonly distinct: number;
+    readonly usages: readonly Usage[];
+    readonly clusters: readonly Cluster[];
+}
+/** One element's contribution to the inventory. */
+export interface StyleSample {
+    readonly selector: string;
+    readonly values: Readonly<Record<string, string>>;
+}
+/**
+ * Colours closer than this delta E are treated as one intent.
+ *
+ * Delta E rather than contrast ratio. Contrast compares relative
+ * luminance only and is blind to hue, so it called pure red and
+ * a mid grey the same colour: their ratio is about 1.001, well
+ * inside any sameness threshold. That is the right measure for
+ * whether text can be read and the wrong one for whether two
+ * values were meant to be one.
+ *
+ * Around 2 is a just-noticeable difference, so 5 catches the
+ * pairs a person would have to look twice at while leaving a
+ * deliberate step in a palette alone.
+ */
+export declare const COLOUR_SAMENESS = 5;
+/**
+ * How close two opacities must be to belong to one intent.
+ *
+ * A solid colour and a half-transparent one are a deliberate
+ * pair, and delta E does not see alpha at all.
+ */
+export declare const ALPHA_SAMENESS = 0.05;
+/**
+ * How close two lengths must be to read as one intent.
+ *
+ * Two thresholds, because one does not work. A purely relative
+ * test is too loose at large values and too strict at small
+ * ones: it clustered 14px with 16px, which is a deliberate step
+ * in any type scale, while leaving 4px and 5px apart, which is
+ * exactly the radius drift worth reporting. An absolute
+ * tolerance handles the small end and a tight relative one
+ * handles the large.
+ */
+export declare const LENGTH_SAMENESS = 0.08;
+export declare const LENGTH_TOLERANCE_PX = 1.5;
+/** Count every value of every property across the samples. */
+export declare function tallyUsage(samples: readonly StyleSample[], property: string): readonly Usage[];
+/** Whether two values are near enough to be one intent. */
+export type Nearness = (one: string, other: string) => boolean;
+/**
+ * Group values that are nearly the same.
+ *
+ * Greedy from the most used value outward, which is what makes
+ * the leader the likely intended one: a value used forty times
+ * with three near neighbours reads as a standard plus three
+ * mistakes, not as four equal options.
+ */
+export declare function clusterUsage(usages: readonly Usage[], near: Nearness): readonly Cluster[];
+/** Two colour values nobody could tell apart side by side. */
+export declare const coloursAreNear: Nearness;
+/**
+ * Collapse sub-pixel noise so one authored value stays one value.
+ *
+ * Only the numbers move, and only in their last decimals, so a
+ * real difference of a third of a pixel survives while the layout
+ * engine's rounding does not.
+ */
+export declare function canonicalLengths(css: string): string;
+/**
+ * Two lengths close enough to have been meant as one.
+ *
+ * Every number is compared, not just the first. A value like a
+ * box shadow or a four-sided padding carries several, and
+ * reading only the first made every shadow whose x offset is
+ * 0px cluster with every other, which is all of them, while
+ * `8px 16px` and `8px 4px` read as the same value.
+ */
+export declare const lengthsAreNear: Nearness;
+/** Values are the same or they are not. */
+export declare const exactlyEqual: Nearness;
+/** Which properties are worth inventorying, and how they compare. */
+export declare const DIMENSIONS: readonly {
+    readonly property: string;
+    readonly near: Nearness;
+}[];
+/** Take the inventory. */
+export declare function takeInventory(samples: readonly StyleSample[], dimensions?: readonly {
+    property: string;
+    near: Nearness;
+}[]): readonly Dimension[];
+/** Say what the page is built from. */
+export declare function renderInventory(dimensions: readonly Dimension[], options?: {
+    readonly property?: string;
+}): string;