simplemdg-dev-cli 1.2.0 → 1.3.1

package/dist/commands/cf.command.js

@@ -7,12 +7,73 @@ import prompts from "prompts";
 import { authenticateCloudFoundry, buildCloudFoundryTargetKey, listCloudFoundryApps, inferCloudFoundryRegionFromApiEndpoint, listCloudFoundryOrganizations, listCloudFoundrySpaces, readCloudFoundryTarget, scanCloudFoundryOrganizationsAcrossRegions, setCloudFoundryApiEndpoint, targetCloudFoundryOrg, targetCloudFoundrySpace, } from "../core/cf.js";
 import { parseCloudFoundryEnvironment } from "../core/cf-env-parser.js";
 import { readCache, rememberCloudFoundryApps, rememberCloudFoundryLoginProfile, rememberCloudFoundryOrgEntries, rememberEnvironmentFileName, rememberSelectedApp, } from "../core/cache.js";
-import { ensureCommandAvailable, runCommand, runCommandInherit } from "../core/process.js";
+import { runCommand, runCommandInherit } from "../core/process.js";
 import { resolveRepositoryPath } from "../core/repository.js";
 import { searchableSelectChoice, selectFromHistoryOrInput } from "../core/prompts.js";
 function validateRequired(value) {
     return value.trim() ? true : "Value is required";
 }
+async function ensureCloudFoundrySessionFromCache() {
+    const target = await readCloudFoundryTarget();
+    if (target.apiEndpoint && target.user) {
+        return target;
+    }
+    const cache = await readCache();
+    const profilesWithPassword = cache.cloudFoundry.loginProfiles.filter((profile) => profile.password?.trim());
+    if (!profilesWithPassword.length) {
+        console.log(chalk.yellow("You are not logged in to Cloud Foundry yet and no cached password was found."));
+        console.log(chalk.gray("Run smdg cf login once and choose to save the password for automatic re-login."));
+        throw new Error("Cloud Foundry login is required");
+    }
+    const preferredProfiles = target.apiEndpoint
+        ? [
+            ...profilesWithPassword.filter((profile) => profile.apiEndpoint === target.apiEndpoint),
+            ...profilesWithPassword.filter((profile) => profile.apiEndpoint !== target.apiEndpoint),
+        ]
+        : profilesWithPassword;
+    const selectedProfileIndex = preferredProfiles.length === 1
+        ? "0"
+        : await searchableSelectChoice({
+            message: "Select cached CF login profile for automatic re-login",
+            choices: preferredProfiles.map((profile, index) => ({
+                title: `${profile.username} · ${profile.org}${profile.space ? `/${profile.space}` : ""} · ${inferCloudFoundryRegionFromApiEndpoint(profile.apiEndpoint)}`,
+                value: String(index),
+            })),
+            allowCustomValue: false,
+        });
+    const profile = preferredProfiles[Number(selectedProfileIndex)] ?? preferredProfiles[0];
+    console.log(chalk.gray(`Auto login CF: ${profile.username} · ${inferCloudFoundryRegionFromApiEndpoint(profile.apiEndpoint)} · ${profile.org}${profile.space ? `/${profile.space}` : ""}`));
+    const apiExitCode = await setCloudFoundryApiEndpoint(profile.apiEndpoint);
+    if (apiExitCode !== 0) {
+        process.exitCode = apiExitCode;
+        throw new Error("CF api target failed");
+    }
+    const authExitCode = await authenticateCloudFoundry({
+        username: profile.username,
+        password: profile.password,
+    });
+    if (authExitCode !== 0) {
+        process.exitCode = authExitCode;
+        throw new Error("CF automatic login failed. Run smdg cf login and update the cached password.");
+    }
+    const orgExitCode = await targetCloudFoundryOrg(profile.org);
+    if (orgExitCode !== 0) {
+        process.exitCode = orgExitCode;
+        throw new Error("CF org target failed");
+    }
+    if (profile.space) {
+        const spaceExitCode = await targetCloudFoundrySpace(profile.space);
+        if (spaceExitCode !== 0) {
+            process.exitCode = spaceExitCode;
+            throw new Error("CF space target failed");
+        }
+    }
+    await rememberCloudFoundryLoginProfile({
+        ...profile,
+        updatedAt: new Date().toISOString(),
+    });
+    return readCloudFoundryTarget();
+}
 function buildCloudFoundryLogsArgs(options) {
     const args = ["logs", options.appName];
     if (options.recent) {
@@ -20,6 +81,293 @@ function buildCloudFoundryLogsArgs(options) {
     }
     return args;
 }
+function parsePositivePort(value, defaultValue) {
+    if (!value?.trim()) {
+        return defaultValue;
+    }
+    const port = Number(value.trim());
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port: ${value}`);
+    }
+    return port;
+}
+function buildNodeInspectorRemoteCommand(remotePort) {
+    if (remotePort !== 9229) {
+        return [
+            `echo "Remote port ${remotePort} was requested."`,
+            `echo "SIGUSR1 starts the Node.js inspector on its default port 9229 for a running Node process."`,
+            `echo "Use remote port 9229, or start the app process with NODE_OPTIONS=--inspect=127.0.0.1:${remotePort}."`,
+            `exit 2`,
+        ].join("; ");
+    }
+    return [
+        `PID=$(pgrep -xo node || pgrep -x node | head -n 1)`,
+        `if [ -z "$PID" ]; then echo "No Node.js PID found in app container" >&2; exit 1; fi`,
+        `if command -v ss >/dev/null 2>&1 && ss -H -ntl "sport = :9229" | grep -q .; then echo "Node inspector already listening on 127.0.0.1:9229"`,
+        `else kill -s SIGUSR1 "$PID" && echo "Started Node inspector for PID $PID on 127.0.0.1:9229"; fi`,
+        `tail -f /dev/null`,
+    ].join("; ");
+}
+function buildCloudFoundryDebugSshArgs(options) {
+    const args = [
+        "ssh",
+        options.appName,
+        "-i",
+        options.instanceIndex,
+    ];
+    if (options.processName?.trim()) {
+        args.push("--process", options.processName.trim());
+    }
+    args.push("-T", "-L", `${options.localPort}:127.0.0.1:${options.remotePort}`, "-c", buildNodeInspectorRemoteCommand(options.remotePort));
+    return args;
+}
+async function getNodeInspectorDebugUrl(localPort) {
+    const response = await fetch(`http://127.0.0.1:${localPort}/json/list`);
+    if (!response.ok) {
+        return undefined;
+    }
+    const targets = await response.json();
+    const webSocketDebuggerUrl = targets.find((target) => target.webSocketDebuggerUrl)?.webSocketDebuggerUrl;
+    if (!webSocketDebuggerUrl) {
+        return undefined;
+    }
+    const webSocketAddress = webSocketDebuggerUrl.replace(/^ws:\/\//, "");
+    return `devtools://devtools/bundled/inspector.html?ws=${webSocketAddress}`;
+}
+async function waitForNodeInspectorDebugUrl(localPort, timeoutMs = 10000) {
+    const startedAt = Date.now();
+    let lastError;
+    while (Date.now() - startedAt < timeoutMs) {
+        try {
+            const debugUrl = await getNodeInspectorDebugUrl(localPort);
+            if (debugUrl) {
+                return debugUrl;
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    if (lastError instanceof Error) {
+        console.log(chalk.gray(`Could not read inspector JSON yet: ${lastError.message}`));
+    }
+    return undefined;
+}
+function printNodeInspectorAttachInfo(options) {
+    console.log("");
+    console.log(chalk.green(`Debug tunnel is ready for ${options.appName} instance ${options.instanceIndex}.`));
+    console.log(`Chrome inspect: ${chalk.cyan("chrome://inspect")}`);
+    console.log(`Local inspector JSON: ${chalk.cyan(`http://127.0.0.1:${options.localPort}/json/list`)}`);
+    if (options.debugUrl) {
+        console.log(`Direct DevTools link: ${chalk.cyan(options.debugUrl)}`);
+    }
+    else {
+        console.log(chalk.yellow("Direct DevTools link was not detected yet. Open chrome://inspect and configure localhost target."));
+    }
+    console.log("");
+    console.log(chalk.gray("VS Code attach config:"));
+    console.log(JSON.stringify({
+        type: "node",
+        request: "attach",
+        name: `Attach ${options.appName} on BTP`,
+        address: "127.0.0.1",
+        port: options.localPort,
+        localRoot: "${workspaceFolder}",
+        remoteRoot: "/home/vcap/app",
+        skipFiles: ["<node_internals>/**"],
+    }, null, 2));
+    console.log("");
+    console.log(chalk.gray("Keep this terminal open. Press Ctrl+C to close the debug tunnel."));
+}
+function buildVscodeNodeAttachConfiguration(options) {
+    return {
+        type: "node",
+        request: "attach",
+        name: `Attach BTP ${options.appName}`,
+        address: "127.0.0.1",
+        port: options.localPort,
+        localRoot: "${workspaceFolder}",
+        remoteRoot: options.remoteRoot,
+        protocol: "inspector",
+        sourceMaps: true,
+        restart: true,
+        skipFiles: ["<node_internals>/**"],
+        outFiles: [
+            "${workspaceFolder}/**/*.js",
+            "!**/node_modules/**",
+        ],
+    };
+}
+async function writeVscodeLaunchConfiguration(options) {
+    const vscodeDirectoryPath = path.resolve(options.cwd, ".vscode");
+    const launchJsonPath = path.join(vscodeDirectoryPath, "launch.json");
+    const configuration = buildVscodeNodeAttachConfiguration({
+        appName: options.appName,
+        localPort: options.localPort,
+        remoteRoot: options.remoteRoot ?? "/home/vcap/app",
+    });
+    await fs.ensureDir(vscodeDirectoryPath);
+    let launchJson = {
+        version: "0.2.0",
+        configurations: [],
+    };
+    if (await fs.pathExists(launchJsonPath)) {
+        try {
+            const currentContent = await fs.readFile(launchJsonPath, "utf8");
+            const parsed = JSON.parse(currentContent);
+            launchJson = {
+                version: typeof parsed.version === "string" ? parsed.version : "0.2.0",
+                configurations: Array.isArray(parsed.configurations) ? parsed.configurations : [],
+            };
+        }
+        catch {
+            const backupPath = `${launchJsonPath}.backup-${Date.now()}`;
+            await fs.copyFile(launchJsonPath, backupPath);
+            console.log(chalk.yellow(`Existing launch.json is not valid JSON. Backup created: ${backupPath}`));
+        }
+    }
+    const configurationName = String(configuration.name);
+    const existingIndex = launchJson.configurations.findIndex((item) => item.name === configurationName);
+    if (existingIndex >= 0) {
+        launchJson.configurations[existingIndex] = configuration;
+    }
+    else {
+        launchJson.configurations.unshift(configuration);
+    }
+    await fs.writeFile(launchJsonPath, `${JSON.stringify(launchJson, null, 2)}\n`, "utf8");
+    return launchJsonPath;
+}
+function printVscodeAttachInstructions(options) {
+    console.log("");
+    console.log(chalk.green(`VS Code debug config is ready for ${options.appName} instance ${options.instanceIndex}.`));
+    console.log(`Launch file: ${chalk.cyan(options.launchJsonPath)}`);
+    console.log(`Attach config: ${chalk.cyan(`Attach BTP ${options.appName}`)}`);
+    console.log(`Inspector: ${chalk.cyan(`127.0.0.1:${options.localPort}`)}`);
+    console.log("");
+    console.log(chalk.gray("Keep this terminal open, then open VS Code Run and Debug and choose the attach config above."));
+    console.log(chalk.gray("Press Ctrl+C in this terminal to close the tunnel."));
+}
+async function openVisualStudioCode(options) {
+    const result = await runCommand("code", [options.cwd]);
+    if (result.exitCode !== 0) {
+        console.log(chalk.yellow("Could not open VS Code automatically. Open this folder manually in VS Code."));
+        if (result.stderr)
+            console.log(chalk.gray(result.stderr));
+    }
+}
+async function selectDebugMode(options) {
+    if (options.check)
+        return "check-ssh";
+    if (options.enableSsh)
+        return "enable-ssh";
+    if (options.configOnly)
+        return "config-only";
+    if (options.linkOnly)
+        return "link-only";
+    if (options.chrome)
+        return "chrome";
+    if (options.vscode)
+        return "vscode";
+    return searchableSelectChoice({
+        message: "Select debug mode",
+        choices: [
+            {
+                title: "VS Code attach debugger (recommended)",
+                value: "vscode",
+                description: "Create/update .vscode/launch.json and open a CF SSH tunnel",
+            },
+            {
+                title: "Chrome DevTools / chrome://inspect",
+                value: "chrome",
+                description: "Open a CF SSH tunnel and print Chrome inspector links",
+            },
+            {
+                title: "Create/update VS Code launch.json only",
+                value: "config-only",
+                description: "Use when the tunnel is already open or you only need config",
+            },
+            {
+                title: "Print attach links/config only",
+                value: "link-only",
+                description: "Use when localhost inspector tunnel is already open",
+            },
+            {
+                title: "Check SSH enabled for app",
+                value: "check-ssh",
+                description: "Run cf ssh-enabled <app>",
+            },
+            {
+                title: "Enable SSH and restart app",
+                value: "enable-ssh",
+                description: "Run cf enable-ssh <app> and cf restart <app>",
+            },
+        ],
+        allowCustomValue: false,
+    });
+}
+async function maybeSwitchCloudFoundryTargetForDebug(options) {
+    if (options.skipOrgSelect || options.app?.trim()) {
+        return;
+    }
+    const target = await ensureCloudFoundrySessionFromCache();
+    const currentTargetLabel = [
+        target.org ? `org: ${target.org}` : "org: N/A",
+        target.space ? `space: ${target.space}` : "space: N/A",
+        target.apiEndpoint ? inferCloudFoundryRegionFromApiEndpoint(target.apiEndpoint) : "current region",
+    ].join(" · ");
+    const action = await searchableSelectChoice({
+        message: "Select BTP target for debug",
+        choices: [
+            { title: `Use current target (${currentTargetLabel})`, value: "current" },
+            { title: "Search org across regions and switch", value: "switch" },
+        ],
+        allowCustomValue: false,
+    });
+    if (action === "switch") {
+        await runOrgCommand({ switch: true });
+    }
+}
+async function selectDebugInstance(options) {
+    if (options.instance?.trim()) {
+        return options.instance.trim();
+    }
+    return searchableSelectChoice({
+        message: "Select app instance index",
+        choices: [
+            { title: "0", value: "0" },
+            { title: "1", value: "1" },
+            { title: "2", value: "2" },
+            { title: "3", value: "3" },
+        ],
+        validateCustomValue: (value) => /^\d+$/.test(value.trim()) ? true : "Instance index must be a number",
+        customValueTitle: (value) => `Use typed instance index: ${value}`,
+    });
+}
+async function selectDebugPort(options) {
+    if (options.value?.trim()) {
+        return parsePositivePort(options.value, options.defaultPort);
+    }
+    const portValue = await searchableSelectChoice({
+        message: options.message,
+        choices: [
+            { title: `${options.defaultPort} recommended`, value: String(options.defaultPort) },
+            { title: "9230", value: "9230" },
+            { title: "9231", value: "9231" },
+        ],
+        validateCustomValue: (value) => {
+            try {
+                parsePositivePort(value, options.defaultPort);
+                return true;
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : "Invalid port";
+            }
+        },
+        customValueTitle: (value) => `Use typed port: ${value}`,
+    });
+    return parsePositivePort(portValue, options.defaultPort);
+}
 function shouldIncludeLogLine(line, options) {
     const trimmedInstance = options.instance?.trim();
     const trimmedProcess = options.process?.trim();
@@ -231,6 +579,7 @@ async function runLoginCommand(options) {
         validate: validateRequired,
     });
     let password = options.password ?? lastProfile?.password;
+    let shouldSavePassword = options.savePassword ?? false;
     if (!password) {
         const response = await prompts({
             type: "password",
@@ -267,6 +616,19 @@ async function runLoginCommand(options) {
             password = passwordResponse.password;
         }
     }
+    if (!shouldSavePassword) {
+        const savePasswordResponse = await prompts({
+            type: "select",
+            name: "savePassword",
+            message: "Save password for automatic re-login and region scan?",
+            choices: [
+                { title: "Yes, save password on this machine", value: true },
+                { title: "No", value: false },
+            ],
+            initial: 0,
+        });
+        shouldSavePassword = Boolean(savePasswordResponse.savePassword);
+    }
     const apiExitCode = await setCloudFoundryApiEndpoint(apiEndpoint);
     if (apiExitCode !== 0) {
         process.exitCode = apiExitCode;
@@ -307,11 +669,11 @@ async function runLoginCommand(options) {
         username,
         org,
         space,
-        password: options.savePassword ? password : undefined,
+        password: shouldSavePassword ? password : undefined,
         updatedAt: new Date().toISOString(),
     });
-    if (options.savePassword) {
-        console.log(chalk.yellow("Password was cached in ~/.simplemdg/cache.json. Do not use --save-password on shared machines."));
+    if (shouldSavePassword) {
+        console.log(chalk.yellow("Password was cached in ~/.simplemdg/cache.json for automatic re-login. Do not use this on shared machines."));
     }
     console.log(chalk.green("CF login completed."));
 }
@@ -339,7 +701,12 @@ async function getCloudFoundryOrganizationsAcrossRegions(options) {
     }
     const apiEndpoints = getCloudFoundryApiEndpointsForOrgSearch(options, target, cache);
     console.log(chalk.gray(`Searching CF orgs across ${apiEndpoints.length} region endpoint(s)...`));
-    const entries = await scanCloudFoundryOrganizationsAcrossRegions(apiEndpoints);
+    const credentials = cache.cloudFoundry.loginProfiles.map((profile) => ({
+        apiEndpoint: profile.apiEndpoint,
+        username: profile.username,
+        password: profile.password,
+    }));
+    const entries = await scanCloudFoundryOrganizationsAcrossRegions(apiEndpoints, credentials);
     if (entries.length) {
         await rememberCloudFoundryOrgEntries(entries);
         return entries;
@@ -358,11 +725,7 @@ async function getCloudFoundryOrganizationsAcrossRegions(options) {
     return fallbackEntries;
 }
 async function runOrgCommand(options) {
-    const target = await readCloudFoundryTarget();
-    if (!target.apiEndpoint || !target.user) {
-        console.log(chalk.yellow("You are not logged in to Cloud Foundry yet. Run smdg cf login first."));
-        return;
-    }
+    const target = await ensureCloudFoundrySessionFromCache();
     const action = options.list
         ? "list"
         : options.switch
@@ -412,6 +775,11 @@ async function runOrgCommand(options) {
         };
     }
     else {
+        if (!organizationEntries.length) {
+            console.log(chalk.yellow("No orgs were found across regions."));
+            console.log(chalk.gray("Run smdg cf login and save the password, then run smdg cf org --list --refresh."));
+            return;
+        }
         const selectedIndex = await searchableSelectChoice({
             message: "Search CF org across regions",
             choices: organizationEntries.map((entry, index) => ({
@@ -564,9 +932,7 @@ async function runLogsCommand(options) {
         console.log(chalk.gray(`Streaming logs and appending to ${outputPath}`));
     }
     console.log(chalk.gray("Press Ctrl+C to stop realtime logs."));
-    const resolvedCommand = await ensureCommandAvailable("cf");
-    const childProcess = spawn(resolvedCommand.command, buildCloudFoundryLogsArgs({ appName, recent: false }), {
-        env: resolvedCommand.env,
+    const childProcess = spawn("cf", buildCloudFoundryLogsArgs({ appName, recent: false }), {
         stdio: ["ignore", "pipe", "pipe"],
         shell: false,
         windowsHide: true,
@@ -594,6 +960,169 @@ async function runLogsCommand(options) {
         childProcess.on("close", () => resolve());
     });
 }
+async function runDebugCommand(options) {
+    await maybeSwitchCloudFoundryTargetForDebug(options);
+    const appName = await resolveAppSelection({
+        app: options.app,
+        refresh: options.refresh,
+        message: "Search/select BTP app to debug",
+    });
+    const debugMode = await selectDebugMode(options);
+    const instanceIndex = await selectDebugInstance(options);
+    const localPort = await selectDebugPort({
+        value: options.localPort,
+        message: "Select local debug port",
+        defaultPort: 9229,
+    });
+    const remotePort = parsePositivePort(options.remotePort, 9229);
+    const repositoryPath = await resolveRepositoryPath(process.cwd()).catch(() => process.cwd());
+    if (debugMode === "check-ssh") {
+        const result = await runCommand("cf", ["ssh-enabled", appName]);
+        if (result.stdout)
+            console.log(result.stdout);
+        if (result.stderr)
+            console.error(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+    }
+    if (debugMode === "enable-ssh") {
+        const result = await runCommand("cf", ["enable-ssh", appName]);
+        if (result.stdout)
+            console.log(result.stdout);
+        if (result.stderr)
+            console.error(result.stderr);
+        if (result.exitCode !== 0) {
+            process.exitCode = result.exitCode;
+            return;
+        }
+        const restartResponse = await prompts({
+            type: "select",
+            name: "restart",
+            message: "Restart app now so SSH setting takes effect?",
+            choices: [
+                { title: "Yes, restart app", value: true },
+                { title: "No, I will restart later", value: false },
+            ],
+            initial: 0,
+        });
+        if (restartResponse.restart) {
+            const restartExitCode = await runCommandInherit("cf", ["restart", appName]);
+            process.exitCode = restartExitCode;
+            return;
+        }
+        console.log(chalk.yellow(`SSH was enabled. Restart the app before debugging: cf restart ${appName}`));
+        return;
+    }
+    let launchJsonPath;
+    if (debugMode === "vscode" || debugMode === "config-only") {
+        launchJsonPath = await writeVscodeLaunchConfiguration({
+            cwd: repositoryPath,
+            appName,
+            localPort,
+            remoteRoot: "/home/vcap/app",
+        });
+        console.log(chalk.green(`Updated VS Code launch config: ${launchJsonPath}`));
+        const openResponse = await prompts({
+            type: "select",
+            name: "open",
+            message: "Open current folder in VS Code?",
+            choices: [
+                { title: "No", value: false },
+                { title: "Yes", value: true },
+            ],
+            initial: options.open ? 1 : 0,
+        });
+        if (openResponse.open) {
+            await openVisualStudioCode({ cwd: repositoryPath });
+        }
+    }
+    if (debugMode === "config-only") {
+        printVscodeAttachInstructions({
+            appName,
+            instanceIndex,
+            localPort,
+            launchJsonPath: launchJsonPath ?? path.resolve(repositoryPath, ".vscode", "launch.json"),
+        });
+        return;
+    }
+    if (debugMode === "link-only") {
+        const debugUrl = await waitForNodeInspectorDebugUrl(localPort, 2000);
+        printNodeInspectorAttachInfo({ appName, instanceIndex, localPort, debugUrl });
+        return;
+    }
+    if (options.enableSsh) {
+        const result = await runCommand("cf", ["enable-ssh", appName]);
+        if (result.stdout)
+            console.log(result.stdout);
+        if (result.stderr)
+            console.error(result.stderr);
+        if (result.exitCode !== 0) {
+            process.exitCode = result.exitCode;
+            return;
+        }
+        if (options.restart) {
+            const restartExitCode = await runCommandInherit("cf", ["restart", appName]);
+            if (restartExitCode !== 0) {
+                process.exitCode = restartExitCode;
+                return;
+            }
+        }
+        else {
+            console.log(chalk.yellow("SSH was enabled. If cf ssh still fails, restart the app or run: cf restart " + appName));
+        }
+    }
+    console.log(chalk.gray(`Starting Node.js inspector tunnel for ${appName} instance ${instanceIndex}...`));
+    console.log(chalk.gray(`Forwarding localhost:${localPort} -> app container 127.0.0.1:${remotePort}`));
+    const childProcess = spawn("cf", buildCloudFoundryDebugSshArgs({
+        appName,
+        instanceIndex,
+        processName: options.process,
+        localPort,
+        remotePort,
+    }), {
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+        windowsHide: true,
+    });
+    let hasPrintedAttachInfo = false;
+    const printAttachInfoOnce = async () => {
+        if (hasPrintedAttachInfo) {
+            return;
+        }
+        hasPrintedAttachInfo = true;
+        if (debugMode === "vscode") {
+            printVscodeAttachInstructions({
+                appName,
+                instanceIndex,
+                localPort,
+                launchJsonPath: launchJsonPath ?? path.resolve(repositoryPath, ".vscode", "launch.json"),
+            });
+            return;
+        }
+        const debugUrl = await waitForNodeInspectorDebugUrl(localPort);
+        printNodeInspectorAttachInfo({ appName, instanceIndex, localPort, debugUrl });
+    };
+    childProcess.stdout?.on("data", (chunk) => {
+        const text = chunk.toString("utf8");
+        process.stdout.write(text);
+        if (/inspector|debug|listening|started/i.test(text)) {
+            void printAttachInfoOnce();
+        }
+    });
+    childProcess.stderr?.on("data", (chunk) => {
+        process.stderr.write(chunk.toString("utf8"));
+    });
+    const fallbackTimer = setTimeout(() => {
+        void printAttachInfoOnce();
+    }, 3000);
+    childProcess.on("close", (exitCode) => {
+        clearTimeout(fallbackTimer);
+        process.exitCode = exitCode ?? 0;
+    });
+    await new Promise((resolve) => {
+        childProcess.on("close", () => resolve());
+    });
+}
 async function runTargetCommand() {
     const target = await readCloudFoundryTarget();
     printTarget(target);
@@ -658,6 +1187,25 @@ export function registerCloudFoundryCommands(program) {
         .option("--instance <index>", "Filter logs by app instance index, for example 0 or 1")
         .option("--process <processName>", "Filter logs by process name, for example WEB")
         .action(runLogsCommand);
+    cfCommand
+        .command("debug")
+        .description("Debug a deployed BTP Cloud Foundry Node.js app with selectable VS Code or Chrome mode")
+        .option("--app <appName>", "BTP app name")
+        .option("--refresh", "Refresh app list before selecting")
+        .option("--instance <index>", "App instance index", "0")
+        .option("--process <processName>", "CF process name for multi-process apps")
+        .option("--local-port <port>", "Local inspector port", "9229")
+        .option("--remote-port <port>", "Remote inspector port in app container", "9229")
+        .option("--enable-ssh", "Run cf enable-ssh <app> before opening the debug tunnel")
+        .option("--restart", "Restart app after --enable-ssh")
+        .option("--check", "Run cf ssh-enabled <app> and exit")
+        .option("--link-only", "Only print attach links/config for an already-open tunnel")
+        .option("--vscode", "Use VS Code attach debug mode")
+        .option("--chrome", "Use Chrome DevTools debug mode")
+        .option("--config-only", "Only create/update .vscode/launch.json")
+        .option("--open", "Open current folder in VS Code after creating launch.json")
+        .option("--skip-org-select", "Use current CF org/space without asking")
+        .action(runDebugCommand);
     cfCommand
         .command("apps-cache-refresh")
         .description("Refresh cached cf apps for current target. Internal command used by smdg cf apps.")