gingee-cli 1.0.3 → 1.0.5

package/README.md

@@ -1,16 +1,58 @@
 # 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.
+The `gingee-cli` is the official, all-in-one command-line interface for the Gingee platform. 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.
+NOTE: You might need to install pre-requistes based on your setup.
 
 ```bash
 npm install -g gingee-cli
 ```
 After installation, you will have access to the `gingee-cli` command in your terminal.
 
+## Verifying the Installation
+
+After the installation is complete, you can verify that it was successful by running the version command:
+```bash
+gingee-cli --version
+```
+This should print the installed version number of the CLI.
+
+## Platform Specific Requirements
+
+### **Windows**
+For most Windows users, no additional setup is required. The standard Node.js installer from [nodejs.org](https://nodejs.org/) includes everything you need.
+
+For advanced users or those who encounter issues, it's recommended to install the Node.js build tools by running the following command in an **Administrator PowerShell**:
+
+```code
+npm install --global windows-build-tools
+```
+
+### **macOS**
+macOS users need the **Xcode Command Line Tools**. Most developer-focused setups will already have this. You can install them by running:
+
+```bash
+xcode-select --install
+```
+If you already have them, this command will report an error, which you can safely ignore.
+
+### **Linux (Debian/Ubuntu)**
+Linux systems require a C++ compiler toolchain to build some of the CLI's dependencies. You can install the necessary packages by running:
+
+```bash
+sudo apt-get update && sudo apt-get install -y build-essential python
+```
+
+### **Linux (RHEL/Fedora/CentOS)**
+For Red Hat-based distributions, you can install the necessary build tools with:
+
+```bash
+sudo yum groupinstall "Development Tools" && sudo yum install python3
+```
+
 ---
 
 ## Commands
@@ -25,7 +67,7 @@ Scaffolds a complete, new Gingee project in a new directory. It launches an inte
 
 **Usage:**
 ```bash
-gingee-cli init my-awesome-project```
+gingee-cli init my-awesome-project
 ```
 
 **Wizard Prompts:**
@@ -50,6 +92,8 @@ 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).
+-   If `MPA` is chosen, it scaffolds a complete "hello world" application with HTML, CSS, and JS.
+-   If `SPA` is chosen, it scaffolds a minimal backend structure (`box/`, `app.json`) and provides clear instructions for you to initialize your chosen frontend framework inside the app's directory.
 -   `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`.
 
@@ -81,10 +125,11 @@ gingee-cli login
 
 -  Login to a remote server
 ```bash
-gingee-cli login https://prod.my-server.com
+gingee-cli login -s http://remote-gingee:7070
 ```
 
 **Options:**
+-   `-s, --serverUrl <server-url>`: The target Gingee server URL. Defaults to `http://localhost:7070`.
 -   `-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.
 
@@ -94,20 +139,78 @@ Logs out of a specific Glade session by deleting the stored credentials.
 
 **Usage:**
 ```bash
-gingee-cli logout https://prod.my-server.com
+gingee-cli logout -s http://remote-gingee:7070
 ```
 
+**Options:**
+-   `-s, --serverUrl <server-url>`: The target Gingee server URL. Defaults to `http://localhost:7070`
+
 #### `list-apps`
 
 Lists all applications installed on the target server.
 
 **Usage:**
 ```bash
-gingee-cli list-apps --server https://prod.my-server.com
+gingee-cli list-apps -s https://remote-gingee:7070
+```
+
+**Options:**
+-   `-s, --server <url>` (Optional): The base URL of the target Gingee server. Defaults to `http://localhost:7070`.
+
+---
+
+### App Store Commands
+
+These commands allow you to discover and install applications from a decentralized "app store," which is simply a server hosting a `store.json` manifest file.
+
+#### `list-store-apps`
+
+Fetches the manifest from a store URL and displays a list of available applications.
+
+**Usage:**
+```bash
+gingee-cli list-store-apps -g https://my-store.example.com
+```
+
+**Options:**
+-   `-g, --gStoreUrl <gstore-url>` (Optional): The Gingee App Store url
+
+#### `install-store-app <app-name>`
+
+Initiates an interactive installation of an application from a store. The CLI will:
+1.  Download the app's `.gin` package.
+2.  Read the app's required permissions from its internal `pmft.json` manifest.
+3.  Prompt you for consent to grant these permissions.
+4.  Prompt you to configure any requirements (like database connections).
+5.  Repackage the app with your configuration and securely install it on your target Gingee server.
+
+**Usage:**
+```bash
+gingee-cli install-store-app my-blog-app -g https://my-store.example.com  -s http://<remote-gingee>
 ```
 
 **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`.
+-   `-g, --gStoreUrl <gstore-url>` (Optional): The Gingee App Store url
+-   `-s, --server <url>` (Optional): The base URL of the target Gingee server. Defaults to `http://localhost:7070`
+
+#### `upgrade-store-app <app-name>`
+
+Initiates an interactive installation of an application from a store. The CLI will:
+1.  Download the app's `.gin` package.
+2.  Read the app's required permissions from its internal `pmft.json` manifest.
+3.  Create the new set of permissions that are requested. (auto assigns previous version grants)
+4.  Prompt you for consent to grant these permissions.
+5.  Prompt you to configure any requirements (like database connections).
+6.  Repackage the app with your configuration and securely install it on your target Gingee server.
+
+**Usage:**
+```bash
+gingee-cli install-store-app my-blog-app -g https://my-store.example.com  -s http://<remote-gingee>
+```
+
+**Options:**
+-   `-g, --gStoreUrl <gstore-url>` (Optional): The Gingee App Store url
+-   `-s, --server <url>` (Optional): The base URL of the target Gingee server. Defaults to `http://localhost:7070`
 
 ---
 
@@ -126,10 +229,13 @@ These powerful commands allow for remote deployment and management of your appli
 -   `-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.
+-   `-f, --file <path>` (Automation): Provide a preset file for non-interactive execution.
 
-**Example Usage:**```bash
+**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```
+gingee-cli upgrade-app --appName my-blog --ginPath ./builds/my-blog-v2.gin --server https://prod.server
+```
 
 ---
 
@@ -145,9 +251,58 @@ Commands for the disaster recovery and rollback features.
 **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.
+-   `-f, --file <path>` (Automation): Provide a preset file for non-interactive execution.
 
 ---
 
+### **Automation with Preset Files**
+
+For use in CI/CD pipelines or other automated scripts, the lifecycle commands (`install-app`, `upgrade-app`, `rollback-app`, `delete-app`) can be run in a non-interactive mode by providing a preset file using the `-f, --file <path>` option.
+
+The preset file is a simple JSON file that contains the configuration for the action you want to perform. The CLI will use the values from this file instead of showing interactive prompts.
+
+**Example `myapp-deploy-presets.json`:**
+```json
+{
+  "upgrade": {
+    "ginPath": "./build/my-blog-app-v2.gin",
+    "consent": {
+      "grantPermissions": ["db", "fs", "httpclient"]
+    },
+    "config": {
+      "db": [
+        {
+          "name": "main_db",
+          "host": "prod-db.cluster.internal",
+          "user": "prod_user",
+          "password": "$DB_PASSWORD_PROD",
+          "database": "blog_production"
+        }
+      ]
+    }
+  },
+  "rollback": {
+    "consent": {
+      "grantPermissions": ["db", "fs"]
+    }
+  },
+  "delete": {
+    "confirm": true
+  }
+}
+```
+
+**Security with Environment Variables:**
+For sensitive values like passwords, you can use environment variable placeholders (a string starting with `$`). The CLI will automatically substitute `$VAR_NAME` with the value of the `process.env.VAR_NAME` variable at runtime.
+
+**Example Usage in a CI/CD script:**
+```bash
+# The server URL and app name are still passed as arguments for safety
+export DB_PASSWORD_PROD="a-very-secret-password"
+gingee-cli upgrade-app --appName my-blog-app --serverUrl https://prod.server --file ./deploy.json
+```
+---
+
 ### 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.
@@ -157,6 +312,8 @@ Commands for running Gingee as a native background service. These commands must
 -   **`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.

package/commands/init.js

@@ -56,8 +56,9 @@ async function init(projectName) {
 
     spinner.start('Scaffolding project files...');
     fs.mkdirSync(projectPath);
-    const templatePath = path.join(__dirname, '..', 'templates', 'project');
-    fs.copySync(templatePath, projectPath);
+    const templatePath = path.join(__dirname, '..', 'templates');
+    const projectTemplatePath = path.join(templatePath, 'project');
+    fs.copySync(projectTemplatePath, projectPath);
 
     const pkgJsonPath = path.join(projectPath, 'package.json');
     const pkgJson = fs.readJsonSync(pkgJsonPath);
@@ -73,7 +74,7 @@ async function init(projectName) {
 
     // Find the glade.gin file using require.resolve, which is robust.
     // It looks for the 'gingee' package in the CLI's own node_modules.
-    const gladeGinPath = require.resolve('gingee/templates/glade.gin');
+    const gladeGinPath = path.join(templatePath, 'glade.gin');
     const gladePackageBuffer = fs.readFileSync(gladeGinPath);
     const gladeDestPath = path.join(projectPath, 'web', 'glade');
 

package/commands/resetGlade.js

@@ -43,7 +43,8 @@ async function resetGlade() {
 
         // --- Re-installation ---
         spinner.start('Installing a clean version of `glade`...');
-        const gladeGinPath = require.resolve('gingee/templates/glade.gin');
+        const templatePath = path.join(__dirname, '..', 'templates');
+        const gladeGinPath = path.join(templatePath, 'glade.gin');
         const gladePackageBuffer = fs.readFileSync(gladeGinPath);
         await _unzipBuffer(gladePackageBuffer, gladeAppPath);
         spinner.succeed('Clean `glade` version installed.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gingee-cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "The Gingee Command Line Interface (CLI), official command line tool for creating and managing Gingee projects.",
   "main": "index.js",
   "bin": {
@@ -41,7 +41,6 @@
     "commander": "^14.0.0",
     "form-data": "^4.0.4",
     "fs-extra": "^11.3.1",
-    "gingee": "^1.0.2",
     "inquirer": "^12.9.2",
     "ora": "^8.2.0",
     "yauzl": "^3.2.0"

package/templates/project/package.json

@@ -7,7 +7,7 @@
     "dev": "nodemon start.js"
   },
   "dependencies": {
-    "gingee": "^1.0.0"
+    "gingee": "^1.0.3"
   },
   "devDependencies": {
     "nodemon": "^3.0.0"