@dikshanty94/webnav 0.2.0

package/dist/contract.d.ts

@@ -0,0 +1,20 @@
+import type { SiteNode, State } from './mapstore/types.js';
+export type { SiteNode, State, Affordance, AffordanceKind, StateRole, EdgeKind, DeclaredShadow, } from './mapstore/types.js';
+/** One site's full skeleton. This is what `webnav dev export-map` emits, what
+ *  the site's `publish-map` uploads, and what `GET /api/maps/:site` returns. */
+export interface MapPack {
+    node: SiteNode;
+    states: State[];
+}
+/** Request header carrying the API key on hosted-route calls. */
+export declare const WEBNAV_KEY_HEADER = "X-Webnav-Key";
+/** Path of the metered map-fetch endpoint for a site id (the SiteNode id,
+ *  e.g. 'www.saucedemo.com'). */
+export declare function mapFetchPath(site: string): string;
+/** Non-200 statuses the map-fetch endpoint returns:
+ *  401 missing/invalid/revoked/expired key · 404 no shared map · 429 quota. */
+export type MapFetchErrorStatus = 401 | 404 | 429;
+/** Body of every non-200 map-fetch response. */
+export interface MapFetchError {
+    error: string;
+}

package/dist/contract.js

@@ -0,0 +1,15 @@
+// The CLI <-> hosted-service CONTRACT — single source of truth for every shape
+// that crosses the wire between the open-source CLI (this repo) and the hosted
+// shared-knowledge service (webnav-site). The site imports this module
+// types-only from `@dikshanty94/webnav/contract`; nothing here may import
+// runtime code, so consuming it never pulls in better-sqlite3 etc.
+//
+// HARD INVARIANT (CLAUDE.md): the wire carries the MAP SKELETON ONLY —
+// site navigation structure. It never carries credentials.
+/** Request header carrying the API key on hosted-route calls. */
+export const WEBNAV_KEY_HEADER = 'X-Webnav-Key';
+/** Path of the metered map-fetch endpoint for a site id (the SiteNode id,
+ *  e.g. 'www.saucedemo.com'). */
+export function mapFetchPath(site) {
+    return `/api/maps/${encodeURIComponent(site)}`;
+}

package/dist/creds.d.ts

@@ -0,0 +1,46 @@
+export type CredCategory = 'login' | 'personal' | 'other';
+export interface CredEntry {
+    value: string;
+    category: CredCategory;
+}
+export type SiteCreds = Record<string, string>;
+export type SiteCredsDetailed = Record<string, CredEntry>;
+export declare function credsPath(): string;
+export declare function categorize(key: string): CredCategory;
+export declare class CredStore {
+    private path;
+    constructor(path?: string);
+    private read;
+    private write;
+    /** All creds for a site as a flat slot→value map (the walk fills inputs from
+     *  this — the contract the walk depends on, unchanged). Legacy + new shapes
+     *  both flatten to value strings here. */
+    get(site: string): SiteCreds;
+    /** All creds for a site WITH categories (for the dashboard). */
+    getDetailed(site: string): SiteCredsDetailed;
+    /** Merge key/values into a site's creds (existing keys overwritten). Category
+     *  is inferred per key unless `category` is supplied (applies to all keys set
+     *  in this call). Returns the site's key names after the merge. */
+    set(site: string, values: SiteCreds, category?: CredCategory): string[];
+    /** Change just the CATEGORY of an existing key (value untouched). Returns true
+     *  if the key existed. */
+    setCategory(site: string, key: string, category: CredCategory): boolean;
+    /** Remove a whole site, or just one key when `key` is given. Returns true if
+     *  anything was removed. */
+    remove(site: string, key?: string): boolean;
+    /** Sites + their KEY names only — never the values (for `creds list`). Shape
+     *  unchanged so the CLI JSON contract stays stable. */
+    list(): {
+        site: string;
+        keys: string[];
+    }[];
+    /** Like list() but with each key's CATEGORY (still never the values). Lets the
+     *  dashboard group by category without revealing anything. */
+    listDetailed(): {
+        site: string;
+        keys: {
+            name: string;
+            category: CredCategory;
+        }[];
+    }[];
+}

package/dist/creds.js

@@ -0,0 +1,126 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+export function credsPath() {
+    return process.env.WEBNAV_CREDS ?? join(homedir(), '.webnav', 'credentials.json');
+}
+// Infer a credential's category from its key name. Conservative: anything not
+// recognized as a login secret or a piece of personal info falls back to 'other'.
+const LOGIN_KEYS = /^(user(name)?|login|email|e-?mail|pass(word|wd)?|pin|otp|token|secret|api[-_]?key)$/i;
+const PERSONAL_KEYS = /^(first[-_]?name|last[-_]?name|full[-_]?name|name|phone|mobile|tel|address|street|city|state|country|zip|postal[-_]?code|postcode|dob|birth|gender|company)$/i;
+export function categorize(key) {
+    if (LOGIN_KEYS.test(key))
+        return 'login';
+    if (PERSONAL_KEYS.test(key))
+        return 'personal';
+    return 'other';
+}
+// Normalize a stored entry (legacy string OR object) to a full CredEntry.
+function normalize(key, e) {
+    if (typeof e === 'string')
+        return { value: e, category: categorize(key) };
+    return { value: e.value, category: e.category ?? categorize(key) };
+}
+export class CredStore {
+    path;
+    constructor(path = credsPath()) { this.path = path; }
+    read() {
+        if (!existsSync(this.path))
+            return {};
+        try {
+            return JSON.parse(readFileSync(this.path, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    write(data) {
+        const dir = dirname(this.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(this.path, JSON.stringify(data, null, 2), { mode: 0o600 });
+        // Re-assert 0600 in case the file already existed with looser perms.
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch { /* best-effort */ }
+    }
+    /** All creds for a site as a flat slot→value map (the walk fills inputs from
+     *  this — the contract the walk depends on, unchanged). Legacy + new shapes
+     *  both flatten to value strings here. */
+    get(site) {
+        const stored = this.read()[site] ?? {};
+        const out = {};
+        for (const [k, e] of Object.entries(stored))
+            out[k] = normalize(k, e).value;
+        return out;
+    }
+    /** All creds for a site WITH categories (for the dashboard). */
+    getDetailed(site) {
+        const stored = this.read()[site] ?? {};
+        const out = {};
+        for (const [k, e] of Object.entries(stored))
+            out[k] = normalize(k, e);
+        return out;
+    }
+    /** Merge key/values into a site's creds (existing keys overwritten). Category
+     *  is inferred per key unless `category` is supplied (applies to all keys set
+     *  in this call). Returns the site's key names after the merge. */
+    set(site, values, category) {
+        const data = this.read();
+        const site_creds = { ...(data[site] ?? {}) };
+        for (const [k, v] of Object.entries(values)) {
+            // Preserve an existing key's category on a value-only update unless told otherwise.
+            const existing = site_creds[k] ? normalize(k, site_creds[k]).category : undefined;
+            site_creds[k] = { value: v, category: category ?? existing ?? categorize(k) };
+        }
+        data[site] = site_creds;
+        this.write(data);
+        return Object.keys(data[site]);
+    }
+    /** Change just the CATEGORY of an existing key (value untouched). Returns true
+     *  if the key existed. */
+    setCategory(site, key, category) {
+        const data = this.read();
+        if (!data[site] || !(key in data[site]))
+            return false;
+        const { value } = normalize(key, data[site][key]);
+        data[site][key] = { value, category };
+        this.write(data);
+        return true;
+    }
+    /** Remove a whole site, or just one key when `key` is given. Returns true if
+     *  anything was removed. */
+    remove(site, key) {
+        const data = this.read();
+        if (!data[site])
+            return false;
+        if (key) {
+            if (!(key in data[site]))
+                return false;
+            delete data[site][key];
+            if (Object.keys(data[site]).length === 0)
+                delete data[site];
+        }
+        else {
+            delete data[site];
+        }
+        this.write(data);
+        return true;
+    }
+    /** Sites + their KEY names only — never the values (for `creds list`). Shape
+     *  unchanged so the CLI JSON contract stays stable. */
+    list() {
+        const data = this.read();
+        return Object.keys(data).sort().map((site) => ({ site, keys: Object.keys(data[site]).sort() }));
+    }
+    /** Like list() but with each key's CATEGORY (still never the values). Lets the
+     *  dashboard group by category without revealing anything. */
+    listDetailed() {
+        const data = this.read();
+        return Object.keys(data).sort().map((site) => ({
+            site,
+            keys: Object.keys(data[site]).sort().map((name) => ({ name, category: normalize(name, data[site][name]).category })),
+        }));
+    }
+}

package/dist/dashboard/server.d.ts

@@ -0,0 +1,137 @@
+import { type Server } from 'node:http';
+import type { IMapStore } from '../mapstore/store.js';
+import type { CredStore } from '../creds.js';
+import type { RecordSessionInfo } from '../mapstore/record.js';
+import type { ReplayState } from '../recorder/replay.js';
+/**
+ * webnav's local OPERATOR dashboard — a single long-lived process that lets a
+ * human inspect what webnav knows (sites + their JSON map) and manage the login
+ * credentials webnav uses. Bind 127.0.0.1 ONLY (single user, no auth/CORS): this
+ * is a local tool and credential plaintext must never leave the machine. The
+ * server reads SQLite (via MapStore) and the creds file (via CredStore); the only
+ * writes are credential set/remove/recategorize, which go through CredStore (chmod 600).
+ */
+export interface DashboardOpts {
+    port?: number;
+}
+/**
+ * Human-session recording + replay, injected so the dashboard doesn't hard-depend
+ * on the recorder/playwright stack. Absent (undefined) → recordings routes 503.
+ */
+export interface RecordingsDeps {
+    list(): RecordSessionInfo[] | Promise<RecordSessionInfo[]>;
+    steps(id: string): {
+        seq: number;
+        label: string;
+        kind: string;
+        fromUrl: string;
+        toUrl: string;
+        value?: string;
+        capturedAt: number;
+    }[];
+    del(id: string): void;
+    draft(id: string): unknown;
+    open(url: string, session: string, persistent: boolean, armedOnly?: boolean, profile?: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    record(id: string): boolean;
+    stop(id: string): boolean;
+    replay(id: string, mode?: 'steps' | 'ledger'): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    events(id: string): unknown;
+    replayState(): ReplayState | null;
+    replayControl(action: string, payload: {
+        value?: string;
+        save?: boolean;
+        fire?: boolean;
+    }): boolean;
+    shotPath(session: string, file: string): string | null;
+    toggle(id: string, desired?: boolean): {
+        recording: boolean;
+    };
+    videos(id: string): string[];
+    videoPath(session: string, file: string): string | null;
+    subscribe(cb: (type: string) => void): () => void;
+    activeWindow(): string | null;
+    logs(): {
+        now: number;
+        lines: {
+            t: number;
+            line: string;
+        }[];
+    };
+    notify(kind: string, line?: string): void;
+    review(id: string, opts?: {
+        model?: string;
+        instructions?: string;
+    }): {
+        ok: boolean;
+        error?: string;
+    };
+    reviewReport(id: string): {
+        report: string;
+        at: number;
+        verdict?: {
+            approved: boolean;
+            gaps: number;
+            reason?: string;
+        } | null;
+    } | null;
+    reviewRunning(): string | null;
+    reviewConfig(): {
+        model: string;
+        instructions: string;
+    };
+    profiles(): {
+        name: string;
+        site: string | null;
+        sessions: number;
+        sizeMb: number;
+        lastUsed: number;
+        open: boolean;
+        status?: {
+            auth: 'valid' | 'needs-login' | 'unknown';
+            loginUrl?: string;
+            checkedAt: string;
+        };
+    }[];
+    profileNew(name: string): {
+        ok: boolean;
+        error?: string;
+    };
+    profileOpen(name: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    profileRename(from: string, to: string): {
+        ok: boolean;
+        error?: string;
+    };
+    profileDelete(name: string): {
+        ok: boolean;
+    };
+    profileStatus(name: string, site: string): Promise<{
+        ok: true;
+        auth: 'valid' | 'needs-login' | 'unknown';
+        loginUrl?: string;
+        checkedAt: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    profileReset(name: string): {
+        ok: boolean;
+        error?: string;
+    };
+    reviewFramePath(session: string, file: string): string | null;
+}
+export declare function startDashboard(store: IMapStore, creds: CredStore, opts?: DashboardOpts, rec?: RecordingsDeps): Server;