@saptools/cf-explorer

---

✨ Why

Cloud Foundry app exploration often starts with a slow, repetitive loop:

1. Open cf ssh.
2. Find where the deployed app actually lives.
3. Search filenames and content.
4. Inspect the exact runtime line.
5. Turn the match into a useful file/line location.
6. Repeat after every wrong guess.

cf-explorer turns that loop into a structured workflow:

• 🔎 Discover deployed app roots and runtime files.
• 🧭 Map grep results into reusable file/line candidates.
• ⚡ Reuse one SSH-backed session when many reads are needed.
• 🧩 Import the same behavior from another Node.js project.
• 🛡️ Protect inputs with bounded commands; SSH is enabled and restarted automatically when needed.

---

🚀 What It Does

Capability	Purpose
roots	Locate likely app roots with bounded read-only probes
instances	Show app process instance indexes and status
ls	List direct children under a known remote directory
find	Search filenames under a remote root
grep	Search remote file content and return path + line
view	Print a bounded line window around a remote file location
inspect-candidates	Suggest candidate paths, line numbers, and root mappings
session start	Keep one SSH-backed broker alive for fast repeated reads

---

📦 Install

npm install -g @saptools/cf-explorer

---

Updates

Every command first checks npm for a newer @saptools/cf-explorer (at most once an hour, one small request with a 2-second timeout) and, when one exists, installs that exact version with the package manager that owns the running binary and re-runs the command you typed on the new version. Both steps are announced on stderr; nothing is printed when the install is already current:

cf-explorer: updating 0.5.0 -> 0.6.0 ...
cf-explorer: updated to 0.6.0; re-running the command

If the install cannot complete, one stderr line gives the manual command and the command runs on the installed version; that version is not retried for a day. cf-explorer self-update forces the check and install now; cf-explorer self-update --check only reports.

Control	Effect
SAPTOOLS_AUTO_UPDATE=on|notify|off	on (default) installs and re-runs; notify prints the manual command once per version; off never checks. Applies to every @saptools CLI.
CF_EXPLORER_AUTO_UPDATE	same values, this CLI only; wins over the global variable
SAPTOOLS_UPDATE_INTERVAL_MINUTES	minutes between checks (default 60; 0 checks on every run)
SAPTOOLS_NPM_REGISTRY	registry to check and install from (default: npm's configured registry, then npmjs)
SAPTOOLS_UPDATE_DEBUG=1	explain on stderr why nothing happened

The updater switches itself off in CI (CI set), under NODE_ENV=test or NO_UPDATE_NOTIFIER, when the binary runs from a source checkout, an npm link or an npx cache, and inside the re-run itself. It never writes to stdout, never asks for input, never uses sudo, and never moves onto a prerelease. Its state lives in ~/.saptools/updates/.

🔐 Credentials

cf-explorer uses the same environment variables as the other SAP tools packages:

export SAP_EMAIL="user@example.com"
export SAP_PASSWORD="your-password"

Optional overrides:

export CF_EXPLORER_CF_BIN="/path/to/cf"
export CF_EXPLORER_HOME="$HOME/.saptools/cf-explorer"

Credential handling is intentionally conservative:

• credentials are resolved from env by default;
• SAP_EMAIL and SAP_PASSWORD are stripped from normal child-process env after resolution;
• cf auth should receive credentials through scoped child env variables;
• secrets, tokens, and remote file contents are not written to session state.

---

⚡ Quick Start

Find a root, search for code, inspect context, then reuse the location in your next command, script, editor, or debugging tool.

cf-explorer roots \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name

cf-explorer ls \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --path /app-root

cf-explorer grep \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --root /app-root \
  --text "needle"

cf-explorer view \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --file /app-root/src/handler.js \
  --line 42 \
  --context 6

Generate reusable file/line candidates:

cf-explorer inspect-candidates \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --text "needle"

---

🧰 CLI

Check the installed CLI version:

cf-explorer --version

All read/discovery commands accept:

Flag	Description
--region <key>	CF region key resolved through the SAP tools region catalog
--org <name>	CF org
--space <name>	CF space
--app <name>	CF app
--process <name>	CF process name, default web
--instance <index>	One app process instance; defaults to the first/default instance (0)
--timeout <seconds>	Command timeout
--max-files <count>	Result limit for path-like discovery and inspect file-candidate scans
--max-matches <count>	Result limit for grep, session grep, and inspect-candidates content matches
--max-bytes <bytes>	Output byte limit
--follow-symlinks	Follow symlinked directories during find/grep traversal for pnpm-style layouts

Single-shot and session commands write compact human-readable results directly to stdout. If a discovery result exceeds a count limit, the CLI keeps stdout unchanged and writes a truncation warning to stderr. A single-shot response that reaches its byte limit produces the same warning; a persistent-session request instead fails with OUTPUT_LIMIT_EXCEEDED. Increase --max-matches, --max-files, or --max-bytes, as appropriate, and retry.

🪄 Discovery

cf-explorer roots --region region-key --org org-name --space space-name --app app-name
cf-explorer instances --region region-key --org org-name --space space-name --app app-name
cf-explorer ls --region region-key --org org-name --space space-name --app app-name --path /app-root --pattern "*helper*"
cf-explorer find --region region-key --org org-name --space space-name --app app-name --root /app-root --name "*handler*.js"
cf-explorer grep --region region-key --org org-name --space space-name --app app-name --root /app-root --text "needle" --max-matches 20 --follow-symlinks
cf-explorer view --region region-key --org org-name --space space-name --app app-name --file /app-root/src/handler.js --line 42 --context 8

🎯 File/Line Candidates

cf-explorer inspect-candidates \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --text "needle"

inspect-candidates prints sectioned roots, content matches, and suggested breakpoints. Use --max-matches to bound breakpoint-oriented search output. The typed API can additionally populate its files array when called with includeFiles: true; compact CLI output does not render that array.

Suggested breakpoint shape from the typed API:

{
  "instance": 0,
  "bp": "/app-root/src/handler.js",
  "remoteRoot": "/app-root",
  "line": 42,
  "confidence": "high",
  "reason": "content match"
}

🔁 SSH Access

SSH-backed commands automatically enable app SSH and restart the app when SSH is disabled.

🧵 Persistent Sessions

One-shot mode is simple: each CLI invocation opens a fresh cf ssh, runs one bounded command, and exits. Persistent mode is for deeper exploration where that round trip becomes the bottleneck.

cf-explorer session start \
  --region region-key \
  --org org-name \
  --space space-name \
  --app app-name \
  --instance 0 \
  --idle-timeout 900 \
  --max-lifetime 3600

cf-explorer session list
cf-explorer session status --session-id <id>

cf-explorer session ls --session-id <id> --path /app-root
cf-explorer session grep --session-id <id> --root /app-root --text "needle"
cf-explorer session view --session-id <id> --file /app-root/src/handler.js --line 42

cf-explorer session stop --session-id <id>

--idle-timeout and --max-lifetime are optional seconds-based guards for the local broker process.

🛰️ How Session Reuse Works

Persistent sessions use a local broker process:

CLI command
  -> local IPC socket
    -> cf-explorer broker
      -> live cf ssh child process
        -> remote sh

The broker is the only process that owns the live SSH stdin/stdout streams. sessions.json is only an index; it is not the command channel.

The broker:

• opens one cf ssh --disable-pseudo-tty --process <process> -i <index> -c sh;
• performs a startup handshake;
• accepts newline-delimited JSON requests over local IPC;
• validates each request against known explorer commands;
• queues one remote command at a time;
• wraps remote output in sentinel markers;
• enforces timeouts, output limits, and stale-session cleanup.

---

🧑‍💻 TypeScript API

import {
  attachExplorerSession,
  createExplorer,
  listExplorerSessions,
  startExplorerSession,
  stopExplorerSession,
} from "@saptools/cf-explorer";

const explorer = await createExplorer({
  target: {
    region: "region-key",
    org: "org-name",
    space: "space-name",
    app: "app-name",
  },
});

const rootsResult = await explorer.roots();
const root = rootsResult.roots[0] ?? "/app-root";
const entries = await explorer.ls({ path: root, instance: 0 });

const matches = await explorer.grep({
  root,
  text: "needle",
  instance: 0,
});

await explorer.dispose();

Broker-backed session:

const session = await startExplorerSession({
  target: {
    region: "region-key",
    org: "org-name",
    space: "space-name",
    app: "app-name",
  },
  instance: 0,
});

const attached = await attachExplorerSession(session.sessionId);
const entries = await attached.ls({ path: "/app-root" });
const result = await attached.grep({ root: "/app-root", text: "needle" });

await stopExplorerSession({ sessionId: session.sessionId });

---

🛡️ Safety Model

cf-explorer is designed around a narrow safety boundary.

Read-only discovery commands:

• generate remote commands from templates;
• reject arbitrary shell text;
• quote user-provided values;
• reject NUL bytes, newlines, unsafe roots, and invalid instance selectors;
• enforce output, file, context, depth, and timeout limits;
• prune noisy folders such as node_modules, .git, dist, build, and .cache;
• omit grep previews unless explicitly requested. Preview and view output can contain remote file content, so it is returned only to the caller and is not stored in session state.

Automatic SSH access:

• checks SSH before opening SSH-backed reads;
• runs cf enable-ssh and cf restart only when SSH is disabled;
• marks related persistent sessions stale after restart.

No command uploads, edits, deletes, installs packages, changes permissions, or opens an unrestricted interactive shell.

---

🗂️ Local State

All package-owned files live under:

~/.saptools/cf-explorer/
  sessions.json
  sessions.lock
  sockets/
    <session-id>.sock
  cf-homes/
    <session-id>/
  tmp/
    <run-id>/
  logs/

Rules:

• sessions.json stores only non-secret session metadata.
• Persistent CF_HOME folders are treated as sensitive and removed on session stop.
• Temp files are deleted after one-shot workflows.
• Logs must not contain credentials or remote file contents.
• Stale sessions are pruned by hostname, broker PID, SSH PID, and socket health.

---

📤 Result Metadata

Typed API discovery results include metadata:

interface ExplorerMeta {
  target: {
    region: string;
    org: string;
    space: string;
    app: string;
  };
  process: string;
  instance?: number;
  durationMs: number;
  truncated: boolean;
}

meta.truncated is true when a returned one-shot response reached maxBytes or when a returned one-shot or session result exceeded the requested maxFiles or maxMatches window. The returned data is incomplete; increase the corresponding limit and retry. The CLI exposes the same condition through its stderr warning while keeping result stdout compact. Persistent-session requests that exceed maxBytes fail with OUTPUT_LIMIT_EXCEEDED instead of returning partial result metadata.

---

🧯 Error Codes

Code	Meaning
MISSING_CREDENTIALS	SAP_EMAIL or SAP_PASSWORD is missing
UNKNOWN_REGION	Region key is not known
CF_LOGIN_FAILED	cf api or cf auth failed
CF_TARGET_FAILED	cf target failed
APP_NOT_FOUND	Target app was not found
SSH_DISABLED	SSH could not be used after automatic preparation
INSTANCE_NOT_FOUND	Requested app process instance is unavailable
UNSAFE_INPUT	Input failed validation
OUTPUT_LIMIT_EXCEEDED	Remote output exceeded configured limits
REMOTE_COMMAND_FAILED	A bounded remote command failed
SESSION_NOT_FOUND	The requested persistent session does not exist
SESSION_STALE	The persistent session is no longer usable
SESSION_BUSY	Persistent broker queue is full
BROKER_UNAVAILABLE	The broker process is not reachable
IPC_FAILED	Local IPC request failed
SESSION_PROTOCOL_ERROR	Persistent shell marker parsing failed
SESSION_HANDSHAKE_FAILED	Persistent shell startup handshake failed
SESSION_RECOVERY_FAILED	Broker could not recover the remote shell
ABORTED	The caller aborted the operation

---

🤝 Related Packages

• @saptools/cf-debugger: opens Node debugging tunnels through CF SSH.
• @saptools/cf-files: reads CF env and pulls individual remote files.

---

👨‍💻 Author

dongtran ✨

📄 License

MIT

---

Made with ❤️ to make your work life easier!