gina 0.7.2 → 0.7.3

package/framework/{v0.7.2 → v0.7.3}/core/server.js

@@ -3095,6 +3095,56 @@ function Server(options) {
             }).finish().body.read().decodeToString();
     }
 
+    /**
+     * #B766 — whether a stylesheet `<link>` or a `<script src>` written in a
+     * layout may be preloaded through the `link` header (`as=style` /
+     * `as=script`). A preload the browser cannot match to the tag's own request
+     * costs a second download, so the tag is left out when it carries
+     * `integrity` or `crossorigin` (the preload would carry neither), is a
+     * module or `nomodule` script, or is a stylesheet not applied to the screen
+     * (a `media` other than `all` / `screen`, an `alternate` one). The tests
+     * read the tag's own text: up to its first `>` outside a quoted attribute
+     * value, since a value may hold one (`media="(width > 600px)"`).
+     *
+     * One more condition, a guard for a caller that passes more than one tag:
+     * until #B768, getAssets()' layout scan matched up to the end of a source
+     * line and kept the LAST `src` / `href` it found there, so when several tags
+     * shared a line the URL could be another tag's; it now passes one start tag.
+     * The tag only qualifies when nothing after its `>` carries a `src`, `href`
+     * or `srcset`.
+     *
+     * @inner
+     * @private
+     * @param {string} match - One match of getAssets()' layout scan
+     * @param {string|null} rel - The `rel` value of a `<link>`, `null` for a `<script>`
+     * @returns {boolean}
+     *
+     * @example
+     * isPreloadableLayoutTag('<link rel="stylesheet" href="/css/app.css">', 'stylesheet');                // true
+     * isPreloadableLayoutTag('<link rel="stylesheet" href="/css/print.css" media="print">', 'stylesheet'); // false
+     */
+    var isPreloadableLayoutTag = function(match, rel) {
+        var tagEnd = match.match(/^<[^>"']*(?:(?:"[^"]*"|'[^']*')[^>"']*)*>/);
+        if ( !tagEnd ) {
+            return false;
+        }
+        var tag = tagEnd[0];
+        if ( /(src|href|srcset)\=/.test(match.substring(tag.length)) ) {
+            return false;
+        }
+        if ( /\s(integrity|crossorigin|nomodule)(\s|=|>|\/)/i.test(tag) || /\stype\s*=\s*["']?module\b/i.test(tag) ) {
+            return false;
+        }
+        if ( rel && /\balternate\b/i.test(rel) ) {
+            return false;
+        }
+        var media = tag.match(/\smedia\s*=\s*["']([^"']*)["']/i);
+        if ( media && !/^\s*(all|screen)\s*$/i.test(media[1]) ) {
+            return false;
+        }
+        return true;
+    };
+
     /**
      * Parses a rendered layout string for `<link>`, `<script>`, `<source>`,
      * and `<img>` tags, resolves each asset URL to an absolute file path, and
@@ -3107,14 +3157,69 @@ function Server(options) {
      * @param {object} bundleConf - Bundle/env configuration slice
      * @param {string} layoutStr - Rendered HTML layout string to scan for asset tags
      * @param {object} [swig] - Swig instance when called from the controller
-     * @param {object} [data] - Template data when called from the controller
+     * @param {object} [data] - Template data when called from the controller; its
+     *   `page.environment.webroot` (the public webroot) is stripped, like
+     *   `bundleConf.server.webroot`, from a URL before it is resolved (#B769)
      * @returns {object} Assets map keyed by URL
      */
     var getAssets = function (bundleConf, layoutStr, swig, data) {
 
         // layout search for <link|source|script|img>; this is an asset-tag scan over the bundle's own
-        // layout template, not an HTML sanitizer
-        var layoutAssets        = layoutStr.match(/<link .*?<\/link>|<link .*?(rel\=\"(stylesheet|icon|manifest|(.*)\-icon))(.*)|<source .*?(type\=\"(image))(.*)|<script.*?<\/script>|<img .*?(.*)/g) || [];
+        // layout template, not an HTML sanitizer.
+        // #B768 — one match per TAG. Each alternative used to run to the end of its source line,
+        // and the URL loop below kept the last `src` / `href` it met, so tags sharing a line were
+        // read as one: `<img><script>` preloaded the script `as=image`, a <picture>'s <img> was
+        // swallowed by its <source>, a minified layout got no hint. A start tag now ends at its
+        // first `>` outside a quoted attribute value (isPreloadableLayoutTag's rule); a <script>
+        // element is consumed whole and only its start tag kept, so the text of an inline script
+        // is never read as markup; `</picture>` is kept as the marker that ends the srcset a
+        // picture's <source> tags collected. Which tags count is unchanged (filtered below): a
+        // <link> whose rel starts with stylesheet, icon or manifest or ends in -icon, a <source>
+        // whose type is an image type, every <script> and <img>.
+        var layoutAssets        = []
+            , layoutTagRe       = /(<script\b(?:[^>"']|"[^"]*"|'[^']*')*>)[\s\S]*?<\/script\s*>|<(?:link|source|img)\b(?:[^>"']|"[^"]*"|'[^']*')*>|<\/picture\s*>/g
+            , layoutTag         = null
+        ;
+        while ( (layoutTag = layoutTagRe.exec(layoutStr)) !== null ) {
+            layoutAssets.push( layoutTag[1] || layoutTag[0] );
+        }
+
+        /**
+         * #B769 — the path to hand getAssetFilenameFromUrl() for a URL written in the layout
+         * or in a stylesheet's url(). The resolver takes a path WITHOUT the webroot
+         * (handleStatics strips it from a request first), while a layout writes its URLs with
+         * it: `{{ page.environment.webroot }}img/x.png` reaches this scan as `/web/img/x.png`,
+         * or as `/proxy/web/img/x.png` behind a path-prefixing proxy, and resolved to
+         * '404.html', so the asset got no hint. Strips the public webroot, else the bundle's
+         * own, once, when the URL starts with it, ending `/` included (`/webx/` is never
+         * stripped by `/web/`). The entry keeps the URL as written.
+         *
+         * @inner
+         * @private
+         * @param {string} u - An asset URL as written
+         * @returns {string} The URL without its webroot, or `u` unchanged
+         *
+         * @example
+         * // server.webroot '/web/', no proxy prefix
+         * withoutWebroot('/web/img/x.png');  // '/img/x.png'
+         * withoutWebroot('/webx/img/x.png'); // '/webx/img/x.png'
+         */
+        var withoutWebroot = function (u) {
+            var roots = [
+                ( data && data.page && data.page.environment ) ? data.page.environment.webroot : null,
+                bundleConf.server.webroot
+            ];
+            for (var r = 0; r < roots.length; ++r) {
+                if ( typeof(roots[r]) != 'string' || roots[r].length < 2 ) {
+                    continue;
+                }
+                var root = roots[r].replace(/\/*$/, '/');
+                if ( u.indexOf(root) === 0 ) {
+                    return '/' + u.substring(root.length);
+                }
+            }
+            return u;
+        };
 
         var assets      = {}
             , cssFiles  = []
@@ -3144,6 +3249,13 @@ function Server(options) {
         ;
         for (; i < len; ++i) {
 
+            // #B768 — a picture ends here: the srcset its <source> tags collected no longer
+            // waits for an <img>
+            if ( /^<\/picture/.test(layoutAssets[i]) ) {
+                sourceTagSrcSetStr = '';
+                continue;
+            }
+
             if (
                 !/(\<img|\<link|\<source|\<script)/g.test(layoutAssets[i])
                 // ||
@@ -3155,10 +3267,26 @@ function Server(options) {
                 continue;
             }
 
+            // #B768 — the tag's kind, from its own name: the kind tests used to run on the whole
+            // match, so with several tags in it the last test that matched won
+            let tagName = layoutAssets[i].match(/^<([a-z]+)/)[1];
+            // only the tags the former alternatives took
+            if (
+                tagName == 'link' && !/rel\=\"(stylesheet|icon|manifest|[^"]*\-icon)/.test(layoutAssets[i])
+                || tagName == 'source' && !/type\=\"image/.test(layoutAssets[i])
+            ) {
+                continue;
+            }
+            // #B775 — nothing carried over from the previous tag: `url` and `ext` were kept, so a
+            // tag with no src / href reused the previous URL (the first such tag threw, and the
+            // page answered 500) and a missing asset showed the previous asset's extension
+            url = null;
+            ext = null;
+
             // https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload
             let asType = null;
 
-            if ( /\<img/.test(layoutAssets[i]) ) {
+            if ( tagName == 'img' ) {
                 type    = 'image';
                 tag     = 'img';
                 asType  = type;
@@ -3166,7 +3294,7 @@ function Server(options) {
 
 
 
-            if ( /\<link/.test(layoutAssets[i]) ) {
+            if ( tagName == 'link' ) {
                 // if ( /rel\=\"stylesheet/.test(layoutAssets[i]) ) {
                 //     type    = 'stylesheet';
                 // } else if ( /rel\=\"(icon|(.*)\-icon)/.test(layoutAssets[i]) ) {
@@ -3180,7 +3308,10 @@ function Server(options) {
                 }
 
 
-                switch (type) {
+                // #B766 — this switch used to test `type`, the rel STRING, against the
+                // BOOLEAN results of its case tests, so no case ever matched and a
+                // layout stylesheet never got an `as`
+                switch (true) {
                     case /stylesheet/.test(type):
                         asType  = 'style';
                         break;
@@ -3204,11 +3335,15 @@ function Server(options) {
                         // }
                         break;
                 }
+                // #B766 — no preload the browser could not match to the tag
+                if ( ( asType == 'style' || asType == 'script' ) && !isPreloadableLayoutTag(layoutAssets[i], type) ) {
+                    asType  = null;
+                }
 
                 tag     = 'link';
             }
 
-            if ( /\<source/.test(layoutAssets[i]) ) {
+            if ( tagName == 'source' ) {
                 if ( /type\=\"image/.test(layoutAssets[i]) ) {
                     type    = 'image';
                 }
@@ -3216,13 +3351,17 @@ function Server(options) {
                 tag     = 'source';
             }
 
-            if ( /\<script/.test(layoutAssets[i]) ) {
+            if ( tagName == 'script' ) {
                 type    = 'javascript';
                 tag     = 'script';
                 // Skip inline scripts (no src attribute) — not external assets
                 if ( !/\ssrc\s*=/.test(layoutAssets[i]) ) {
                     continue;
                 }
+                // #B766 — a layout script is preloaded too (it never got an `as`)
+                if ( isPreloadableLayoutTag(layoutAssets[i], null) ) {
+                    asType  = 'script';
+                }
             }
 
             domain  = null;
@@ -3267,6 +3406,12 @@ function Server(options) {
                 continue;
             }
 
+            // #B775 — a tag with no `src` / `href` (an <img> with only a srcset) names no file
+            // to preload; first in a layout, it threw at the quote strip below
+            if ( !url ) {
+                continue;
+            }
+
 
             // if ( /data\:/.test(url) ) { // ignoring "data:..."
             //     continue
@@ -3291,7 +3436,7 @@ function Server(options) {
             }
 
             if (!/(\:\/\/|^\/\/)/.test(url) ) {
-                filename = getAssetFilenameFromUrl(bundleConf, url);
+                filename = getAssetFilenameFromUrl(bundleConf, withoutWebroot(url));
             } else {
                 domain      = url.match(/^.*:\/\/[a-z0-9._-]+\/?/);
                 //url         = ( new RegExp('/'+ bundleConf.host +'/' ).test(domain) ) ? url.replace(domain, '/') : url;
@@ -3305,7 +3450,9 @@ function Server(options) {
             }
             //key =  (( /404/.test(filename) ) ? '[404]' : '[200]') +' '+ url;
             key         = url;
-            isAvailable =  ( /404/.test(filename) ) ? false : true;
+            // #B777 — a miss is the resolver's own '404.html'; `/404/` anywhere in the path also
+            // took a bundle under a directory holding `404`, or a file like `error-404.png`, for one
+            isAvailable =  ( filename == '404.html' ) ? false : true;
             if ( isAvailable ) {
                 try {
                     ext         = url.substring(url.lastIndexOf('.')).match(/(\.[A-Za-z0-9]+)/)[0];
@@ -3323,12 +3470,12 @@ function Server(options) {
                 url         : url,
                 ext         : ext,
                 mime        : (!ext) ? 'NA' : (bundleConf.server.coreConfiguration.mime[ext.substring(1)] || 'NA'),
-                filename    : ( /404/.test(filename) ) ? 'not found' : filename,
+                filename    : ( filename == '404.html' ) ? 'not found' : filename,
                 isAvailable : isAvailable
             };
 
-            //sourceTagSrcSetStr
-            if (sourceTagSrcSetStr.length > 0) {
+            //sourceTagSrcSetStr — #B768: for the picture's <img> only, never another asset
+            if ( sourceTagSrcSetStr.length > 0 && tagName == 'img' ) {
                 assets[key]['imagesrcset'] = sourceTagSrcSetStr.substring(0, sourceTagSrcSetStr.length-1);
                 // reset
                 sourceTagSrcSetStr = '';
@@ -3444,7 +3591,13 @@ function Server(options) {
 
                     if ( /(url\(|url\s+\()/.test(cssArr[c]) && !/data\:|\@font-face/.test(cssArr[c]) ) {
 
-                        url = cssArr[c].match(/((background\:url|url)+\()([A-Za-z0-9->~_.,:"'%/\s+]+).*?\)+/g)[0].replace(/((background\:url|url)+\(|\))/g, '').trim();
+                        // #B774 — a `url()` this pattern cannot read (an SVG reference such as
+                        // `url(#grad)`), or one naming a fragment, is not a file: skip the block. The
+                        // unguarded `[0]` threw, and render-swig answered 500 for the page.
+                        let urlMatched = cssArr[c].match(/((background\:url|url)+\()([A-Za-z0-9->~_.,:"'%/\s+]+).*?\)+/g);
+                        if ( !urlMatched ) continue;
+                        url = urlMatched[0].replace(/((background\:url|url)+\(|\))/g, '').trim();
+                        if ( /^["']?#/.test(url) ) continue;
                         if ( typeof(assetsInClassFound[url]) != 'undefined') continue; // already defined
 
                         //cssMatched = cssArr[c].match(/((\.[A-Za-z0-9-_.,;:"'%\s+]+)(\s+\{|{))/);
@@ -3469,7 +3622,7 @@ function Server(options) {
                                 //     url: url
                                 // }
                                 if (!/(\:\/\/|^\/\/)/.test(url) ) {
-                                    filename = getAssetFilenameFromUrl(bundleConf, url);
+                                    filename = getAssetFilenameFromUrl(bundleConf, withoutWebroot(url));
                                 } else {
                                     domain      = url.match(/^.*:\/\/[a-z0-9._-]+\/?/);
                                     url         = url.replace(domain, '/');
@@ -3478,16 +3631,25 @@ function Server(options) {
 
                                 //key =  (( /404/.test(filename) ) ? '[404]' : '[200]') +' '+ url;
                                 key         = url;
-                                isAvailable =  ( /404/.test(filename) ) ? false : true;
-                                ext         = url.substring(url.lastIndexOf('.')).match(/(\.[A-Za-z0-9]+)/)[0];
+                                // #B776 — the layout scan's entry for the same URL stays: it carries the
+                                // `as` the 200's link header needs, a CSS entry carries none (the
+                                // layout image lost its hint)
+                                if ( typeof(assets[key]) != 'undefined' ) {
+                                    break;
+                                }
+                                isAvailable =  ( filename == '404.html' ) ? false : true; // #B777
+                                // #B774 — a `url()` with no extension (`url(/img/sprite)`) threw here;
+                                // the layout scan reads its own `ext` inside a try
+                                let extMatched = url.substring(url.lastIndexOf('.')).match(/(\.[A-Za-z0-9]+)/);
+                                ext         = ( extMatched ) ? extMatched[0] : null;
                                 assets[key] = {
                                     referrer    : cssFiles[i],
                                     definition  : definition,
                                     type        : type,
                                     url         : url,
                                     ext         : ext,
-                                    mime        : bundleConf.server.coreConfiguration.mime[ext.substring(1)] || 'NA',
-                                    filename    : ( /404/.test(filename) ) ? 'not found' : filename
+                                    mime        : ( ext ) ? ( bundleConf.server.coreConfiguration.mime[ext.substring(1)] || 'NA' ) : 'NA',
+                                    filename    : ( filename == '404.html' ) ? 'not found' : filename
                                 };
 
                                 if (domain)

package/framework/{v0.7.2 → v0.7.3}/core/template/conf/templates.json

@@ -9,7 +9,6 @@
     "forms"                     : "${bundlePath}/forms",
     "handlers"                  : "${templatesPath}/handlers",
     "routeNameAsFilenameEnabled": true,
-    "ginaEnabled"               : true, // set to false, this will exclude gina assets from being loaded
     "pluginLoader"              : "{src:${gina}/framework/v${version}/core/asset/plugin/dist/vendor/gina/js/gina.onload.min.js}",
     "http-metas": {
       "content-type": "text/html"
@@ -28,6 +27,8 @@
     "javascriptsDeferEnabled": true, // will place scripts in defer mode in the head by default. If false, will place in the footer
     "sriEnabled": false, // opt-in Subresource Integrity: adds integrity= + crossorigin= to same-origin <script>/<link> tags whose files resolve on disk; external URLs and unresolvable paths are skipped (fail-open)
     "assetVersioningEnabled": true, // #P48: appends ?v=<10 hex of the file's sha384> to the same-origin asset URLs gina emits (tags + their preload hints) so they can be cached for a year; false keeps today's URLs. Never applied to js external plugins, layoutless renders or dev (fail-open: an unresolvable file keeps its plain URL)
+    "preloadHintsEnabled": true, // #B765: the automatic preload hints of an http/2.0 bundle in production, i.e. the `link` header of an HTML page and the 103 Early Hints sent before it; false sends neither (calls to self.setEarlyHints() are not affected)
+    "preloadHintsMaxSize": 1024, // #B765: bytes; each automatic hint stops at the last entry that keeps it within this size, so a reverse proxy's response-header buffer (nginx: 4 KiB by default) is not outgrown; 0 = no cap; a negative or non-integer value falls back to 1024 with one warning
     "javascripts": [
       {
         "name"      : "gina",

package/framework/{v0.7.2 → v0.7.3}/lib/cmd/connector/add.js

@@ -21,7 +21,7 @@ var CmdHelper = require('./../helper');
  *
  * After writing the entry, prints the exact `npm install <driver>@<range>`
  * command to run, using the resolved version range in this order:
- *   1. the entry's `version` field (set via `--version=`)
+ *   1. the entry's `version` field (set via `--driver-version=`)
  *   2. the framework's built-in driver range table (DRIVER_MAP / AI_DRIVER_MAP)
  *
  * Leading header comments at the top of an existing `connectors.json` are

package/framework/{v0.7.2 → v0.7.3}/lib/cmd/connector/help.txt

@@ -83,9 +83,10 @@
                                  install (e.g. ^5.0.0, >=5.3.0 <6.0.0).
                                  Named `--driver-version=` (not `--version=`)
                                  because the framework reserves the bare
-                                 `--version` flag (maps to GINA_VERSION and
-                                 triggers a framework migration). Written to
-                                 the connector entry under the `version` key.
+                                 `--version` flag (maps to GINA_VERSION; a
+                                 value naming no installed framework version
+                                 is refused). Written to the connector entry
+                                 under the `version` key.
     --force                      Overwrite an existing entry with the
                                  same <name>.
     --install                    After writing the entry, run the detected
@@ -215,8 +216,8 @@
 
     After writing, `connector:add` prints the exact
     `npm install <driver>@"<range>"` command. The resolved range comes
-    from `--version=` when supplied, otherwise from the framework's
-    built-in driver range table.
+    from `--driver-version=` when supplied, otherwise from the
+    framework's built-in driver range table.
 
     `connector:rm` writes to the same two targets (shared vs bundle) per
     positional-absence. It never uninstalls the npm driver — another

package/framework/{v0.7.2 → v0.7.3}/lib/cmd/framework/help.txt

@@ -17,7 +17,11 @@ $ gina --status | -t
 $ gina framework:start | start
 
     Start the framework socket server (port 8124) + MQ listener (8125) in the
-    background. Required before any online command (e.g. bundle:start).
+    background. Required before any online command (e.g. bundle:start). Exits 0
+    once the server is ready or already running; if it stops before that, exits
+    with its exit code (1 when that is 0, 128 + the signal number on a signal).
+    Exits 1 when another program holds the framework port, printing how to free
+    the port or move the framework (gina framework:set --port=<port>).
 
 $ gina framework:stop | stop [ @<version> ]
 

package/framework/v0.7.3/lib/cmd/framework/inc/listen-error.js

@@ -0,0 +1,217 @@
+/**
+ * @module gina/lib/cmd/framework/inc/listen-error
+ *
+ * Decides what `gina start` does when the framework's command socket cannot
+ * listen (#B761). `bin/cli` binds the MQ listener, then `bin/cmd` binds the
+ * command socket on the framework port; its `error` handler asks `decide()`.
+ *
+ * When the port is in use, « Framework already running … [ <pid> ] » (the line
+ * the `gina` wrapper exits 0 on) is printed only for a `procs.json` entry whose
+ * pid is alive and a framework daemon, read with `inc/ps-titles.js`
+ * `readPidTitle()`: titled `gina-v<version>` on Node, or, on Bun (which does
+ * not show `process.title`), still running the framework's own start command.
+ * Otherwise, and for any other listen error, the start writes the reason to
+ * stderr and exits 1, which also frees the MQ port the starting process holds.
+ *
+ * Before 0.7.3 the handler trusted any `procs.json` entry for the port without
+ * checking it, returned when there was none, and only logged any other error:
+ * a port held by another program read « already running » with exit 0, a stale
+ * entry named a dead pid, the process never ended (a half-started daemon kept
+ * the MQ port), and an EACCES left `gina start` hanging.
+ */
+var psTitles = require('./ps-titles');
+
+/**
+ * The prefix of every message this module writes.
+ *
+ * @constant
+ * @type {string}
+ */
+var PREFIX = 'gina: cannot start the framework: ';
+
+/**
+ * Lists the pids that `procs.json` records for a port, in the file's order:
+ * each entry of its own whose `port` equals `port` once both are strings, its
+ * `pid` read with `parsePid()` (so `-1`, `0`, `12abc` and `null` are no pid).
+ * A pid recorded twice is listed once.
+ *
+ * @param {?object} procs - The parsed `procs.json`: `{ "<title>": { pid, port, … } }`
+ * @param {number|string} port - The framework port
+ * @returns {Array<number>} The recorded pids; empty when there is none
+ * @example
+ * findRecordedPids({ 'gina-v0.7.2': { pid: 111, port: 8124 }, 'gina-v0.7.3': { pid: 222, port: '8124' } }, 8124);
+ * // [ 111, 222 ]
+ */
+function findRecordedPids(procs, port) {
+    var pids = [];
+    if (!procs || typeof procs !== 'object' || port === null || typeof port === 'undefined' || String(port) === '') {
+        return pids;
+    }
+    Object.keys(procs).forEach(function (key) {
+        var entry = procs[key];
+        if (!entry || typeof entry !== 'object' || String(entry.port) !== String(port)) {
+            return;
+        }
+        var pid = psTitles.parsePid(entry.pid);
+        if (pid !== null && pids.indexOf(pid) < 0) {
+            pids.push(pid);
+        }
+    });
+    return pids;
+}
+
+/**
+ * The first pid that `procs.json` records for a port (see `findRecordedPids()`).
+ *
+ * @param {?object} procs - The parsed `procs.json`
+ * @param {number|string} port - The framework port
+ * @returns {?number} The pid, or `null` when no entry for the port has one
+ * @example
+ * findRecordedPid({ x: { pid: 4321, port: '8124' } }, 8124);  // 4321
+ * findRecordedPid({ x: { pid: '-1', port: 8124 } }, 8124);    // null
+ */
+function findRecordedPid(procs, port) {
+    var pids = findRecordedPids(procs, port);
+    return pids.length > 0 ? pids[0] : null;
+}
+
+/**
+ * Tells what a recorded pid is now. It is `'dead'` when no process has it
+ * (`process.kill(pid, 0)` throws, other than EPERM, which another user's live
+ * process gives) or when it is a zombie; `'framework'` when it is a framework
+ * daemon: titled `gina-v<version>` (`DAEMON_TITLE_RE`, Node), or running the
+ * framework's own start command (`DAEMON_COMMAND_RE`, Bun, which does not
+ * show `process.title`); `'other'` when another program has it. Where the
+ * process cannot be read, the alive check decides, as before 0.7.3: `ps`
+ * cannot tell (no `ps` on Windows, busybox), or `ps` lists nothing for
+ * another user's live process (a `/proc` mounted with `hidepid`).
+ *
+ * @param {number} pid - A pid read with `parsePid()`
+ * @param {{kill: function(number, number), readPidTitle: function(number): (?object|undefined)}} [probe]
+ *   Replaces `process.kill` and `readPidTitle()` (tests)
+ * @returns {string} `'framework'`, `'other'` or `'dead'`
+ * @example
+ * classifyPid(process.pid);  // 'other' — a live process that is not a framework daemon
+ * classifyPid(99999);        // 'dead' — when no process has that pid
+ */
+function classifyPid(pid, probe) {
+    var kill = (probe && probe.kill) ? probe.kill : function (p, signal) { return process.kill(p, signal); };
+    var read = (probe && probe.readPidTitle) ? probe.readPidTitle : psTitles.readPidTitle;
+    var otherUser = false;
+    try {
+        kill(pid, 0);
+    } catch (killErr) {
+        if (!killErr || killErr.code !== 'EPERM') {
+            return 'dead';
+        }
+        otherUser = true;
+    }
+    var seen = read(pid);
+    if (typeof seen === 'undefined') {
+        return 'framework';
+    }
+    if (seen === null) {
+        // our own process is always listed, so it has just exited; another
+        // user's live process can be hidden from `ps`
+        return otherUser ? 'framework' : 'dead';
+    }
+    if (seen.zombie) {
+        return 'dead';
+    }
+    var isDaemon = psTitles.DAEMON_TITLE_RE.test(seen.title || '')
+        || psTitles.DAEMON_COMMAND_RE.test(seen.command || '');
+    return isDaemon ? 'framework' : 'other';
+}
+
+/**
+ * The message for a framework port held by something that is not a running
+ * framework: the cause, the fix, and (not on Windows) how to find the holder.
+ * It never says « address already in use »: the `gina` wrapper exits on those
+ * words at once instead of waiting for the start's exit code.
+ *
+ * @param {number|string} port - The framework port
+ * @param {?{procsFile: string, pid: number, state: string}} recorded - The
+ *   `procs.json` entry for the port, with the `classifyPid()` state of its pid
+ *   (`'dead'` or `'other'`); `null` when there is none
+ * @param {string} platform - `process.platform`
+ * @returns {string} Two or three lines, without a trailing newline
+ * @example
+ * heldPortMessage(8124, null, 'darwin');
+ * // gina: cannot start the framework: port 8124 is held by another program, not a running gina framework.
+ * // Free the port, or move the framework: gina framework:set --port=<port>
+ * // Find the holder: lsof -nP -iTCP:8124 -sTCP:LISTEN
+ */
+function heldPortMessage(port, recorded, platform) {
+    var cause = PREFIX + 'port ' + port + ' is held by another program';
+    if (recorded && recorded.pid) {
+        cause += '; ' + recorded.procsFile + ' names pid ' + recorded.pid + ', which is '
+            + (recorded.state === 'dead' ? 'not running.' : 'not a gina framework.');
+    } else {
+        cause += ', not a running gina framework.';
+    }
+    var lines = [cause, 'Free the port, or move the framework: gina framework:set --port=<port>'];
+    if (platform !== 'win32') {
+        lines.push('Find the holder: lsof -nP -iTCP:' + port + ' -sTCP:LISTEN');
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Decides what the command socket's `error` handler does when the socket
+ * cannot listen. Only an EADDRINUSE under `framework:start` looks at
+ * `procs.json`: when a pid recorded for the port is a running framework, the
+ * start reports it as already running; otherwise it exits 1 with
+ * `heldPortMessage()`. Any other error exits 1 with its own message, on one
+ * line.
+ *
+ * @param {Error} err - The listen error (`code`, `port`, `message`)
+ * @param {object} ctx
+ * @param {string} ctx.command - The command being run (`process.argv[2]`)
+ * @param {number|string} ctx.port - The framework port
+ * @param {string} ctx.procsFile - The path of `procs.json`, named in the message
+ * @param {?object} ctx.procs - The parsed `procs.json`; `null` when it is
+ *   missing or does not parse
+ * @param {string} [ctx.platform] - Defaults to `process.platform`
+ * @param {function(number): string} [ctx.classifyPid] - Defaults to `classifyPid()` (tests)
+ * @returns {{action: string, pid: number, port: (number|string)}|{action: string, code: number, message: string}}
+ *   `{ action: 'already-running', pid, port }` or `{ action: 'exit', code: 1, message }`
+ * @example
+ * var decision = decide(err, { command: 'framework:start', port: 8124, procsFile: procsFile, procs: procs });
+ * if (decision.action === 'already-running') {
+ *     console.warn('Framework already running on port `'+ decision.port +'`: [ '+ decision.pid +' ]');
+ * } else {
+ *     fs.writeSync(2, decision.message + '\n');
+ *     process.exit(decision.code);
+ * }
+ */
+function decide(err, ctx) {
+    ctx = ctx || {};
+    var platform = ctx.platform || process.platform;
+
+    if (err && err.code === 'EADDRINUSE' && ctx.command === 'framework:start') {
+        var classify = ctx.classifyPid || classifyPid;
+        var pids     = findRecordedPids(ctx.procs, ctx.port);
+        var recorded = null;
+        for (var i = 0; i < pids.length; i++) {
+            var state = classify(pids[i]);
+            if (state === 'framework') {
+                return { action: 'already-running', pid: pids[i], port: ctx.port };
+            }
+            if (!recorded) {
+                recorded = { procsFile: ctx.procsFile, pid: pids[i], state: state };
+            }
+        }
+        return { action: 'exit', code: 1, message: heldPortMessage(ctx.port, recorded, platform) };
+    }
+
+    var reason = (err && err.message) ? String(err.message) : String(err);
+    return { action: 'exit', code: 1, message: PREFIX + reason.split(/\r?\n/)[0] };
+}
+
+module.exports = {
+    findRecordedPids : findRecordedPids,
+    findRecordedPid  : findRecordedPid,
+    classifyPid      : classifyPid,
+    heldPortMessage  : heldPortMessage,
+    decide           : decide
+};