gina 0.3.1 → 0.3.2

package/framework/v0.3.2/lib/cmd/inspector/help.js

@@ -0,0 +1,48 @@
+var fs          = require('fs');
+
+var CmdHelper   = require('./../helper');
+var console     = lib.logger;
+
+/**
+ * @module gina/lib/cmd/inspector/help
+ */
+/**
+ * Displays the inspector command group help text.
+ *
+ * Usage:
+ *  gina inspector:help
+ *
+ * @class Help
+ * @constructor
+ * @param {object} opt - Parsed command-line options
+ * @param {object} opt.client - Socket client for terminal output
+ * @param {string[]} opt.argv - Full argv array
+ * @param {number} [opt.debugPort] - Node.js inspector port
+ * @param {boolean} [opt.debugBrkEnabled] - True when --inspect-brk is active
+ * @param {object} cmd - The cmd dispatcher object (lib/cmd/index.js)
+ */
+function Help(opt, cmd) {
+    var self = {};
+
+    /**
+     * Loads CMD helpers and prints the inspector group help text, then exits.
+     *
+     * @inner
+     * @private
+     */
+    var init = function() {
+
+        // import CMD helpers
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+
+        // check CMD configuration
+        if ( !isCmdConfigured() ) return false;
+
+        getHelp();
+        process.exit(0);
+    }
+
+    init()
+};
+
+module.exports = Help

package/framework/v0.3.2/lib/cmd/inspector/help.txt

@@ -0,0 +1,28 @@
+
+  Usage: gina inspector:<action> [options]
+
+  Actions:
+
+    open [bundle] [@project]    Open the Inspector SPA in a chromeless browser window
+
+  Options:
+
+    --browser=<name>            Override the default browser
+                                Available: chrome, chromium, edge, brave,
+                                           vivaldi, opera, firefox, safari
+
+    --port=<number>             Override the bundle port (skip config lookup)
+
+  Examples:
+
+    gina inspector:open                         Open for default bundle on port 3100
+    gina inspector:open demo @myproject         Open for bundle "demo"
+    gina inspector:open --port=3200             Open for a specific port
+    gina inspector:open --browser=chrome        Force Chrome (app mode)
+    gina inspector:open --browser=firefox       Force Firefox (normal window)
+
+  App mode support (chromeless window — no address bar, no tabs):
+
+    Supported:    chrome, chromium, edge, brave, vivaldi, opera
+    Not supported: firefox, safari (opens in a normal browser window)
+

package/framework/v0.3.2/lib/cmd/inspector/open.js

@@ -0,0 +1,510 @@
+var Open;
+/**
+ * @module gina/lib/cmd/inspector/open
+ *
+ * Opens the dev-mode Inspector SPA in a chromeless browser window (app mode).
+ *
+ * Usage:
+ *   gina inspector:open [<bundle>] [@<project>] [--browser=<name>] [--port=<port>]
+ *
+ * The command detects the default browser on macOS, Linux, and Windows.
+ * When available, it launches in app mode (chromeless window — no address
+ * bar, no tabs). Chromium-based browsers (Chrome, Edge, Brave, Vivaldi,
+ * Opera) all support `--app=<url>`. Firefox and Safari fall back to a
+ * normal browser window.
+ *
+ * `--browser=<name>` overrides the default browser. Accepted short names:
+ *   chrome, chromium, edge, brave, vivaldi, opera, firefox, safari
+ *
+ * `--port=<port>` overrides the bundle port (skips project config lookup).
+ *
+ * When `--port` is used, `@<project>` is optional.
+ *
+ * @class Open
+ * @constructor
+ * @param {object} opt - Parsed command-line options
+ * @param {object} opt.client - Socket client for terminal output
+ * @param {string[]} opt.argv - Full argv array
+ * @param {number} [opt.debugPort] - Node.js inspector port
+ * @param {boolean} [opt.debugBrkEnabled] - True when --inspect-brk is active
+ * @param {object} cmd - The cmd dispatcher object (lib/cmd/index.js)
+ */
+
+var fs        = require('fs');
+var child     = require('child_process');
+var os        = require('os');
+var CmdHelper = require('./../helper');
+var console   = lib.logger;
+
+/**
+ * Browser registry — short names mapped to per-platform details.
+ * `appMode: true` means the browser supports `--app=<url>` for a chromeless window.
+ *
+ * @constant
+ * @type {Object<string, {name: string, appMode: boolean, darwin: object, linux: object, win32: object}>}
+ */
+var BROWSERS = {
+    chrome: {
+        name      : 'Google Chrome'
+      , appMode   : true
+      , darwin    : { app: 'Google Chrome' }
+      , linux     : { bins: ['google-chrome-stable', 'google-chrome', 'chrome'] }
+      , win32     : { bins: ['chrome'], paths: [
+            '%ProgramFiles%\\Google\\Chrome\\Application\\chrome.exe'
+          , '%ProgramFiles(x86)%\\Google\\Chrome\\Application\\chrome.exe'
+          , '%LocalAppData%\\Google\\Chrome\\Application\\chrome.exe'
+        ]}
+    }
+  , chromium: {
+        name      : 'Chromium'
+      , appMode   : true
+      , darwin    : { app: 'Chromium' }
+      , linux     : { bins: ['chromium-browser', 'chromium'] }
+      , win32     : { bins: ['chromium'], paths: [] }
+    }
+  , edge: {
+        name      : 'Microsoft Edge'
+      , appMode   : true
+      , darwin    : { app: 'Microsoft Edge' }
+      , linux     : { bins: ['microsoft-edge-stable', 'microsoft-edge'] }
+      , win32     : { bins: ['msedge'], paths: [
+            '%ProgramFiles(x86)%\\Microsoft\\Edge\\Application\\msedge.exe'
+          , '%ProgramFiles%\\Microsoft\\Edge\\Application\\msedge.exe'
+        ]}
+    }
+  , brave: {
+        name      : 'Brave'
+      , appMode   : true
+      , darwin    : { app: 'Brave Browser' }
+      , linux     : { bins: ['brave-browser-stable', 'brave-browser'] }
+      , win32     : { bins: ['brave'], paths: [
+            '%ProgramFiles%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe'
+          , '%LocalAppData%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe'
+        ]}
+    }
+  , vivaldi: {
+        name      : 'Vivaldi'
+      , appMode   : true
+      , darwin    : { app: 'Vivaldi' }
+      , linux     : { bins: ['vivaldi-stable', 'vivaldi'] }
+      , win32     : { bins: ['vivaldi'], paths: [
+            '%LocalAppData%\\Vivaldi\\Application\\vivaldi.exe'
+        ]}
+    }
+  , opera: {
+        name      : 'Opera'
+      , appMode   : true
+      , darwin    : { app: 'Opera' }
+      , linux     : { bins: ['opera'] }
+      , win32     : { bins: ['opera'], paths: [
+            '%LocalAppData%\\Programs\\Opera\\launcher.exe'
+        ]}
+    }
+  , firefox: {
+        name      : 'Firefox'
+      , appMode   : false
+      , darwin    : { app: 'Firefox' }
+      , linux     : { bins: ['firefox'] }
+      , win32     : { bins: ['firefox'], paths: [
+            '%ProgramFiles%\\Mozilla Firefox\\firefox.exe'
+        ]}
+    }
+  , safari: {
+        name      : 'Safari'
+      , appMode   : false
+      , darwin    : { app: 'Safari' }
+      , linux     : null
+      , win32     : null
+    }
+};
+
+/**
+ * macOS bundle IDs → short name mapping for default browser detection.
+ * @constant
+ * @type {Object<string, string>}
+ */
+var BUNDLE_ID_MAP = {
+    'com.google.chrome'            : 'chrome'
+  , 'org.chromium.chromium'        : 'chromium'
+  , 'com.microsoft.edgemac'        : 'edge'
+  , 'com.brave.browser'            : 'brave'
+  , 'com.vivaldi.vivaldi'          : 'vivaldi'
+  , 'com.operasoftware.opera'      : 'opera'
+  , 'org.mozilla.firefox'          : 'firefox'
+  , 'com.apple.safari'             : 'safari'
+};
+
+/**
+ * Linux .desktop file prefixes → short name mapping.
+ * @constant
+ * @type {Object<string, string>}
+ */
+var DESKTOP_MAP = {
+    'google-chrome'     : 'chrome'
+  , 'chromium'          : 'chromium'
+  , 'microsoft-edge'    : 'edge'
+  , 'brave-browser'     : 'brave'
+  , 'vivaldi'           : 'vivaldi'
+  , 'opera'             : 'opera'
+  , 'firefox'           : 'firefox'
+};
+
+/**
+ * Windows ProgId prefixes → short name mapping.
+ * @constant
+ * @type {Object<string, string>}
+ */
+var PROGID_MAP = {
+    'ChromeHTML'     : 'chrome'
+  , 'ChromiumHTM'    : 'chromium'
+  , 'MSEdgeHTM'      : 'edge'
+  , 'BraveHTML'      : 'brave'
+  , 'VivaldiHTM'     : 'vivaldi'
+  , 'OperaStable'    : 'opera'
+  , 'FirefoxURL'     : 'firefox'
+};
+
+
+/**
+ * Detect the default browser on macOS by reading Launch Services plist.
+ * Falls back to `'safari'` (the OS default).
+ *
+ * @inner
+ * @returns {string} Browser short name
+ */
+function detectDarwin() {
+    try {
+        var plistPath = process.env.HOME
+            + '/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist';
+
+        if (!fs.existsSync(plistPath)) return 'safari';
+
+        var raw = child.execSync(
+            'plutil -convert json -o - "' + plistPath + '"'
+          , { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        var plist    = JSON.parse(raw);
+        var handlers = plist.LSHandlers || [];
+        for (var i = 0; i < handlers.length; i++) {
+            var h = handlers[i];
+            if (h.LSHandlerURLScheme === 'https' && h.LSHandlerRoleAll) {
+                var bid = h.LSHandlerRoleAll.toLowerCase();
+                for (var key in BUNDLE_ID_MAP) {
+                    if (bid === key) return BUNDLE_ID_MAP[key];
+                }
+            }
+        }
+    } catch (e) { /* plist unreadable — fall through */ }
+    return 'safari';
+}
+
+/**
+ * Detect the default browser on Linux via `xdg-settings`.
+ * Falls back to `'firefox'`.
+ *
+ * @inner
+ * @returns {string} Browser short name
+ */
+function detectLinux() {
+    try {
+        var desktop = child.execSync(
+            'xdg-settings get default-web-browser 2>/dev/null'
+          , { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        ).trim().toLowerCase();
+        for (var prefix in DESKTOP_MAP) {
+            if (desktop.indexOf(prefix) !== -1) return DESKTOP_MAP[prefix];
+        }
+    } catch (e) { /* xdg not available */ }
+    return 'firefox';
+}
+
+/**
+ * Detect the default browser on Windows via registry query.
+ * Falls back to `'edge'` (the OS default).
+ *
+ * @inner
+ * @returns {string} Browser short name
+ */
+function detectWindows() {
+    try {
+        var raw = child.execSync(
+            'reg query "HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\https\\UserChoice" /v ProgId 2>nul'
+          , { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        var match = raw.match(/ProgId\s+REG_SZ\s+(\S+)/);
+        if (match) {
+            var progId = match[1];
+            for (var prefix in PROGID_MAP) {
+                if (progId.indexOf(prefix) !== -1) return PROGID_MAP[prefix];
+            }
+        }
+    } catch (e) { /* registry unreadable */ }
+    return 'edge';
+}
+
+/**
+ * Detect the default browser for the current platform.
+ *
+ * @inner
+ * @returns {string} Browser short name
+ */
+function detectDefaultBrowser() {
+    var platform = os.platform();
+    if (platform === 'darwin') return detectDarwin();
+    if (platform === 'linux')  return detectLinux();
+    if (platform === 'win32')  return detectWindows();
+    return 'chrome';
+}
+
+/**
+ * Check whether a binary is available on the system PATH (Linux/Windows).
+ *
+ * @inner
+ * @param {string} bin - Binary name to look up
+ * @returns {boolean}
+ */
+function hasBin(bin) {
+    try {
+        var cmd = (os.platform() === 'win32')
+            ? 'where ' + bin + ' 2>nul'
+            : 'which ' + bin + ' 2>/dev/null';
+        child.execSync(cmd, { stdio: ['pipe', 'pipe', 'pipe'] });
+        return true;
+    } catch (e) { return false; }
+}
+
+/**
+ * Resolve the executable path for a browser on Windows.
+ * Tries the `paths` list (with env var expansion) before falling back to
+ * `where` lookup on the short binary name.
+ *
+ * @inner
+ * @param {object} winDef - The `win32` entry from the BROWSERS registry
+ * @returns {string|null} Resolved path or null
+ */
+function resolveWindowsPath(winDef) {
+    if (!winDef) return null;
+    var paths = winDef.paths || [];
+    for (var i = 0; i < paths.length; i++) {
+        try {
+            var expanded = child.execSync(
+                'echo ' + paths[i]
+              , { encoding: 'utf8', shell: true, stdio: ['pipe', 'pipe', 'pipe'] }
+            ).trim();
+            if (fs.existsSync(expanded)) return expanded;
+        } catch (e) { /* skip */ }
+    }
+    var bins = winDef.bins || [];
+    for (var b = 0; b < bins.length; b++) {
+        if (hasBin(bins[b])) return bins[b];
+    }
+    return null;
+}
+
+/**
+ * Build the shell command to open a URL in a specific browser.
+ *
+ * @inner
+ * @param {string} shortName - Browser short name from BROWSERS
+ * @param {string} url - The URL to open
+ * @returns {{ cmd: string, appMode: boolean }|null}
+ */
+function buildLaunchCmd(shortName, url) {
+    var browser  = BROWSERS[shortName];
+    if (!browser) return null;
+
+    var platform = os.platform();
+    var platDef  = browser[platform];
+    if (!platDef) return null;
+
+    var appFlag  = browser.appMode ? ('--app=' + url) : '';
+
+    if (platform === 'darwin') {
+        if (browser.appMode) {
+            // Chromium-based: call the binary directly so --app= works even
+            // when the browser is already running. `open --args` is unreliable
+            // in that case — macOS sends the URL to the existing instance as a
+            // regular navigation, ignoring --app=.
+            var binPath = '/Applications/' + platDef.app + '.app/Contents/MacOS/' + platDef.app;
+            if (!fs.existsSync(binPath)) return null;
+            return {
+                cmd     : '"' + binPath + '" --app="' + url + '"'
+              , appMode : true
+            };
+        }
+        // Non-app-mode browsers (Firefox, Safari): use `open -a`
+        return {
+            cmd     : 'open -a "' + platDef.app + '" "' + url + '"'
+          , appMode : false
+        };
+    }
+
+    if (platform === 'linux') {
+        var bins = platDef.bins || [];
+        var bin  = null;
+        for (var i = 0; i < bins.length; i++) {
+            if (hasBin(bins[i])) { bin = bins[i]; break; }
+        }
+        if (!bin) return null;
+        var linuxArgs = browser.appMode
+            ? bin + ' --app="' + url + '"'
+            : bin + ' "' + url + '"';
+        return { cmd: linuxArgs, appMode: browser.appMode };
+    }
+
+    if (platform === 'win32') {
+        var winBin = resolveWindowsPath(platDef);
+        if (!winBin) return null;
+        var quoted = (winBin.indexOf(' ') !== -1) ? '"' + winBin + '"' : winBin;
+        var winArgs = browser.appMode
+            ? 'start "" ' + quoted + ' --app="' + url + '"'
+            : 'start "" ' + quoted + ' "' + url + '"';
+        return { cmd: winArgs, appMode: browser.appMode };
+    }
+
+    return null;
+}
+
+
+function Open(opt, cmd) {
+    var self = {};
+
+    /**
+     * Parse argv, validate project/bundle, resolve port, and launch browser.
+     *
+     * @inner
+     * @private
+     */
+    var init = function () {
+
+        // import CMD helpers — provides isCmdConfigured(), isDefined(), etc.
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+
+        var browserOverride = null;
+        var portOverride    = null;
+        var bundleName      = null;
+        var i;
+
+        for (i = 3; i < process.argv.length; i++) {
+            var arg = process.argv[i];
+            if (/^--browser=/.test(arg)) {
+                browserOverride = arg.split('=')[1].toLowerCase();
+            } else if (/^--port=/.test(arg)) {
+                portOverride = parseInt(arg.split('=')[1], 10);
+            } else if (!/^--/.test(arg) && !/^@/.test(arg)) {
+                bundleName = arg;
+            }
+        }
+
+        // When --port is given, skip project/bundle validation entirely
+        if (!portOverride) {
+            // check CMD configuration (project existence, etc.)
+            if ( !isCmdConfigured() ) return false;
+
+            // validate the bundle if one was specified
+            if (bundleName && !isDefined('bundle', bundleName)) {
+                console.error(
+                    'Bundle [ ' + bundleName + ' ] is not registered inside `@'
+                    + self.projectName + '`.\n'
+                    + 'Did you run `gina bundle:add ' + bundleName
+                    + ' @' + self.projectName + '` first?'
+                );
+                process.exit(1);
+                return;
+            }
+        }
+
+        // Resolve the target port from ports.reverse.json
+        var port = portOverride || null;
+        if (!portOverride && bundleName) {
+            try {
+                var key          = bundleName + '@' + self.projectName;
+                var portsReverse = self.portsReverseData || {};
+                var bundlePorts  = portsReverse[key];
+                if (bundlePorts) {
+                    // Use dev env by default, fall back to the first available env
+                    var env      = bundlePorts['dev'] ? 'dev' : Object.keys(bundlePorts)[0];
+                    var envPorts = bundlePorts[env];
+                    // Prefer http/1.1 http port
+                    if (envPorts['http/1.1'] && envPorts['http/1.1']['http']) {
+                        port = envPorts['http/1.1']['http'];
+                    } else if (envPorts['http/1.1'] && envPorts['http/1.1']['https']) {
+                        port = envPorts['http/1.1']['https'];
+                    }
+                }
+            } catch (e) { /* use fallback */ }
+        }
+        if (!port) {
+            port = 3100;
+        }
+
+        var target = 'http://localhost:' + port;
+        var url    = target + '/_gina/inspector/?target=' + encodeURIComponent(target);
+
+        // Resolve browser
+        var shortName = browserOverride || detectDefaultBrowser();
+        if (!BROWSERS[shortName]) {
+            console.error(
+                'Unknown browser "' + shortName + '". '
+                + 'Available: ' + Object.keys(BROWSERS).join(', ')
+            );
+            process.exit(1);
+            return;
+        }
+
+        // If the resolved browser doesn't support app mode and the user
+        // didn't explicitly pick it, try to find an installed Chromium
+        // browser that does.
+        if (!browserOverride && !BROWSERS[shortName].appMode) {
+            var appModeBrowsers = ['chrome', 'edge', 'brave', 'chromium', 'vivaldi', 'opera'];
+            for (var a = 0; a < appModeBrowsers.length; a++) {
+                var candidate = buildLaunchCmd(appModeBrowsers[a], url);
+                if (candidate) {
+                    shortName = appModeBrowsers[a];
+                    break;
+                }
+            }
+        }
+
+        var launch = buildLaunchCmd(shortName, url);
+        if (!launch) {
+            // No app-mode browser found — fall back to system default
+            console.warn(
+                'No app-mode browser found. '
+                + 'Opening in system default browser.'
+            );
+            var fallbackCmd = (os.platform() === 'win32')
+                ? 'start "" "' + url + '"'
+                : (os.platform() === 'darwin')
+                    ? 'open "' + url + '"'
+                    : 'xdg-open "' + url + '"';
+            child.exec(fallbackCmd);
+            process.exit(0);
+            return;
+        }
+
+        var modeLabel = launch.appMode ? 'app mode' : 'normal window';
+        console.log(
+            'Opening Inspector in ' + BROWSERS[shortName].name
+            + ' (' + modeLabel + ')'
+        );
+        console.log(url);
+
+        child.exec(launch.cmd, function (err) {
+            if (err) {
+                console.warn('Browser launch failed, trying system default.');
+                var fallback = (os.platform() === 'win32')
+                    ? 'start "" "' + url + '"'
+                    : (os.platform() === 'darwin')
+                        ? 'open "' + url + '"'
+                        : 'xdg-open "' + url + '"';
+                child.exec(fallback);
+            }
+            process.exit(0);
+        });
+    };
+
+    init();
+}
+
+module.exports = Open;

package/framework/{v0.3.1 → v0.3.2}/lib/index.js

@@ -131,6 +131,7 @@ lib.cmd.load = function(opt){
     setPath('gina.root', _(opt.ginaPath));
     setPath('framework', _(opt.frameworkPath));
     setPath('gina.core', _(opt.frameworkPath +'/core'));
+    setPath('gina.home', opt.homedir);
     setPath('gina.lib', _(opt.frameworkPath +'/lib'));
     setPath('gina.helpers', _(opt.frameworkPath +'/helpers'));
 

package/framework/{v0.3.1 → v0.3.2}/lib/model.js

@@ -158,6 +158,14 @@ function ModelUtil() {
 
         self.models[bundle][model][name] =  entityObject;
 
+        // Register a short-name alias (without the "Entity" suffix) so
+        // controllers can use `db.link` instead of `db.linkEntity`.
+        if (/Entity$/.test(name)) {
+            var _shortName = name.replace(/Entity$/, '');
+            if (_shortName && !self.models[bundle][model][_shortName]) {
+                self.models[bundle][model][_shortName] = entityObject;
+            }
+        }
 
         ModelUtil.instance.models = self.models;
         setContext('modelUtil.models', self.models, true);
@@ -237,6 +245,14 @@ function ModelUtil() {
                     console.warn('no models attached to connector '+ connector);
                 }
 
+                // Count only actual connector entries (skip annotations like $schema)
+                var _connectorCount = 0;
+                for (var _ck in models) {
+                    if (models.hasOwnProperty(_ck) && typeof(models[_ck]) == 'object' && models[_ck] !== null) {
+                        ++_connectorCount;
+                    }
+                }
+
                 var t = 0;
 
                 var done = function(connector, modelConnectors) {
@@ -246,7 +262,7 @@ function ModelUtil() {
                         console.error('connector '+ connector +' not found in configuration')
                     }
 
-                    if ( t == models.count() ) {
+                    if ( t == _connectorCount ) {
                         setContext('modelConnectors', modelConnectors);
 
                         var conn                = null
@@ -299,6 +315,9 @@ function ModelUtil() {
                 }
 
                 for (var c in models) {//c as connector name
+                    // skip non-connector entries (e.g. $schema annotations in connectors.json)
+                    if (typeof(models[c]) != 'object' || models[c] === null) continue;
+
                     if ( modelObject && typeof(modelObject[c]) != 'undefined' ) {
                         done(connector, modelConnectors)
                     } else {
@@ -551,7 +570,12 @@ function ModelUtil() {
         // ) {
 
         // } else {
-            self.models = ModelUtil.instance.models
+            // Dev-mode cache bust: ModelUtil.instance may reference a stale
+            // constructor function. Fall back to getContext for the live singleton.
+            var _modelUtilRef = ModelUtil.instance || getContext('modelUtil');
+            if (_modelUtilRef) {
+                self.models = _modelUtilRef.models;
+            }
         // }
 
         if ( typeof(model) != 'undefined' && typeof(self.models[bundle]) != 'undefined' ) {
@@ -570,7 +594,7 @@ function ModelUtil() {
                 return undefined
             }
         } else {
-            throw new Error('[ MODEL ][ '+ name +' ][ '+ bundle +'] No model found !');
+            throw new Error('[ MODEL ][ '+ model +' ][ '+ bundle +'] No model found !');
         }
     }
 

package/llms.txt

@@ -416,7 +416,8 @@ gina bundle:restart <bundle> @<project> # Restart a bundle
 gina project:start @<project> --env=dev # Start all bundles in a project
 gina project:stop @<project>            # Stop all bundles in a project
 gina project:restart @<project>         # Restart all bundles in a project
-gina bundle:add <bundle> @<project>     # Scaffold a new bundle
+gina bundle:add <bundle> @<project>     # Scaffold a new bundle (overwrites existing src)
+gina bundle:add <bundle> @<project> --import  # Register existing bundle (preserves src)
 gina bundle:remove <bundle> @<project>  # Remove a bundle
 gina bundle:list @<project>             # List bundles
 gina view:add <bundle> @<project>       # Add HTML templates to a bundle
@@ -496,10 +497,14 @@ The Inspector is a dev-mode SPA embedded in every bundle at `/_gina/inspector/`.
 - **Server-side (SSE agent):** `/_gina/agent` endpoint `event: log` — combined stream in standalone mode. Same log format as `/_gina/logs`.
 - **Server-side (engine.io):** `{ type: 'log', data: {...} }` WebSocket messages pushed from the `ioServer` connection handler when engine.io is configured.
 
+**Lazy activation** — `process.gina._inspectorActive` is `false` at startup. Set to `true` when the Inspector SPA, `/_gina/logs`, or `/_gina/agent` is first accessed. All profiling infrastructure (timeline init, query log wiring, Inspector payload emission) is gated on this flag. JSON responses stay clean until a developer actually opens the Inspector.
+
 **Dev mode injections** (both added to user pages in dev mode, before `</body>`):
 - **`__logsScript`** — patches `console.log/info/warn/error/debug` to push `{ t, l, b, s }` entries to `window.__ginaLogs`. The Inspector reads this via `window.opener.__ginaLogs`.
 - **`__gdScript`** — `window.__ginaData = { gina: {...}, user: {...} }`. `__gdPayload` also stored on `self.serverInstance._lastGinaData` for engine.io. Also emits `process.emit('inspector#data', __gdPayload)` for `/_gina/agent` SSE clients.
 
+**JSON API coverage** — `render-json.js` emits the same `process.emit('inspector#data')` event and stores `_lastGinaData` when `_inspectorActive` is true. Environment is built from `getContext('gina')` + `local.options.conf` (since `data.page` doesn't exist in the JSON path). The JSON response body itself is NOT modified — Inspector data travels only via the SSE/engine.io channel.
+
 **`statusbar.html` link** — simple relative `/_gina/inspector/` (opens in new tab, same origin).
 
 **Serving** — `server.js` `onRequest()` matches `GET /_gina/inspector/*` in dev mode (engine-agnostic — works with both Isaac and Express). Files served from `core/asset/plugin/dist/vendor/gina/inspector/` with `no-cache` headers. Requests for `/_gina/inspector/` or `/_gina/inspector` serve `index.html`. MIME types: `html` → `text/html`, `js` → `application/javascript`, `css` → `text/css`, `svg` → `image/svg+xml`.