gina 0.5.4 → 0.5.5

package/framework/{v0.5.4 → v0.5.5}/lib/cmd/project/arguments.json

@@ -2,6 +2,8 @@
   "--env",
   "--scope",
   "--path",
+  "--to",
+  "--out",
   "--homedir",
   "--force",
   "--more",

package/framework/v0.5.5/lib/cmd/project/backup.js

@@ -0,0 +1,228 @@
+var fs   = require('fs');
+var path = require('path');
+
+var CmdHelper = require('./../helper');
+var console   = lib.logger;
+
+/**
+ * @module gina/lib/cmd/project/backup
+ */
+/**
+ * Archives a registered project's SOURCE TREE into a single `.zip`.
+ *
+ * The archive is produced with `lib/archiver`'s ARRAY form: the handler walks the
+ * project source itself and hands `compress()` an explicit `{ input, output }`
+ * file list. This is deliberate — the directory form (`compress(dir, ...)`) walks
+ * with `fs.statSync`, which FOLLOWS symlinks, so it would recurse the project's
+ * absolute `node_modules/gina` link into the entire framework install (and it also
+ * leaks absolute paths into the entries). The self-walk skips symlinks and
+ * excludes `node_modules` by name, so the archive holds only the real source tree
+ * with clean relative paths.
+ *
+ * The artifact is a DEFLATE `.zip` (`@<project>-<YYYYMMDD-HHMMSS>.zip`), not a
+ * `.tar.gz`: `lib/archiver` has no tar producer — it builds zips via JSZip. The
+ * timestamp keeps repeated backups from clobbering each other.
+ *
+ * The output directory is given with `--out=` (default: the current working
+ * directory). It is deliberately NOT `--path`: `--path` carries add/import
+ * semantics in the shared CmdHelper bootstrap (it pre-creates the directory and
+ * can point `projectLocation` at it when the basename matches the project name —
+ * helper.js:345/358), whereas `--out` is opaque to the bootstrap.
+ *
+ * Backup is READ-ONLY on the project: it never mutates the source tree, never
+ * writes the `~/.gina` registry, and never touches the port matrix. There is no
+ * refuse-if-running guard — a source snapshot of a live project is safe (the
+ * mutable runtime state lives under the `~/.<project>` home, outside the source).
+ *
+ * `--with-password` is advertised in help.txt but has no backing (the archiver's
+ * encryption hooks are unimplemented and JSZip cannot produce encrypted zips), so
+ * it is REFUSED rather than silently producing a plaintext archive when a caller
+ * explicitly asked for encryption.
+ *
+ * Project-scoped, offline: `gina project:backup @<project> [ --out=/dump ]`.
+ *
+ * @class Backup
+ * @constructor
+ * @param {object} opt - Parsed command-line options
+ * @param {object} opt.client - Socket client for terminal output
+ * @param {string[]} opt.argv - Full argv array
+ * @param {number} [opt.debugPort] - Node.js inspector port
+ * @param {boolean} [opt.debugBrkEnabled] - True when --inspect-brk is active
+ * @param {object} cmd - The cmd dispatcher object (lib/cmd/index.js)
+ *
+ * @example
+ *  // back up project `myproject` into /var/dump
+ *  $ gina project:backup @myproject --out=/var/dump
+ *  project [ myproject ] backed up to [ /var/dump/myproject-20260619-124016.zip ]
+ *
+ * @example
+ *  // no --out: writes the archive into the current directory
+ *  $ gina project:backup @myproject
+ */
+function Backup(opt, cmd) {
+
+    var self  = {};
+    var local = { project: null, source: null, outDir: null, archive: null, count: 0 };
+
+    /**
+     * Wires CmdHelper, validates the project is registered and has an on-disk
+     * source, refuses the unimplemented `--with-password`, resolves the `--out`
+     * output directory (default cwd), then runs the backup.
+     *
+     * @inner
+     * @private
+     */
+    var init = function() {
+
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+        if ( !isCmdConfigured() ) return false;
+
+        local.project = self.projectName;
+
+        if ( local.project == null || typeof(self.projects[local.project]) == 'undefined' ) {
+            console.error('[ '+ local.project +' ] is not a registered project.');
+            process.exit(1);
+            return;
+        }
+
+        // --with-password is advertised but unimplemented (no encryption backing).
+        // Refuse rather than hand back a plaintext archive when a caller explicitly
+        // asked for one. A bare `--with-password` stays on argv; `--with-password=x`
+        // is hoisted to GINA_WITH_PASSWORD by filterArgs — check both.
+        var wantsPassword = process.argv.some(function(a){ return /^--with-password(=|$)/.test(a); })
+                            || typeof(process.gina.GINA_WITH_PASSWORD) != 'undefined';
+        if ( wantsPassword ) {
+            console.error('project:backup: --with-password is not supported yet (archives are NOT encrypted). No archive was created.');
+            process.exit(1);
+            return;
+        }
+
+        local.source = self.projects[local.project].path;
+        if ( !local.source || local.source === '' ) {
+            console.error('Project [ '+ local.project +' ] has no source path to back up.');
+            process.exit(1);
+            return;
+        }
+        if ( !fs.existsSync(local.source) ) {
+            console.error('Project source path [ '+ local.source +' ] does not exist on disk.');
+            process.exit(1);
+            return;
+        }
+
+        // Output directory: --out (opaque to the bootstrap, unlike --path).
+        // Default to the current working directory. Read off argv directly (the
+        // move.js precedent) — argv survives filterArgs for project:* tasks.
+        var outArg = process.argv.find(function(a){ return /^--out=/.test(a); }) || null;
+        var outVal = outArg ? outArg.split('=').slice(1).join('=').replace(/['"]/g, '') : null;
+        local.outDir = outVal ? path.resolve(outVal) : process.cwd();
+
+        run();
+    };
+
+    /**
+     * Recursively collects the project source files as an archiver
+     * `{ input, output }` list — EXCLUDING `node_modules` (regenerable + the
+     * symlink-recursion hazard) and SKIPPING symlinks (the absolute
+     * `node_modules/gina` link would otherwise pull in the whole framework).
+     *
+     * @inner
+     * @private
+     * @param {string} dir - directory to scan
+     * @param {number} baseLen - length of the source root prefix to strip for the relative output path
+     * @param {object[]} out - accumulator of `{ input, output }` entries
+     */
+    var collectFiles = function(dir, baseLen, out) {
+        var entries = fs.readdirSync(dir, { withFileTypes: true });
+        for ( var i = 0; i < entries.length; ++i ) {
+            var e = entries[i];
+            if ( e.isSymbolicLink() ) {
+                continue;
+            }
+            var abs = dir + '/' + e.name;
+            if ( e.isDirectory() ) {
+                if ( e.name === 'node_modules' ) {
+                    continue;
+                }
+                collectFiles(abs, baseLen, out);
+            } else if ( e.isFile() ) {
+                out.push({ input: abs, output: abs.substring(baseLen) });
+            }
+        }
+    };
+
+    /**
+     * @inner
+     * @private
+     * @returns {string} a `YYYYMMDD-HHMMSS` stamp for the archive name
+     */
+    var timestamp = function() {
+        var d = new Date();
+        var p = function(n) { return (n < 10 ? '0' : '') + n; };
+        return '' + d.getFullYear() + p(d.getMonth() + 1) + p(d.getDate())
+                  + '-' + p(d.getHours()) + p(d.getMinutes()) + p(d.getSeconds());
+    };
+
+    /**
+     * Collects the source file list, then compresses it into
+     * `<outDir>/<project>-<timestamp>.zip` via the archiver ARRAY form. Reports
+     * the path the archiver actually wrote and asserts it exists before declaring
+     * success.
+     *
+     * @inner
+     * @private
+     */
+    var run = function() {
+
+        var files = [];
+        try {
+            collectFiles(local.source, local.source.replace(/\/+$/, '').length + 1, files);
+        } catch ( walkErr ) {
+            console.error('Could not read the project source [ '+ local.source +' ]: '+ (walkErr && (walkErr.stack || walkErr.message) || walkErr));
+            process.exit(1);
+            return;
+        }
+
+        if ( files.length === 0 ) {
+            console.error('Nothing to back up in [ '+ local.source +' ].');
+            process.exit(1);
+            return;
+        }
+        local.count = files.length;
+
+        var base = local.project + '-' + timestamp();
+        local.archive = path.join(local.outDir, base + '.zip');
+
+        try {
+            if ( !fs.existsSync(local.outDir) ) {
+                fs.mkdirSync(local.outDir, { recursive: true });
+            }
+        } catch ( mkdirErr ) {
+            console.error('Could not create the output directory [ '+ local.outDir +' ]: '+ (mkdirErr && (mkdirErr.message || mkdirErr)));
+            process.exit(1);
+            return;
+        }
+
+        lib.archiver.compress(files, local.outDir + '/', { method: 'gzip', name: base, level: 9 })
+            .onComplete(function onBackupComplete(err, archivePath) {
+                if ( err ) {
+                    console.error('project:backup failed: '+ (err && (err.stack || err.message) || err));
+                    process.exit(1);
+                    return;
+                }
+                var finalPath = archivePath || local.archive;
+                if ( !finalPath || !fs.existsSync(finalPath) ) {
+                    console.error('project:backup: the archive was not created.');
+                    process.exit(1);
+                    return;
+                }
+                var bytes = fs.statSync(finalPath).size;
+                console.log('project [ '+ local.project +' ] backed up to [ '+ finalPath +' ] ('+ local.count +' files, '+ bytes +' bytes)');
+                console.log('  node_modules was excluded — run `npm install` after restoring.');
+                process.exit(0);
+            });
+    };
+
+    init();
+};
+
+module.exports = Backup

package/framework/{v0.5.4 → v0.5.5}/lib/cmd/project/help.txt

@@ -84,23 +84,33 @@
     $ gina project:rename @<project_name> @<new_project_name>
 
 
+[ Move project ]
+
+    Relocates the project source tree to a new path. The project name and its
+    ~/.<project_name> home are unchanged; all bundles must be stopped first.
+
+    $ gina project:move @<project_name> --to=/new/path
+
+
 [ Build project ]
 
     $ gina project:build @<project_name> --scope=local --env=prod
 
 [ Backup project ]
 
-    N.B.: Only available when ordering for supoort
+    Archives the project source tree (excluding node_modules) into a .zip.
+
+    $ gina project:backup @<project_name> [ --out=/var/dump ] (if no --out given, writes to the current path)
 
-    $ gina project:backup @<project_name> --path=/var/dump --with-password
+    N.B.: --with-password is not implemented yet — archives are NOT encrypted.
 
 
 [ Restore project ]
 
-    N.B.: Only available when ordering for support
+    Rebuilds a project from a project:backup .zip: extracts the source tree to
+    --to and re-registers the project (entry, ports, and the gina symlink).
+
+    $ gina project:restore @<project_name> <archive.zip> --to=/new/path
 
-    $ gina project:restore /var/dump/myproject.tar.gz (will restore in current path)
-    or
-    $ gina project:restore myproject.tar.gz  (will restore from current path to current path: myproject.gna must be under the PWD)
-    or
-    $ gina project:restore /var/dump/myproject.tar.gz —-path=/other/path
+    N.B.: node_modules is not in the backup — run `npm install` afterwards.
+    Pass --force to overwrite an already-registered name or a non-empty target.

package/framework/v0.5.5/lib/cmd/project/man.js

@@ -0,0 +1,10 @@
+/**
+ * @module gina/lib/cmd/project/man
+ * @description `gina project:man` — shows the project manual. No
+ * `gina-project.1.md` source exists yet, so the shared engine falls back to
+ * `lib/cmd/project/help.txt`. Thin re-export of
+ * {@link module:gina/lib/cmd/man-render}, which picks the group from
+ * `opt.task.topic`.
+ */
+// alias
+module.exports = require('../man-render');

package/framework/v0.5.5/lib/cmd/project/move.js

@@ -0,0 +1,215 @@
+var fs   = require('fs');
+var path = require('path');
+
+var CmdHelper = require('./../helper');
+var console   = lib.logger;
+
+/**
+ * @module gina/lib/cmd/project/move
+ */
+/**
+ * Relocates a registered project's source tree to a new filesystem path.
+ *
+ * Unlike `project:rename` (which changes the project NAME and therefore rekeys
+ * `ports.json` / `ports.reverse.json` by owner), `project:move` changes only the
+ * filesystem location. The project name, its `~/.<project>` home directory, the
+ * homedir-derived paths (`bundles_path` / `releases_path` / `logs_path` /
+ * `tmp_path`), the port matrix, and the per-bundle RELATIVE manifest paths are
+ * all preserved — only the registry `path` field (and any other field rooted at
+ * the old source path) is rewritten.
+ *
+ * The target is given with `--to=`, NOT `--path=`. `--path` carries add/import
+ * semantics in the shared CmdHelper bootstrap (it pre-creates the directory and
+ * can even point `projectLocation` at it when the basename matches the project
+ * name — helper.js:345/358), which would clobber a move target. `--to` is opaque
+ * to the bootstrap, so the move owns the target's creation entirely.
+ *
+ * The move uses an atomic `fs.renameSync` (symlink-preserving — the absolute
+ * `node_modules/gina` link survives). A cross-filesystem target (EXDEV) is
+ * REFUSED with guidance to use `project:import` after a manual copy, rather than
+ * silently falling back to a slow, symlink-dereferencing copy.
+ *
+ * Every bundle in the project must be STOPPED — moving a project whose bundles
+ * are serving would strand their processes against a path that no longer exists.
+ * It refuses if any bundle is running (no `--force` bypass). The stale bundle
+ * mount symlinks (recreated on next start) are removed best-effort after the
+ * move. On any post-move failure the rename is reversed so disk and registry
+ * stay consistent.
+ *
+ * Project-scoped, offline: `gina project:move @<project> --to=/new/path`.
+ *
+ * @class Move
+ * @constructor
+ * @param {object} opt - Parsed command-line options
+ * @param {object} opt.client - Socket client for terminal output
+ * @param {string[]} opt.argv - Full argv array
+ * @param {number} [opt.debugPort] - Node.js inspector port
+ * @param {boolean} [opt.debugBrkEnabled] - True when --inspect-brk is active
+ * @param {object} cmd - The cmd dispatcher object (lib/cmd/index.js)
+ *
+ * @example
+ *  // move project `myproject` to /srv/apps/myproject
+ *  $ gina project:move @myproject --to=/srv/apps/myproject
+ *  project [ myproject ] moved to [ /srv/apps/myproject ]
+ */
+function Move(opt, cmd) {
+
+    var self  = {};
+    var local = { project: null, source: null, target: null, moved: false };
+
+    /**
+     * Wires CmdHelper, parses the single project token + the required `--to`,
+     * validates that the project is registered and the target is a fresh,
+     * different location, then runs the move.
+     *
+     * @inner
+     * @private
+     */
+    var init = function() {
+
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+        if ( !isCmdConfigured() ) return false;
+
+        local.project = self.projectName;
+
+        if ( local.project == null || typeof(self.projects[local.project]) == 'undefined' ) {
+            console.error('[ '+ local.project +' ] is not a registered project.');
+            process.exit(1);
+            return;
+        }
+
+        // --to is REQUIRED (the new location). It is deliberately NOT --path:
+        // the bootstrap pre-creates a --path directory (add/import semantics).
+        var toArg  = process.argv.find(function(a){ return /^--to=/.test(a); }) || null;
+        var newPath = toArg ? toArg.split('=').slice(1).join('=').replace(/['"]/g, '') : null;
+        if ( !newPath ) {
+            console.error('project:move requires a target path: gina project:move @'+ local.project +' --to=/new/path');
+            process.exit(1);
+            return;
+        }
+
+        local.source = self.projects[local.project].path;
+        if ( !local.source || local.source === '' ) {
+            console.error('Project [ '+ local.project +' ] has no source path to move.');
+            process.exit(1);
+            return;
+        }
+
+        // resolve the target to an absolute, normalized path
+        local.target = path.resolve(newPath);
+
+        if ( local.target === path.resolve(local.source) ) {
+            console.error('Target path is the project current location ('+ local.source +'). Nothing to move.');
+            process.exit(1);
+            return;
+        }
+
+        if ( fs.existsSync(local.target) ) {
+            console.error('Target path [ '+ local.target +' ] already exists. Choose a path that does not exist yet.');
+            process.exit(1);
+            return;
+        }
+
+        run();
+    }
+
+    /**
+     * Refuses if any bundle in the project is running, moves the source tree
+     * (atomic rename), rewrites the registry path, removes stale mount symlinks,
+     * and writes projects.json. Reverses the move on any post-move failure.
+     *
+     * @inner
+     * @private
+     */
+    var run = function() {
+
+        var project = local.project;
+        var bundles = self.bundles || [];
+
+        // refuse to move a project with a RUNNING bundle (no --force bypass): a
+        // live move would strand processes against a path that no longer exists.
+        var runDir  = (typeof(GINA_RUNDIR) != 'undefined' && GINA_RUNDIR) ? GINA_RUNDIR : (GINA_HOMEDIR + '/run');
+        var running = [];
+        for ( var i = 0; i < bundles.length; ++i ) {
+            var st = lib.cmdStatusFormat.readPidfile(runDir, bundles[i], project);
+            if ( st && st.running ) {
+                running.push(bundles[i] + ' (pid '+ st.pid +')');
+            }
+        }
+        if ( running.length > 0 ) {
+            console.error('Cannot move [ '+ project +' ]: these bundles are running — stop them first (gina project:stop @'+ project +'):\n  - '+ running.join('\n  - '));
+            process.exit(1);
+            return;
+        }
+
+        // ensure the target parent exists so renameSync does not ENOENT
+        var parent = path.dirname(local.target);
+        try {
+            if ( !fs.existsSync(parent) ) {
+                fs.mkdirSync(parent, { recursive: true });
+            }
+        } catch ( mkdirErr ) {
+            console.error('Could not create the target parent directory [ '+ parent +' ]: '+ (mkdirErr.message || mkdirErr));
+            process.exit(1);
+            return;
+        }
+
+        // move the tree (atomic, symlink-preserving)
+        try {
+            new _(local.source).renameSync(local.target);
+            local.moved = true;
+        } catch ( mvErr ) {
+            if ( mvErr && mvErr.code === 'EXDEV' ) {
+                console.error('Target path [ '+ local.target +' ] is on a different filesystem. Copy the tree there manually, then re-register it: gina project:import @'+ project +' --path='+ local.target);
+            } else {
+                console.error('Could not move the project tree: '+ (mvErr && (mvErr.stack || mvErr.message) || mvErr));
+            }
+            process.exit(1);
+            return;
+        }
+
+        // rewrite the registry: the `path` field (exact match) plus any other
+        // string field rooted UNDER the old source path. The homedir-derived
+        // fields live under ~/.<project> and never match, so they are preserved.
+        try {
+            var entry  = self.projects[project];
+            var oldDir = local.source;
+            for ( var k in entry ) {
+                if ( typeof(entry[k]) === 'string' ) {
+                    if ( entry[k] === oldDir ) {
+                        entry[k] = local.target;
+                    } else if ( entry[k].indexOf(oldDir + '/') === 0 ) {
+                        entry[k] = local.target + entry[k].slice(oldDir.length);
+                    }
+                }
+            }
+
+            // remove stale mount symlinks — they point at the old source and are
+            // recreated under the new path on the next start (mirrors bundle:rename).
+            for ( var b = 0; b < bundles.length; ++b ) {
+                try {
+                    var coreEnv = getCoreEnv(bundles[b]);
+                    if ( coreEnv && coreEnv.mountPath ) {
+                        new _(coreEnv.mountPath + '/' + bundles[b], true).rmSync();
+                    }
+                } catch ( unmountErr ) { /* not mounted — fine */ }
+            }
+
+            lib.generator.createFileFromDataSync(self.projects, _(GINA_HOMEDIR + '/projects.json'));
+        } catch ( regErr ) {
+            // reverse the move so the registry and disk stay consistent
+            try { new _(local.target).renameSync(local.source); } catch ( revErr ) { /* leave as-is */ }
+            console.error('Could not update the project registry; reverted the move: '+ (regErr && (regErr.stack || regErr.message) || regErr));
+            process.exit(1);
+            return;
+        }
+
+        console.log('project [ '+ project +' ] moved to [ '+ local.target +' ]');
+        console.log('  restart it to refresh bundle mounts: gina project:start @'+ project);
+        process.exit(0);
+    }
+
+    init();
+};
+
+module.exports = Move