simplemdg-dev-cli 1.5.1 → 2.4.4

package/README.md

@@ -1,283 +1,105 @@
-# SimpleMDG Dev CLI Guide
+# SimpleMDG Dev CLI
 
-## Purpose
+SimpleMDG local development helper for npm install workflows, SAP CAP, Cloud Foundry/BTP, request tracing, GitLab sync, and BTP database exploration.
 
-`simplemdg-dev-cli` helps SimpleMDG developers run common local development and BTP tasks without remembering long commands.
+## Install local package
 
-Main command:
-
-```bash
-smdg
-```
-
-Install:
-
-```bash
-npm i -g simplemdg-dev-cli@latest
-```
-
-Open this guide:
-
-```bash
-smdg guide
-```
-
----
-
-# Select Usage
-
-When the CLI shows a select list:
-
-* Type a few characters to search.
-* Use `↑` and `↓` to move.
-* Press `Enter` to select.
-* If no item matches, some prompts allow using the typed value.
-
-This is useful for long lists of BTP orgs, spaces, apps, package IDs, CAP profiles, and CDS services.
-
----
-
-# Common Commands
-
-## `smdg npmrc import`
-
-Import SimpleMDG GitLab package IDs into local cache.
-
-Use this after downloading the package ID import file from the team.
-
-```bash
-smdg npmrc import
+```powershell
+npm install -g .\simplemdg-dev-cli-2.4.0.tgz --force
+smdg -V
 ```
 
-## `smdg npmrc create`
+## Prerequisites & auto-install
 
-Create `.npmrc` for SimpleMDG private npm packages.
+Some commands rely on external CLIs: `cf` (Cloud Foundry), `cds` (SAP CAP), and `git`. The CLI checks for these **before** running an interactive flow — so you are not asked for credentials only to fail at the end. If a tool is missing, it offers to install it via a detected package manager (`choco`/`brew` for `cf`, `winget`/`choco`/`scoop`/`brew`/`apt-get` for `git`, `npm -g` for `@sap/cds-dk`), or prints the official install link when no manager is available. After installing a tool, open a new terminal so PATH refreshes.
 
-```bash
-smdg npmrc create
-```
+## Main commands
 
-The CLI helps select package name/package ID and token from cache.
-
-## `smdg i`
-
-Install dependencies for the current project.
-
-```bash
+```powershell
 smdg i
-```
-
-It can scan variables such as `${SIMPLEMDG_BRANCH}` and ask for replacement values automatically.
-
-## `smdg cf login`
-
-Login to BTP Cloud Foundry.
-
-```bash
 smdg cf login
-```
-
-The CLI helps select API endpoint, org, and space.
-
-It can save login information on your local machine so later commands can re-login automatically when the CF session expires.
-
-## `smdg cf org`
-
-Search, list, and switch Cloud Foundry orgs across regions.
-
-```bash
-smdg cf org
-```
-
-The CLI scans known BTP region endpoints and shows orgs in one searchable list.
-
-The list includes region information, for example:
-
-```txt
-arthrex-dev-simplemdg    eu10 · 1 space
-alcon-dev-simplemdg      br10 · 1 space
-ait-dev-simplemdg        us21 · 1 space
-```
-
-Use this when you have many orgs across many BTP regions.
-
-## `smdg cf target`
-
-Show the current Cloud Foundry target.
-
-```bash
-smdg cf target
-```
-
-It shows API endpoint, user, org, and space.
-
-## `smdg cf apps`
-
-List BTP apps in the current org and space.
-
-```bash
 smdg cf apps
-```
-
-The CLI uses cache first for speed and refreshes in the background.
-
-## `smdg cf bind`
-
-Bind the local CAP project to a deployed BTP app service.
-
-```bash
 smdg cf bind
-```
-
-This helps run `cds bind --to-app-services` and update `.cdsrc-private.json`.
-
-## `smdg cf env`
-
-Export BTP app environment variables to a clean JSON file.
-
-```bash
 smdg cf env
-```
-
-Useful for creating `default-env.json`.
-
-## `smdg cds watch`
-
-Run CAP locally.
-
-```bash
-smdg cds watch
-```
-
-The CLI helps select CAP profile and port.
-
-## `smdg cf logs`
-
-View BTP app logs.
-
-```bash
 smdg cf logs
+smdg cf request-trace
+smdg gitlab login
+smdg gitlab clone
+smdg gitlab pull
+smdg cf db studio
 ```
 
-It can be used for realtime log monitoring.
-
-## `smdg cf debug`
+## GitLab sync
 
-Debug a deployed BTP Cloud Foundry Node.js app.
+`gitlab` commands are implemented in the same source-code style as the existing CLI: command registration stays in `src/commands`, reusable logic stays close to the command, and cache files are stored under `~/.simplemdg`.
 
-```bash
-smdg cf debug
+```powershell
+smdg gitlab login
+smdg gitlab groups
+smdg gitlab clone
 ```
 
-The CLI guides you through:
+The clone/pull flow separates:
 
-* selecting current target or searching orgs across regions
-* selecting BTP app
-* selecting debug mode
-* selecting app instance
-* preparing Node.js inspector
-* creating VS Code attach config
-* opening the CF SSH tunnel
-
-Recommended mode:
-
-```txt
-VS Code guided debugging
-```
+- pull/clone a root group
+- pull/clone a single repository
 
-Important VS Code note:
+It uses GitLab API and native `git`, so `ghorg` is not required. Pulling can run multiple repositories in parallel and skips invalid branch refs such as `origin` and `origin/HEAD`.
 
-The debug toolbar buttons such as pause, step over, restart, and stop only appear after VS Code successfully attaches to the running Node.js inspector.
+## CF DB Studio
 
-Normal flow:
-
-1. Run `smdg cf debug`.
-2. Select `VS Code guided debugging`.
-3. First time for an app, select `Set NODE_OPTIONS and restart app`.
-4. Keep the terminal open because it owns the CF SSH tunnel.
-5. In VS Code, open Run and Debug with `Ctrl+Shift+D`.
-6. Select `Attach BTP <app-name>`.
-7. Press `F5` or the green Start Debugging button.
-8. After attach succeeds, the debug toolbar appears.
-
-Use this mainly in dev/test environments because enabling Node inspector restarts the BTP app.
-
-## `smdg cds compline`
-
-Generate metadata XML from CDS services.
-
-```bash
-smdg cds compline
-```
+A local, browser-based database explorer (HANA / PostgreSQL) styled after SAP HANA Database Explorer and DBeaver, with deep BTP/Cloud Foundry integration.
 
-The CLI scans CDS services, suggests output XML names, and writes XML using UTF-8 encoding.
-
----
-
-# Recommended Daily Flow
-
-```bash
-smdg npmrc create
-smdg i
+```powershell
 smdg cf login
-smdg cf apps
-smdg cf bind
-smdg cf env
-smdg cds watch
+smdg cf db studio
 ```
 
-For logs:
+Studio starts a local web server bound to `127.0.0.1` only (auto-selects a free port) and opens your browser. It can:
 
-```bash
-smdg cf logs
-```
-
-For BTP debugging:
+- import database credentials directly from a BTP app's `cf env` (`VCAP_SERVICES`) — no manual copy/paste
+- **add direct connections manually** (host/port/user/password) for databases not behind a CF app, e.g. Neon — like a DBeaver connection
+- detect SAP HANA and PostgreSQL services automatically
+- cache connections locally with the password **encrypted** (never stored in plain text, never sent to the browser)
+- browse schemas, tables, views, columns, indexes, procedures, functions, synonyms (HANA)
+- inspect column metadata incl. type, key, nullable, default, and **comments**
+- open table data with pagination, quick `WHERE` filter, and **click-to-sort** column headers (server-side)
+- **edit data directly in the grid** — double-click a cell to update, insert rows, delete rows; generates parameterized `UPDATE`/`INSERT`/`DELETE` keyed on the primary key (read-only when a table has no PK)
+- run any SQL — including CREATE / ALTER / UPDATE / DDL — across **multiple editor tabs**, with a row-limit selector, execution timing, CSV/JSON export, and clipboard copy
+- generate `SELECT` / `COUNT` / **`CREATE TABLE` DDL** for any object from the explorer
+- save/reload `.sql` query files and keep a query history
+- toggle a **read-only** mode that blocks INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER/CREATE/GRANT/REVOKE
+- confirm before running dangerous SQL (DROP, TRUNCATE, ALTER, DELETE/UPDATE without WHERE)
 
-```bash
-smdg cf debug
-```
-
-For metadata XML:
+### Commands
 
-```bash
-smdg cds compline
+```powershell
+smdg cf db studio        # open the local browser studio
+smdg cf db add           # add a direct connection manually (host/port/user/password)
+smdg cf db import        # import a connection from a BTP app's cf env
+smdg cf db connections   # list/test/rename/duplicate/remove cached connections
+smdg cf db query         # run one SQL query against a cached connection
+smdg cf db console        # interactive terminal SQL console (/help for commands)
 ```
 
----
-
-# Key Features
+In the Studio, click **+ New** in the Connections sidebar to add a direct connection without leaving the browser.
 
-## Private npm registry helper
+`smdg cf db studio` options: `--port <port>` (preferred port), `--read-only`, `--timeout <ms>`.
 
-Creates `.npmrc` for SimpleMDG GitLab npm packages and caches package IDs with readable names.
+### Local cache files
 
-## Smart install helper
-
-Scans project variables like `${SIMPLEMDG_BRANCH}` and asks for values automatically before install.
-
-## Cloud Foundry helper
-
-Helps with login, target checking, org switching, app list, binding, env export, logs, and debugging.
-
-## Across-region org search
-
-Scans known BTP regions and shows orgs from many regions in one searchable list.
-
-## CAP helper
-
-Helps run `cds watch`, select profiles/ports, and generate CDS metadata XML.
-
-## VS Code BTP debugging
-
-Creates VS Code attach config and opens a CF SSH tunnel to debug BTP Node.js apps from local source code.
-
----
+```text
+~/.simplemdg/db-connections.json     # connection profiles (passwords encrypted)
+~/.simplemdg/db-query-history.json   # query history
+~/.simplemdg/db-queries/             # saved .sql query files
+```
 
-# Notes
+Passwords are encrypted with a key derived from the current machine + user, so a copied cache file cannot be decrypted elsewhere.
 
-Do not commit real secrets to Git.
+### Database drivers
 
-Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
+HANA and PostgreSQL drivers are optional dependencies. If a driver is missing, the studio reports it clearly. Install:
 
-Use saved password only on your own machine.
+```powershell
+npm i -g pg @sap/hana-client
+```

package/USER_GUIDE.md

@@ -1,283 +1,89 @@
-# SimpleMDG Dev CLI Guide
+# SimpleMDG CLI User Guide
 
-## Purpose
+## GitLab
 
-`simplemdg-dev-cli` helps SimpleMDG developers run common local development and BTP tasks without remembering long commands.
+Login once:
 
-Main command:
-
-```bash
-smdg
-```
-
-Install:
-
-```bash
-npm i -g simplemdg-dev-cli@latest
-```
-
-Open this guide:
-
-```bash
-smdg guide
-```
-
----
-
-# Select Usage
-
-When the CLI shows a select list:
-
-* Type a few characters to search.
-* Use `↑` and `↓` to move.
-* Press `Enter` to select.
-* If no item matches, some prompts allow using the typed value.
-
-This is useful for long lists of BTP orgs, spaces, apps, package IDs, CAP profiles, and CDS services.
-
----
-
-# Common Commands
-
-## `smdg npmrc import`
-
-Import SimpleMDG GitLab package IDs into local cache.
-
-Use this after downloading the package ID import file from the team.
-
-```bash
-smdg npmrc import
-```
-
-## `smdg npmrc create`
-
-Create `.npmrc` for SimpleMDG private npm packages.
-
-```bash
-smdg npmrc create
-```
-
-The CLI helps select package name/package ID and token from cache.
-
-## `smdg i`
-
-Install dependencies for the current project.
-
-```bash
-smdg i
-```
-
-It can scan variables such as `${SIMPLEMDG_BRANCH}` and ask for replacement values automatically.
-
-## `smdg cf login`
-
-Login to BTP Cloud Foundry.
-
-```bash
-smdg cf login
-```
-
-The CLI helps select API endpoint, org, and space.
-
-It can save login information on your local machine so later commands can re-login automatically when the CF session expires.
-
-## `smdg cf org`
-
-Search, list, and switch Cloud Foundry orgs across regions.
-
-```bash
-smdg cf org
+```powershell
+smdg gitlab login
 ```
 
-The CLI scans known BTP region endpoints and shows orgs in one searchable list.
+The CLI opens the GitLab token page, tries to detect the copied token from clipboard, validates it, caches it, and approves it for Git Credential Manager.
 
-The list includes region information, for example:
+Clone or pull:
 
-```txt
-arthrex-dev-simplemdg    eu10 · 1 space
-alcon-dev-simplemdg      br10 · 1 space
-ait-dev-simplemdg        us21 · 1 space
+```powershell
+smdg gitlab clone
+smdg gitlab pull
 ```
 
-Use this when you have many orgs across many BTP regions.
+The flow is split clearly:
 
-## `smdg cf target`
-
-Show the current Cloud Foundry target.
-
-```bash
-smdg cf target
-```
+1. Pull/clone a GitLab group
+2. Pull/clone a single repository
 
-It shows API endpoint, user, org, and space.
+Then select root group, destination folder, sync action, and parallel jobs.
 
-## `smdg cf apps`
+## CF DB Studio
 
-List BTP apps in the current org and space.
+A local database explorer for SAP HANA and PostgreSQL, with one-click import of credentials from BTP apps. The studio runs a web server bound to `127.0.0.1` only and opens your browser.
 
-```bash
-smdg cf apps
-```
+### Recommended flow
 
-The CLI uses cache first for speed and refreshes in the background.
+1. Run `smdg cf login` (once; you can save the password for auto re-login)
+2. Run `smdg cf db studio`
+3. Open the **BTP Import** tab → **Load CF apps**
+4. Select an app → its `cf env` is read and database services are detected
+5. Click **Save+Use** on a detected service → the connection is tested and activated
+6. Pick the connection in the left sidebar, choose a schema
+7. Browse tables/views in the Object Explorer, or write SQL in the **SQL Console**
+8. Run with **Ctrl+Enter**, export to CSV/JSON, save the query, or open table **Data**
 
-## `smdg cf bind`
+The studio never deploys anything to BTP and never shows the database password.
 
-Bind the local CAP project to a deployed BTP app service.
+### Studio tabs
 
-```bash
-smdg cf bind
-```
+- **SQL Console** — multiple editor tabs, run (Ctrl+Enter), format, explain (PostgreSQL), row-limit selector, export CSV/JSON, save query
+- **Data Grid** — paginated table data with WHERE filter, click-to-sort headers, export, and inline editing
+- **Metadata** — columns (type, nullable, default, primary key) and indexes
+- **BTP Import** — current CF target, app list, detected services, save/activate
+- **Query Files** — saved `.sql` queries (load, run, rename, delete)
+- **History** — recent queries (click to reload into the editor)
+- **Messages** — log of every action and error
 
-This helps run `cds bind --to-app-services` and update `.cdsrc-private.json`.
+### Read-only and dangerous SQL
 
-## `smdg cf env`
+Toggle **Read-only** in the top bar to block INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER/CREATE/GRANT/REVOKE. Even in read/write mode, dangerous statements (DROP, TRUNCATE, ALTER, DELETE/UPDATE without WHERE) require confirmation. A "Production-like" badge appears for prod-looking orgs/apps.
 
-Export BTP app environment variables to a clean JSON file.
+### Terminal alternatives
 
-```bash
-smdg cf env
+```powershell
+smdg cf db add           # add a direct connection manually (host/port/user/password)
+smdg cf db import        # interactive import from a BTP app
+smdg cf db connections   # manage cached connections
+smdg cf db query         # run one SQL query and print/export the result
+smdg cf db console        # interactive SQL REPL
 ```
 
-Useful for creating `default-env.json`.
+### Direct connections (no CF app)
 
-## `smdg cds watch`
+Not every database is behind a Cloud Foundry app (for example a Neon PostgreSQL or a standalone HANA Cloud). Add those directly:
 
-Run CAP locally.
+- In the Studio: click **+ New** in the Connections sidebar, fill in type/host/port/database/schema/user/password, click **Test**, then **Save & use**.
+- In the terminal: `smdg cf db add`.
 
-```bash
-smdg cds watch
-```
+Direct connections are cached and encrypted exactly like imported ones, so they reappear next time you open the Studio.
 
-The CLI helps select CAP profile and port.
+Console slash commands: `/connect`, `/schemas`, `/tables`, `/desc TABLE`, `/top TABLE`, `/count TABLE`, `/save NAME`, `/history`, `/export csv|json`, `/full`, `/clear`, `/help`, `/exit`.
 
-## `smdg cf logs`
+## DB cache
 
-View BTP app logs.
+Connections are cached under:
 
-```bash
-smdg cf logs
+```text
+~/.simplemdg/db-connections.json
 ```
 
-It can be used for realtime log monitoring.
-
-## `smdg cf debug`
-
-Debug a deployed BTP Cloud Foundry Node.js app.
-
-```bash
-smdg cf debug
-```
-
-The CLI guides you through:
-
-* selecting current target or searching orgs across regions
-* selecting BTP app
-* selecting debug mode
-* selecting app instance
-* preparing Node.js inspector
-* creating VS Code attach config
-* opening the CF SSH tunnel
-
-Recommended mode:
-
-```txt
-VS Code guided debugging
-```
-
-Important VS Code note:
-
-The debug toolbar buttons such as pause, step over, restart, and stop only appear after VS Code successfully attaches to the running Node.js inspector.
-
-Normal flow:
-
-1. Run `smdg cf debug`.
-2. Select `VS Code guided debugging`.
-3. First time for an app, select `Set NODE_OPTIONS and restart app`.
-4. Keep the terminal open because it owns the CF SSH tunnel.
-5. In VS Code, open Run and Debug with `Ctrl+Shift+D`.
-6. Select `Attach BTP <app-name>`.
-7. Press `F5` or the green Start Debugging button.
-8. After attach succeeds, the debug toolbar appears.
-
-Use this mainly in dev/test environments because enabling Node inspector restarts the BTP app.
-
-## `smdg cds compline`
-
-Generate metadata XML from CDS services.
-
-```bash
-smdg cds compline
-```
-
-The CLI scans CDS services, suggests output XML names, and writes XML using UTF-8 encoding.
-
----
-
-# Recommended Daily Flow
-
-```bash
-smdg npmrc create
-smdg i
-smdg cf login
-smdg cf apps
-smdg cf bind
-smdg cf env
-smdg cds watch
-```
-
-For logs:
-
-```bash
-smdg cf logs
-```
-
-For BTP debugging:
-
-```bash
-smdg cf debug
-```
-
-For metadata XML:
-
-```bash
-smdg cds compline
-```
-
----
-
-# Key Features
-
-## Private npm registry helper
-
-Creates `.npmrc` for SimpleMDG GitLab npm packages and caches package IDs with readable names.
-
-## Smart install helper
-
-Scans project variables like `${SIMPLEMDG_BRANCH}` and asks for values automatically before install.
-
-## Cloud Foundry helper
-
-Helps with login, target checking, org switching, app list, binding, env export, logs, and debugging.
-
-## Across-region org search
-
-Scans known BTP regions and shows orgs from many regions in one searchable list.
-
-## CAP helper
-
-Helps run `cds watch`, select profiles/ports, and generate CDS metadata XML.
-
-## VS Code BTP debugging
-
-Creates VS Code attach config and opens a CF SSH tunnel to debug BTP Node.js apps from local source code.
-
----
-
-# Notes
-
-Do not commit real secrets to Git.
-
-Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
+Saved queries live in `~/.simplemdg/db-queries/` and history in `~/.simplemdg/db-query-history.json`.
 
-Use saved password only on your own machine.
+Passwords are encrypted with a key derived from the current Windows user + machine. A cache file copied to another machine cannot be decrypted, and the password is never sent to the browser.