@leftium/gg 0.0.49 → 0.0.51

package/dist/eruda/types.d.ts

@@ -29,7 +29,7 @@ export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
  * A captured log entry from gg()
  */
 export interface CapturedEntry {
-    /** Namespace (e.g., "gg:routes/+page.svelte@handleClick") */
+    /** Namespace (e.g., "routes/+page.svelte@handleClick") */
     namespace: string;
     /** Color assigned by the debug library (e.g., "#CC3366") */
     color: string;
@@ -59,6 +59,25 @@ export interface CapturedEntry {
         rows: Array<Record<string, unknown>>;
     };
 }
+/**
+ * Tracks loggs dropped by the keep gate (Layer 1) for a single namespace.
+ * Maintained outside the ring buffer — does not consume buffer slots.
+ * The `preview` field holds the most recent dropped logg so the future
+ * sentinel UI can show what the namespace is producing right now.
+ */
+export interface DroppedNamespaceInfo {
+    namespace: string;
+    /** Timestamp of the first dropped logg for this namespace */
+    firstSeen: number;
+    /** Timestamp of the most recent dropped logg */
+    lastSeen: number;
+    /** Total number of dropped loggs across all time */
+    total: number;
+    /** Count per logg type key ('log' for unlabelled calls, or 'debug'/'info'/'warn'/'error') */
+    byType: Record<string, number>;
+    /** Most recent dropped logg — overwritten on each drop, used for sentinel preview */
+    preview: CapturedEntry;
+}
 /**
  * Eruda plugin interface
  */

package/dist/gg-call-sites-plugin.js

@@ -28,9 +28,16 @@ export default function ggCallSitesPlugin(options = {}) {
             // Set a compile-time flag so gg() can detect the plugin is installed.
             // Vite replaces all occurrences of __GG_TAG_PLUGIN__ with true at build time,
             // before any code executes — no ordering issues.
+            // Alias GG_ENABLED → VITE_GG_ENABLED so users only need to set one variable.
+            // VITE_ prefix is required for client-side exposure via import.meta.env.
+            // If VITE_GG_ENABLED is already set explicitly, it takes precedence.
+            const ggEnabled = process.env.VITE_GG_ENABLED ?? process.env.GG_ENABLED;
             return {
                 define: {
-                    __GG_TAG_PLUGIN__: 'true'
+                    __GG_TAG_PLUGIN__: 'true',
+                    ...(ggEnabled !== undefined && {
+                        'import.meta.env.VITE_GG_ENABLED': JSON.stringify(ggEnabled)
+                    })
                 }
             };
         },
@@ -735,7 +742,7 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
             if (code.slice(i + 2, i + 9) === '.here()') {
                 const { line, col } = getLineCol(code, i);
                 const fnName = getFunctionName(i, range);
-                const callpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
+                const callpoint = `gg:${shortPath}${fnName ? `@${fnName}` : ''}`;
                 const escapedNs = escapeForString(callpoint);
                 result.push(code.slice(lastIndex, i));
                 result.push(`gg._here(${buildOptions(range, escapedNs, line, col)})`);
@@ -754,7 +761,7 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
                 const openParenPos = i + methodCallLen - 1;
                 const { line, col } = getLineCol(code, i);
                 const fnName = getFunctionName(i, range);
-                const callpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
+                const callpoint = `gg:${shortPath}${fnName ? `@${fnName}` : ''}`;
                 const escapedNs = escapeForString(callpoint);
                 const closeParenPos = findMatchingParen(code, openParenPos);
                 if (closeParenPos === -1) {
@@ -788,7 +795,7 @@ export function transformGgCalls(code, shortPath, filePath, svelteInfo, jsFuncti
             if (code[i + 2] === '(') {
                 const { line, col } = getLineCol(code, i);
                 const fnName = getFunctionName(i, range);
-                const callpoint = `${shortPath}${fnName ? `@${fnName}` : ''}`;
+                const callpoint = `gg:${shortPath}${fnName ? `@${fnName}` : ''}`;
                 const escapedNs = escapeForString(callpoint);
                 const openParenPos = i + 2; // position of '(' in 'gg('
                 // Find matching closing paren

package/dist/gg-file-sink-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+export interface GgFileSinkOptions {
+    /** Directory to write log files into. Defaults to `.gg/` in the project root. */
+    dir?: string;
+}
+export default function ggFileSinkPlugin(options?: GgFileSinkOptions): Plugin;

package/dist/gg-file-sink-plugin.js

@@ -0,0 +1,394 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { gg } from './gg.js';
+import { matchesPattern } from './pattern.js';
+/**
+ * Serialize a CapturedEntry for writing to the JSONL log file.
+ *
+ * IMPORTANT: The SSR injection string (in the `transform` hook below) and the
+ * browser injection string hand-roll the same logic as plain JS because injected
+ * code cannot import from this module. If you change the SerializedEntry schema
+ * (add/rename/remove fields), update both injection strings to match.
+ *
+ * Server path: `serializeEntry(entry, 'server')` → appended via configureServer listener
+ * SSR path:    ssrInjection string (search for `__ggFileSinkServerWriter`)
+ * Browser path: injection string (search for `__ggFileSinkSender`)
+ */
+function serializeEntry(entry, env, origin) {
+    const out = {
+        ns: entry.namespace,
+        msg: entry.message,
+        ts: entry.timestamp,
+        env,
+        diff: entry.diff
+    };
+    if (entry.level && entry.level !== 'debug')
+        out.lvl = entry.level;
+    if (origin)
+        out.origin = origin;
+    if (entry.file)
+        out.file = entry.file;
+    if (entry.line !== undefined)
+        out.line = entry.line;
+    if (entry.src)
+        out.src = entry.src;
+    if (entry.tableData)
+        out.table = entry.tableData;
+    return out;
+}
+/**
+ * Pre-dedup field filters: namespace glob and timestamp.
+ * Applied before dedup/mismatch so the index sees all entries for a call site.
+ */
+function filterLinePreDedup(line, params) {
+    let entry;
+    try {
+        entry = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    const filter = params.get('filter');
+    if (filter && !matchesPattern(entry.ns, filter))
+        return false;
+    const since = params.get('since');
+    if (since && entry.ts < Number(since))
+        return false;
+    return true;
+}
+/**
+ * Post-dedup field filters: env and origin.
+ * Applied after dedup/mismatch so cross-env comparisons see both sides first.
+ * e.g. ?mismatch&env=server correctly returns the server half of mismatch pairs.
+ */
+function filterEntryPostDedup(entry, params) {
+    const env = params.get('env');
+    if (env && entry.env !== env)
+        return false;
+    const origin = params.get('origin');
+    if (origin && entry.origin !== origin)
+        return false;
+    return true;
+}
+/**
+ * Dedup key for an entry: namespace + line number.
+ * Two entries with the same key are the "same call site" — server and client
+ * rendering the same gg() call. If their msg also matches they're identical;
+ * if msg differs they're a hydration mismatch.
+ */
+function dedupKey(entry) {
+    return `${entry.ns}\0${entry.line ?? ''}`;
+}
+/**
+ * Apply dedup / mismatch logic to an already-field-filtered list of entries.
+ *
+ * Default (all=false, mismatch=false):
+ *   Server entries always pass. A client entry is dropped when a server entry
+ *   at the same [ns, line] produced the same msg (exact duplicate). Client
+ *   entries at call sites with no server counterpart (onMount, event handlers)
+ *   are kept. Client entries where msg differs from the server entry are kept —
+ *   they surface as hydration mismatches alongside the server entry.
+ *
+ * all=true:
+ *   No dedup. Every entry is returned as written.
+ *
+ * mismatch=true:
+ *   Return only entries from call sites where BOTH envs exist AND msg differs.
+ *   Entries from server-only or client-only call sites are suppressed.
+ */
+function applyDedup(entries, all, mismatch) {
+    if (all)
+        return entries;
+    // Build index: dedupKey → { serverMsgs, clientMsgs }
+    const index = new Map();
+    for (const e of entries) {
+        const k = dedupKey(e);
+        if (!index.has(k))
+            index.set(k, { serverMsgs: new Set(), clientMsgs: new Set() });
+        const slot = index.get(k);
+        if (e.env === 'server')
+            slot.serverMsgs.add(e.msg);
+        else
+            slot.clientMsgs.add(e.msg);
+    }
+    if (mismatch) {
+        // Keep only entries from call sites where both envs exist and at least one
+        // msg is present in one env but not the other (i.e. any difference exists).
+        return entries.filter((e) => {
+            const slot = index.get(dedupKey(e));
+            if (slot.serverMsgs.size === 0 || slot.clientMsgs.size === 0)
+                return false;
+            // Check for any msg that exists on one side but not the other
+            for (const m of slot.serverMsgs)
+                if (!slot.clientMsgs.has(m))
+                    return true;
+            for (const m of slot.clientMsgs)
+                if (!slot.serverMsgs.has(m))
+                    return true;
+            return false;
+        });
+    }
+    // Default dedup: drop client entries that are exact duplicates of a server entry.
+    return entries.filter((e) => {
+        if (e.env !== 'client')
+            return true;
+        const slot = index.get(dedupKey(e));
+        if (!slot || slot.serverMsgs.size === 0)
+            return true; // no server counterpart — keep
+        return !slot.serverMsgs.has(e.msg); // keep only if msg differs (mismatch)
+    });
+}
+/**
+ * Collapse consecutive entries with the same ns+msg into a single entry with
+ * a `count` field. Mirrors the Chrome DevTools repeat-counter behaviour.
+ *
+ * Only consecutive runs are collapsed — intentional: an entry appearing again
+ * after different messages is a new event and should be shown separately.
+ *
+ * The `ts` and `diff` of the *first* occurrence are kept; `count` is omitted
+ * when it is 1 (no repetition) so the schema stays clean for non-repeated entries.
+ */
+function collapseRepeats(entries) {
+    const out = [];
+    for (const e of entries) {
+        const prev = out.at(-1);
+        if (prev && prev.ns === e.ns && prev.msg === e.msg) {
+            prev.count = (prev.count ?? 1) + 1;
+        }
+        else {
+            out.push({ ...e });
+        }
+    }
+    return out;
+}
+export default function ggFileSinkPlugin(options = {}) {
+    let logFile;
+    let serverSideListener = null;
+    let ggModulePath = '';
+    return {
+        name: 'gg-file-sink',
+        configResolved(config) {
+            // Resolve the absolute path to gg.ts — works both in this repo (src/lib/gg.ts)
+            // and in consumer projects where gg is in node_modules/@leftium/gg/src/lib/gg.ts.
+            // We try both locations; whichever resolves to an existing file wins.
+            const candidates = [
+                path.resolve(config.root, 'src/lib/gg.ts'),
+                path.resolve(config.root, 'node_modules/@leftium/gg/src/lib/gg.ts')
+            ];
+            ggModulePath = candidates.find((p) => fs.existsSync(p)) ?? candidates[0];
+        },
+        transform(code, id, transformOptions) {
+            if (id !== ggModulePath)
+                return null;
+            if (transformOptions?.ssr) {
+                // SSR injection: write server-side entries directly to the log file.
+                // Runs in Vite's SSR module runner (same Node.js process but separate module
+                // instance from configureServer, so we can't share a listener — inject instead).
+                // We pass appendFileSync + the log file path via globalThis so the injected
+                // code has no imports of its own (avoids TLA / static import constraints).
+                // Guarded by import.meta.env.DEV — tree-shaken in production builds.
+                // NOTE: this string mirrors serializeEntry() above — keep in sync if schema changes.
+                const ssrInjection = `
+// gg-file-sink: server-side direct writer (injected by ggFileSinkPlugin)
+if (import.meta.env.DEV && globalThis.__ggFileSink) {
+	const { appendFileSync: __ggAppendFileSync, logFile: __ggLogFile } = globalThis.__ggFileSink;
+	gg.addLogListener(function __ggFileSinkServerWriter(entry) {
+		if (!__ggLogFile) return;
+		const s = {
+			ns: entry.namespace,
+			msg: entry.message,
+			ts: entry.timestamp,
+			env: 'server',
+			diff: entry.diff,
+		};
+		if (entry.level && entry.level !== 'debug') s.lvl = entry.level;
+		if (entry.file) s.file = entry.file;
+		if (entry.line !== undefined) s.line = entry.line;
+		if (entry.src) s.src = entry.src;
+		if (entry.tableData) s.table = entry.tableData;
+		try { __ggAppendFileSync(__ggLogFile, JSON.stringify(s) + '\\n'); } catch {}
+	});
+}
+`;
+                return { code: code + ssrInjection, map: null };
+            }
+            // Browser injection: relay entries to Vite dev server via HMR WebSocket.
+            // Runs once when the gg module is first loaded in the browser.
+            // Guarded by import.meta.hot — Vite tree-shakes this in production builds.
+            // NOTE: this string mirrors serializeEntry() above — keep in sync if schema changes.
+            const injection = `
+// gg-file-sink: client-side HMR sender (injected by ggFileSinkPlugin)
+if (import.meta.hot) {
+	const __ggFileSinkOrigin =
+		typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window
+			? 'tauri'
+			: 'browser';
+	gg.addLogListener(function __ggFileSinkSender(entry) {
+		if (!import.meta.hot) return;
+		const s = {
+			ns: entry.namespace,
+			msg: entry.message,
+			ts: entry.timestamp,
+			env: 'client',
+			origin: __ggFileSinkOrigin,
+			diff: entry.diff,
+		};
+		if (entry.level && entry.level !== 'debug') s.lvl = entry.level;
+		if (entry.file) s.file = entry.file;
+		if (entry.line !== undefined) s.line = entry.line;
+		if (entry.src) s.src = entry.src;
+		if (entry.tableData) s.table = entry.tableData;
+		import.meta.hot.send('gg:log', { entry: s });
+	});
+}
+`;
+            return { code: code + injection, map: null };
+        },
+        configureServer(server) {
+            // Truncate/create log file once the actual port is known.
+            // appendEntry() guards with `if (!logFile) return` for the brief window
+            // before listening fires, so no entries are written to the wrong file.
+            server.httpServer?.once('listening', () => {
+                const addr = server.httpServer?.address();
+                const port = addr && typeof addr === 'object' ? addr.port : (server.config.server.port ?? 5173);
+                const dir = options.dir ? path.resolve(options.dir) : path.resolve(process.cwd(), '.gg');
+                fs.mkdirSync(dir, { recursive: true });
+                logFile = path.join(dir, `logs-${port}.jsonl`);
+                fs.writeFileSync(logFile, '');
+            });
+            // Expose appendFileSync + logFile path via globalThis so the SSR-injected
+            // listener (running in Vite's separate module runner context) can write to the
+            // same file without needing its own fs import.
+            globalThis.__ggFileSink = {
+                appendFileSync: fs.appendFileSync.bind(fs),
+                get logFile() {
+                    return logFile;
+                }
+            };
+            const appendEntry = (serialized) => {
+                if (!logFile)
+                    return;
+                fs.appendFileSync(logFile, JSON.stringify(serialized) + '\n');
+            };
+            // Client-side entries arrive via HMR custom event
+            server.hot.on('gg:log', (data) => {
+                if (!data?.entry)
+                    return;
+                const serialized = {
+                    ...data.entry,
+                    env: 'client',
+                    origin: data.entry.origin ?? 'browser'
+                };
+                appendEntry(serialized);
+            });
+            // Server-side entries: register listener on the gg module directly
+            serverSideListener = (entry) => {
+                appendEntry(serializeEntry(entry, 'server'));
+            };
+            gg.addLogListener(serverSideListener);
+            // Clean up on dev server close
+            server.httpServer?.once('close', () => {
+                if (serverSideListener) {
+                    gg.removeLogListener(serverSideListener);
+                    serverSideListener = null;
+                }
+                delete globalThis.__ggFileSink;
+            });
+            // /__gg/ index — JSON status for agents and developers
+            server.middlewares.use('/__gg', (req, res, next) => {
+                const pathname = new URL(req.url || '/', 'http://x').pathname;
+                // Only handle exact /__gg or /__gg/ — let other /__gg/* routes fall through
+                if (pathname !== '' && pathname !== '/')
+                    return next();
+                if (req.method?.toUpperCase() !== 'GET')
+                    return next();
+                let entries = 0;
+                try {
+                    const content = fs.readFileSync(logFile, 'utf-8');
+                    entries = content.split('\n').filter((l) => l.trim()).length;
+                }
+                catch {
+                    // file not yet created — leave entries at 0
+                }
+                const port = (() => {
+                    const addr = server.httpServer?.address();
+                    return addr && typeof addr === 'object' ? addr.port : (server.config.server.port ?? 5173);
+                })();
+                const body = JSON.stringify({
+                    plugin: 'gg-file-sink',
+                    logFile: `.gg/logs-${port}.jsonl`,
+                    entries,
+                    endpoints: {
+                        'GET /__gg/logs': 'read deduplicated JSONL entries (?filter=, ?since=, ?env=, ?origin=, ?all, ?mismatch, ?raw)',
+                        'DELETE /__gg/logs': 'truncate log file',
+                        'GET /__gg/project-root': 'project root path'
+                    }
+                }, null, 2);
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                res.end(body);
+            });
+            // /__gg/logs middleware
+            server.middlewares.use('/__gg/logs', (req, res) => {
+                const method = req.method?.toUpperCase();
+                // HEAD: used by runGgDiagnostics() to detect plugin presence
+                if (method === 'HEAD') {
+                    res.statusCode = 200;
+                    res.end();
+                    return;
+                }
+                if (method === 'DELETE') {
+                    try {
+                        fs.writeFileSync(logFile, '');
+                        res.statusCode = 204;
+                        res.end();
+                    }
+                    catch (err) {
+                        res.statusCode = 500;
+                        res.end(String(err));
+                    }
+                    return;
+                }
+                if (method === 'GET') {
+                    try {
+                        const params = new URL(req.url || '/', 'http://x').searchParams;
+                        const all = params.has('all');
+                        const mismatch = params.has('mismatch');
+                        // ?raw disables consecutive-repeat collapsing (count field)
+                        const noCollapse = params.has('raw');
+                        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                        const fileContent = fs.readFileSync(logFile, 'utf-8');
+                        const lines = fileContent.split('\n').filter((l) => l.trim());
+                        // Pre-dedup filters: namespace glob and timestamp (symmetric — don't affect cross-env index)
+                        const preFiltered = lines.filter((l) => filterLinePreDedup(l, params));
+                        // Parse surviving lines for dedup/mismatch pass
+                        const entries = preFiltered.flatMap((l) => {
+                            try {
+                                return [JSON.parse(l)];
+                            }
+                            catch {
+                                return [];
+                            }
+                        });
+                        // Apply dedup / mismatch logic (default: dedup on)
+                        const deduped = applyDedup(entries, all, mismatch);
+                        // Post-dedup filters: env and origin (applied after so cross-env index is intact)
+                        const postFiltered = deduped.filter((e) => filterEntryPostDedup(e, params));
+                        // Collapse consecutive repeated messages (count field), unless ?raw
+                        const result = noCollapse ? postFiltered : collapseRepeats(postFiltered);
+                        res.statusCode = 200;
+                        res.end(result.map((e) => JSON.stringify(e)).join('\n') + (result.length ? '\n' : ''));
+                    }
+                    catch (err) {
+                        res.statusCode = 500;
+                        res.end(String(err));
+                    }
+                    return;
+                }
+                res.statusCode = 405;
+                res.setHeader('Allow', 'GET, HEAD, DELETE');
+                res.end('Method Not Allowed');
+            });
+        }
+    };
+}

package/dist/gg.d.ts

@@ -208,7 +208,10 @@ export declare function underline(): ChainableColorFn;
  */
 export declare function dim(): ChainableColorFn;
 export declare namespace gg {
+    /** @deprecated Use gg.addLogListener / gg.removeLogListener instead */
     let _onLog: OnLogCallback | null;
+    let addLogListener: (callback: OnLogCallback) => void;
+    let removeLogListener: (callback: OnLogCallback) => void;
     let _ns: (options: {
         ns: string;
         file?: string;