@cspeach/cli 1.1.18 → 1.1.19

package/dist/tools/fiori/preview/registry.js

@@ -0,0 +1,412 @@
+// cspeach-cli/src/tools/fiori/preview/registry.ts
+/**
+ * L1-6 — the in-process preview registry, keyed by ABSOLUTE app directory.
+ *
+ * WHY NOT subagent/_background-shared.ts
+ * --------------------------------------
+ * That registry is keyed by `bg_id` and has no notion of a port, a URL or
+ * reuse: two `background_run` calls for the same command are two independent
+ * children, and that is correct THERE. A preview is different — one app
+ * directory has at most ONE preview server, because a second one binds a second
+ * port and then nobody can say which of :8080 and :8081 the browser check is
+ * looking at. That ambiguity is the July bug.
+ *
+ * IDENTITY — WHOSE PROCESS IS IT? (review F-3)
+ * -------------------------------------------
+ * A pid is not an identity. Windows recycles pids aggressively once the process
+ * handle is closed, so `taskkill /PID <remembered pid> /T /F` hours later can
+ * hit the owner's editor. Therefore:
+ *   - the registry listens for the child's own `'exit'` and forgets the entry
+ *     the moment the preview dies, so a dead entry never lingers with its pid;
+ *   - nothing is ever killed unless THIS process still holds a LIVE child
+ *     handle for it (`exitCode === null && signalCode === null`);
+ *   - `pid <= 1` or a non-integer pid is refused before any kill — `-1` is
+ *     "every process of this user" on POSIX and `taskkill /PID 0` is the
+ *     System Idle Process on Windows;
+ *   - a preview started by a PREVIOUS CLI process is not ours to kill by pid.
+ *
+ * KILLING THE TREE
+ * ----------------
+ * The process we spawn is usually NOT the process holding the port. On Windows
+ * cross-spawn runs `npm.cmd` through cmd.exe, which runs node, which runs the
+ * ui5 server: three levels, and cmd.exe creates no job object, so its
+ * descendants outlive it.
+ *   - Windows: the ABSOLUTE `%SystemRoot%\System32\taskkill.exe` (never the bare
+ *     name — libuv searches the current directory first on Windows and the CLI's
+ *     cwd is the model-writable workspace), with a minimal environment.
+ *   - POSIX: the child leads its own process group (spawned detached), so
+ *     `process.kill(-pid, …)` signals the whole group; SIGTERM, poll, SIGKILL.
+ *
+ * THE EXIT PATH (review F-1)
+ * --------------------------
+ * An asynchronous `spawn` inside `process.on('exit')` is a NO-OP on Windows:
+ * the taskkill child sits in libuv's KILL_ON_JOB_CLOSE job, which closes
+ * milliseconds later and takes it down before it has killed anything (measured:
+ * 8 of 8 targets survived). The exit path is therefore `spawnSync`, and the
+ * signal listeners are PREPENDED so they run before a handler that re-raises,
+ * and re-raise themselves when ours is the only listener so the CLI still exits
+ * on Ctrl+C.
+ *
+ * Per-process only, never persisted — the lifetime of a previewId is bounded by
+ * the CLI process that started it, and the exit path makes sure of it.
+ */
+import { spawn as nodeSpawn, spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { KILL_GRACE_MS } from '../../_command-shared.js';
+/** appDirKey → tracked preview. At most one per directory, by construction. */
+const registry = new Map();
+/**
+ * Children spawned but not yet registered — a preview can sit in the readiness
+ * wait for up to two minutes, and quitting the CLI during that window used to
+ * orphan it (F-5). Everything here is swept by the exit path too.
+ */
+const pendingChildren = new Set();
+let exitHandlerInstalled = false;
+/** Absolute taskkill, with a minimal environment — never the bare name (F-6). */
+// R1-11: an empty or RELATIVE value would make taskkill resolve against the
+// cwd (os.tmpdir()), so only an absolute drive path is trusted.
+export function resolveSystemRoot(env) {
+    for (const v of [env.SystemRoot, env.windir]) {
+        if (typeof v === 'string' && /^[A-Za-z]:[\\/]/.test(v))
+            return v;
+    }
+    return 'C:\\Windows';
+}
+const SYSTEM_ROOT = resolveSystemRoot(process.env);
+const TASKKILL = path.join(SYSTEM_ROOT, 'System32', 'taskkill.exe');
+const TASKKILL_ENV = { SystemRoot: SYSTEM_ROOT };
+const TASKKILL_TIMEOUT_MS = 4_000;
+/** How long `stopPreview` waits for the port to actually close. */
+export const PORT_CLOSE_BUDGET_MS = 5_000;
+/**
+ * The registry key. Absolute, then the REAL path (so a junction, an 8.3 short
+ * name and the long name collapse to one key), then lower-cased on Windows
+ * (where `apps/MyApp` and `apps/myapp` are the same directory but `resolveSafePath`
+ * is lexical and case-preserving). Falls back to the lexical path when the
+ * directory does not exist yet.
+ */
+export function previewKeyFor(appDir) {
+    return keyFor(appDir);
+}
+function keyFor(appDir) {
+    const abs = path.resolve(appDir);
+    let real = abs;
+    try {
+        real = realpathSync.native(abs);
+    }
+    catch { /* not on disk (yet) — lexical is fine */ }
+    let trimmed = real.length > 1 ? real.replace(/[\\/]+$/, '') : real;
+    if (/^[A-Za-z]:$/.test(trimmed))
+        trimmed += path.sep; // R1-13: a drive root stays a root
+    return process.platform === 'win32' ? trimmed.toLowerCase() : trimmed;
+}
+/** True only while THIS process holds a live handle on the child. */
+export function childIsLive(child) {
+    return !!child && child.exitCode === null && child.signalCode === null;
+}
+/** A pid we are allowed to signal. 0 = own group / idle process, 1 = everything. */
+function killablePid(pid) {
+    return typeof pid === 'number' && Number.isInteger(pid) && pid > 1;
+}
+export function registerPreview(e, child) {
+    const key = keyFor(e.appDir);
+    const previous = registry.get(key);
+    // F-5.3: replacing a live, DIFFERENT child would make its tree unreachable by
+    // stop/list/the exit path — the ':8080 beside :8081' shape. Kill it first.
+    if (previous && previous.child !== child && childIsLive(previous.child)) {
+        void killProcessTree(previous.entry.pid, previous.child);
+    }
+    registry.set(key, { entry: e, child });
+    if (child) {
+        pendingChildren.delete(child);
+        // F-3.1: the preview dying on its own (crash, port clash, user closes it)
+        // must empty the registry at once — otherwise `list` lies and a later stop
+        // fires a kill at a pid that may since have been recycled.
+        child.once('exit', () => {
+            pendingChildren.delete(child);
+            const tracked = registry.get(key);
+            if (tracked?.entry.previewId === e.previewId)
+                registry.delete(key);
+        });
+    }
+}
+/** Track a child from spawn until it is registered (or dies) — see F-5. */
+export function markPendingChild(child) {
+    pendingChildren.add(child);
+    child.once('exit', () => pendingChildren.delete(child));
+}
+export function unmarkPendingChild(child) {
+    pendingChildren.delete(child);
+}
+/** One entry per app dir — this is what removes the ':8080 beside :8081' ambiguity. */
+export function findPreviewByAppDir(appDir) {
+    return registry.get(keyFor(appDir))?.entry;
+}
+export function findPreviewById(previewId) {
+    for (const t of registry.values())
+        if (t.entry.previewId === previewId)
+            return t.entry;
+    return undefined;
+}
+/** The live child handle for a previewId, when this process still holds one. */
+export function findChildById(previewId) {
+    for (const t of registry.values())
+        if (t.entry.previewId === previewId)
+            return t.child;
+    return undefined;
+}
+export function listPreviews() {
+    return [...registry.values()].map((t) => t.entry);
+}
+/** Forget an entry WITHOUT killing anything (a preview that already exited). */
+export function forgetPreview(previewId) {
+    for (const [k, t] of registry) {
+        if (t.entry.previewId === previewId) {
+            registry.delete(k);
+            return true;
+        }
+    }
+    return false;
+}
+/** True when the pid still exists (signal 0 probe). Undefined pid → false. */
+export function isPidAlive(pid) {
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill a process and everything it spawned. Resolves when the kill has been
+ * issued (and, on Windows, when taskkill has exited), reporting WHAT happened
+ * so the caller can claim only what it can show (F-7).
+ */
+async function realKillProcessTree(pid, child) {
+    if (!killablePid(pid)) {
+        // No usable pid. A live handle can still be closed politely.
+        if (childIsLive(child)) {
+            try {
+                child.kill('SIGKILL');
+                return { issued: true, exitCode: null };
+            }
+            catch { /* gone */ }
+        }
+        return { issued: false, exitCode: null, reason: `refusing to signal pid ${String(pid)}` };
+    }
+    if (process.platform === 'win32') {
+        // R1-1: once the child has exited, libuv closed its handle and Windows may
+        // already have handed its pid to another process. `taskkill /T` at a dead
+        // pid walks nothing of ours and could hit a stranger. (POSIX keeps the
+        // group signal below: survivors of a dead leader are still in the group,
+        // and a pgid is not reused while a member lives.)
+        if (child !== undefined && !childIsLive(child)) {
+            return { issued: false, exitCode: null, reason: 'the process already exited — its pid is no longer ours' };
+        }
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = (o) => { if (!done) {
+                done = true;
+                resolve(o);
+            } };
+            try {
+                const tk = nodeSpawn(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    cwd: os.tmpdir(),
+                    env: TASKKILL_ENV,
+                });
+                tk.on('exit', (code) => finish({ issued: true, exitCode: code }));
+                tk.on('error', (err) => {
+                    try {
+                        if (childIsLive(child))
+                            child.kill('SIGKILL');
+                    }
+                    catch { /* gone */ }
+                    finish({ issued: false, exitCode: null, reason: err.message });
+                });
+                // Never hang the CLI on a wedged taskkill.
+                const t = setTimeout(() => finish({ issued: true, exitCode: null, reason: 'taskkill timed out' }), TASKKILL_TIMEOUT_MS);
+                t.unref();
+            }
+            catch (err) {
+                try {
+                    if (childIsLive(child))
+                        child.kill('SIGKILL');
+                }
+                catch { /* gone */ }
+                finish({ issued: false, exitCode: null, reason: err instanceof Error ? err.message : String(err) });
+            }
+        });
+    }
+    // POSIX: the child leads its own process group (spawned detached), so the
+    // negative pid signals the group — the grandchildren included.
+    let issued = false;
+    try {
+        process.kill(-pid, 'SIGTERM');
+        issued = true;
+    }
+    catch {
+        try {
+            if (childIsLive(child)) {
+                child.kill('SIGTERM');
+                issued = true;
+            }
+        }
+        catch { /* gone */ }
+    }
+    // F-14: poll instead of always sleeping the full grace...
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (Date.now() < deadline && isPidAlive(pid)) {
+        await new Promise((r) => { const t = setTimeout(r, 100); t.unref(); });
+    }
+    // ...and SIGKILL the GROUP unconditionally afterwards: a surviving group
+    // member whose leader already died would otherwise never be signalled.
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* group already gone */ }
+    return { issued, exitCode: null };
+}
+let killImpl = realKillProcessTree;
+export function killProcessTree(pid, child) {
+    return killImpl(pid, child);
+}
+/** Test-only — replace the kill so the unit suite never signals a real pid (F-4). */
+export function __setKillForTests(fn) { killImpl = fn; }
+export function __resetKillForTests() { killImpl = realKillProcessTree; }
+// ───────────────────────────────── stop, with evidence ──────────────────────
+/** True when something is listening on host:port. */
+function portOpen(host, port, timeoutMs = 1_000) {
+    return new Promise((resolve) => {
+        const sock = net.connect({ port, host });
+        const done = (v) => { sock.destroy(); resolve(v); };
+        sock.once('connect', () => done(true));
+        sock.once('error', () => done(false));
+        sock.setTimeout(timeoutMs, () => done(false));
+    });
+}
+/** Poll BOTH loopback families until the port is closed, or the budget ends. */
+async function waitForPortClosed(port, budgetMs = PORT_CLOSE_BUDGET_MS) {
+    const deadline = Date.now() + budgetMs;
+    for (;;) {
+        const v4 = await portOpen('127.0.0.1', port);
+        const v6 = v4 ? true : await portOpen('::1', port);
+        if (!v4 && !v6)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => { setTimeout(r, 150); });
+    }
+}
+/**
+ * Stop a preview: kill the tree of a child THIS process still holds, then prove
+ * the port closed. An entry with no live handle is forgotten, never killed by
+ * pid (F-3).
+ */
+export async function stopPreview(previewId) {
+    let found;
+    let key;
+    for (const [k, t] of registry) {
+        if (t.entry.previewId === previewId) {
+            found = t;
+            key = k;
+            break;
+        }
+    }
+    if (!found || key === undefined) {
+        return { stopped: false, portClosed: false, issued: false, exitCode: null, reason: 'no such previewId' };
+    }
+    // Delete FIRST so a kill that throws still leaves a consistent registry and a
+    // concurrent second stop cannot fire twice at the same pid.
+    registry.delete(key);
+    const port = found.entry.port;
+    if (!childIsLive(found.child)) {
+        // It already exited, or it belongs to a previous CLI process. Either way its
+        // pid is not an identity we may act on.
+        const portClosed = await waitForPortClosed(port, 1_000);
+        return {
+            stopped: true, portClosed, port, issued: false, exitCode: null,
+            reason: 'this session holds no live process handle for that preview — nothing was killed',
+        };
+    }
+    const outcome = await killProcessTree(found.entry.pid, found.child);
+    const portClosed = await waitForPortClosed(port);
+    return { stopped: true, portClosed, port, ...outcome };
+}
+function realSyncKill(pid) {
+    if (process.platform === 'win32') {
+        spawnSync(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
+            windowsHide: true,
+            stdio: 'ignore',
+            cwd: os.tmpdir(),
+            env: TASKKILL_ENV,
+            timeout: TASKKILL_TIMEOUT_MS,
+        });
+    }
+    else {
+        process.kill(-pid, 'SIGTERM');
+    }
+}
+let syncKillImpl = realSyncKill;
+/** Test-only — replace the exit-path kill (R1-9). */
+export function __setSyncKillForTests(fn) { syncKillImpl = fn; }
+export function __resetSyncKillForTests() { syncKillImpl = realSyncKill; }
+export function killAllPreviewsSync() {
+    const victims = [];
+    for (const t of registry.values())
+        victims.push({ pid: t.entry.pid, child: t.child });
+    for (const c of pendingChildren)
+        victims.push({ pid: c.pid, child: c });
+    for (const v of victims) {
+        // Same identity rule as everywhere else: a live handle we hold, a sane pid.
+        if (!childIsLive(v.child) || !killablePid(v.pid))
+            continue;
+        try {
+            syncKillImpl(v.pid);
+        }
+        catch { /* already gone */ }
+    }
+    registry.clear();
+    pendingChildren.clear();
+}
+/** Kill every live preview on CLI exit or on a terminating signal. Idempotent. */
+export function installPreviewExitHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    process.on('exit', killAllPreviewsSync);
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        // PREPEND: ui/alt-screen.ts re-raises with process.kill(process.pid, sig),
+        // which on Windows is an immediate TerminateProcess — a listener appended
+        // after it would never run, and 'exit' would never fire either.
+        process.prependListener(sig, () => {
+            killAllPreviewsSync();
+            // In one-shot/classic mode ours may be the ONLY listener, and merely
+            // having one removes Node's default exit-on-signal. Re-raise so Ctrl+C
+            // still stops the CLI.
+            if (process.listenerCount(sig) === 1) {
+                process.removeAllListeners(sig);
+                process.kill(process.pid, sig);
+            }
+        });
+    }
+}
+export function __resetPreviewRegistryForTests() {
+    registry.clear();
+    pendingChildren.clear();
+}
+/** Test-only — observe whether installPreviewExitHandler has fired. */
+export function __isPreviewExitHandlerInstalledForTests() {
+    return exitHandlerInstalled;
+}
+/** Test-only — how many spawned-but-not-yet-registered children are tracked. */
+export function __pendingChildCountForTests() {
+    return pendingChildren.size;
+}