simplemdg-dev-cli 2.0.4 → 2.4.5

package/README.md

@@ -1,396 +1,104 @@
-# 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
+```powershell
+npm install -g .\simplemdg-dev-cli-2.4.0.tgz --force
+smdg -V
 ```
 
----
-
-# 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.
+## Prerequisites & auto-install
 
-This is useful for long lists of BTP orgs, spaces, apps, package IDs, CAP profiles, and CDS services.
+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.
 
----
+## Main commands
 
-# 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
+```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. Choose to save the password on your own machine if you want automatic re-login for org switching, logs, app listing, and debugging.
-
-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 and cached BTP region endpoints and shows orgs from different regions in one searchable list. If the CF session for a region is expired, the CLI automatically re-authenticates by using the username/password saved from `smdg cf login`.
-
-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. Run `smdg cf login` once and choose to save the password on your machine so org switching, app listing, logs, and debug can re-login automatically when the CF session expires.
-
-## `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
-```
-
-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 and cached BTP regions and shows orgs from many regions in one searchable list. The CLI now re-authenticates per region using the cached login profile, so switching orgs should not fail just because `cf api` changed to another region.
-
-## 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. For the first debug session of an app, use `Set NODE_OPTIONS and restart app`; later sessions can use `Inspector is already enabled`.
-
----
-
-# Notes
-
-Do not commit real secrets to Git.
-
-Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
-
-Use saved password only on your own machine.
-
-
-## Request Trace
-
-```bash
 smdg cf request-trace
+smdg gitlab login
+smdg gitlab clone
+smdg gitlab pull
+smdg cf db studio
 ```
 
-Watch incoming HTTP requests on deployed BTP Node.js/CAP apps without editing backend source code.
-
-The CLI guides you to select one or more apps, choose trace depth, prepare Node Inspector, inject a temporary runtime trace, and stream request logs.
-
-It can show method, path, headers, request body, response body, status, and duration. Authorization tokens are masked by default and should only be shown fully in dev/test environments.
+## GitLab sync
 
-Alias:
+`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 traffic
+```powershell
+smdg gitlab login
+smdg gitlab groups
+smdg gitlab clone
 ```
 
-Notes:
+The clone/pull flow separates:
 
-- This works best for Node.js/CAP apps.
-- It uses CF SSH tunnel and Node Inspector.
-- It does not change repository source code.
-- The trace disappears after app restart.
-- Avoid full token/body tracing in production.
+- pull/clone a root group
+- pull/clone a single repository
 
-## New in 2.0.2: HTTP Watch
+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`.
 
-`request-trace` deep runtime injection is experimental and may not catch every CAP runtime request body. Version 2.0.2 adds a stable log-based watcher:
-
-```bash
-smdg cf http-watch
-```
+## CF DB Studio
 
-It reads existing CF/CDS/RTR logs and prints a clean realtime HTTP view: method, path, status, user, tenant, instance, request size, and request id. It does not restart apps and does not change source code.
+A local, browser-based database explorer (HANA / PostgreSQL) styled after SAP HANA Database Explorer and DBeaver, with deep BTP/Cloud Foundry integration.
 
-Use this first for reliable microservice tracking. For deeper diagnostics:
-
-```bash
-smdg cf request-trace-doctor
+```powershell
+smdg cf login
+smdg cf db studio
 ```
 
-`request-trace` now asks which engine to use: stable HTTP watch, experimental deep inspector trace, or doctor.
+Studio starts a local web server bound to `127.0.0.1` only (auto-selects a free port) and opens your browser. It is a DBeaver / SAP HANA Database Explorer–style IDE:
 
-## Network body capture
+- opens on a **Welcome page**; SQL / Data / Structure tabs open only on demand (closable, with dirty indicators)
+- **DBeaver-style lazy object tree**: connection → Catalog → Schemas → schema → Tables/Views/Procedures/Functions/Synonyms, loaded only when expanded, with per-folder search and count badges
+- **right-click context menus** on tables/views (Open Data, Open Structure, Generate SELECT/COUNT, Copy Full Name) and connections (Connect, Test, Edit, Favorite, Refresh from BTP, Duplicate, Remove)
+- **connection cards** with custom name, color, environment tag (DEV/QAS/PROD/SANDBOX), favorite star, and a production-like warning
+- import credentials from a BTP app's `cf env` via a **guided modal wizard** (target → app → service → save), or **add direct connections** (host/port/user/password) for non-CF databases like Neon
+- passwords are **encrypted** locally and never sent to the browser (the UI only uses a connection id)
+- inspect metadata (columns incl. comments, indexes, primary key, row count, generated DDL)
+- data grid with pagination, quick `WHERE` filter, click-to-sort headers, and **inline editing with pending changes** — edited cells highlight yellow, inserts green, deletes red; review then **Save** (batch, per-row results) or **Revert**; conflicts/failures stay pending with error markers
+- editing requires a detected **primary key** (read-only grid otherwise)
+- run any SQL across multiple tabs, with row-limit, timing, CSV/JSON export, save to `.sql`, history
+- **read-only** mode blocks all writes/DDL; dangerous SQL (DROP/TRUNCATE/ALTER/DELETE-or-UPDATE-without-WHERE) asks for confirmation
+- clear loading states (skeletons, spinners, status bar) for every async action
 
-Use this when `smdg cf http-watch` can show POST/PATCH requests but not the request body.
+### Commands
 
-```bash
-smdg cf request-trace
+```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)
 ```
 
-Choose **Deep Node Inspector trace**. The CLI injects a temporary Node runtime hook through the Node Inspector. It does not modify repository source code. It attempts to capture request headers, body, response status, and response body depending on the selected mode.
-
-Recommended test flow:
+In the Studio, click **+ New** in the Connections sidebar to add a direct connection without leaving the browser.
 
-1. Run `smdg cf request-trace`.
-2. Select the target app.
-3. Select **Deep Node Inspector trace**.
-4. Select **Headers + body**.
-5. Select **Mask token** first.
-6. If the inspector is not reachable, choose the prepare mode that sets `NODE_OPTIONS` and restarts the app.
-7. Send a new request after the CLI prints that the trace is installed.
+`smdg cf db studio` options: `--port <port>` (preferred port), `--read-only`, `--timeout <ms>`.
 
-Important: full body/token capture is a dev/test feature only. Do not enable full token output in production.
+### Local cache files
 
-
-# Request Trace Runtime Tools
-
-Use this command when you need to inspect real request headers and bodies from a BTP Node.js/CAP app without changing repository source code:
-
-```bash
-smdg cf request-trace
+```text
+~/.simplemdg/db-connections.json     # connection profiles (passwords encrypted)
+~/.simplemdg/db-query-history.json   # query history
+~/.simplemdg/db-queries/             # saved .sql query files
 ```
 
-Alias:
+Passwords are encrypted with a key derived from the current machine + user, so a copied cache file cannot be decrypted elsewhere.
 
-```bash
-smdg cf network-trace
-```
+### Database drivers
 
-The CLI will ask for:
+HANA and PostgreSQL drivers are optional dependencies. If a driver is missing, the studio reports it clearly. Install:
 
-* target app or apps
-* trace depth: path, headers, body, or response body
-* Authorization handling: masked, full, or omitted
-* displayed headers: minimal, common, all, or custom
-* whether to parse body as JSON/form data
-* whether to export trace events to a JSONL file
-
-While the trace is running, you can type commands directly in the same terminal:
-
-```txt
-/method POST
-/path getBusinessRequest
-/body CR0000135951
-/status 500
-/text single.npi
-/headers authorization,content-type,x-correlationid,x-vcap-request-id
-/headers all
-/clear
-/show
-/replay
-/pause
-/resume
-/help
+```powershell
+npm i -g pg @sap/hana-client
 ```
-
-Exported files use JSONL format: one request event per line. This makes it easier to search later with editor tools or scripts.
-
-Security note: full Authorization token output should only be used in dev/test and on a trusted machine. The recommended mode is masked token.