simplemdg-dev-cli 1.5.1 → 2.0.4

package/README.md

@@ -77,7 +77,7 @@ Login to BTP Cloud Foundry.
 smdg cf login
 ```
 
-The CLI helps select API endpoint, org, and space.
+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.
 
@@ -89,7 +89,7 @@ Search, list, and switch Cloud Foundry orgs across regions.
 smdg cf org
 ```
 
-The CLI scans known BTP region endpoints and shows orgs in one searchable list.
+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:
 
@@ -99,7 +99,7 @@ alcon-dev-simplemdg      br10 · 1 space
 ait-dev-simplemdg        us21 · 1 space
 ```
 
-Use this when you have many orgs across many BTP regions.
+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`
 
@@ -262,7 +262,7 @@ Helps with login, target checking, org switching, app list, binding, env export,
 
 ## Across-region org search
 
-Scans known BTP regions and shows orgs from many regions in one searchable list.
+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
 
@@ -270,7 +270,7 @@ 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.
+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`.
 
 ---
 
@@ -281,3 +281,116 @@ 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
+```
+
+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.
+
+Alias:
+
+```bash
+smdg cf traffic
+```
+
+Notes:
+
+- 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.
+
+## New in 2.0.2: HTTP Watch
+
+`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
+```
+
+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.
+
+Use this first for reliable microservice tracking. For deeper diagnostics:
+
+```bash
+smdg cf request-trace-doctor
+```
+
+`request-trace` now asks which engine to use: stable HTTP watch, experimental deep inspector trace, or doctor.
+
+## Network body capture
+
+Use this when `smdg cf http-watch` can show POST/PATCH requests but not the request body.
+
+```bash
+smdg cf request-trace
+```
+
+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:
+
+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.
+
+Important: full body/token capture is a dev/test feature only. Do not enable full token output in production.
+
+
+# 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
+```
+
+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
+```
+
+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.

package/USER_GUIDE.md

@@ -77,7 +77,7 @@ Login to BTP Cloud Foundry.
 smdg cf login
 ```
 
-The CLI helps select API endpoint, org, and space.
+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.
 
@@ -89,7 +89,7 @@ Search, list, and switch Cloud Foundry orgs across regions.
 smdg cf org
 ```
 
-The CLI scans known BTP region endpoints and shows orgs in one searchable list.
+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:
 
@@ -99,7 +99,7 @@ alcon-dev-simplemdg      br10 · 1 space
 ait-dev-simplemdg        us21 · 1 space
 ```
 
-Use this when you have many orgs across many BTP regions.
+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`
 
@@ -262,7 +262,7 @@ Helps with login, target checking, org switching, app list, binding, env export,
 
 ## Across-region org search
 
-Scans known BTP regions and shows orgs from many regions in one searchable list.
+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
 
@@ -270,7 +270,7 @@ 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.
+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`.
 
 ---
 
@@ -281,3 +281,132 @@ 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
+```
+
+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.
+
+Alias:
+
+```bash
+smdg cf traffic
+```
+
+Notes:
+
+- 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.
+
+# HTTP Watch
+
+Use this when you want to see what is calling your BTP app without adding backend logs.
+
+```bash
+smdg cf http-watch
+```
+
+The CLI shows a clean realtime list from existing Cloud Foundry/CDS/router logs.
+
+It can show:
+
+* HTTP method
+* URL/path
+* status code
+* duration
+* app instance
+* remote user
+* tenant
+* request size
+* request id / correlation id
+
+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.
+
+# Request Trace Doctor
+
+Use this before trying deep body capture:
+
+```bash
+smdg cf request-trace-doctor
+```
+
+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.
+
+# Network Trace
+
+```bash
+smdg cf request-trace
+```
+
+This command can capture request data from inside a running Node.js/CAP app.
+
+Use it when you need more than `smdg cf http-watch`, especially request body for POST/PATCH APIs.
+
+Recommended mode:
+
+```txt
+Deep Node Inspector trace
+Headers + body
+Mask token
+```
+
+The trace is temporary and disappears after the app restarts. It does not change source code.
+
+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
+```
+
+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
+```
+
+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.