gingee-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) [2025] [Vignesh Swaminathan]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# Gingee CLI: Command Reference
+
+The `gingee-cli` is the official, all-in-one command-line interface for the **[Gingee platform](https://github.com/gingerhome/gingee)**. It is a powerful tool for both developers and system administrators, designed to streamline every phase of the application lifecycle, from initial project creation to ongoing production management.
+
+## Installation
+
+The `gingee-cli` is designed to be installed globally on your machine, making it available everywhere.
+
+```bash
+npm install -g gingee-cli
+```
+After installation, you will have access to the `gingee-cli` command in your terminal.
+
+---
+
+## Commands
+
+### Project Initialization
+
+This is the main entry point for starting a new Gingee project.
+
+#### `init <project-name>`
+
+Scaffolds a complete, new Gingee project in a new directory. It launches an interactive wizard to guide you through the setup.
+
+**Usage:**
+```bash
+gingee-cli init my-awesome-project```
+```
+
+**Wizard Prompts:**
+-   `Administrator Username for glade:` Sets the initial username for the bundled Glade admin panel. Defaults to `admin`.
+-   `Administrator Password for glade:` Securely prompts for the admin password. This is hashed and stored in Glade's configuration.
+-   `Install npm dependencies automatically?` If yes (default), it will run `npm install` so the project is ready to run immediately.
+
+---
+
+### Local Scaffolding
+
+These commands should be run from the root directory of an existing Gingee project.
+
+#### `add-app <app-name>`
+
+Scaffolds a new, working "hello world" application inside your project's `web` directory.
+
+**Usage:**
+```bash
+gingee-cli add-app my-blog
+```
+
+**Wizard Prompts:**
+-   `What type of app is this?` Choose between `MPA` (Multi-Page App, default) or `SPA` (Single Page Application, for React/Vue/Angular).
+-   `Would you like to configure a database connection?` If yes, it will guide you through setting up the `db` block in the new app's `app.json`.
+-   `Generate a JWT secret for this app?` If yes, it will automatically generate a secure secret and add it to `app.json`.
+
+#### `add-script <app-name> <script-path>`
+
+Quickly creates a new server script file, pre-populated with the standard Gingee boilerplate.
+
+**Usage:**
+```bash
+gingee-cli add-script my-blog api/posts
+```
+Creates ./web/my-blog/box/api/posts.js
+
+---
+
+### Server Administration
+
+These commands interact with the API of a live, running `glade` instance. They require you to be authenticated via the `login` command.
+
+#### `login [server-url]`
+
+Authenticates the CLI with a Glade admin panel and saves the session for subsequent commands.
+
+**Usage:**
+-  Login to a local server
+```bash
+gingee-cli login
+```
+
+-  Login to a remote server
+```bash
+gingee-cli login https://prod.my-server.com
+```
+
+**Options:**
+-   `-u, --username <username>`: Provide the username non-interactively. Defaults to `admin`.
+-   `-p, --password <password>`: Provide the password non-interactively. If this option is omitted, you will be securely prompted to enter a password.
+
+#### `logout [server-url]`
+
+Logs out of a specific Glade session by deleting the stored credentials.
+
+**Usage:**
+```bash
+gingee-cli logout https://prod.my-server.com
+```
+
+#### `list-apps`
+
+Lists all applications installed on the target server.
+
+**Usage:**
+```bash
+gingee-cli list-apps --server https://prod.my-server.com
+```
+
+**Options:**
+-   `-s, --server <url>` (Optional): The base URL of the target Gingee server. Defaults to the server you last logged into, or `http://localhost:7070`.
+
+---
+
+### Application Lifecycle Management
+
+These powerful commands allow for remote deployment and management of your applications.
+
+| Command | Description |
+| :--- | :--- |
+| **`package-app`** | Packages a live application from the server into a distributable `.gin` archive file. |
+| **`install-app`** | Installs a new application onto a server from a local `.gin` package file. |
+| **`upgrade-app`** | Upgrades an existing application on a server using a new `.gin` package file. |
+| **`delete-app`** | Permanently deletes an application and all its content from the server. |
+
+**Common Options for Lifecycle Commands:**
+-   `-s, --server <url>` (Optional): The URL of the target server. Defaults to the last-logged-in server.
+-   `-a, --appName <app-name>` (Required): The name of the target application.
+-   `-p, --ginPath <path>` (Required for install/upgrade): The path to the local `.gin` package file.
+
+**Example Usage:**```bash
+# Upgrade the 'my-blog' app on a production server
+gingee-cli upgrade-app --appName my-blog --ginPath ./builds/my-blog-v2.gin --server https://prod.server```
+
+---
+
+### Backup & Recovery
+
+Commands for the disaster recovery and rollback features.
+
+| Command | Description |
+| :--- | :--- |
+| **`list-app-backups`** | Lists all available `.gin` backup files for an application stored on the server. |
+| **`rollback-app`** | Rolls an application back to its most recently created backup on the server. |
+
+**Common Options for Recovery Commands:**
+-   `-s, --server <url>` (Optional): The URL of the target server.
+-   `-a, --appName <app-name>` (Required): The name of the target application.
+
+---
+
+### Service Management
+
+Commands for running Gingee as a native background service. These commands must be run from a project's root directory and typically require `sudo` or Administrator privileges.
+
+-   **`service install`**: Installs and starts the server as a background service.
+-   **`service uninstall`**: Stops and removes the background service.
+-   **`service start`**: Manually starts the installed service.
+-   **`service stop`**: Manually stops the installed service.
+
+### Local Utilities
+
+-   **`reset-pwd`**: A local recovery tool. Prompts for a new admin user password for `glade` admin panel.
+-   **`reset-glade`**: A local recovery tool that performs a clean re-installation or reset of the `glade` admin panel.

package/commands/addApp.js

@@ -0,0 +1,126 @@
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto'); // Use Node's built-in crypto for the JWT
+const { getProjectRoot, getWebRoot } = require('./utils');
+
+async function addApp(appName) {
+    const { default: chalk } = await import('chalk');
+    const { default: inquirer } = await import('inquirer');
+
+    try {
+        const projectRoot = getProjectRoot();
+        const webRoot = getWebRoot(projectRoot);
+        const appPath = path.join(webRoot, appName);
+
+        if (fs.existsSync(appPath)) {
+            throw new Error(`An application named '${appName}' already exists at ${appPath}`);
+        }
+
+        console.log(`Creating a new Gingee app named '${appName}'...`);
+
+        // --- Run the interactive wizard ---
+        const answers = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'type',
+                message: 'What type of app is this?',
+                choices: ['MPA', 'SPA'],
+                default: 'MPA',
+            },
+            {
+                type: 'confirm',
+                name: 'configureDb',
+                message: 'Would you like to configure a database connection now?',
+                default: false,
+            },
+            {
+                type: 'list',
+                name: 'dbType',
+                message: 'Select Database Type:',
+                choices: ['postgres', 'mysql', 'sqlite', 'mssql', 'oracle'],
+                when: (ans) => ans.configureDb,
+            },
+            {
+                type: 'input', name: 'dbName', message: 'Connection Name (e.g., main_db):', default: 'main_db', 
+                when: (ans) => ans.configureDb,
+            },
+            {
+                type: 'input', name: 'dbHost', message: 'Database Host:', default: 'localhost', 
+                when: (ans) => ans.configureDb && ans.dbType !== 'sqlite',
+            },
+            {
+                type: 'input', name: 'dbUser', message: 'Database User:', 
+                when: (ans) => ans.configureDb && ans.dbType !== 'sqlite',
+            },
+            {
+                type: 'password', name: 'dbPass', message: 'Database Password:', mask: '*', 
+                when: (ans) => ans.configureDb && ans.dbType !== 'sqlite',
+            },
+            {
+                type: 'input', name: 'dbDatabase', message: 'Database Name:', 
+                when: (ans) => ans.configureDb && ans.dbType !== 'sqlite',
+            },
+            {
+                type: 'input', name: 'dbFile', message: 'Database File Path (relative to box folder):', default: 'data/app.db', 
+                when: (ans) => ans.dbType === 'sqlite',
+            },
+            {
+                type: 'confirm',
+                name: 'configureJwt',
+                message: 'Generate a JWT secret for this app?',
+                default: false,
+            },
+        ]);
+
+        // --- Scaffold the files and folders ---
+        console.log('Scaffolding app structure...');
+        const boxPath = path.join(appPath, 'box');
+        fs.ensureDirSync(boxPath);
+        fs.ensureDirSync(path.join(appPath, 'css'));
+        fs.ensureDirSync(path.join(appPath, 'images'));
+        fs.ensureDirSync(path.join(appPath, 'scripts'));
+
+        // --- Create app.json ---
+        const appConfig = { name: appName, version: '1.0.0', type: answers.type };
+        if (answers.configureDb) {
+            appConfig.db = [{
+                type: answers.dbType,
+                name: answers.dbName,
+                host: answers.dbHost,
+                user: answers.dbUser,
+                password: answers.dbPass,
+                database: answers.dbType === 'sqlite' ? answers.dbFile : answers.dbDatabase,
+            }];
+        }
+        if (answers.configureJwt) {
+            appConfig.jwt_secret = crypto.randomBytes(32).toString('hex');
+        }
+        fs.writeJsonSync(path.join(boxPath, 'app.json'), appConfig, { spaces: 2 });
+
+        // --- Create hello.js ---
+        const helloScriptContent = `module.exports = async function() {\n   await gingee(async ($g) => {\n        $g.response.send({ message: 'Hello from the ${appName} server script!' });\n    });\n};`;
+        fs.writeFileSync(path.join(boxPath, 'hello.js'), helloScriptContent);
+
+        // --- Create index.html ---
+        const indexHtmlContent = `<!DOCTYPE html>\n<html lang="en">\n<head>\n  <meta charset="UTF-8">\n  <title>${appName}</title>\n</head>\n<body>\n  <h1>${appName}</h1>\n  <button id="helloButton">Say Hello</button>\n  <div id="response" style="margin-top: 1rem; font-family: monospace;"></div>\n  <script src="/${appName}/scripts/cl_app.js"></script>\n</body>\n</html>`;
+        fs.writeFileSync(path.join(appPath, 'index.html'), indexHtmlContent);
+
+        // --- Create cl_app.js ---
+        const clAppJsContent = `document.getElementById('helloButton').addEventListener('click', async () => {\n    const responseElement = document.getElementById('response');\n    responseElement.innerText = 'Loading...';\n    try {\n        const res = await fetch('/${appName}/hello');\n        const data = await res.json();\n        responseElement.innerText = \`Server says: \${data.message}\`;\n    } catch (err) {\n        responseElement.innerText = 'Error: Could not connect to server.';\n    }\n});`;
+        fs.writeFileSync(path.join(appPath, 'scripts', 'cl_app.js'), clAppJsContent);
+
+        console.log(chalk.bgGreen(`\n✅ Success!`), chalk.blueBright(`App '${appName}' created.`));
+        console.log(`   Navigate to /${appName} in your browser to see it in action.`);
+
+    } catch (err) {
+        if (err.errors) { //for AggregateError
+            const messages = err.errors.map(e => e.message).join('\n');
+            console.error(chalk.bgRed(`Error: `), chalk.blueBright(`${messages}`));
+        } else {
+            console.error(chalk.bgRed(`\nError: `), chalk.blueBright(`${err.message}`));
+        }
+        process.exit(1);
+    }
+}
+
+module.exports = { addApp };

package/commands/addScript.js

@@ -0,0 +1,45 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { getProjectRoot, getWebRoot } = require('./utils');
+
+// The function signature now accepts two distinct arguments.
+async function addScript(appName, scriptPath) {
+    const { default: chalk } = await import('chalk');
+    
+    try {
+        const projectRoot = getProjectRoot();
+        const webRoot = getWebRoot(projectRoot);
+
+        const appPath = path.join(webRoot, appName);
+        if (!fs.existsSync(appPath)) {
+            throw new Error(`Application '${appName}' does not exist at: ${appPath}`);
+        }
+
+        const finalPath = path.join(appPath, 'box', scriptPath + '.js');
+
+        if (fs.existsSync(finalPath)) {
+            throw new Error(`Script already exists at: ${path.relative(projectRoot, finalPath)}`);
+        }
+
+        fs.ensureDirSync(path.dirname(finalPath));
+
+        const boilerplate = `module.exports = async function() {\n    await gingee(async ($g) => {\n        // Your script logic goes here\n        $g.response.send('Hello from ${scriptPath}');\n    });\n};`;
+
+        fs.writeFileSync(finalPath, boilerplate);
+
+        console.log(chalk.bgGreen(`✅ Success!`), chalk.blueBright(`Script created at:`));
+        console.log(chalk.blueBright(`   ${path.relative(projectRoot, finalPath)}`));
+        console.log(`\n   You can access it at the URL: /${appName}/${scriptPath}`);
+
+    } catch (err) {
+        if (err.errors) { //for AggregateError
+            const messages = err.errors.map(e => e.message).join('\n');
+            console.error(chalk.bgRed(`Error: `), chalk.blueBright(`${messages}`));
+        } else {
+            console.error(chalk.bgRed(`\nError: `), chalk.blueBright(`${err.message}`));
+        }
+        process.exit(1);
+    }
+}
+
+module.exports = { addScript };

package/commands/apiClient.js

@@ -0,0 +1,139 @@
+const axios = require('axios');
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const configDir = path.join(os.homedir(), '.gingee');
+const credsDir = path.join(configDir, 'sessions');
+
+/**
+ * Sanitizes a server URL into a safe filename.
+ * @private
+ */
+function getCredsFilePath(serverUrl) {
+    // Use a hash to create a unique, fixed-length, safe filename
+    const hash = crypto.createHash('sha256').update(serverUrl).digest('hex');
+    if (!fs.existsSync(credsDir)) {
+        fs.mkdirSync(credsDir);
+    }
+    return path.join(credsDir, `${hash}.json`);
+}
+
+/**
+ * Creates an authenticated axios instance by manually adding the session cookie.
+ * @returns {Promise<{client: import('axios').AxiosInstance, serverUrl: string}>}
+ */
+async function getAuthenticatedClient(serverUrl = 'http://localhost:7070') {
+    const credsPath = getCredsFilePath(serverUrl);
+
+    if (!fs.existsSync(credsPath)) {
+        throw new Error("You are not logged in. Please run `gingee-cli login <server-url>` first.");
+    }
+    
+    const { cookie } = fs.readJsonSync(credsPath);
+    if (!serverUrl || !cookie) {
+        throw new Error("Credentials file is corrupted or empty. Please log in again.");
+    }
+    
+    // Create a standard axios instance.
+    const client = axios.create();
+    
+    // Manually set the 'Cookie' header for all requests made with this instance.
+    client.defaults.headers.common['Cookie'] = cookie;
+    
+    return { client, serverUrl };
+}
+
+function deleteSession(serverUrl) {
+    const credsPath = getCredsFilePath(serverUrl);
+    if (fs.existsSync(credsPath)) {
+        fs.removeSync(credsPath);
+    }
+}
+
+async function installApp(serverUrl, appName, ginFileName, ginFileBuffer, permissions) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const FormData = require('form-data');
+    
+    const form = new FormData();
+    form.append('appName', appName);
+    form.append('package', ginFileBuffer, ginFileName);
+    form.append('permissions', JSON.stringify(permissions));
+
+    const response = await client.post(`${serverUrl}/glade/api/install`, form, {
+        headers: form.getHeaders()
+    });
+    return response.data;
+}
+
+async function upgradeApp(serverUrl, appName, ginFileName, ginFileBuffer, permissions) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const FormData = require('form-data');
+    
+    const form = new FormData();
+    form.append('appName', appName);
+    form.append('package', ginFileBuffer, ginFileName);
+    form.append('permissions', JSON.stringify(permissions));
+
+    const response = await client.post(`${serverUrl}/glade/api/upgrade`, form, {
+        headers: form.getHeaders()
+    });
+    return response.data;
+}
+
+async function deleteApp(serverUrl, appName) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const response = await client.get(`${serverUrl}/glade/api/delete?app=${appName}`);
+    return response.data;
+}
+
+async function rollbackApp(serverUrl, appName, grantedPermissions) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const response = await client.post(`${serverUrl}/glade/api/rollback`, {
+        appName,
+        permissions: grantedPermissions
+    });
+    return response.data;
+}
+
+async function listBackups(serverUrl, appName) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const response = await client.get(`${serverUrl}/glade/api/list-backups?app=${appName}`);
+    return response.data;
+}
+
+async function packageApp(serverUrl, appName) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    // CRITICAL: We expect a binary stream, so set responseType to 'stream'.
+    const response = await client.get(`${serverUrl}/glade/api/package?app=${appName}`, {
+        responseType: 'stream'
+    });
+    return response;
+}
+
+async function analyzeBackup(serverUrl, appName) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const response = await client.get(`${serverUrl}/glade/api/analyze-backup?app=${appName}`);
+    return response.data;
+}
+
+async function getAppPermissions(serverUrl, appName) {
+    const { client } = await getAuthenticatedClient(serverUrl);
+    const response = await client.get(`${serverUrl}/glade/api/get-permissions?app=${appName}`);
+    return response.data;
+}
+
+module.exports = { 
+    getCredsFilePath, 
+    getAuthenticatedClient, 
+    deleteSession,
+    installApp,
+    upgradeApp,
+    deleteApp,
+    rollbackApp,
+    listBackups,
+    packageApp,
+    analyzeBackup,
+    getAppPermissions
+};

package/commands/deleteApp.js

@@ -0,0 +1,62 @@
+const apiClient = require('./apiClient');
+const { _readAppPreset, _validateAppPreset } = require('./installerUtils');
+
+async function deleteApp(options) {
+    const { default: chalk } = await import('chalk');
+    const { default: ora } = await import('ora');
+    const { default: inquirer } = await import('inquirer');
+    const { serverUrl, appName, file: presetFilePath } = options;
+
+    const spinner = ora();
+
+    try {
+        let confirmation = false;
+        if (presetFilePath) {
+            // --- NON-INTERACTIVE MODE ---
+            console.log(chalk.blue(`Running in non-interactive mode using preset file: ${presetFilePath}`));
+            const preset = _readAppPreset(presetFilePath);
+            _validateAppPreset(preset, 'delete');
+            confirmation = preset.delete.confirm; // This will be true if validation passed
+        } else {
+            const { confirmDelete } = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'confirmDelete',
+                    message: `This will ${chalk.bgRed('PERMANENTLY DELETE')} the application '${chalk.bgRed(appName)}' and all its content.\n  This action cannot be undone. To confirm, please type the name of the app:`
+                }
+            ]);
+            if (confirmDelete === appName) {
+                confirmation = true;
+            } else {
+                throw new Error('Confirmation text did not match. Deletion cancelled.');
+            }
+        }
+
+        if (confirmation) {
+            spinner.start(`Deleting app '${appName}'...`)
+            const result = await apiClient.deleteApp(serverUrl, appName);
+
+            if (result.status !== 'success') {
+                throw new Error(result.message || 'Server responded with an unknown error.');
+            }
+
+            spinner.succeed(chalk.bgGreen(`✅ Success!`));
+            console.log(chalk.blueBright(`App '${appName}' deleted from Gingee Server - ${serverUrl}`));
+        } else {
+            console.log(chalk.bgGreen(`Canceled: `), chalk.blueBright('Deletion cancelled. No changes made.'));
+        }
+
+    } catch (err) {
+        spinner.fail(chalk.bgRed('Deletion failed.'));
+        if (err.errors) { //for AggregateError
+            const messages = err.errors.map(e => e.message).join('\n');
+            console.error(chalk.bgRed(`Error: `), chalk.blueBright(`${messages}`));
+        } else {
+            const message = err.response ? (err.response.data.message || 'Server error.') : err.message;
+            console.error(chalk.bgRed(`Error: `), chalk.blueBright(`${message}`));
+        }
+        process.exit(1);
+    }
+}
+
+module.exports = { deleteApp };