@leftium/gg 0.0.50 → 0.0.51

package/dist/gg.js

@@ -16,13 +16,13 @@ function createGgDebugger(namespace) {
         if (originalFormatArgs) {
             originalFormatArgs.call(dbg, args);
         }
-        // Extract the callpoint from namespace (strip 'gg:' prefix and any URL suffix)
-        const nsMatch = dbg.namespace.match(/^gg:([^h]+?)(?:http|$)/);
-        const callpoint = nsMatch ? nsMatch[1] : dbg.namespace.replace(/^gg:/, '');
+        // Pad the namespace for aligned console output (strip URL suffix if present)
+        const nsMatch = dbg.namespace.match(/^([^h]+?)(?:http|$)/);
+        const callpoint = nsMatch ? nsMatch[1] : dbg.namespace;
         const paddedCallpoint = callpoint.padEnd(maxCallpointLength, ' ');
         // Replace the namespace in the formatted string with padded version
         if (typeof args[0] === 'string') {
-            args[0] = args[0].replace(dbg.namespace, `gg:${paddedCallpoint}`);
+            args[0] = args[0].replace(dbg.namespace, paddedCallpoint);
         }
     };
     return dbg;
@@ -110,9 +110,11 @@ function isGgEnabled() {
     // GG_ENABLED=false: completely removes gg (even in DEV)
     // GG_ENABLED=true: force-enables gg (even in PROD, e.g. Vercel deployments)
     if (BROWSER) {
-        if (typeof import.meta.env?.VITE_GG_ENABLED === 'string' &&
-            import.meta.env.VITE_GG_ENABLED === 'false') {
-            return false;
+        if (typeof import.meta.env?.VITE_GG_ENABLED === 'string') {
+            if (import.meta.env.VITE_GG_ENABLED === 'false')
+                return false;
+            if (import.meta.env.VITE_GG_ENABLED === 'true')
+                return true;
         }
     }
     else {
@@ -235,7 +237,7 @@ gg.here = function () {
         return { fileName: '', functionName: '', url: '' };
     }
     const callpoint = resolveCallpoint(3);
-    const namespace = `gg:${callpoint}`;
+    const namespace = callpoint;
     // Log the call-site info
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
         namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
@@ -303,12 +305,10 @@ export class GgChain {
     #args;
     #options;
     #flushed = false;
-    #disabled;
     constructor(value, args, options, disabled = false) {
         this.#value = value;
         this.#args = args;
         this.#options = options;
-        this.#disabled = disabled;
         if (!disabled) {
             // Auto-flush on microtask if not flushed synchronously by .v or another trigger
             queueMicrotask(() => this.#flush());
@@ -380,14 +380,67 @@ export class GgChain {
  *
  * Handles namespace resolution, debug output, capture hook, and return value.
  */
+/**
+ * Format a single value for the flat `msg` string written to the file sink
+ * (and stored on CapturedEntry.message). Produces readable output for the
+ * common types that String() handles poorly:
+ *
+ * - plain objects / arrays → compact JSON (depth-limited, no circular crash)
+ * - DOM nodes              → "tag#id.firstClass" summary
+ * - everything else        → String() as before
+ *
+ * This mirrors what `debug`'s %o/%O formatters do and what Node's util.inspect
+ * does by default — display formatting, not round-trip serialization.
+ */
+function formatValue(v) {
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'undefined';
+    if (typeof v === 'string')
+        return v;
+    if (typeof v !== 'object' && typeof v !== 'function')
+        return String(v);
+    // DOM nodes: "div#id.firstClass" summary
+    if (typeof Element !== 'undefined' && v instanceof Element) {
+        let s = v.tagName.toLowerCase();
+        if (v.id)
+            s += `#${v.id}`;
+        if (v.classList.length)
+            s += `.${v.classList[0]}`;
+        return s;
+    }
+    if (typeof Node !== 'undefined' && v instanceof Node) {
+        return `[${v.constructor?.name ?? 'Node'}]`;
+    }
+    // Arrays and plain objects: compact JSON, depth-limited
+    try {
+        return JSON.stringify(v, jsonReplacer, 0) ?? String(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** JSON replacer that limits nesting depth to avoid huge output. */
+function jsonReplacer(key, value) {
+    // 'this' is the parent object; key === '' at the root level
+    if (key !== '' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        // Count depth by checking how many ancestors are objects/arrays
+        // Simple approximation: truncate any nested object at depth > 2
+        const str = JSON.stringify(value);
+        if (str && str.length > 120)
+            return '{…}';
+    }
+    return value;
+}
 function ggLog(options, ...args) {
     const { ns: nsLabel, file, line, col, src, level, stack, tableData } = options;
     if (!ggConfig.enabled) {
         return args.length ? args[0] : { fileName: '', functionName: '', url: '' };
     }
-    const namespace = `gg:${nsLabel}`;
-    if (nsLabel.length < 80 && nsLabel.length > maxCallpointLength) {
-        maxCallpointLength = nsLabel.length;
+    const namespace = nsLabel.startsWith('gg:') ? nsLabel : `gg:${nsLabel}`;
+    if (namespace.length < 80 && namespace.length > maxCallpointLength) {
+        maxCallpointLength = namespace.length;
     }
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
         namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
@@ -424,7 +477,7 @@ function ggLog(options, ...args) {
         namespace,
         color: ggLogFunction.color,
         diff,
-        message: logArgs.length === 1 ? String(logArgs[0]) : logArgs.map(String).join(' '),
+        message: logArgs.length === 1 ? formatValue(logArgs[0]) : logArgs.map(formatValue).join(' '),
         args: logArgs,
         timestamp: Date.now(),
         file,
@@ -435,11 +488,14 @@ function ggLog(options, ...args) {
         stack,
         tableData
     };
-    if (_onLogCallback) {
-        _onLogCallback(entry);
-    }
-    else {
-        earlyLogBuffer.push(entry);
+    // Always buffer — earlyLogBuffer is a persistent replay log so late-registering
+    // listeners (e.g. Eruda mounting after the file-sink listener) still receive entries
+    // that fired before they registered. Dispatched to all current listeners too.
+    earlyLogBuffer.push(entry);
+    if (earlyLogBuffer.length > EARLY_BUFFER_MAX)
+        earlyLogBuffer.shift();
+    if (_logListeners.size > 0) {
+        _dispatchToListeners(entry);
     }
 }
 /**
@@ -466,10 +522,10 @@ gg._here = function (options) {
         return { fileName: '', functionName: '', url: '' };
     }
     const { ns: nsLabel, file, line, col } = options;
-    const namespace = `gg:${nsLabel}`;
+    const namespace = nsLabel.startsWith('gg:') ? nsLabel : `gg:${nsLabel}`;
     const ggLogFunction = namespaceToLogFunction.get(namespace) ||
         namespaceToLogFunction.set(namespace, createGgDebugger(namespace)).get(namespace);
-    ggLogFunction(`    📝 ${nsLabel}`);
+    ggLogFunction(`    📝 ${namespace}`);
     const fileName = file ? file.replace(srcRootRegex, '') : nsLabel;
     const functionName = nsLabel.includes('@') ? nsLabel.split('@').pop() || '' : '';
     const url = file ? openInEditorUrl(file, line, col) : '';
@@ -918,23 +974,65 @@ export function dim() {
     return createColorFunction('', '', STYLE_CODES.dim);
 }
 /**
- * Hook for capturing gg() output (used by Eruda plugin)
- * Set this to a callback function to receive log entries
+ * Multi-listener hook for capturing gg() output.
+ *
+ * Listeners can be added/removed via gg.addLogListener / gg.removeLogListener.
+ * The legacy gg._onLog setter is preserved as a backward-compatible alias
+ * (it replaces the single "legacy" slot without affecting other listeners).
  */
-// Buffer for capturing early logs before Eruda initializes
+// Persistent replay buffer — every new listener gets a full replay of recent entries,
+// so late-registering listeners (e.g. Eruda mounting after the file-sink listener) still
+// receive entries that fired before they registered. In practice this only holds a handful
+// of page-load entries. Capped at 2000 to bound memory in pathological cases.
+// Note: this does NOT cap the JSONL file — the file grows unbounded and agents clear it
+// explicitly via DELETE /__gg/logs.
+const EARLY_BUFFER_MAX = 2000;
 const earlyLogBuffer = [];
-let _onLogCallback = null;
-// Proxy property that replays buffered logs when hook is registered
+const _logListeners = new Set();
+// Legacy single-slot: tracks the callback assigned via `gg._onLog = fn`
+let _legacyOnLogCallback = null;
+function _dispatchToListeners(entry) {
+    _logListeners.forEach((fn) => fn(entry));
+}
+// gg.addLogListener / gg.removeLogListener — primary multi-listener API
+Object.defineProperty(gg, 'addLogListener', {
+    value(callback) {
+        _logListeners.add(callback);
+        // Replay early buffer to every new listener — buffer accumulates entries that
+        // fired before any listener was registered. Each listener gets the full replay;
+        // the buffer is never cleared so late-registering listeners (e.g. Eruda mounting
+        // after the file-sink listener) still receive the early entries.
+        if (earlyLogBuffer.length > 0) {
+            earlyLogBuffer.forEach((entry) => callback(entry));
+        }
+    },
+    writable: false,
+    configurable: true
+});
+Object.defineProperty(gg, 'removeLogListener', {
+    value(callback) {
+        _logListeners.delete(callback);
+    },
+    writable: false,
+    configurable: true
+});
+// Legacy gg._onLog — backward-compatible single-slot alias
 Object.defineProperty(gg, '_onLog', {
     get() {
-        return _onLogCallback;
+        return _legacyOnLogCallback;
     },
     set(callback) {
-        _onLogCallback = callback;
-        // Replay buffered logs when callback is first registered
-        if (callback && earlyLogBuffer.length > 0) {
-            earlyLogBuffer.forEach((entry) => callback(entry));
-            earlyLogBuffer.length = 0; // Clear buffer after replay
+        // Remove previous legacy callback if any
+        if (_legacyOnLogCallback) {
+            _logListeners.delete(_legacyOnLogCallback);
+        }
+        _legacyOnLogCallback = callback;
+        if (callback) {
+            _logListeners.add(callback);
+            // Replay early buffer — same policy as addLogListener
+            if (earlyLogBuffer.length > 0) {
+                earlyLogBuffer.forEach((entry) => callback(entry));
+            }
         }
     }
 });
@@ -956,7 +1054,7 @@ export async function runGgDiagnostics() {
     await serverModulesReady;
     await debugReady;
     // Create test debugger for server-side enabled check
-    const ggLogTest = debugFactory('gg:TEST');
+    const ggLogTest = debugFactory('TEST');
     let ggMessage = '\n';
     const message = (s) => (ggMessage += `${s}\n`);
     const checkbox = (test) => (test ? '✅' : '❌');
@@ -983,15 +1081,19 @@ export async function runGgDiagnostics() {
     }
     message(`${checkbox(ggConfig.enabled)} gg enabled: ${ggConfig.enabled}${enableHint}`);
     if (!BROWSER) {
-        // Server-side: check DEBUG env var (the only output path on the server)
-        const hint = makeHint(!ggLogTest.enabled, ' (Try `DEBUG=gg:* npm run dev` or use --env-file=.env)');
-        message(`${checkbox(ggLogTest.enabled)} DEBUG env variable: ${process?.env?.DEBUG}${hint}`);
+        // Server-side: GG_KEEP controls which namespaces are output to the server console.
+        // Falls back to '*' (all) if not set, so gg works zero-config.
+        const hint = makeHint(!ggLogTest.enabled, ' (Try setting GG_KEEP=* in your .env file or shell)');
+        message(`${checkbox(ggLogTest.enabled)} GG_KEEP env variable: ${process?.env?.GG_KEEP ?? '* (default)'}${hint}`);
     }
-    // Optional plugin diagnostics
-    message(makeHint(_ggCallSitesPlugin, `✅ gg-call-sites vite plugin detected! Call-site namespaces and open-in-editor links baked in at build time.`, `⚠️ gg-call-sites vite plugin not detected. Add ggCallSitesPlugin() to vite.config.ts for file:line call-site namespaces and open-in-editor links. Without plugin, using word-tuple names (e.g. calm-fox) as call-site identifiers.`));
     if (BROWSER && DEV) {
+        // Optional plugin diagnostics — only meaningful in browser where Vite's define
+        // replacements apply. Server-side Node.js load never sees __GG_TAG_PLUGIN__ = true.
+        message(makeHint(_ggCallSitesPlugin, `✅ gg-call-sites vite plugin detected! Call-site namespaces and open-in-editor links baked in at build time.`, `⚠️ gg-call-sites vite plugin not detected. Add ggCallSitesPlugin() to vite.config.ts for file:line call-site namespaces and open-in-editor links. Without plugin, using word-tuple names (e.g. calm-fox) as call-site identifiers.`));
         const { status } = await fetch('/__open-in-editor?file=+');
         message(makeHint(status === 222, `✅ (optional) open-in-editor vite plugin detected! (status code: ${status}) Clickable links open source files in editor.`, `⚠️ (optional) open-in-editor vite plugin not detected. (status code: ${status}) Add openInEditorPlugin() to vite.config.ts for clickable links that open source files in editor`));
+        const fileSinkStatus = await fetch('/__gg/logs', { method: 'HEAD' }).then((r) => r.status, () => 0);
+        message(makeHint(fileSinkStatus === 200, `✅ gg-file-sink vite plugin detected! Logs written to .gg/logs-{port}.jsonl. Agent API at /__gg/logs.`, `ℹ️ (optional) gg-file-sink vite plugin not detected. Add fileSink: true to ggPlugins() options to write logs to .gg/logs-{port}.jsonl for coding agent access.`));
     }
     console.log(ggMessage);
     resetNamespaceWidth();

package/dist/open-in-editor.js

@@ -36,7 +36,7 @@ export default function openInEditorPlugin(specifiedEditor, srcRoot, onErrorCall
                 }
             });
             // Expose project root for client-side $ROOT variable (forward slashes for URI compat)
-            server.middlewares.use('/__gg-project-root', (_req, res) => {
+            server.middlewares.use('/__gg/project-root', (_req, res) => {
                 res.setHeader('Content-Type', 'text/plain');
                 res.end(srcRoot.replace(/\\/g, '/'));
             });

package/dist/pattern.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared namespace pattern matching used by both the Eruda plugin and the
+ * gg-file-sink plugin.
+ *
+ * Patterns are comma-separated globs. A `-` prefix marks an exclusion:
+ *   "gg:*"            — all gg namespaces
+ *   "gg:api:*,-gg:api:verbose:*"  — gg:api:* except verbose
+ */
+/**
+ * Test whether `str` matches a single glob `pattern`.
+ * Supports `*` as a wildcard. Both sides are trimmed before comparison
+ * (namespaces may have trailing spaces from padEnd in the Eruda display).
+ */
+export declare function matchesGlob(str: string, pattern: string): boolean;
+/**
+ * Test whether `ns` matches a comma-separated pattern string.
+ *
+ * - Empty pattern, `*`, or `gg:*` → always true (fast path).
+ * - Inclusions (no `-` prefix) are OR-ed; at least one must match.
+ * - Exclusions (`-` prefix) take priority: any match → false.
+ * - If the pattern contains only exclusions, `ns` is included by default.
+ */
+export declare function matchesPattern(ns: string, pattern: string): boolean;

package/dist/pattern.js

@@ -0,0 +1,41 @@
+/**
+ * Shared namespace pattern matching used by both the Eruda plugin and the
+ * gg-file-sink plugin.
+ *
+ * Patterns are comma-separated globs. A `-` prefix marks an exclusion:
+ *   "gg:*"            — all gg namespaces
+ *   "gg:api:*,-gg:api:verbose:*"  — gg:api:* except verbose
+ */
+/**
+ * Test whether `str` matches a single glob `pattern`.
+ * Supports `*` as a wildcard. Both sides are trimmed before comparison
+ * (namespaces may have trailing spaces from padEnd in the Eruda display).
+ */
+export function matchesGlob(str, pattern) {
+    const s = str.trim();
+    const p = pattern.trim();
+    const regexPattern = p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(s);
+}
+/**
+ * Test whether `ns` matches a comma-separated pattern string.
+ *
+ * - Empty pattern, `*`, or `gg:*` → always true (fast path).
+ * - Inclusions (no `-` prefix) are OR-ed; at least one must match.
+ * - Exclusions (`-` prefix) take priority: any match → false.
+ * - If the pattern contains only exclusions, `ns` is included by default.
+ */
+export function matchesPattern(ns, pattern) {
+    if (!pattern || pattern === '*' || pattern === 'gg:*')
+        return true;
+    const parts = pattern
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const inclusions = parts.filter((p) => !p.startsWith('-'));
+    const exclusions = parts.filter((p) => p.startsWith('-')).map((p) => p.slice(1));
+    const included = inclusions.length === 0 || inclusions.some((p) => matchesGlob(ns, p));
+    const excluded = exclusions.some((p) => matchesGlob(ns, p));
+    return included && !excluded;
+}

package/dist/vite.d.ts

@@ -2,6 +2,8 @@ import type { Plugin } from 'vite';
 import ggCallSitesPlugin from './gg-call-sites-plugin.js';
 import type { GgCallSitesPluginOptions } from './gg-call-sites-plugin.js';
 import openInEditorPlugin from './open-in-editor.js';
+import ggFileSinkPlugin from './gg-file-sink-plugin.js';
+import type { GgFileSinkOptions } from './gg-file-sink-plugin.js';
 export interface GgPluginsOptions {
     /**
      * Options for the call-sites Vite plugin (source metadata rewriting).
@@ -14,6 +16,13 @@ export interface GgPluginsOptions {
      * @default true
      */
     openInEditor?: boolean;
+    /**
+     * Enable the file sink plugin — writes all gg() entries to `.gg/logs-{port}.jsonl`
+     * for coding agent access. Exposes `GET`/`DELETE /__gg/logs` for agent workflows.
+     * Set to `false` to disable.
+     * @default true
+     */
+    fileSink?: boolean | GgFileSinkOptions;
 }
 /**
  * All gg Vite plugins bundled together.
@@ -21,6 +30,7 @@ export interface GgPluginsOptions {
  * Includes:
  * - `ggCallSitesPlugin` — rewrites `gg()` calls with source file/line/col metadata
  * - `openInEditorPlugin` — adds `/__open-in-editor` dev server middleware
+ * - `ggFileSinkPlugin` — writes gg() entries to `.gg/logs-{port}.jsonl` for agent access
  * @example
  * ```ts
  * import ggPlugins from '@leftium/gg/vite';
@@ -31,5 +41,5 @@ export interface GgPluginsOptions {
  * ```
  */
 export default function ggPlugins(options?: GgPluginsOptions): Plugin[];
-export { ggCallSitesPlugin, openInEditorPlugin };
-export type { GgCallSitesPluginOptions };
+export { ggCallSitesPlugin, openInEditorPlugin, ggFileSinkPlugin };
+export type { GgCallSitesPluginOptions, GgFileSinkOptions };

package/dist/vite.js

@@ -1,11 +1,13 @@
 import ggCallSitesPlugin from './gg-call-sites-plugin.js';
 import openInEditorPlugin from './open-in-editor.js';
+import ggFileSinkPlugin from './gg-file-sink-plugin.js';
 /**
  * All gg Vite plugins bundled together.
  *
  * Includes:
  * - `ggCallSitesPlugin` — rewrites `gg()` calls with source file/line/col metadata
  * - `openInEditorPlugin` — adds `/__open-in-editor` dev server middleware
+ * - `ggFileSinkPlugin` — writes gg() entries to `.gg/logs-{port}.jsonl` for agent access
  * @example
  * ```ts
  * import ggPlugins from '@leftium/gg/vite';
@@ -21,7 +23,11 @@ export default function ggPlugins(options = {}) {
     if (options.openInEditor !== false) {
         plugins.push(openInEditorPlugin());
     }
+    if (options.fileSink !== false) {
+        const fileSinkOptions = typeof options.fileSink === 'object' ? options.fileSink : {};
+        plugins.push(ggFileSinkPlugin(fileSinkOptions));
+    }
     return plugins;
 }
 // Allow granular imports for advanced users
-export { ggCallSitesPlugin, openInEditorPlugin };
+export { ggCallSitesPlugin, openInEditorPlugin, ggFileSinkPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftium/gg",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Leftium/gg.git"
@@ -40,27 +40,28 @@
     }
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.2",
+    "@eslint/compat": "^2.0.3",
     "@eslint/js": "^10.0.1",
     "@picocss/pico": "^2.1.1",
-    "@sveltejs/adapter-vercel": "^6.3.1",
-    "@sveltejs/kit": "^2.50.2",
+    "@sveltejs/adapter-vercel": "^6.3.3",
+    "@sveltejs/kit": "^2.53.4",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
-    "@types/node": "^25.2.2",
+    "@types/estree": "^1.0.8",
+    "@types/node": "^25.3.5",
     "add": "^2.0.6",
-    "eslint": "^10.0.0",
+    "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-svelte": "^3.14.0",
-    "globals": "^17.3.0",
+    "eslint-plugin-svelte": "^3.15.0",
+    "globals": "^17.4.0",
     "prettier": "^3.8.1",
-    "prettier-plugin-svelte": "^3.4.1",
-    "publint": "^0.3.17",
+    "prettier-plugin-svelte": "^3.5.1",
+    "publint": "^0.3.18",
     "supports-color": "^10.2.2",
-    "svelte": "^5.50.1",
-    "svelte-check": "^4.3.6",
+    "svelte": "^5.53.7",
+    "svelte-check": "^4.4.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0",
+    "typescript-eslint": "^8.56.1",
     "vite": "^7.3.1",
     "vite-plugin-devtools-json": "^1.0.0",
     "vitest": "^4.0.18"
@@ -70,12 +71,11 @@
   ],
   "dependencies": {
     "@sveltejs/acorn-typescript": "^1.0.9",
-    "@tanstack/virtual-core": "^3.13.18",
-    "@types/estree": "^1.0.8",
-    "acorn": "^8.15.0",
+    "@tanstack/virtual-core": "^3.13.21",
+    "acorn": "^8.16.0",
     "eruda": "^3.4.3",
     "esm-env": "^1.2.2",
-    "launch-editor": "^2.12.0"
+    "launch-editor": "^2.13.1"
   },
   "scripts": {
     "dev": "vite dev",