gina 0.4.2 → 0.4.3

package/framework/{v0.4.2 → v0.4.3}/core/gna.js

@@ -1197,11 +1197,15 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                                     if (!process.gina) process.gina = {};
                                     process.gina._inspectorAgentEnabled = (_inspAgent.enabled === true);
                                     process.gina._inspectorAgentKey     = (typeof _inspAgent.key === 'string' && _inspAgent.key) ? _inspAgent.key : null;
+                                    // #INS8 — Origin allowlist for the WebSocket /_gina/agent upgrade
+                                    // (empty ⇒ allow any origin; enforced only when non-empty).
+                                    process.gina._inspectorAgentAllowedOrigins = Array.isArray(_inspAgent.allowedOrigins) ? _inspAgent.allowedOrigins : [];
                                 } catch (inspAgentErr) {
                                     console.warn('[inspector-agent] init skipped: ' + (inspAgentErr.message || inspAgentErr));
                                     if (!process.gina) process.gina = {};
                                     process.gina._inspectorAgentEnabled = false;
                                     process.gina._inspectorAgentKey     = null;
+                                    process.gina._inspectorAgentAllowedOrigins = [];
                                 }
 
                                 // #INS10 — capture the instrumentation-window opt-in + key + window
@@ -1237,6 +1241,56 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                                     process.gina._inspectorWindowUntil       = 0;
                                 }
 
+                                // #INS8 — dev-only auto-start of the standalone Inspector
+                                // bundle (inspector@gina). Best-effort + fail-closed.
+                                // Gated on:
+                                //  - isDev: never fires outside the project's dev env.
+                                //  - projectName !== 'gina': a @gina service (inspector /
+                                //    proxy) must never trigger this — otherwise the
+                                //    Inspector would re-spawn itself when it boots. This is
+                                //    the timing-proof guard; the not-running check below is
+                                //    a second line of defense.
+                                //  - srcExists: the @gina project is registered AND
+                                //    services/src/inspector is on disk. services/ is
+                                //    gitignored + npmignored, so it is absent in any
+                                //    `npm install gina` — the auto-start no-ops for everyone
+                                //    but a maintainer who scaffolded the services/ project.
+                                //  - not-running: a live inspector@gina pidfile skips the
+                                //    spawn (no duplicate Inspector).
+                                // Launches via the daemon-free bin/gina-container, so no
+                                // `gina start` socket server is required. Keep the spawn
+                                // shape in sync with lib/cmd/service/start.js.
+                                if (isDev && projectName !== 'gina') {
+                                    try {
+                                        var _inspProj = projects['gina'];
+                                        // 'src/inspector' mirrors @gina manifest.bundles.inspector.src
+                                        var _inspSrc  = _inspProj ? _(_inspProj.path + '/src/inspector') : null;
+                                        if (_inspProj && _inspSrc && require('fs').existsSync(_inspSrc)) {
+                                            var _inspRun = lib.cmdStatusFormat.readPidfile(getEnvVar('GINA_HOMEDIR') + '/run', 'inspector', 'gina');
+                                            if (!_inspRun.running) {
+                                                var _inspContainer = getEnvVar('GINA_DIR') + '/bin/gina-container';
+                                                if (require('fs').existsSync(_inspContainer)) {
+                                                    var _inspEnv = Object.assign({}, process.env);
+                                                    delete _inspEnv.NODE_ENV;
+                                                    delete _inspEnv.NODE_SCOPE;
+                                                    delete _inspEnv.NODE_PORT;
+                                                    delete _inspEnv.NODE_BUNDLE;
+                                                    delete _inspEnv.NODE_PROJECT;
+                                                    var _inspChild = require('child_process').spawn(
+                                                        process.execPath,
+                                                        [_inspContainer, 'inspector', '@gina'],
+                                                        { detached: true, stdio: 'ignore', env: _inspEnv }
+                                                    );
+                                                    _inspChild.unref();
+                                                    console.debug('[inspector-autostart] started inspector@gina (pid ' + ((_inspChild && _inspChild.pid) || '?') + ')');
+                                                }
+                                            }
+                                        }
+                                    } catch (inspAutoErr) {
+                                        console.warn('[inspector-autostart] skipped: ' + (inspAutoErr.message || inspAutoErr));
+                                    }
+                                }
+
                                 // #AI6 — initialise the async-job primitive. Always-on (unlike
                                 // metrics): self.startJob() / lib.job.create() must work out of the
                                 // box, so this is NOT gated on an `enabled` flag. The app.json `jobs`

package/framework/{v0.4.2 → v0.4.3}/core/plugins/lib/validator/src/main.js

@@ -573,9 +573,43 @@ function ValidatorPlugin(rules, data, formId) {
         }
     }
 
+    /**
+     * #A11Y1 (slice 4) — lazily create one visually-hidden aria-live="polite" status region per
+     * form and announce a blur-time committed error through it. A CSS :user-invalid display toggle
+     * is not reliably announced by screen readers, and on blur the field has lost focus so its own
+     * aria-invalid / aria-errormessage are not re-read; the polite region decouples the announcement
+     * from visual display. Submit-time errors use focus (see onValidate), not this region.
+     * @param {object} $form - the HTMLFormElement the region belongs to
+     * @param {string} text - the error text to announce
+     * @returns {object|null} the live-region element, or null when nothing was announced
+     */
+    var announceA11yError = function($form, text) {
+        if ( !$form || !text ) return null;
+        var _fid    = ( typeof($form.id) != 'undefined' && $form.id ) ? $form.id : ( $form.getAttribute('id') || 'form' );
+        var _liveId = 'gina-aria-live-' + _fid;
+        var _live   = document.getElementById(_liveId);
+        if ( !_live ) {
+            _live = document.createElement('div');
+            _live.id = _liveId;
+            _live.setAttribute('role', 'status');
+            _live.setAttribute('aria-live', 'polite');
+            _live.setAttribute('aria-atomic', 'true');
+            _live.className = 'gina-visually-hidden';
+            _live.style.cssText = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0;';
+            $form.appendChild(_live);
+        }
+        _live.textContent = text;
+        return _live;
+    };
+
     /**
      * handleErrorsDisplay
      * Attention: if you are going to handle errors display by hand, set data to `null` to prevent Toolbar refresh with empty data
+     *
+     * #A11Y1 — besides toggling `form-item-error` / `form-item-warning` and the error-message div,
+     * this reflects each managed field's committed validity into `aria-invalid` ("true" on a
+     * committed error, "false" when valid — mirroring the native ValidityState where the field has
+     * native HTML constraints so it agrees with `:user-invalid`). Soft live-check warnings are not asserted.
      * @param {object} $form - Target (HTMLFormElement)
      * @param {object} errors
      * @param {object|null} data
@@ -706,6 +740,14 @@ function ValidatorPlugin(rules, data, formId) {
 
             if (!name) continue;
 
+            // #A11Y1 (slice 2) — detect a consumer-provided aria-errormessage association. When
+            // present, the field already references its own error element, so we must NOT inject a
+            // competing form-item-error-message div (aria-invalid alone exposes it). Any wire we add
+            // ourselves is marked (data-gina-aria-errormessage) so it is not mistaken for a consumer's.
+            var _ariaErrId         = $el.getAttribute('aria-errormessage');
+            var _ginaOwnsErrMsg    = ( typeof($el.dataset) != 'undefined' && typeof($el.dataset.ginaAriaErrormessage) != 'undefined' ) ? true : false;
+            var _hasConsumerErrMsg = ( _ariaErrId && !_ginaOwnsErrMsg ) ? true : false;
+
             if (
                 errors
                 && typeof(errors[name]) != 'undefined'
@@ -728,6 +770,14 @@ function ValidatorPlugin(rules, data, formId) {
                     $err.className = 'form-item-error-message';
                 }
 
+                // #A11Y1 — reflect a committed invalid state into aria-invalid so any
+                // aria-errormessage association on the field is exposed to assistive tech.
+                // Soft (live-check) warnings while the field is still being edited are not
+                // asserted — only committed errors (blur/submit) are.
+                if ( !isWarning && $el.type != 'hidden' ) {
+                    $el.setAttribute('aria-invalid', 'true');
+                }
+
                 // injecting error messages
                 for (var e in errors[name]) {
 
@@ -746,10 +796,31 @@ function ValidatorPlugin(rules, data, formId) {
                     }
                 }
 
-                if ($target.type != 'hidden')
+                // #A11Y1 (slice 2) — skip the injected message div when the field already references
+                // a consumer-provided error element; otherwise inject it and wire aria-errormessage
+                // to it so assistive tech can resolve the message text.
+                if ($target.type != 'hidden' && !_hasConsumerErrMsg) {
+                    if ( !$el.getAttribute('aria-errormessage') || _ginaOwnsErrMsg ) {
+                        $err.id = ('gina-errormessage-' + (id || 'form') + '-' + (name || 'field')).replace(/[^a-zA-Z0-9_-]+/g, '-');
+                        $el.setAttribute('aria-errormessage', $err.id);
+                        if ( typeof($el.dataset) != 'undefined' ) {
+                            $el.dataset.ginaAriaErrormessage = 'true';
+                        }
+                    }
                     insertAfter($target, $err);
+                }
 
-
+                // #A11Y1 (slice 4) — announce a blur-time committed error through the form's polite
+                // live region (submit-time errors use focus instead). Only on the per-field/blur path
+                // (fieldName set) and only once focus has left the field; soft warnings are skipped.
+                if (
+                    !isWarning
+                    && typeof(fieldName) != 'undefined'
+                    && $err
+                    && $el !== document.activeElement
+                ) {
+                    announceA11yError($form, $err.textContent);
+                }
 
             } else if (
                 errors
@@ -782,6 +853,21 @@ function ValidatorPlugin(rules, data, formId) {
 
                 $parent.className = $parent.className.replace(/(\s+form\-item\-error|form\-item\-error|\s+form\-item\-warning|form\-item\-warning)/, '');
 
+                // #A11Y1 — field is valid per Gina; mirror the native ValidityState (where the
+                // field has native HTML constraints) so aria-invalid never disagrees with the
+                // :user-invalid styling already shown. Explicit "false" is a touched-and-valid signal.
+                if ( $el.type != 'hidden' ) {
+                    var _a11yNativeInvalid = ( $el.willValidate && $el.validity && !$el.validity.valid ) ? true : false;
+                    $el.setAttribute('aria-invalid', _a11yNativeInvalid ? 'true' : 'false');
+                }
+
+                // #A11Y1 (slice 2) — the referenced div was just removed; drop the aria-errormessage
+                // wire we own (a consumer-provided association, lacking our marker, is left intact).
+                if ( typeof($el.dataset) != 'undefined' && typeof($el.dataset.ginaAriaErrormessage) != 'undefined' ) {
+                    $el.removeAttribute('aria-errormessage');
+                    delete $el.dataset.ginaAriaErrormessage;
+                }
+
             } else if (
                 errors.count() > 0
                 && typeof(errors[name]) != 'undefined'
@@ -802,6 +888,11 @@ function ValidatorPlugin(rules, data, formId) {
                         $err = document.createElement('div');
                         $err.setAttribute('class', 'form-item-error-message');
 
+                        // #A11Y1 (slice 2) — preserve the aria-errormessage wire we own across refresh.
+                        if ( _ginaOwnsErrMsg && _ariaErrId ) {
+                            $err.id = _ariaErrId;
+                        }
+
                         // Fixed on 2025-03-09: className cleanup
                         if (
                             !isWarning
@@ -834,9 +925,14 @@ function ValidatorPlugin(rules, data, formId) {
                     }
                 }
 
-                if ($err && $target.type != 'hidden') {
+                if ($err && $target.type != 'hidden' && !_hasConsumerErrMsg) {
                     insertAfter($target, $err);
                 }
+
+                // #A11Y1 — the committed error persists on refresh; keep aria-invalid asserted.
+                if ( !isWarning && $el.type != 'hidden' ) {
+                    $el.setAttribute('aria-invalid', 'true');
+                }
             }
 
             if (
@@ -6001,6 +6097,28 @@ function ValidatorPlugin(rules, data, formId) {
                     } else if ($form) { // just in case the form is being destroyed
                         $form.send(result['data']);
                     }
+                } else {
+                    // #A11Y1 (slice 3) — failed submit: move focus to the first invalid field so
+                    // assistive tech announces it (accessible name + aria-invalid + the
+                    // aria-errormessage text). DOM order; hidden / unfocusable fields are skipped.
+                    var _a11yErrs = result['fields'] || result['error'];
+                    if ( _a11yErrs ) {
+                        var $a11yForm = event['target'];
+                        for (var _ai = 0, _aLen = $a11yForm.length; _ai < _aLen; ++_ai) {
+                            var _aField = $a11yForm[_ai];
+                            var _aName  = _aField.getAttribute('name');
+                            if (
+                                _aName
+                                && typeof(_a11yErrs[_aName]) != 'undefined'
+                                && ( typeof(_a11yErrs[_aName].count) != 'function' || _a11yErrs[_aName].count() > 0 )
+                                && _aField.type != 'hidden'
+                                && typeof(_aField.focus) == 'function'
+                            ) {
+                                _aField.focus();
+                                break;
+                            }
+                        }
+                    }
                 }
             })
         }
@@ -6168,14 +6286,15 @@ function ValidatorPlugin(rules, data, formId) {
                 isSubmitType        = $submit.getAttribute('data-gina-form-submit');
 
                 if ( !onclickAttribute && !isSubmitType) {
-                    $submit.setAttribute('onclick', 'return false;')
-                } else if ( !/return false/i.test(onclickAttribute) && !isSubmitType) {
-                    if ( /\;$/.test(onclickAttribute) ) {
-                        onclickAttribute += 'return false;'
-                    } else {
-                        onclickAttribute += '; return false;'
-                    }
+                    // [CSP] Suppress the default action via a click listener instead of an inline
+                    // onclick="return false;" attribute (tripped CSP script-src-attr under nonce
+                    // policies). A preventDefault-only listener sets event.defaultPrevented exactly
+                    // as the inline handler did, so the form-level clickProxyHandler's
+                    // `if (event.defaultPrevented) return` guard still short-circuits identically.
+                    addListener(gina, $submit, 'click', function(e) { e.preventDefault(); });
                 }
+                // (an existing onclick is left untouched, as before; the dead else-if append
+                //  branch — it only mutated a local, never written back — was removed.)
             }
 
             if (!$submit['id']) {

package/framework/{v0.4.2 → v0.4.3}/core/server.isaac.js

@@ -1900,6 +1900,9 @@ function ServerEngineClass(options) {
         });
 
         server.on('upgrade', function(req, socket, head){
+            // #INS8 — defer /_gina/agent upgrades to the WebSocket agent handler
+            // attached in server.js; engine.io owns only its own upgrade path.
+            if (/\/_gina\/agent(?:\?|$)/.test(req.url || '')) { return; }
             console.debug('[IO SERVER ] upgrading socket #'+ this.id);
             ioServer.handleUpgrade(req, socket, head);
         });

package/framework/{v0.4.2 → v0.4.3}/core/server.js

@@ -146,6 +146,152 @@ function _instrumentKeyValid(req) {
     try { return crypto.timingSafeEqual(a, b); } catch (e) { return false; }
 }
 
+/**
+ * #INS8 — Attach the authenticated WebSocket transport for `/_gina/agent` to
+ * the raw HTTP server. The standalone Inspector (services/src/inspector on
+ * :4101) can connect over a WebSocket as an alternative to the SSE channel —
+ * same data + log frames, same #INS9b auth — but over a single bidirectional
+ * socket, the substrate for future bidirectional commands (#INS11 multi-bundle
+ * dashboard, #INS12 browser extension).
+ *
+ * Engine-agnostic by design: `rawServer` is the value returned by
+ * `self.instance.listen()`, and server.js owns the single `listen()` call for
+ * BOTH engines (the isaac instance IS the raw server; express's `app.listen()`
+ * returns it), so one `upgrade` listener here covers both. There is deliberately
+ * NO isaac-specific mirror — the isaac engine.io upgrade handler defers to this
+ * one via a `/_gina/agent` skip-guard (see server.isaac.js).
+ *
+ * Auth parity with the SSE endpoint: dev stays open + keyless; outside dev the
+ * upgrade requires a valid key (`x-gina-inspector-key` header or `?key=` query
+ * param) via the shared {@link _agentKeyValid}, fail-closed. When an Origin
+ * allowlist is configured (`process.gina._inspectorAgentAllowedOrigins`), the
+ * upgrade `Origin` must be in it; unconfigured ⇒ allow (parity with the SSE
+ * endpoint's `access-control-allow-origin: *`; cross-origin is the norm here,
+ * Inspector on :4101 → target on another port). Denials are written as a raw
+ * HTTP status line on the upgrade socket (no `ServerResponse` exists yet), then
+ * the socket is destroyed.
+ *
+ * Snapshot replay + capture egress mirror the SSE handler: the last snapshot is
+ * only sent in dev OR during an active instrumentation window (#INS10), never a
+ * post-window snapshot to a late authenticated client.
+ *
+ * Fail-graceful: if the `ws` module cannot be loaded the attach is skipped with
+ * a warning and SSE remains the transport — the WebSocket is an enhancement,
+ * not a hard dependency of the inspector channel.
+ *
+ * @inner
+ * @param {http.Server|https.Server|http2.Http2Server} rawServer - the raw server returned by listen()
+ * @param {object} ctx - the Server instance (provides `ctx.instance._lastGinaData`, `ctx.appName`, `ctx.env`)
+ * @returns {void}
+ * @example
+ * // Browser (standalone Inspector), non-dev target with a configured key:
+ * //   new WebSocket('ws://host:port/_gina/agent?key=' + encodeURIComponent(key))
+ * // Frames: {"event":"data","data":{...}} and {"event":"log","data":{t,l,b,s,src}}
+ */
+function attachInspectorAgentWs(rawServer, ctx) {
+    if (!rawServer || typeof rawServer.on !== 'function') { return; }
+    var WebSocketServer;
+    try {
+        var _wsMod = require('ws');
+        WebSocketServer = _wsMod.WebSocketServer || _wsMod.Server;
+    } catch (wsErr) {
+        console.warn('[inspector-agent] WebSocket transport disabled — ws module unavailable: ' + (wsErr.message || wsErr));
+        return;
+    }
+    if (typeof WebSocketServer !== 'function') { return; }
+
+    var _wss     = new WebSocketServer({ noServer: true });
+    var _agAnsiRe = /\x1B\[\d+m/g;
+
+    rawServer.on('upgrade', function(req, socket, head) {
+        // Only handle the agent WS path; leave every other upgrade (e.g.
+        // engine.io in ioServer-attach mode) for its own listener.
+        if (!/\/_gina\/agent(?:\?|$)/.test(req.url || '')) { return; }
+
+        var _agIsDev = (process.env.NODE_ENV_IS_DEV && process.env.NODE_ENV_IS_DEV.toLowerCase() === 'true');
+
+        // Gate: dev OR explicitly enabled outside dev — otherwise the endpoint
+        // does not exist (404), matching the SSE handler's opt-in invisibility.
+        if (!_agIsDev && !(process.gina && process.gina._inspectorAgentEnabled)) {
+            try { socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n'); } catch (e) {}
+            try { socket.destroy(); } catch (e) {}
+            return;
+        }
+
+        // #INS9b auth — outside dev a valid key is required (header or ?key=).
+        if (!_agIsDev && !_agentKeyValid(req)) {
+            try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n'); } catch (e) {}
+            try { socket.destroy(); } catch (e) {}
+            return;
+        }
+
+        // Optional Origin allowlist — enforced only when configured (parity with
+        // the SSE endpoint, open by default). The operator lists the Inspector
+        // origin(s) for production use.
+        var _allowed = (process.gina && Array.isArray(process.gina._inspectorAgentAllowedOrigins))
+            ? process.gina._inspectorAgentAllowedOrigins : [];
+        if (_allowed.length > 0) {
+            var _origin = (req.headers && req.headers.origin) || '';
+            if (_allowed.indexOf(_origin) < 0) {
+                try { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); } catch (e) {}
+                try { socket.destroy(); } catch (e) {}
+                return;
+            }
+        }
+
+        _wss.handleUpgrade(req, socket, head, function(ws) {
+            if (!process.gina._inspectorActive) { process.gina._inspectorActive = true; }
+
+            // Initial snapshot — dev OR an active instrumentation window only,
+            // never a post-window snapshot to a late authenticated client (#INS10).
+            try {
+                if ((_agIsDev || (lib.instrument && lib.instrument.isActive())) && ctx.instance && ctx.instance._lastGinaData) {
+                    ws.send(JSON.stringify({ event: 'data', data: ctx.instance._lastGinaData }));
+                } else {
+                    var _initEnv = { bundle: ctx.appName || '', env: ctx.env || '' };
+                    ws.send(JSON.stringify({ event: 'data', data: { gina: { environment: _initEnv }, user: { environment: _initEnv } } }));
+                }
+            } catch (e) {}
+
+            // Data updates — emitted by the render delegates on every render.
+            var _wsDataListener = function(payload) {
+                try { ws.send(JSON.stringify({ event: 'data', data: payload })); } catch (e) {}
+            };
+            // Log entries — same source + frame shape as the SSE endpoint.
+            var _wsLogListener = function(payload) {
+                try {
+                    var entry = JSON.parse(payload);
+                    var level = entry.level === 'catch' ? 'log' : (entry.level || 'log');
+                    var msg   = (entry.content || '').replace(_agAnsiRe, '').replace(/\n$/, '');
+                    if (!msg) { return; }
+                    ws.send(JSON.stringify({ event: 'log', data: { t: Date.now(), l: level, b: entry.group || '', s: msg, src: 'server' } }));
+                } catch (e) {}
+            };
+
+            process.on('inspector#data', _wsDataListener);
+            process.on('logger#default', _wsLogListener);
+
+            var _cleanup = function() {
+                process.removeListener('inspector#data', _wsDataListener);
+                process.removeListener('logger#default', _wsLogListener);
+            };
+            ws.on('close', _cleanup);
+            ws.on('error', _cleanup);
+
+            // Inbound frames are reserved for future bidirectional commands
+            // (#INS11/#INS12). For now, answer only a lightweight heartbeat.
+            ws.on('message', function(raw) {
+                try {
+                    var m = JSON.parse(raw.toString());
+                    if (m && m.type === 'ping') { ws.send(JSON.stringify({ event: 'pong', data: Date.now() })); }
+                } catch (e) {}
+            });
+
+            try { console.info((req.method || 'GET') + ' [101] ' + req.url + ' (WS agent)'); } catch (e) {}
+        });
+    });
+}
+
 /**
  * Read a small JSON request body for the POST /_gina/instrument control
  * endpoint (#INS10). Bounded at 4 KB — the control body is tiny
@@ -3378,6 +3524,11 @@ function Server(options) {
         var _rawServer = self.instance.listen(self.conf[self.appName][self.env].server.port);
         process.server = (_rawServer && typeof _rawServer.close === 'function') ? _rawServer : self.instance;
 
+        // #INS8 — attach the authenticated WebSocket transport for /_gina/agent
+        // to the raw server. Covers both the isaac and express engines (server.js
+        // owns the single listen() call), so no engine-specific mirror is needed.
+        attachInspectorAgentWs(process.server, self);
+
         self.emit('started', self.conf[self.appName][self.env], true);
     }
 

package/framework/{v0.4.2 → v0.4.3}/core/template/conf/settings.json

@@ -145,10 +145,14 @@
   //             process.env at config-load time). Example:
   //             "key": "${secret:INSPECTOR_AGENT_KEY}". When enabled is true
   //             but key is empty, the endpoint stays closed (fail-closed).
+  //   allowedOrigins — #INS8: when non-empty, a WebSocket /_gina/agent upgrade
+  //             is accepted only if its Origin header is in this list. Empty ⇒
+  //             allow any origin (the SSE channel is open by CORS * regardless).
   "inspector": {
     "agent": {
       "enabled": false,
-      "key": ""
+      "key": "",
+      "allowedOrigins": []
     },
     // #INS10 — time-boxed instrumentation window. Lets the Inspector's query +
     // flow capture run OUTSIDE dev mode for a bounded period, without enabling

package/framework/{v0.4.2 → v0.4.3}/lib/cmd/service/help.txt

@@ -3,6 +3,10 @@
 
   Actions:
 
+    start <service> [@gina]      Start a framework-internal service (a bundle of
+                                 the @gina project, e.g. `inspector`) via the
+                                 daemon-free gina-container launcher. No-op when
+                                 the service is already running.
     list [@gina]                 List framework-internal services registered
                                  under @gina, with ports and running state.
     help                         Show this message.
@@ -11,6 +15,8 @@
 
     --format=json                Emit machine-readable JSON instead of the
                                  human-readable text table.
+    --dry-run                    (service:start) Print the launch command that
+                                 would run, without spawning anything.
 
   Notes:
 
@@ -22,8 +28,16 @@
     with `process.kill(pid, 0)` — a stale pidfile (process gone) reports
     the service as stopped.
 
+    `service:start` spawns the service detached via bin/gina-container, so it
+    does not need the `gina start` socket daemon. The service runs in @gina's
+    own dev/local defaults; use `bundle:start` for explicit env/scope control.
+    Stop a service with `bundle:stop <service> @gina`.
+
   Examples:
 
+    gina service:start inspector Start the Inspector standalone bundle (dev)
+    gina service:start inspector --dry-run
+                                 Show the launch command without spawning
     gina service:list            List all services with ports + running state
     gina service:list @gina      Same (explicit @gina)
     gina service:list --format=json