gina 0.6.6 → 0.6.7

package/framework/{v0.6.6 → v0.6.7}/core/server.js

@@ -4471,6 +4471,192 @@ function Server(options) {
                 });
             }
 
+            // ── /_gina/storage/* — storage maintenance (#STO1 CLI slice; always-on, admin-gated) ──
+            // Engine-agnostic ONLY — no isaac fast-path, per the /_gina/agent
+            // precedent (the isaac instance runs this same onRequest chain, so
+            // one handler covers both engines). Same admin IP allowlist as
+            // /_gina/info & /_gina/cache/* — the surface discloses filesystem
+            // ROOTS and gc DELETES, the /_gina/cache/stats class. NO dev gate:
+            // operational tooling. Patterns are ^-anchored (the RW-F9 lesson —
+            // unanchored, any URL that merely EMBEDS the path would match).
+            // No fix-over-HTTP: verify's racy half stays offline where it is
+            // safe by construction — the running process serves REPORTS, and
+            // the gc sweep is the one sanctioned mutation.
+            //
+            // GET /_gina/storage/stats?driver=<name>
+            //   → { configured, drivers: [ {name, strategy, root, capabilities,
+            //     store: {objects, refcounted, zeroRefPending, inline, bytes}|null }
+            //     | {name, error} ] } — the driver's own stats() shape, verbatim.
+            if (
+                request.method.toUpperCase() === 'GET'
+                && /^\/_gina\/storage\/stats(\?.*)?$/i.test(request.url)
+            ) {
+                response.setHeader('content-type',  'application/json; charset=utf8');
+                response.setHeader('cache-control', 'no-cache, no-store, must-revalidate');
+                response.setHeader('pragma',  'no-cache');
+                response.setHeader('expires', '0');
+                if ( !lib.admin.isClientAllowed(request) ) {
+                    response.statusCode = 403;
+                    return response.end(JSON.stringify({ error: 'forbidden', message: '/_gina/storage/stats: client IP not in app.json admin.allowFrom' }));
+                }
+                var _stoStatsNames  = lib.storage.list();
+                var _stoStatsDriver = null;
+                var _stoStatsQi     = request.url.indexOf('?');
+                if ( _stoStatsQi > -1 ) {
+                    _stoStatsDriver = new URLSearchParams(request.url.slice(_stoStatsQi + 1)).get('driver') || null;
+                }
+                if ( _stoStatsDriver ) {
+                    if ( _stoStatsNames.indexOf(_stoStatsDriver) < 0 ) {
+                        response.statusCode = 404;
+                        return response.end(JSON.stringify({ error: 'not_found', message: '/_gina/storage/stats: no driver `' + _stoStatsDriver + '` (configured: ' + (_stoStatsNames.join(', ') || 'none') + ')' }));
+                    }
+                    _stoStatsNames = [ _stoStatsDriver ];
+                }
+                var _stoStatsOut  = { configured: lib.storage.isStarted(), drivers: [] };
+                var _stoStatsNext = function(_stoI) {
+                    if ( _stoI >= _stoStatsNames.length ) {
+                        return response.end(JSON.stringify(_stoStatsOut));
+                    }
+                    lib.storage.get(_stoStatsNames[_stoI]).stats(function(_stoErr, _stoView) {
+                        _stoStatsOut.drivers.push(_stoErr
+                            ? { name: _stoStatsNames[_stoI], error: _stoErr.message || String(_stoErr) }
+                            : _stoView);
+                        _stoStatsNext(_stoI + 1);
+                    });
+                };
+                return _stoStatsNext(0);
+            }
+
+            // POST /_gina/storage/gc?dryRun=1&driver=<name> — POST only: a gc
+            // pass is a mutation (a prefetch/crawler must never fire it — the
+            // /_gina/cache/clear rationale). `dryRun=1` lists what a real pass
+            // would collect and touches NOTHING. A real pass LOOPS sweepNow()
+            // until the driver reports `drained` (each pass is batch-capped),
+            // bounded so a pathological store cannot pin the request forever.
+            // A driver without a sweep (sharded) is named-and-skipped, never
+            // an error — the design's "no sweep" is a strategy fact.
+            if (
+                request.method.toUpperCase() === 'POST'
+                && /^\/_gina\/storage\/gc(\?.*)?$/i.test(request.url)
+            ) {
+                response.setHeader('content-type',  'application/json; charset=utf8');
+                response.setHeader('cache-control', 'no-cache, no-store, must-revalidate');
+                response.setHeader('pragma',  'no-cache');
+                response.setHeader('expires', '0');
+                if ( !lib.admin.isClientAllowed(request) ) {
+                    response.statusCode = 403;
+                    return response.end(JSON.stringify({ error: 'forbidden', message: '/_gina/storage/gc: client IP not in app.json admin.allowFrom' }));
+                }
+                var _stoGcNames  = lib.storage.list();
+                var _stoGcDriver = null;
+                var _stoGcDry    = false;
+                var _stoGcQi     = request.url.indexOf('?');
+                if ( _stoGcQi > -1 ) {
+                    var _stoGcQs = new URLSearchParams(request.url.slice(_stoGcQi + 1));
+                    _stoGcDriver = _stoGcQs.get('driver') || null;
+                    _stoGcDry    = ( _stoGcQs.get('dryRun') === '1' || _stoGcQs.get('dryRun') === 'true' );
+                }
+                if ( _stoGcDriver ) {
+                    if ( _stoGcNames.indexOf(_stoGcDriver) < 0 ) {
+                        response.statusCode = 404;
+                        return response.end(JSON.stringify({ error: 'not_found', message: '/_gina/storage/gc: no driver `' + _stoGcDriver + '` (configured: ' + (_stoGcNames.join(', ') || 'none') + ')' }));
+                    }
+                    _stoGcNames = [ _stoGcDriver ];
+                }
+                var _stoGcOut  = { configured: lib.storage.isStarted(), dryRun: _stoGcDry, drivers: [] };
+                var _stoGcNext = function(_stoI) {
+                    if ( _stoI >= _stoGcNames.length ) {
+                        return response.end(JSON.stringify(_stoGcOut));
+                    }
+                    var _stoGcName = _stoGcNames[_stoI];
+                    var _stoGcDrv  = lib.storage.get(_stoGcName);
+                    if ( typeof _stoGcDrv.sweepNow !== 'function' ) {
+                        _stoGcOut.drivers.push({ name: _stoGcName, skipped: true, reason: 'this driver\'s strategy has no sweep (only `cas` collects garbage)' });
+                        return _stoGcNext(_stoI + 1);
+                    }
+                    if ( _stoGcDry ) {
+                        return _stoGcDrv.sweepNow({ dryRun: true }, function(_stoErr, _stoRes) {
+                            _stoGcOut.drivers.push(_stoErr
+                                ? { name: _stoGcName, error: _stoErr.message || String(_stoErr) }
+                                : { name: _stoGcName, collectable: _stoRes.collectable, drained: _stoRes.drained });
+                            _stoGcNext(_stoI + 1);
+                        });
+                    }
+                    // full drain: loop the batch-capped pass until `drained`,
+                    // hard-bounded at 1000 passes (100k blobs per request)
+                    var _stoGcTotal  = 0;
+                    var _stoGcPasses = 0;
+                    var _stoGcLoop   = function() {
+                        _stoGcDrv.sweepNow(function(_stoErr, _stoRes) {
+                            if (_stoErr) {
+                                _stoGcOut.drivers.push({ name: _stoGcName, error: _stoErr.message || String(_stoErr) });
+                                return _stoGcNext(_stoI + 1);
+                            }
+                            _stoGcTotal += _stoRes.collected;
+                            _stoGcPasses++;
+                            if ( !_stoRes.drained && _stoGcPasses < 1000 ) {
+                                return setImmediate(_stoGcLoop);
+                            }
+                            _stoGcOut.drivers.push({ name: _stoGcName, collected: _stoGcTotal, drained: _stoRes.drained, passes: _stoGcPasses });
+                            _stoGcNext(_stoI + 1);
+                        });
+                    };
+                    _stoGcLoop();
+                };
+                return _stoGcNext(0);
+            }
+
+            // GET /_gina/storage/verify?driver=<name> — REPORT-ONLY over HTTP,
+            // deliberately: `fix` is not even parsed here (the CLI refuses
+            // --fix while the bundle runs, and this handler is what makes that
+            // refusal structural rather than advisory). A driver without
+            // verify (sharded, v1) is named-and-skipped, never an error.
+            if (
+                request.method.toUpperCase() === 'GET'
+                && /^\/_gina\/storage\/verify(\?.*)?$/i.test(request.url)
+            ) {
+                response.setHeader('content-type',  'application/json; charset=utf8');
+                response.setHeader('cache-control', 'no-cache, no-store, must-revalidate');
+                response.setHeader('pragma',  'no-cache');
+                response.setHeader('expires', '0');
+                if ( !lib.admin.isClientAllowed(request) ) {
+                    response.statusCode = 403;
+                    return response.end(JSON.stringify({ error: 'forbidden', message: '/_gina/storage/verify: client IP not in app.json admin.allowFrom' }));
+                }
+                var _stoVerNames  = lib.storage.list();
+                var _stoVerDriver = null;
+                var _stoVerQi     = request.url.indexOf('?');
+                if ( _stoVerQi > -1 ) {
+                    _stoVerDriver = new URLSearchParams(request.url.slice(_stoVerQi + 1)).get('driver') || null;
+                }
+                if ( _stoVerDriver ) {
+                    if ( _stoVerNames.indexOf(_stoVerDriver) < 0 ) {
+                        response.statusCode = 404;
+                        return response.end(JSON.stringify({ error: 'not_found', message: '/_gina/storage/verify: no driver `' + _stoVerDriver + '` (configured: ' + (_stoVerNames.join(', ') || 'none') + ')' }));
+                    }
+                    _stoVerNames = [ _stoVerDriver ];
+                }
+                var _stoVerOut  = { configured: lib.storage.isStarted(), drivers: [] };
+                var _stoVerNext = function(_stoI) {
+                    if ( _stoI >= _stoVerNames.length ) {
+                        return response.end(JSON.stringify(_stoVerOut));
+                    }
+                    var _stoVerName = _stoVerNames[_stoI];
+                    var _stoVerDrv  = lib.storage.get(_stoVerName);
+                    if ( typeof _stoVerDrv.verify !== 'function' ) {
+                        _stoVerOut.drivers.push({ name: _stoVerName, skipped: true, reason: 'verify is cas-only in v1' });
+                        return _stoVerNext(_stoI + 1);
+                    }
+                    _stoVerDrv.verify(function(_stoErr, _stoRep) {
+                        _stoVerOut.drivers.push(_stoErr
+                            ? { name: _stoVerName, error: _stoErr.message || String(_stoErr) }
+                            : _stoRep);
+                        _stoVerNext(_stoI + 1);
+                    });
+                };
+                return _stoVerNext(0);
+            }
+
             // ── /_gina/release/* — stale built-release watch (#RWATCH) ──────────
             // Present ONLY when the service armed at boot (local scope + non-dev +
             // server.releaseWatch.enabled) — when inactive the URLs fall through to
@@ -5553,7 +5739,10 @@ function Server(options) {
                             // drains slower.
                             fileRecord = {
                                 name: fieldname,
-                                group: group,
+                                // #B140 — the RESOLVED group (`untagged` when the part
+                                // carried no group tag), never the raw disposition
+                                // param: this record is what `self.store()` routes on
+                                group: fileGroup,
                                 originalFilename: filename,
                                 encoding: encoding,
                                 type: mimetype,

package/framework/{v0.6.6 → v0.6.7}/core/template/conf/settings.json

@@ -94,13 +94,12 @@
   },
   "upload": {
     "_comment": "for more details, check out https://github.com/gina-io/busboy",
-    "encoding": "utf8",
     "tmpPath": "${tmpPath}",
-    "maxFieldsSize": "2MB", // for all uploads by default - can be redefined under the group
-    "maxFields": 1000, // number of assets when isMultipleAllowed - can be redifined under the group
+    "maxFieldsSize": "2MB", // WHOLE-REQUEST cap vs Content-Length (431 past it); B/KB/MB/GB, bare number = MB
+    "maxFields": 1000, // per-request FILE-COUNT cap (400 past it); 0 disables
     "maxTextFields": 1000, // #B92-adjacent — max multipart TEXT (non-file) fields per request; 0 = no limit
     "maxTextFieldSize": "1MB", // #B92-adjacent — per text-field size cap (B/KB/MB/GB, bare number = MB); 0 = no limit
-    // timeout for tmp files removal - can be redifined under the group
+    // timeout for tmp files removal (block-level — applies to every group)
     // will be ignored by server if set to 0 or false
     // but you will have to setup a cron to remove files from tmp dir
     // eg.: "5s" for 5 seconds, "10m" for 10 minutes, "1h" for 1 hour
@@ -113,11 +112,11 @@
         "path": "${tmpPath}",
         "allowedExtensions": "*", // or [ "jpg", "jpeg", "png", "svg" ]
         "isMultipleAllowed": true // #B50 — untagged is the permissive default (now enforced); set false to require single-file
-        // optional sample
+        // optional — route this group's `self.store()` step through a
+        // `settings.storage` driver (#STO1); `path` then only sets the
+        // parse-time staging dir
         // ,
-        // "filePrefix": "$designId_",
-        // "subFolder": "/$ownerId_$companyId",
-        // "maxFieldsSize": "512K"
+        // "driver": "assets"
       }
       // ,
       // // #B144 — a TEST-ONLY write-error probe group. Every upload tagged

package/framework/v0.6.7/lib/cmd/storage/arguments.json

@@ -0,0 +1,6 @@
+[
+    "--driver",
+    "--dry-run",
+    "--fix",
+    "--format"
+]

package/framework/v0.6.7/lib/cmd/storage/gc.js

@@ -0,0 +1,418 @@
+var fs       = require('fs');
+var http     = require('http');
+var https    = require('https');
+var nodePath = require('path');
+
+var CmdHelper  = require('./../helper');
+var storageLib = require('../../index').storage;
+var console    = lib.logger;
+
+/**
+ * @module gina/lib/cmd/storage/gc
+ */
+/**
+ * Runs the cas GC sweep NOW for a bundle's storage drivers: blobs whose
+ * reference count has sat at zero for longer than `sweepGrace` are collected
+ * (row claimed first, file unlinked second — the loss-proof order the driver
+ * owns). `sharded` drivers have no sweep and are named-and-skipped, never an
+ * error. `--dry-run` lists what a pass would collect and touches NOTHING.
+ *
+ * Who does the work depends on who OWNS the store (#STO1):
+ *   - bundle RUNNING — `POST /_gina/storage/gc` and the OWNING process
+ *     sweeps (the endpoint drains: it loops the batch-capped pass until the
+ *     driver reports `drained`);
+ *   - bundle DOWN (every assigned port ECONNREFUSED) — the REAL driver is
+ *     built offline (`sweepInterval: 0`) and `sweepNow()` is looped here
+ *     until `drained`;
+ *   - anything else (timeout, socket error) — reported as unknown, the
+ *     store is NOT opened.
+ *
+ * Usage:
+ *  gina storage:gc <bundle> @<project>
+ *  gina storage:gc @<project>                — every bundle in the project
+ *  gina storage:gc <bundle> @<project> --dry-run
+ *  gina storage:gc <bundle> @<project> --driver=<name> --format=json
+ *
+ * @class Gc
+ * @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 {object}   cmd        - The cmd dispatcher object (lib/cmd/index.js)
+ *
+ * @example
+ *  // collect everything past the grace window, now
+ *  $ gina storage:gc api @myproject
+ *
+ * @example
+ *  // preview — nothing is claimed, nothing is unlinked
+ *  $ gina storage:gc api @myproject --dry-run
+ */
+function Gc(opt, cmd) {
+    var self = { format: null, driver: null, dryRun: false, results: [] };
+
+    var init = function(opt, cmd) {
+        // import CMD helpers
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+        // check CMD configuration
+        if (!isCmdConfigured()) return false;
+
+        // Full pre-scan of argv for --format, --driver and --dry-run —
+        // whitelisted in `storage/arguments.json` (mirrors cache:clear).
+        for (let i = 3, len = process.argv.length; i < len; i++) {
+            if ( /^\-\-format\=/.test(process.argv[i]) ) {
+                self.format = process.argv[i].split(/\=/)[1];
+            } else if ( /^\-\-driver\=/.test(process.argv[i]) ) {
+                self.driver = process.argv[i].split(/\=/)[1];
+            } else if ( /^\-\-dry-run$/.test(process.argv[i]) ) {
+                self.dryRun = true;
+            }
+        }
+
+        if (!self.name) {
+            // No bundle specified — sweep every bundle in the project.
+            runAll(opt, cmd, 0);
+        } else {
+            runOne(self.name, opt, cmd, false);
+        }
+    }
+
+    /**
+     * Runs every bundle in the project sequentially, then reports.
+     * @inner
+     */
+    var runAll = function(opt, cmd, index) {
+        if (index >= self.bundles.length) {
+            report(opt, cmd);
+            return;
+        }
+        runOne(self.bundles[index], opt, cmd, true, function() {
+            runAll(opt, cmd, index + 1);
+        });
+    }
+
+    /**
+     * Resolves one bundle (running → endpoint, down → offline), records the
+     * result, then advances / reports.
+     * @inner
+     */
+    var runOne = function(bundle, opt, cmd, isBulk, next) {
+        var advance = function(result) {
+            self.results.push(result);
+            if (isBulk && next) return next();
+            report(opt, cmd);
+        };
+        probeAndSweep(bundle, function(outcome) {
+            if ( outcome.mode === 'down' ) {
+                return gcOffline(bundle, advance);
+            }
+            advance(outcome);
+        });
+    }
+
+    /**
+     * Sends `POST /_gina/storage/gc` (the request IS the probe — a POST is
+     * safe as a probe here because executing the sweep is exactly what the
+     * caller asked for): a response classifies the bundle RUNNING and carries
+     * the result; ECONNREFUSED advances; every candidate refused classifies
+     * it DOWN. The response timeout is 120s, not the 5s probe class: the
+     * server drains the whole backlog before answering, and a big store
+     * legitimately takes a while (the work is chunked server-side, the
+     * response is not).
+     *
+     * @inner
+     * @param {string} bundle
+     * @param {function(object)} done - Result object, or `{mode:'down'}`.
+     */
+    var probeAndSweep = function(bundle, done) {
+        var env      = self.projects[self.projectName].def_env;
+        var portsRev = self.portsReverseData[bundle + '@' + self.projectName];
+
+        if (!portsRev || !portsRev[env]) {
+            return done({ bundle: bundle, mode: 'error', error: 'no port assignment found — is the bundle registered?' });
+        }
+
+        var candidates = [];
+        for (var protocol in portsRev[env]) {
+            for (var s in portsRev[env][protocol]) {
+                candidates.push({ port: portsRev[env][protocol][s], scheme: s });
+            }
+        }
+        if (!candidates.length) {
+            return done({ bundle: bundle, mode: 'error', error: 'could not determine port' });
+        }
+
+        var query = [];
+        if (self.dryRun) { query.push('dryRun=1'); }
+        if (self.driver) { query.push('driver=' + encodeURIComponent(self.driver)); }
+        var endpointPath = '/_gina/storage/gc' + ( query.length ? '?' + query.join('&') : '' );
+
+        var tryNext = function(index) {
+            if (index >= candidates.length) {
+                return done({ mode: 'down' }); // refused on every assigned port — the offline path owns it
+            }
+
+            var candidate  = candidates[index];
+            var transport  = (candidate.scheme === 'https') ? https : http;
+            var reqOptions = {
+                hostname           : '127.0.0.1',
+                port               : candidate.port,
+                path               : endpointPath,
+                method             : 'POST',
+                timeout            : 120000,
+                rejectUnauthorized : false  // allow self-signed certs on internal endpoints
+            };
+
+            var req = transport.request(reqOptions, function(res) {
+                var raw = '';
+                res.on('data', function(chunk) { raw += chunk; });
+                res.on('end', function() {
+                    var parsed = null;
+                    try {
+                        parsed = JSON.parse(raw);
+                    } catch (e) {
+                        return done({ bundle: bundle, mode: 'error', error: 'invalid response from /_gina/storage/gc' });
+                    }
+                    if ( parsed && parsed.error ) {
+                        return done({ bundle: bundle, mode: 'running', error: ( parsed.error === 'forbidden' )
+                            ? 'reachable but admin-gated (app.json admin.allowFrom?)'
+                            : (parsed.message || parsed.error) });
+                    }
+                    done({ bundle: bundle, mode: 'running', configured: !!parsed.configured, dryRun: !!parsed.dryRun, drivers: parsed.drivers || [] });
+                });
+            });
+
+            req.on('timeout', function() {
+                req.destroy();
+                done({ bundle: bundle, mode: 'error', error: 'request timed out — bundle state unknown; not opening its store offline (a live process may own it)' });
+            });
+
+            req.on('error', function(err) {
+                if (err.code === 'ECONNREFUSED') {
+                    return tryNext(index + 1); // this port is not listening — try the next
+                }
+                done({ bundle: bundle, mode: 'error', error: err.message + ' — bundle state unknown; not opening its store offline' });
+            });
+
+            req.end();
+        };
+
+        tryNext(0);
+    }
+
+    /**
+     * The DOWN path: resolve the bundle's `storage` block offline, build each
+     * local cas driver through the boot's own resolver/factories, and loop
+     * `sweepNow()` until `drained` (each pass is batch-capped by the driver;
+     * the loop is hard-bounded so a pathological store cannot spin forever).
+     * `--dry-run` runs a single listing pass and touches nothing.
+     *
+     * @inner
+     * @param {string} bundle
+     * @param {function(object)} done
+     */
+    var gcOffline = function(bundle, done) {
+        var byProject = self.bundlesByProject[self.projectName] || {};
+        var bundleMeta = byProject[bundle];
+        var settingsPath = ( bundleMeta && bundleMeta.configPaths ) ? bundleMeta.configPaths.settings : null;
+        if ( !settingsPath || !fs.existsSync(settingsPath) ) {
+            return done({ bundle: bundle, mode: 'offline', error: 'no config/settings.json found for this bundle' });
+        }
+        var settings = null;
+        try {
+            settings = requireJSON(settingsPath);
+        } catch (e) {
+            return done({ bundle: bundle, mode: 'offline', error: 'could not parse settings.json: ' + (e.message || e) });
+        }
+        var block = settings ? settings.storage : null;
+        if ( !block || !block.drivers || !Object.keys(block.drivers).length ) {
+            return done({ bundle: bundle, mode: 'offline', configured: false, drivers: [] });
+        }
+        var lint = storageLib.validateConfig(block);
+        if ( lint.fatal ) {
+            return done({ bundle: bundle, mode: 'offline', error: 'invalid storage config: ' + lint.fatal });
+        }
+
+        var names = Object.keys(block.drivers);
+        if ( self.driver ) {
+            if ( names.indexOf(self.driver) < 0 ) {
+                return done({ bundle: bundle, mode: 'offline', error: 'no driver `' + self.driver + '` (configured: ' + names.join(', ') + ')' });
+            }
+            names = [ self.driver ];
+        }
+
+        var out = { bundle: bundle, mode: 'offline', configured: true, dryRun: self.dryRun, drivers: [] };
+        var nextDriver = function(i) {
+            if ( i >= names.length ) { return done(out); }
+            var name = names[i];
+            var d    = block.drivers[name];
+            if ( d.store ) {
+                out.drivers.push({ name: name, skipped: true, reason: 'connector-backed store (`' + d.store + '`) — nothing local to open; start the bundle and re-run' });
+                return nextDriver(i + 1);
+            }
+            if ( d.strategy !== 'cas' ) {
+                out.drivers.push({ name: name, skipped: true, reason: 'this driver\'s strategy has no sweep (only `cas` collects garbage)' });
+                return nextDriver(i + 1);
+            }
+            if ( !fs.existsSync(d.root) ) {
+                out.drivers.push({ name: name, collected: 0, drained: true, note: 'root not created yet (nothing stored)' });
+                return nextDriver(i + 1);
+            }
+            var driver = null;
+            try {
+                var resolved = storageLib._resolveDriverConf(d);
+                resolved.sweepInterval = 0; // no GC timer in a CLI process
+                var metaStore = storageLib._createEmbeddedMetaStore(nodePath.join(d.root, '.meta.db'));
+                driver = storageLib._FACTORIES[d.strategy](name, resolved, metaStore);
+            } catch (buildErr) {
+                out.drivers.push({ name: name, error: buildErr.message || String(buildErr) });
+                return nextDriver(i + 1);
+            }
+            var finish = function(entry) {
+                try { driver.close(); } catch (e) { /* already closed */ }
+                out.drivers.push(entry);
+                nextDriver(i + 1);
+            };
+            if ( self.dryRun ) {
+                return driver.sweepNow({ dryRun: true }, function(err, res) {
+                    finish(err
+                        ? { name: name, error: err.message || String(err) }
+                        : { name: name, collectable: res.collectable, drained: res.drained });
+                });
+            }
+            // full drain: loop the batch-capped pass until `drained`,
+            // hard-bounded at 1000 passes (the endpoint's bound, mirrored)
+            var total  = 0;
+            var passes = 0;
+            var loop = function() {
+                driver.sweepNow(function(err, res) {
+                    if (err) {
+                        return finish({ name: name, error: err.message || String(err) });
+                    }
+                    total += res.collected;
+                    passes++;
+                    if ( !res.drained && passes < 1000 ) {
+                        return setImmediate(loop);
+                    }
+                    finish({ name: name, collected: total, drained: res.drained, passes: passes });
+                });
+            };
+            loop();
+        };
+        nextDriver(0);
+    }
+
+    /**
+     * Builds the `--format=json` envelope. Pure. Single-bundle → flattened;
+     * all-bundles → a `bundles` array.
+     *
+     * @inner
+     * @param {string}        project
+     * @param {Array<object>} results
+     * @param {string|null}   singleBundle
+     * @param {string|null}   driver
+     * @returns {object}
+     */
+    var buildEnvelope = function(project, results, singleBundle, driver) {
+        var base = { project: project, dryRun: self.dryRun };
+        if (driver) {
+            base.driver = driver;
+        }
+        if (singleBundle && results.length === 1) {
+            var r = results[0];
+            for (var k in r) { base[k] = r[k]; }
+            return base;
+        }
+        base.bundles = results;
+        return base;
+    }
+
+    /**
+     * Formats the per-bundle results as a human-readable summary. Pure.
+     *
+     * @inner
+     * @param {Array<object>} results
+     * @param {string}        project
+     * @returns {string}
+     */
+    var formatText = function(results, project) {
+        var SEP = '------------------------------------------------------------\n\r';
+        var str = '\n\r' + SEP;
+        str += (self.dryRun ? '[ dry-run ] ' : '') + 'storage:gc @' + project + ( self.driver ? '  --driver=' + self.driver : '' ) + '\n\r';
+        str += SEP;
+
+        if (!results.length) {
+            str += '  (no bundles)\n\r\n\r';
+            return str;
+        }
+
+        for (var i = 0; i < results.length; i++) {
+            var r = results[i];
+            str += '\n\r  [ ' + r.bundle + '@' + project + ' ]' + ( r.mode ? '  (' + r.mode + ')' : '' ) + '\n\r';
+            if (r.error) {
+                str += '    ' + r.error + '\n\r';
+                continue;
+            }
+            if ( r.configured === false ) {
+                str += '    storage not configured (no `storage` block)\n\r';
+                continue;
+            }
+            for (var j = 0; j < r.drivers.length; j++) {
+                var d = r.drivers[j];
+                if (d.error) {
+                    str += '    driver `' + d.name + '`: ' + d.error + '\n\r';
+                    continue;
+                }
+                if (d.skipped) {
+                    str += '    driver `' + d.name + '`: skipped — ' + d.reason + '\n\r';
+                    continue;
+                }
+                if ( typeof d.collectable !== 'undefined' ) {
+                    // dry-run entry
+                    str += '    driver `' + d.name + '`: would collect ' + d.collectable.length
+                        + ' blob(s)' + ( d.drained ? '' : ' (more beyond this batch)' ) + '\n\r';
+                    for (var c = 0; c < d.collectable.length; c++) {
+                        str += '      ' + d.collectable[c] + '\n\r';
+                    }
+                    continue;
+                }
+                str += '    driver `' + d.name + '`: collected ' + d.collected + ' blob(s)'
+                    + ( d.drained ? ' — drained' : ' — NOT drained (pass bound hit)' )
+                    + ( typeof d.passes === 'number' ? ' (passes: ' + d.passes + ')' : '' )
+                    + ( d.note ? ' — ' + d.note : '' ) + '\n\r';
+            }
+        }
+
+        str += '\n\r';
+        return str;
+    }
+
+    /**
+     * Emits the result — JSON synchronously via fs.writeSync (pipe-safe
+     * against the `process.exit` in `end()` — llms.txt #180), else text via
+     * `opt.client` — then terminates. Exit code 1 when any per-bundle result
+     * carries an error.
+     * @inner
+     */
+    var report = function(opt, cmd) {
+        var single   = (self.results.length === 1 && !!self.name) ? self.name : null;
+        var hasError = self.results.some(function(r) { return !!r.error; });
+
+        if ( /^json/i.test(String(self.format || '')) ) {
+            var envelope = buildEnvelope(self.projectName, self.results, single, self.driver);
+            fs.writeSync(1, JSON.stringify(envelope) + '\n');
+            return end(opt, cmd, hasError);
+        }
+
+        opt.client.write(formatText(self.results, self.projectName));
+        end(opt, cmd, hasError);
+    }
+
+    var end = function(opt, cmd, error) {
+        if (!opt.client.destroyed) opt.client.emit('end');
+        process.exit(error ? 1 : 0);
+    }
+
+    init(opt, cmd);
+}
+module.exports = Gc;