@flrande/browserctl 0.4.0-dev.15.1 → 0.5.0-dev.19.1

package/packages/core/src/navigation-memory.test.ts

@@ -0,0 +1,259 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { createNavigationMemoryStore } from "./navigation-memory";
+
+describe("navigation memory contracts", () => {
+  it("scopes by domain+profile", async () => {
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => 1_000
+    });
+
+    await store.upsert({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile",
+      signals: [{ kind: "urlPattern", value: "/u/*" }]
+    });
+
+    const hit = await store.resolve({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile"
+    });
+    const missByProfile = await store.resolve({
+      domain: "forum.example",
+      profileId: "managed-local",
+      intentKey: "open_profile"
+    });
+    const missByDomain = await store.resolve({
+      domain: "news.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile"
+    });
+
+    expect(hit.hit).toBe(true);
+    expect(hit.entry?.signals).toEqual([{ kind: "urlPattern", value: "/u/*" }]);
+    expect(missByProfile.hit).toBe(false);
+    expect(missByDomain.hit).toBe(false);
+  });
+
+  it("implements the core store API", async () => {
+    let now = 10_000;
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => now,
+      ttlDays: 1
+    });
+
+    const upserted = await store.upsert({
+      domain: "news.example",
+      profileId: "chrome-relay",
+      intentKey: "hot",
+      signals: [{ kind: "selector", value: "#hot-list" }],
+      confidence: 0.7
+    });
+
+    expect(upserted.created).toBe(true);
+    expect((await store.list())).toHaveLength(1);
+    expect(await store.inspect(upserted.entry.id)).toMatchObject({
+      id: upserted.entry.id,
+      domain: "news.example",
+      profileId: "chrome-relay",
+      intentKey: "hot"
+    });
+
+    await store.setMode("ask");
+    await store.setTtlDays(0);
+    expect(store.status()).toMatchObject({
+      mode: "ask",
+      ttlDays: 0,
+      totalEntries: 0
+    });
+
+    now += 1;
+    expect(await store.purgeExpired()).toBe(1);
+    expect(await store.delete(upserted.entry.id)).toBe(false);
+    expect(await store.list()).toHaveLength(0);
+  });
+
+  it("keeps task1 store in-memory even when path is set", async () => {
+    const dirPath = await mkdtemp(join(tmpdir(), "navigation-memory-task1-"));
+    const filePath = join(dirPath, "navigation-memory.json");
+
+    try {
+      const store = createNavigationMemoryStore({
+        path: filePath,
+        now: () => 1_000
+      });
+
+      await store.upsert({
+        domain: "forum.example",
+        profileId: "chrome-relay",
+        intentKey: "open_profile",
+        signals: [{ kind: "urlPattern", value: "/u/*" }]
+      });
+
+      expect(existsSync(filePath)).toBe(false);
+    } finally {
+      await rm(dirPath, { recursive: true, force: true });
+    }
+  });
+
+  it("does not revive expired entries when ttl days changes", async () => {
+    const dayMs = 24 * 60 * 60 * 1000;
+    let now = 5_000;
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => now,
+      ttlDays: 1
+    });
+
+    const upserted = await store.upsert({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile",
+      signals: [{ kind: "selector", value: "#profile-link" }]
+    });
+
+    now += dayMs + 1;
+
+    const status = await store.setTtlDays(30);
+    expect(status.totalEntries).toBe(0);
+    expect(await store.inspect(upserted.entry.id)).toBeUndefined();
+  });
+
+  it("supports extracted setMode and setTtlDays calls", async () => {
+    const store = createNavigationMemoryStore({
+      path: ":memory:"
+    });
+
+    const { setMode, setTtlDays } = store;
+
+    const modeStatus = await setMode("ask");
+    expect(modeStatus.mode).toBe("ask");
+
+    const ttlStatus = await setTtlDays(7);
+    expect(ttlStatus.ttlDays).toBe(7);
+
+    expect(store.status()).toMatchObject({
+      mode: "ask",
+      ttlDays: 7
+    });
+  });
+
+  it("renews expireAt when resolve hits", async () => {
+    let now = 10_000;
+    const dayMs = 24 * 60 * 60 * 1000;
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => now,
+      ttlDays: 30
+    });
+
+    const created = await store.upsert({
+      domain: "news.example",
+      profileId: "chrome-relay",
+      intentKey: "hot",
+      signals: []
+    });
+
+    const before = await store.inspect(created.entry.id);
+    now += 60_000;
+
+    const first = await store.resolve({
+      domain: "news.example",
+      profileId: "chrome-relay",
+      intentKey: "hot"
+    });
+
+    expect(first.hit).toBe(true);
+    expect(first.entry).toBeDefined();
+    expect(first.entry!.expireAt).not.toBe(before!.expireAt);
+    expect(first.entry!.expireAt).toBe(new Date(now + 30 * dayMs).toISOString());
+
+    const inspected = await store.inspect(first.entry!.id);
+    expect(inspected!.hitCount).toBe(1);
+    expect(inspected!.expireAt).toBe(first.entry!.expireAt);
+  });
+
+  it("rejects write when mode=ask and no explicit approval", async () => {
+    const store = createNavigationMemoryStore({ path: ":memory:", mode: "ask" });
+
+    await expect(
+      store.upsert({
+        domain: "forum.example",
+        profileId: "chrome-relay",
+        intentKey: "open_profile",
+        signals: [],
+        confirmed: false
+      })
+    ).rejects.toThrow(/confirmation/i);
+  });
+
+  it("returns miss and does not mutate entry when mode=off on resolve", async () => {
+    let now = 10_000;
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => now,
+      ttlDays: 30
+    });
+
+    const created = await store.upsert({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile",
+      signals: [{ kind: "selector", value: "#profile-link" }]
+    });
+
+    const before = await store.inspect(created.entry.id);
+    await store.setMode("off");
+    now += 5_000;
+
+    const resolved = await store.resolve({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile"
+    });
+
+    expect(resolved.hit).toBe(false);
+    expect(resolved.entry).toBeUndefined();
+
+    const after = await store.inspect(created.entry.id);
+    expect(after).toBeDefined();
+    expect(after!.hitCount).toBe(before!.hitCount);
+    expect(after!.lastHitAt).toBe(before!.lastHitAt);
+    expect(after!.expireAt).toBe(before!.expireAt);
+  });
+
+  it("does not delete expired entry when mode=off resolve is called", async () => {
+    const store = createNavigationMemoryStore({
+      path: ":memory:",
+      now: () => 10_000,
+      ttlDays: 0
+    });
+
+    const created = await store.upsert({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile",
+      signals: [{ kind: "selector", value: "#profile-link" }]
+    });
+
+    await store.setMode("off");
+
+    const resolved = await store.resolve({
+      domain: "forum.example",
+      profileId: "chrome-relay",
+      intentKey: "open_profile"
+    });
+
+    expect(resolved.hit).toBe(false);
+    expect(resolved.entry).toBeUndefined();
+    expect(await store.delete(created.entry.id)).toBe(true);
+  });
+});

package/packages/core/src/navigation-memory.ts

@@ -0,0 +1,360 @@
+const DEFAULT_TTL_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type NavigationSignal =
+  | { kind: "urlPattern"; value: string }
+  | { kind: "selector"; value: string }
+  | { kind: "hop"; from: string; to: string };
+
+export type NavigationMemoryEntry = {
+  id: string;
+  domain: string;
+  profileId: string;
+  intentKey: string;
+  signals: NavigationSignal[];
+  confidence: number;
+  createdAt: string;
+  lastHitAt: string;
+  expireAt: string;
+  hitCount: number;
+};
+
+export type NavigationMemoryMode = "off" | "ask" | "auto";
+
+export type NavigationMemoryStoreOptions = {
+  path: string;
+  mode?: NavigationMemoryMode;
+  ttlDays?: number;
+  now?: () => number;
+};
+
+export type NavigationMemoryResolveInput = {
+  domain: string;
+  profileId: string;
+  intentKey: string;
+};
+
+export type NavigationMemoryResolveResult =
+  | { hit: false; entry?: undefined }
+  | { hit: true; entry: NavigationMemoryEntry };
+
+export type NavigationMemoryUpsertInput = {
+  domain: string;
+  profileId: string;
+  intentKey: string;
+  signals: NavigationSignal[];
+  confidence?: number;
+  confirmed?: boolean;
+};
+
+export type NavigationMemoryUpsertResult = {
+  created: boolean;
+  entry: NavigationMemoryEntry;
+};
+
+export type NavigationMemoryListInput = {
+  domain?: string;
+  profileId?: string;
+  intentKey?: string;
+};
+
+export type NavigationMemoryStatus = {
+  path: string;
+  mode: NavigationMemoryMode;
+  ttlDays: number;
+  totalEntries: number;
+};
+
+export type NavigationMemoryStore = {
+  resolve(input: NavigationMemoryResolveInput): Promise<NavigationMemoryResolveResult>;
+  upsert(input: NavigationMemoryUpsertInput): Promise<NavigationMemoryUpsertResult>;
+  list(filter?: NavigationMemoryListInput): Promise<NavigationMemoryEntry[]>;
+  inspect(id: string): Promise<NavigationMemoryEntry | undefined>;
+  delete(id: string): Promise<boolean>;
+  purgeExpired(): Promise<number>;
+  setMode(mode: NavigationMemoryMode): Promise<NavigationMemoryStatus>;
+  setTtlDays(ttlDays: number): Promise<NavigationMemoryStatus>;
+  status(): NavigationMemoryStatus;
+};
+
+function toIso(timestampMs: number): string {
+  return new Date(timestampMs).toISOString();
+}
+
+function parseTime(value: string): number {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function normalizeTtlDays(value: number | undefined): number {
+  if (value === undefined) {
+    return DEFAULT_TTL_DAYS;
+  }
+
+  return Math.max(0, Math.trunc(value));
+}
+
+function normalizeConfidence(value: number | undefined): number {
+  if (value === undefined || Number.isNaN(value) || !Number.isFinite(value)) {
+    return 1;
+  }
+
+  if (value <= 0) {
+    return 0;
+  }
+
+  if (value >= 1) {
+    return 1;
+  }
+
+  return value;
+}
+
+function toExpireAt(nowMs: number, ttlDays: number): string {
+  return toIso(nowMs + normalizeTtlDays(ttlDays) * DAY_MS);
+}
+
+function isScopeMatch(
+  entry: NavigationMemoryEntry,
+  input: Pick<NavigationMemoryResolveInput, "domain" | "profileId" | "intentKey">
+): boolean {
+  return entry.domain === input.domain && entry.profileId === input.profileId && entry.intentKey === input.intentKey;
+}
+
+function cloneSignal(signal: NavigationSignal): NavigationSignal {
+  if (signal.kind === "hop") {
+    return {
+      kind: "hop",
+      from: signal.from,
+      to: signal.to
+    };
+  }
+
+  return {
+    kind: signal.kind,
+    value: signal.value
+  };
+}
+
+function cloneEntry(entry: NavigationMemoryEntry): NavigationMemoryEntry {
+  return {
+    ...entry,
+    signals: entry.signals.map((signal) => cloneSignal(signal))
+  };
+}
+
+function isExpired(entry: NavigationMemoryEntry, nowMs: number): boolean {
+  return parseTime(entry.expireAt) <= nowMs;
+}
+
+function isNewer(a: NavigationMemoryEntry, b: NavigationMemoryEntry): boolean {
+  return parseTime(a.lastHitAt) > parseTime(b.lastHitAt);
+}
+
+export function createNavigationMemoryStore(options: NavigationMemoryStoreOptions): NavigationMemoryStore {
+  if (options.path.trim().length === 0) {
+    throw new Error("Navigation memory path must not be empty.");
+  }
+
+  const now = options.now ?? (() => Date.now());
+  let mode: NavigationMemoryMode = options.mode ?? "auto";
+  let ttlDays = normalizeTtlDays(options.ttlDays);
+  const entries = new Map<string, NavigationMemoryEntry>();
+  let nextId = 1;
+
+  function createId(): string {
+    const id = `memory:${nextId}`;
+    nextId += 1;
+    return id;
+  }
+
+  function pruneExpired(): number {
+    const currentTime = now();
+    let removed = 0;
+    for (const [entryId, entry] of entries.entries()) {
+      if (!isExpired(entry, currentTime)) {
+        continue;
+      }
+
+      entries.delete(entryId);
+      removed += 1;
+    }
+
+    return removed;
+  }
+
+  function findScopedEntry(input: NavigationMemoryResolveInput): NavigationMemoryEntry | undefined {
+    let selected: NavigationMemoryEntry | undefined;
+    for (const entry of entries.values()) {
+      if (!isScopeMatch(entry, input)) {
+        continue;
+      }
+
+      if (selected === undefined) {
+        selected = entry;
+        continue;
+      }
+
+      if (entry.confidence > selected.confidence || (entry.confidence === selected.confidence && isNewer(entry, selected))) {
+        selected = entry;
+      }
+    }
+
+    return selected;
+  }
+
+  function getStatus(): NavigationMemoryStatus {
+    const currentTime = now();
+    const totalEntries = Array.from(entries.values()).filter((entry) => !isExpired(entry, currentTime)).length;
+    return {
+      path: options.path,
+      mode,
+      ttlDays,
+      totalEntries
+    };
+  }
+
+  function assertUpsertAllowed(input: NavigationMemoryUpsertInput): void {
+    if (mode === "auto") {
+      return;
+    }
+
+    if (mode === "ask") {
+      if (input.confirmed === true) {
+        return;
+      }
+
+      throw new Error("Navigation memory write requires confirmation in ask mode.");
+    }
+
+    throw new Error("Navigation memory write is disabled when mode is off.");
+  }
+
+  return {
+    async resolve(input: NavigationMemoryResolveInput): Promise<NavigationMemoryResolveResult> {
+      if (mode === "off") {
+        return { hit: false };
+      }
+
+      pruneExpired();
+      const existing = findScopedEntry(input);
+      if (existing === undefined) {
+        return { hit: false };
+      }
+
+      const currentTime = now();
+      const updated: NavigationMemoryEntry = {
+        ...existing,
+        lastHitAt: toIso(currentTime),
+        expireAt: toExpireAt(currentTime, ttlDays),
+        hitCount: existing.hitCount + 1
+      };
+      entries.set(updated.id, updated);
+
+      return {
+        hit: true,
+        entry: cloneEntry(updated)
+      };
+    },
+
+    async upsert(input: NavigationMemoryUpsertInput): Promise<NavigationMemoryUpsertResult> {
+      assertUpsertAllowed(input);
+      pruneExpired();
+      const currentTime = now();
+      const confidence = normalizeConfidence(input.confidence);
+      const signals = input.signals.map((signal) => cloneSignal(signal));
+      const existing = findScopedEntry(input);
+
+      if (existing !== undefined) {
+        const updated: NavigationMemoryEntry = {
+          ...existing,
+          signals,
+          confidence,
+          expireAt: toExpireAt(currentTime, ttlDays)
+        };
+        entries.set(updated.id, updated);
+        return {
+          created: false,
+          entry: cloneEntry(updated)
+        };
+      }
+
+      const createdAt = toIso(currentTime);
+      const created: NavigationMemoryEntry = {
+        id: createId(),
+        domain: input.domain,
+        profileId: input.profileId,
+        intentKey: input.intentKey,
+        signals,
+        confidence,
+        createdAt,
+        lastHitAt: createdAt,
+        expireAt: toExpireAt(currentTime, ttlDays),
+        hitCount: 0
+      };
+      entries.set(created.id, created);
+
+      return {
+        created: true,
+        entry: cloneEntry(created)
+      };
+    },
+
+    async list(filter?: NavigationMemoryListInput): Promise<NavigationMemoryEntry[]> {
+      pruneExpired();
+      return Array.from(entries.values())
+        .filter((entry) => {
+          if (filter === undefined) {
+            return true;
+          }
+          if (filter.domain !== undefined && filter.domain !== entry.domain) {
+            return false;
+          }
+          if (filter.profileId !== undefined && filter.profileId !== entry.profileId) {
+            return false;
+          }
+          if (filter.intentKey !== undefined && filter.intentKey !== entry.intentKey) {
+            return false;
+          }
+          return true;
+        })
+        .map((entry) => cloneEntry(entry));
+    },
+
+    async inspect(id: string): Promise<NavigationMemoryEntry | undefined> {
+      pruneExpired();
+      const entry = entries.get(id);
+      return entry === undefined ? undefined : cloneEntry(entry);
+    },
+
+    async delete(id: string): Promise<boolean> {
+      return entries.delete(id);
+    },
+
+    async purgeExpired(): Promise<number> {
+      return pruneExpired();
+    },
+
+    async setMode(nextMode: NavigationMemoryMode): Promise<NavigationMemoryStatus> {
+      mode = nextMode;
+      return getStatus();
+    },
+
+    async setTtlDays(nextTtlDays: number): Promise<NavigationMemoryStatus> {
+      pruneExpired();
+      ttlDays = normalizeTtlDays(nextTtlDays);
+      const refreshedExpireAt = toExpireAt(now(), ttlDays);
+      for (const [entryId, entry] of entries.entries()) {
+        entries.set(entryId, {
+          ...entry,
+          expireAt: refreshedExpireAt
+        });
+      }
+      return getStatus();
+    },
+
+    status(): NavigationMemoryStatus {
+      return getStatus();
+    }
+  };
+}

package/packages/core/src/session-store.test.ts

@@ -46,4 +46,37 @@ describe("SessionStore", () => {
 
     expect(store.delete("missing")).toBe(false);
   });
+
+  it("expires sessions after ttl and returns undefined", () => {
+    let now = 1_000;
+    const store = new SessionStore({
+      ttlMs: 100,
+      now: () => now
+    });
+
+    store.useProfile("session:ttl", "managed");
+    now += 150;
+
+    expect(store.get("session:ttl")).toBeUndefined();
+  });
+
+  it("cleans up expired sessions and keeps active ones", () => {
+    let now = 1_000;
+    const store = new SessionStore({
+      ttlMs: 100,
+      now: () => now
+    });
+
+    store.useProfile("session:old", "managed");
+    now += 50;
+    store.useProfile("session:active", "managed");
+    now += 60;
+
+    expect(store.cleanupExpired()).toBe(1);
+    expect(store.get("session:old")).toBeUndefined();
+    expect(store.get("session:active")).toEqual({
+      sessionId: "session:active",
+      profile: "managed"
+    });
+  });
 });