simplemdg-dev-cli 2.0.4 → 2.4.5

package/USER_GUIDE.md

@@ -1,412 +1,91 @@
-# 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. 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
+```powershell
+smdg gitlab login
 ```
 
----
-
-# 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.
+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.
 
-Use saved password only on your own machine.
+Clone or pull:
 
-
-## Request Trace
-
-```bash
-smdg cf request-trace
+```powershell
+smdg gitlab clone
+smdg gitlab pull
 ```
 
-Watch incoming HTTP requests on deployed BTP Node.js/CAP apps without editing backend source code.
+The flow is split clearly:
 
-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.
+1. Pull/clone a GitLab group
+2. Pull/clone a single repository
 
-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.
+Then select root group, destination folder, sync action, and parallel jobs.
 
-Alias:
+## CF DB Studio
 
-```bash
-smdg cf traffic
-```
+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.
 
-Notes:
+### Recommended flow
 
-- 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.
+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**
 
-# HTTP Watch
+The studio never deploys anything to BTP and never shows the database password.
 
-Use this when you want to see what is calling your BTP app without adding backend logs.
-
-```bash
-smdg cf http-watch
-```
+### Layout
 
-The CLI shows a clean realtime list from existing Cloud Foundry/CDS/router logs.
+The Studio opens on a **Welcome page**. The left side has three collapsible sections — **Connections** (cards with color/environment/favorite, right-click for actions), **Object Explorer** (a lazy DBeaver-style tree), and **Saved Queries**. Work opens as **tabs** in the main area only when you act on something.
 
-It can show:
+- **Object Explorer** — expand a connection → Catalog → Schemas → a schema → folders (Tables, Views, Procedures, Functions, Synonyms). Children load only when expanded; each folder has its own search and a count badge. Double-click a table to open its data; right-click for Open Data / Open Structure / Generate SELECT / Generate COUNT / Copy Full Name.
+- **SQL tabs** — open from "Open SQL Console", "New query", "Generate SELECT", or a saved query. Run with **Ctrl+Enter**, format, explain (PostgreSQL), pick a row limit, export CSV/JSON, save to a `.sql` file. Dangerous statements require confirmation; read-only mode blocks writes.
+- **Data tabs** — paginated rows with a WHERE filter and click-to-sort headers. For tables with a detected primary key you can **edit inline**: double-click a cell (turns yellow), **+ Insert row** (green), or select a row and delete it (red). Changes are pending until you click **Save changes** (batched, with a confirm summary and per-row results); **Revert all** discards them. Failed rows stay marked with their error.
+- **Structure tabs** — Columns (name, type, length, scale, nullable, key, default, comment), Indexes + primary key, generated **DDL**, and table Info (row count).
+- **BTP Import wizard** — a modal (Target → App → Services → Save) that reads `cf env`, detects HANA/PostgreSQL services, and saves a connection with a display name, color, environment, and favorite.
 
-* HTTP method
-* URL/path
-* status code
-* duration
-* app instance
-* remote user
-* tenant
-* request size
-* request id / correlation id
+The bottom status bar shows connection state, last query duration, row count, and pending-change count.
 
-It cannot show full body or full Authorization token because CF/CDS logs do not contain them. Use `smdg cf request-trace` only when you need experimental deep runtime inspection.
+### Read-only and dangerous SQL
 
-# Request Trace Doctor
+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.
 
-Use this before trying deep body capture:
+### Terminal alternatives
 
-```bash
-smdg cf request-trace-doctor
+```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
 ```
 
-It checks recent router/app traffic and the remote Node process list so you can confirm whether the app is receiving requests and whether deep inspection is possible.
+### Direct connections (no CF app)
 
-# Network Trace
+Not every database is behind a Cloud Foundry app (for example a Neon PostgreSQL or a standalone HANA Cloud). Add those directly:
 
-```bash
-smdg cf request-trace
-```
-
-This command can capture request data from inside a running Node.js/CAP app.
+- 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`.
 
-Use it when you need more than `smdg cf http-watch`, especially request body for POST/PATCH APIs.
+Direct connections are cached and encrypted exactly like imported ones, so they reappear next time you open the Studio.
 
-Recommended mode:
-
-```txt
-Deep Node Inspector trace
-Headers + body
-Mask token
-```
+Console slash commands: `/connect`, `/schemas`, `/tables`, `/desc TABLE`, `/top TABLE`, `/count TABLE`, `/save NAME`, `/history`, `/export csv|json`, `/full`, `/clear`, `/help`, `/exit`.
 
-The trace is temporary and disappears after the app restarts. It does not change source code.
+## DB cache
 
-If the CLI cannot reach the Node inspector, run the command again and choose the prepare option that sets `NODE_OPTIONS` and restarts the app.
-
-
-# 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
-```
-
-Alias:
-
-```bash
-smdg cf network-trace
-```
+Connections are cached under:
 
-The CLI will ask for:
-
-* 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
+```text
+~/.simplemdg/db-connections.json
 ```
 
-Exported files use JSONL format: one request event per line. This makes it easier to search later with editor tools or scripts.
+Saved queries live in `~/.simplemdg/db-queries/` and history in `~/.simplemdg/db-query-history.json`.
 
-Security note: full Authorization token output should only be used in dev/test and on a trusted machine. The recommended mode is masked token.
+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.