@saptools/cf-debugger 0.1.15 → 0.2.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ interface SessionKey {
     readonly org: string;
     readonly space: string;
     readonly app: string;
+    /** Cloud Foundry process name (for example `web`), not an operating-system process. */
     readonly process?: string;
     readonly instance?: number;
     readonly apiEndpoint?: string;
@@ -18,7 +19,11 @@ interface ActiveSession extends SessionKey {
     /** Compatibility alias for the currently active controller or tunnel PID. */
     readonly pid: number;
     readonly controllerPid?: number;
+    /** Optional OS process birth token; absent records retain PID-only compatibility. */
+    readonly controllerProcessIdentity?: string;
     readonly tunnelPid?: number;
+    /** Optional OS process birth token; absent records retain PID-only compatibility. */
+    readonly tunnelProcessIdentity?: string;
     readonly hostname: string;
     readonly localPort: number;
     readonly remotePort: number;
@@ -27,6 +32,8 @@ interface ActiveSession extends SessionKey {
     readonly startedAt: string;
     readonly status: SessionStatus;
     readonly remoteNodePid?: number;
+    /** Startup budget used for stale-session evaluation; absent records use the supported maximum. */
+    readonly startupTimeoutMs?: number;
     readonly stopRequestedAt?: string;
     readonly message?: string;
 }
@@ -34,8 +41,10 @@ interface StartDebuggerOptions extends SessionKey {
     readonly email?: string;
     readonly password?: string;
     readonly preferredPort?: number;
+    readonly remotePort?: number;
     readonly tunnelReadyTimeoutMs?: number;
-    /** Set false when the caller must not enable SSH or restart the deployed app. Defaults to true. */
+    readonly startupTimeoutMs?: number;
+    /** Set true to permit app-level SSH enablement and an app restart. Defaults to false. */
     readonly allowSshEnableRestart?: boolean;
     readonly verbose?: boolean;
     readonly onStatus?: (status: SessionStatus, message?: string) => void;
@@ -54,27 +63,99 @@ declare class CfDebuggerError extends Error {
 
 declare function startDebugger(options: StartDebuggerOptions): Promise<DebuggerHandle>;
 
+type SessionHealthStatus = "healthy" | "stale" | "unverified";
+interface SessionHealthVerdict {
+    readonly status: SessionHealthStatus;
+    readonly reason: string;
+}
+
+declare function sessionKeyString(key: SessionKey): string;
+
+type DoctorCleanupStatus = "not-requested" | "not-eligible" | "removed" | "skipped" | "failed";
+interface DoctorSessionFinding {
+    readonly session: ActiveSession;
+    readonly health: SessionHealthVerdict;
+}
+interface DoctorHomeFinding {
+    readonly sessionId: string;
+    readonly path: string;
+    readonly cleanupEligible: boolean;
+    readonly cleanupStatus: DoctorCleanupStatus;
+}
+interface DoctorPortFinding {
+    readonly port: number;
+    readonly pids: readonly number[];
+    readonly ownerStatus: "found" | "unverified";
+    readonly reason?: string;
+}
+type DoctorArtifactKind = "state-temp" | "state-lock" | "state-recovery" | "stop-intent" | "corrupt-backup";
+interface DoctorArtifactFinding {
+    readonly kind: DoctorArtifactKind;
+    readonly path: string;
+    readonly ageMs: number;
+    readonly cleanupEligible: boolean;
+    readonly cleanupStatus: DoctorCleanupStatus;
+    readonly cleanupError?: string;
+}
+interface DoctorLegacyFinding {
+    readonly statePath: string;
+    readonly statePresent: boolean;
+    readonly homesPath: string;
+    readonly homesPresent: boolean;
+    readonly warning?: string;
+    readonly manualRemovalCommand?: string;
+}
+interface DoctorReport {
+    readonly sessions: readonly DoctorSessionFinding[];
+    readonly orphanHomes: readonly DoctorHomeFinding[];
+    readonly unclaimedPorts: readonly DoctorPortFinding[];
+    readonly artifacts: readonly DoctorArtifactFinding[];
+    readonly legacy: DoctorLegacyFinding;
+    readonly warnings: readonly string[];
+    readonly cleanedPaths: readonly string[];
+}
+interface DoctorOptions {
+    readonly cleanup?: boolean;
+}
+declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+
 interface StopOptions {
     readonly sessionId?: string;
     readonly key?: SessionKey;
+    readonly force?: boolean;
 }
 interface StopDebuggerResult extends ActiveSession {
     readonly stale: boolean;
     readonly pending: boolean;
+    readonly forced: boolean;
+    readonly warning?: string;
+}
+interface StopAllOutcome {
+    readonly sessionId: string;
+    readonly app: string;
+    readonly status: "failed" | "pending" | "stale" | "stopped";
+    readonly result?: StopDebuggerResult;
+    readonly error?: CfDebuggerError;
+}
+interface StopAllResult {
+    readonly outcomes: readonly StopAllOutcome[];
+    readonly failed: number;
+    readonly pending: number;
+    readonly stale: number;
+    readonly stopped: number;
 }
 declare function stopDebugger(options: StopOptions): Promise<StopDebuggerResult | undefined>;
-declare function stopAllDebuggers(): Promise<number>;
+declare function stopAllDebuggers(force?: boolean): Promise<StopAllResult>;
 declare function listSessions(): Promise<readonly ActiveSession[]>;
 declare function getSession(key: SessionKey): Promise<ActiveSession | undefined>;
 
-declare function resolveApiEndpoint(regionKey: string, override?: string): string;
+declare function resolveApiEndpoint(regionKey: string, override?: string, onWarning?: (warning: string) => void): string;
 declare function listKnownRegionKeys(): readonly string[];
 
-declare function sessionKeyString(key: SessionKey): string;
-
 interface CurrentCfTargetReadOptions {
     readonly command?: string;
     readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
     readonly timeoutMs?: number;
 }
 interface CurrentCfTarget {
@@ -86,7 +167,10 @@ interface CurrentCfTarget {
 declare function readCurrentCfTarget(options?: CurrentCfTargetReadOptions): Promise<CurrentCfTarget | undefined>;
 declare function parseCurrentCfTarget(stdout: string): CurrentCfTarget | undefined;
 declare function requireCurrentCfRegion(target: Pick<CurrentCfTarget, "apiEndpoint" | "region">, instruction?: string): string;
+declare function regionKeyForApiEndpoint(apiEndpoint: string): string | undefined;
+declare function regionKeyFromSapApiEndpoint(apiEndpoint: string): string | undefined;
 
+declare const DEFAULT_NODE_INSPECTOR_PORT = 9229;
 interface NodeTargetSelectors {
     readonly process?: string;
     readonly instance?: number;
@@ -101,7 +185,7 @@ interface NodeProcessSelection {
     readonly remoteNodePid: number;
 }
 declare function resolveNodeTarget(input: NodeTargetSelectors): ResolvedNodeTarget;
-declare function buildNodeInspectorCommand(nodePid?: number): string;
-declare function parseNodeInspectorMarkers(stdout: string): NodeProcessSelection;
+declare function buildNodeInspectorCommand(nodePid?: number, remotePort?: number): string;
+declare function parseNodeInspectorMarkers(stdout: string, remotePort?: number): NodeProcessSelection;
 
-export { type ActiveSession, CfDebuggerError, type CurrentCfTarget, type CurrentCfTargetReadOptions, type DebuggerHandle, type NodeProcessSelection, type NodeTargetSelectors, type ResolvedNodeTarget, type ResolvedSessionKey, type SessionKey, type SessionStatus, type StartDebuggerOptions, buildNodeInspectorCommand, getSession, listKnownRegionKeys, listSessions, parseCurrentCfTarget, parseNodeInspectorMarkers, readCurrentCfTarget, requireCurrentCfRegion, resolveApiEndpoint, resolveNodeTarget, sessionKeyString, startDebugger, stopAllDebuggers, stopDebugger };
+export { type ActiveSession, CfDebuggerError, type CurrentCfTarget, type CurrentCfTargetReadOptions, DEFAULT_NODE_INSPECTOR_PORT, type DebuggerHandle, type DoctorArtifactFinding, type DoctorArtifactKind, type DoctorCleanupStatus, type DoctorHomeFinding, type DoctorLegacyFinding, type DoctorOptions, type DoctorPortFinding, type DoctorReport, type DoctorSessionFinding, type NodeProcessSelection, type NodeTargetSelectors, type ResolvedNodeTarget, type ResolvedSessionKey, type SessionKey, type SessionStatus, type StartDebuggerOptions, type StopAllOutcome, type StopAllResult, type StopDebuggerResult, type StopOptions, buildNodeInspectorCommand, getSession, listKnownRegionKeys, listSessions, parseCurrentCfTarget, parseNodeInspectorMarkers, readCurrentCfTarget, regionKeyForApiEndpoint, regionKeyFromSapApiEndpoint, requireCurrentCfRegion, resolveApiEndpoint, resolveNodeTarget, runDoctor, sessionKeyString, startDebugger, stopAllDebuggers, stopDebugger };