@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/tools/server-tools.js

@@ -1,892 +0,0 @@
-/**
- * server-tools - Phase 1 runtime evidence primitives (PUGI Phase 1).
- *
- * These tools give the model a way to spin up a service, probe its
- * health endpoint, harvest log tails, and tear it down - turning
- * "server is running" prose into pid + health 200 evidence.
- *
- * Surfaced as four tools:
- *   - server_start: spawn `command` in `cwd`, poll `healthUrl` until
- *     status === expectStatus (default 200) OR timeout elapses OR
- *     the process exits. Persist {pid, port, logPath, command} to
- *     `.pugi/runs/<runId>/server.json` for later inspection.
- *   - server_stop: SIGTERM → graceMs → SIGKILL the pid, returning the
- *     exit code + signal. No-op-safe when the process is already dead.
- *   - server_health: one-shot HTTP GET against an arbitrary url with a
- *     timeout. Distinct from `server_start`'s built-in health probe
- *     because the model frequently needs to re-check liveness after
- *     migrations / restarts.
- *   - server_logs: read the trailing N lines of a `runId` (or pid)'s
- *     log file so the model can diagnose a failure without re-running
- *     the server.
- *
- * The async + sync entry points mirror the bash-tool split so the
- * engine-loop tool-bridge can dispatch from spawnSync paths too.
- *
- * Security posture:
- *   - server_start / server_stop use the bash permission class via the
- *     registry so the existing mode-aware permission gate applies. The
- *     tool itself does NOT call evaluateBashPermission - the bash-class
- *     entry in registry.ts pins risk=high and concurrencySafe=false.
- *   - server_logs is read-only against `.pugi/runs/<runId>/server.log`.
- *     Path traversal is gated by `resolveWorkspacePath` to keep the
- *     read inside the workspace.
- *   - env is filtered through the same SAFE_ENV_ALLOW set as bash.ts so
- *     PUGI_API_KEY / PUGI_LOGIN_TOKEN never leak to the spawned child.
- *
- * Brand voice: English only, no emoji, no banned words.
- */
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
-/** Default health-poll cadence. */
-export const SERVER_START_DEFAULT_POLL_MS = 500;
-/** Default health-probe timeout - generous because dev servers warm up. */
-export const SERVER_START_DEFAULT_TIMEOUT_MS = 30_000;
-/** Upper bound on the health-probe timeout. */
-export const SERVER_START_MAX_TIMEOUT_MS = 5 * 60 * 1_000;
-/** Default grace window between SIGTERM and SIGKILL. Mirrors bash.ts. */
-export const SERVER_STOP_DEFAULT_GRACE_MS = 5_000;
-/** Upper bound on the stop grace window. */
-export const SERVER_STOP_MAX_GRACE_MS = 60_000;
-/** Default tail size for server_logs. */
-export const SERVER_LOGS_DEFAULT_TAIL = 200;
-/** Upper bound on log tail size to keep the response envelope sized. */
-export const SERVER_LOGS_MAX_TAIL = 2_000;
-/** Sentinel returned when an argument shape fails validation. */
-export const SERVER_INVALID_ARGS = 'SERVER_INVALID_ARGS';
-/**
- * Subset of process.env we forward to the spawned server. Mirrors the
- * SAFE_ENV_ALLOW set in bash.ts so PUGI credentials never leak across
- * the boundary even when an operator passes them via `env`.
- */
-const SAFE_ENV_ALLOW = new Set([
-    'PATH',
-    'HOME',
-    'USER',
-    'LOGNAME',
-    'SHELL',
-    'LANG',
-    'TZ',
-    'TERM',
-    'PWD',
-    'NODE_ENV',
-    'NODE_OPTIONS',
-    'NODE_VERSION',
-]);
-function buildChildEnv(extra) {
-    const env = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value === undefined)
-            continue;
-        if (SAFE_ENV_ALLOW.has(key) || key.startsWith('LC_')) {
-            env[key] = value;
-        }
-    }
-    // Caller-supplied env overrides system inheritance. We do NOT filter
-    // the caller set - the model is expected to supply concrete keys
-    // (NODE_ENV=development, PORT=3000) and should not be silently
-    // dropped just because the key falls outside the allowlist.
-    if (extra) {
-        for (const [key, value] of Object.entries(extra)) {
-            if (typeof value === 'string')
-                env[key] = value;
-        }
-    }
-    return env;
-}
-/**
- * Resolve `cwd` against the workspace root. Relative paths root at
- * workspaceRoot; absolute paths are accepted ONLY when they fall under
- * workspaceRoot. Anything else collapses to workspaceRoot - defense in
- * depth so a stale path argument cannot spawn a server outside the
- * operator's workspace.
- */
-function resolveCwd(workspaceRoot, requested) {
-    if (!requested)
-        return workspaceRoot;
-    const absolute = isAbsolute(requested) ? requested : resolve(workspaceRoot, requested);
-    const rootAnchor = workspaceRoot.endsWith('/') ? workspaceRoot.slice(0, -1) : workspaceRoot;
-    if (absolute === rootAnchor || absolute.startsWith(`${rootAnchor}/`)) {
-        return absolute;
-    }
-    return workspaceRoot;
-}
-/**
- * Validate `server_start` arguments. Returns the typed payload on
- * success or a sentinel string on failure (consistent with the
- * sleep/brief tool convention).
- */
-export function parseServerStartArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const command = obj['command'];
-    const port = obj['port'];
-    if (typeof command !== 'string' || command.trim() === '') {
-        return `${SERVER_INVALID_ARGS}: command must be a non-empty string`;
-    }
-    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
-        return `${SERVER_INVALID_ARGS}: port must be an integer in [1, 65535]`;
-    }
-    const cwd = obj['cwd'];
-    if (cwd !== undefined && typeof cwd !== 'string') {
-        return `${SERVER_INVALID_ARGS}: cwd must be a string when provided`;
-    }
-    const healthUrl = obj['healthUrl'];
-    if (healthUrl !== undefined && typeof healthUrl !== 'string') {
-        return `${SERVER_INVALID_ARGS}: healthUrl must be a string when provided`;
-    }
-    const timeoutMs = obj['timeoutMs'];
-    if (timeoutMs !== undefined) {
-        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-            return `${SERVER_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
-        }
-    }
-    const expectStatus = obj['expectStatus'];
-    if (expectStatus !== undefined) {
-        if (typeof expectStatus !== 'number' || !Number.isInteger(expectStatus) || expectStatus < 100 || expectStatus > 599) {
-            return `${SERVER_INVALID_ARGS}: expectStatus must be an integer in [100, 599]`;
-        }
-    }
-    const env = obj['env'];
-    if (env !== undefined) {
-        if (typeof env !== 'object' || env === null || Array.isArray(env)) {
-            return `${SERVER_INVALID_ARGS}: env must be a JSON object of string values`;
-        }
-        for (const [k, v] of Object.entries(env)) {
-            if (typeof v !== 'string') {
-                return `${SERVER_INVALID_ARGS}: env["${k}"] must be a string`;
-            }
-        }
-    }
-    const args = {
-        command,
-        port,
-        ...(typeof cwd === 'string' ? { cwd } : {}),
-        ...(typeof healthUrl === 'string' ? { healthUrl } : {}),
-        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
-        ...(typeof expectStatus === 'number' ? { expectStatus } : {}),
-        ...(env !== undefined ? { env: env } : {}),
-    };
-    return args;
-}
-function clampTimeout(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-        return SERVER_START_DEFAULT_TIMEOUT_MS;
-    }
-    return Math.min(value, SERVER_START_MAX_TIMEOUT_MS);
-}
-function clampGrace(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-        return SERVER_STOP_DEFAULT_GRACE_MS;
-    }
-    return Math.min(value, SERVER_STOP_MAX_GRACE_MS);
-}
-function clampTail(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-        return SERVER_LOGS_DEFAULT_TAIL;
-    }
-    return Math.min(Math.floor(value), SERVER_LOGS_MAX_TAIL);
-}
-function ensureRunsDir(workspaceRoot, runId) {
-    const dir = join(workspaceRoot, '.pugi', 'runs', runId);
-    mkdirSync(dir, { recursive: true });
-    return { dir, logPath: join(dir, 'server.log'), metaPath: join(dir, 'server.json') };
-}
-function writeMeta(metaPath, meta) {
-    try {
-        const body = JSON.stringify(meta, null, 2);
-        writeFileSync(metaPath, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
-    }
-    catch {
-        // best-effort - the in-memory return envelope still carries the data
-    }
-}
-/**
- * Open a write stream to the log file. Uses appendFileSync from the
- * spawned child's stdout/stderr handlers because spawn's stdio file
- * descriptor inheritance is fiddly across platforms and we want the
- * loop to honour the cancel/timeout windows above all else.
- */
-function openLogWriter(logPath) {
-    // Truncate existing file so reruns of the same runId start fresh.
-    try {
-        writeFileSync(logPath, '', { encoding: 'utf8', mode: 0o600 });
-    }
-    catch {
-        // ignore - appends below will retry through writeFileSync
-    }
-    return (chunk) => {
-        try {
-            const data = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
-            // appendFileSync via writeFileSync + flag 'a' is simpler than
-            // requiring fs/promises in a sync path. We use the node fs append
-            // mode via an opt-in `flag: 'a'` on writeFileSync.
-            writeFileSync(logPath, data, { encoding: 'utf8', flag: 'a' });
-        }
-        catch {
-            // log capture is best-effort - never crash the server tool
-        }
-    };
-}
-/**
- * Poll the health URL until either:
- *  - the HTTP call returns the expected status code → ok=true
- *  - the timeout elapses → ok=false with reason=timeout_waiting_health
- *  - the spawned child exits before the probe succeeds → ok=false with
- *    reason=process_exited (the close-watcher flips this flag)
- */
-async function pollHealth(input) {
-    const start = input.now();
-    const deadline = start + input.timeoutMs;
-    let lastStatus;
-    while (input.now() < deadline) {
-        if (input.hasExited()) {
-            return {
-                ok: false,
-                durationMs: input.now() - start,
-                reason: 'process_exited',
-                ...(lastStatus !== undefined ? { status: lastStatus } : {}),
-            };
-        }
-        try {
-            const ac = new AbortController();
-            const probeTimeout = setTimeout(() => ac.abort(), Math.min(2_000, input.timeoutMs));
-            try {
-                const res = await input.fetchImpl(input.url, { signal: ac.signal });
-                lastStatus = res.status;
-                if (res.status === input.expectStatus) {
-                    return { ok: true, status: res.status, durationMs: input.now() - start };
-                }
-            }
-            finally {
-                clearTimeout(probeTimeout);
-            }
-        }
-        catch {
-            // network refused / dns / abort - keep polling, the server is
-            // probably still warming up
-        }
-        await input.sleeper(SERVER_START_DEFAULT_POLL_MS);
-    }
-    return {
-        ok: false,
-        durationMs: input.now() - start,
-        reason: 'timeout_waiting_health',
-        ...(lastStatus !== undefined ? { status: lastStatus } : {}),
-    };
-}
-/**
- * Dispatch entry: parse args, spawn the server, poll its health, and
- * return a structured envelope. The pid is persisted to
- * `.pugi/runs/<runId>/server.json` so a later `server_stop` / operator
- * cleanup script can find it.
- */
-export async function dispatchServerStart(ctx, raw) {
-    const parsed = parseServerStartArgs(raw);
-    if (typeof parsed === 'string')
-        return parsed;
-    const args = parsed;
-    const now = ctx.now ?? (() => Date.now());
-    const sleeper = ctx.sleeper ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const fetchImpl = ctx.fetch ?? globalThis.fetch;
-    const spawnImpl = ctx.spawnImpl ?? spawn;
-    if (typeof fetchImpl !== 'function') {
-        const result = {
-            ok: false,
-            runId: '',
-            logPath: '',
-            metaPath: '',
-            durationMs: 0,
-            error: 'no_fetch_available',
-        };
-        return JSON.stringify(result);
-    }
-    const runId = `srv-${randomUUID()}`;
-    const { logPath, metaPath } = ensureRunsDir(ctx.workspaceRoot, runId);
-    const writer = openLogWriter(logPath);
-    const cwd = resolveCwd(ctx.workspaceRoot, args.cwd);
-    const env = buildChildEnv(args.env);
-    const timeoutMs = clampTimeout(args.timeoutMs);
-    const healthUrl = args.healthUrl ?? `http://localhost:${args.port}/health`;
-    const expectStatus = args.expectStatus ?? 200;
-    const startedAt = now();
-    let child;
-    try {
-        child = spawnImpl('/bin/sh', ['-c', args.command], {
-            cwd,
-            env,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            detached: false,
-        });
-    }
-    catch (error) {
-        const message = error.message;
-        writer(`[server_start] spawn failed: ${message}\n`);
-        const result = {
-            ok: false,
-            runId,
-            logPath,
-            metaPath,
-            durationMs: now() - startedAt,
-            error: `spawn_failed: ${message}`,
-        };
-        writeMeta(metaPath, {
-            ok: false,
-            command: args.command,
-            cwd,
-            port: args.port,
-            healthUrl,
-            error: result.error,
-            startedAt: new Date(startedAt).toISOString(),
-        });
-        return JSON.stringify(result);
-    }
-    let exited = false;
-    let exitCode;
-    let exitSignal;
-    child.on('exit', (code, signal) => {
-        exited = true;
-        exitCode = code ?? undefined;
-        exitSignal = signal ?? undefined;
-    });
-    child.stdout?.on('data', (chunk) => writer(chunk));
-    child.stderr?.on('data', (chunk) => writer(chunk));
-    child.on('error', (error) => {
-        writer(`[server_start] child error: ${error.message}\n`);
-    });
-    const pid = child.pid;
-    const meta = {
-        runId,
-        pid: pid ?? -1,
-        command: args.command,
-        cwd,
-        port: args.port,
-        healthUrl,
-        expectStatus,
-        startedAt: new Date(startedAt).toISOString(),
-        logPath,
-    };
-    writeMeta(metaPath, meta);
-    const probe = await pollHealth({
-        url: healthUrl,
-        expectStatus,
-        timeoutMs,
-        fetchImpl,
-        sleeper,
-        now,
-        hasExited: () => exited,
-    });
-    if (probe.ok) {
-        const result = {
-            ok: true,
-            runId,
-            pid,
-            port: args.port,
-            healthStatus: probe.status,
-            logPath,
-            metaPath,
-            durationMs: probe.durationMs,
-        };
-        writeMeta(metaPath, { ...meta, status: 'healthy', healthStatus: probe.status });
-        return JSON.stringify(result);
-    }
-    // Failure path - surface the reason. The child may still be running
-    // (timeout) or already dead (process_exited). The caller decides what
-    // to do with the pid; we do NOT auto-kill so the operator can inspect
-    // a hung process via `pugi jobs` / `ps`.
-    const result = {
-        ok: false,
-        runId,
-        ...(pid !== undefined ? { pid } : {}),
-        port: args.port,
-        logPath,
-        metaPath,
-        durationMs: probe.durationMs,
-        error: probe.reason ?? 'unknown_failure',
-        ...(exitCode !== undefined ? { exitCode } : {}),
-    };
-    writeMeta(metaPath, {
-        ...meta,
-        status: probe.reason ?? 'failed',
-        ...(exitCode !== undefined ? { exitCode } : {}),
-        ...(exitSignal !== undefined ? { exitSignal } : {}),
-    });
-    return JSON.stringify(result);
-}
-export function parseServerStopArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const pid = obj['pid'];
-    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
-        return `${SERVER_INVALID_ARGS}: pid must be a positive integer`;
-    }
-    const graceMs = obj['graceMs'];
-    if (graceMs !== undefined) {
-        if (typeof graceMs !== 'number' || !Number.isFinite(graceMs) || graceMs < 0) {
-            return `${SERVER_INVALID_ARGS}: graceMs must be a non-negative number when provided`;
-        }
-    }
-    return {
-        pid,
-        ...(typeof graceMs === 'number' ? { graceMs } : {}),
-    };
-}
-/**
- * SIGTERM the pid, wait up to graceMs for natural exit, then SIGKILL.
- * Returns `ok: true` when the kill chain ran without error - both
- * "already exited" and "killed by SIGKILL" count as success because
- * the desired outcome (pid no longer running) was achieved.
- */
-export async function dispatchServerStop(ctx, raw) {
-    const parsed = parseServerStopArgs(raw);
-    if (typeof parsed === 'string')
-        return parsed;
-    const args = parsed;
-    const now = ctx.now ?? (() => Date.now());
-    const sleeper = ctx.sleeper ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const killImpl = ctx.killImpl ??
-        ((pid, signal) => {
-            process.kill(pid, signal);
-        });
-    const graceMs = clampGrace(args.graceMs);
-    const start = now();
-    const isAlive = (pid) => {
-        try {
-            killImpl(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
-    if (!isAlive(args.pid)) {
-        const result = {
-            ok: true,
-            pid: args.pid,
-            durationMs: now() - start,
-            signal: undefined,
-        };
-        return JSON.stringify(result);
-    }
-    try {
-        killImpl(args.pid, 'SIGTERM');
-    }
-    catch (error) {
-        const message = error.message;
-        const result = {
-            ok: false,
-            pid: args.pid,
-            durationMs: now() - start,
-            error: `sigterm_failed: ${message}`,
-        };
-        return JSON.stringify(result);
-    }
-    // Poll for exit during the grace window.
-    const deadline = now() + graceMs;
-    let killedSignal = 'SIGTERM';
-    while (now() < deadline) {
-        if (!isAlive(args.pid)) {
-            const result = {
-                ok: true,
-                pid: args.pid,
-                signal: killedSignal,
-                durationMs: now() - start,
-            };
-            return JSON.stringify(result);
-        }
-        await sleeper(50);
-    }
-    // Grace expired - escalate to SIGKILL.
-    try {
-        killImpl(args.pid, 'SIGKILL');
-        killedSignal = 'SIGKILL';
-    }
-    catch (error) {
-        const message = error.message;
-        const result = {
-            ok: false,
-            pid: args.pid,
-            durationMs: now() - start,
-            error: `sigkill_failed: ${message}`,
-        };
-        return JSON.stringify(result);
-    }
-    // Brief poll after SIGKILL - kernel should clean up promptly.
-    const killDeadline = now() + 1_000;
-    while (now() < killDeadline) {
-        if (!isAlive(args.pid)) {
-            const result = {
-                ok: true,
-                pid: args.pid,
-                signal: killedSignal,
-                durationMs: now() - start,
-            };
-            return JSON.stringify(result);
-        }
-        await sleeper(50);
-    }
-    const result = {
-        ok: false,
-        pid: args.pid,
-        durationMs: now() - start,
-        error: 'process_still_alive_after_sigkill',
-    };
-    return JSON.stringify(result);
-}
-export function parseServerHealthArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const url = obj['url'];
-    if (typeof url !== 'string' || url.trim() === '') {
-        return `${SERVER_INVALID_ARGS}: url must be a non-empty string`;
-    }
-    const timeoutMs = obj['timeoutMs'];
-    if (timeoutMs !== undefined) {
-        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-            return `${SERVER_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
-        }
-    }
-    const expectStatus = obj['expectStatus'];
-    if (expectStatus !== undefined) {
-        if (typeof expectStatus !== 'number' || !Number.isInteger(expectStatus) || expectStatus < 100 || expectStatus > 599) {
-            return `${SERVER_INVALID_ARGS}: expectStatus must be an integer in [100, 599]`;
-        }
-    }
-    return {
-        url,
-        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
-        ...(typeof expectStatus === 'number' ? { expectStatus } : {}),
-    };
-}
-/** Cap on the body we return to the model - keeps the envelope small. */
-export const SERVER_HEALTH_BODY_CAP_BYTES = 1024;
-/** Default health-probe timeout. */
-export const SERVER_HEALTH_DEFAULT_TIMEOUT_MS = 5_000;
-/** Upper bound on a single one-shot health-probe timeout. */
-export const SERVER_HEALTH_MAX_TIMEOUT_MS = 60_000;
-function clampHealthTimeout(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-        return SERVER_HEALTH_DEFAULT_TIMEOUT_MS;
-    }
-    return Math.min(value, SERVER_HEALTH_MAX_TIMEOUT_MS);
-}
-/**
- * One-shot HTTP GET against the supplied URL. Caller can pin the
- * expected status (default 200); anything else surfaces as ok=false
- * with the actual status preserved so the model can branch on it.
- */
-export async function dispatchServerHealth(ctx, raw) {
-    const parsed = parseServerHealthArgs(raw);
-    if (typeof parsed === 'string')
-        return parsed;
-    const args = parsed;
-    const now = ctx.now ?? (() => Date.now());
-    const fetchImpl = ctx.fetch ?? globalThis.fetch;
-    const expectStatus = args.expectStatus ?? 200;
-    const timeoutMs = clampHealthTimeout(args.timeoutMs);
-    if (typeof fetchImpl !== 'function') {
-        const result = {
-            ok: false,
-            status: 0,
-            durationMs: 0,
-            error: 'no_fetch_available',
-        };
-        return JSON.stringify(result);
-    }
-    const start = now();
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), timeoutMs);
-    try {
-        const res = await fetchImpl(args.url, { signal: ac.signal });
-        const text = await res.text();
-        const body = text.length > SERVER_HEALTH_BODY_CAP_BYTES ? text.slice(0, SERVER_HEALTH_BODY_CAP_BYTES) : text;
-        const result = {
-            ok: res.status === expectStatus,
-            status: res.status,
-            durationMs: now() - start,
-            body,
-        };
-        return JSON.stringify(result);
-    }
-    catch (error) {
-        const message = error.message;
-        const aborted = error.name === 'AbortError' || ac.signal.aborted;
-        const result = {
-            ok: false,
-            status: 0,
-            durationMs: now() - start,
-            error: aborted
-                ? `timeout_after_${timeoutMs}ms`
-                : message === '' ? 'health_request_failed' : `health_request_failed: ${message}`,
-        };
-        return JSON.stringify(result);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-export function parseServerLogsArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SERVER_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const runId = obj['runId'];
-    const pid = obj['pid'];
-    const tail = obj['tail'];
-    if (runId !== undefined && typeof runId !== 'string') {
-        return `${SERVER_INVALID_ARGS}: runId must be a string when provided`;
-    }
-    // /triple-review P1 (Claude reviewer): runId flows
-    // unchecked into `join(workspaceRoot, '.pugi', 'runs', runId, 'server.log')`.
-    // A runId of `../../etc/passwd` (or other `..` traversal) escapes
-    // the workspace and reads arbitrary files via the surfaced `lines[]`.
-    // Pin к the `srv-<uuid>` shape that `dispatchServerStart` mints
-    // (`srv-` + `randomUUID()` = lowercase hex + dashes).
-    if (typeof runId === 'string' && !/^srv-[a-f0-9-]{36}$/.test(runId)) {
-        return `${SERVER_INVALID_ARGS}: runId must match srv-<uuid> shape`;
-    }
-    if (pid !== undefined) {
-        if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
-            return `${SERVER_INVALID_ARGS}: pid must be a positive integer when provided`;
-        }
-    }
-    if (tail !== undefined) {
-        if (typeof tail !== 'number' || !Number.isFinite(tail) || tail <= 0) {
-            return `${SERVER_INVALID_ARGS}: tail must be a positive number when provided`;
-        }
-    }
-    if (runId === undefined && pid === undefined) {
-        // Allow "latest" by resolving the most recent runs dir at dispatch
-        // time; nothing to validate here.
-    }
-    return {
-        ...(typeof runId === 'string' ? { runId } : {}),
-        ...(typeof pid === 'number' ? { pid } : {}),
-        ...(typeof tail === 'number' ? { tail } : {}),
-    };
-}
-function resolveLatestRunId(workspaceRoot) {
-    const dir = join(workspaceRoot, '.pugi', 'runs');
-    if (!existsSync(dir))
-        return undefined;
-    try {
-        // We avoid statSync per-entry to keep the tool cheap; the runId
-        // includes a uuid so lexicographic sort is stable enough for the
-        // "latest run" answer when the operator does not pin one.
-        const entries = readdirSync(dir, { withFileTypes: true })
-            .filter((e) => e.isDirectory() && e.name.startsWith('srv-'))
-            .map((e) => e.name)
-            .sort();
-        return entries[entries.length - 1];
-    }
-    catch {
-        return undefined;
-    }
-}
-function resolveRunIdByPid(workspaceRoot, pid) {
-    const dir = join(workspaceRoot, '.pugi', 'runs');
-    if (!existsSync(dir))
-        return undefined;
-    try {
-        const entries = readdirSync(dir, { withFileTypes: true })
-            .filter((e) => e.isDirectory() && e.name.startsWith('srv-'))
-            .map((e) => e.name);
-        for (const id of entries) {
-            try {
-                const metaPath = join(dir, id, 'server.json');
-                if (!existsSync(metaPath))
-                    continue;
-                const raw = readFileSync(metaPath, 'utf8');
-                const meta = JSON.parse(raw);
-                if (meta && meta['pid'] === pid)
-                    return id;
-            }
-            catch {
-                // skip unreadable meta files
-            }
-        }
-    }
-    catch {
-        // ignore
-    }
-    return undefined;
-}
-/**
- * Read the trailing N lines of `<runId>/server.log`. When neither
- * runId nor pid is supplied, the dispatcher falls back to the latest
- * run dir (sorted lexicographically by runId). When pid is supplied,
- * the dispatcher walks every run dir looking for a meta.json whose
- * pid matches.
- */
-export async function dispatchServerLogs(ctx, raw) {
-    const parsed = parseServerLogsArgs(raw);
-    if (typeof parsed === 'string')
-        return parsed;
-    const args = parsed;
-    const tail = clampTail(args.tail);
-    let runId = args.runId;
-    if (!runId && typeof args.pid === 'number') {
-        runId = resolveRunIdByPid(ctx.workspaceRoot, args.pid);
-    }
-    if (!runId) {
-        runId = resolveLatestRunId(ctx.workspaceRoot);
-    }
-    if (!runId) {
-        const result = {
-            ok: false,
-            logPath: '',
-            lines: [],
-            totalLines: 0,
-            error: 'no_run_found',
-        };
-        return JSON.stringify(result);
-    }
-    const logPath = join(ctx.workspaceRoot, '.pugi', 'runs', runId, 'server.log');
-    if (!existsSync(logPath)) {
-        const result = {
-            ok: false,
-            logPath,
-            lines: [],
-            totalLines: 0,
-            error: 'log_not_found',
-        };
-        return JSON.stringify(result);
-    }
-    let body = '';
-    try {
-        body = readFileSync(logPath, 'utf8');
-    }
-    catch (error) {
-        const message = error.message;
-        const result = {
-            ok: false,
-            logPath,
-            lines: [],
-            totalLines: 0,
-            error: `read_failed: ${message}`,
-        };
-        return JSON.stringify(result);
-    }
-    const allLines = body.split('\n');
-    // Trim trailing empty produced by a final newline so the line count
-    // reflects "actual log lines" not "lines + trailing blank".
-    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
-        allLines.pop();
-    }
-    const lines = allLines.length > tail ? allLines.slice(allLines.length - tail) : allLines;
-    const result = {
-        ok: true,
-        logPath,
-        lines,
-        totalLines: allLines.length,
-    };
-    return JSON.stringify(result);
-}
-/* ----------------------- JSON schema fragments ----------------------- */
-export const serverStartJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['command', 'port'],
-    properties: {
-        command: {
-            type: 'string',
-            description: 'Shell command to spawn, e.g. "npm run dev" or "node server.js".',
-        },
-        cwd: {
-            type: 'string',
-            description: 'Workspace-relative cwd for the spawn. Absolute paths must fall inside the workspace.',
-        },
-        port: {
-            type: 'integer',
-            minimum: 1,
-            maximum: 65535,
-            description: 'Expected listening port. Used in the default healthUrl when no healthUrl is supplied.',
-        },
-        healthUrl: {
-            type: 'string',
-            description: 'Optional HTTP health URL. Defaults to http://localhost:<port>/health.',
-        },
-        timeoutMs: {
-            type: 'number',
-            description: `Health-probe timeout in ms. Default ${SERVER_START_DEFAULT_TIMEOUT_MS}, max ${SERVER_START_MAX_TIMEOUT_MS}.`,
-        },
-        expectStatus: {
-            type: 'integer',
-            minimum: 100,
-            maximum: 599,
-            description: 'Expected HTTP status. Default 200.',
-        },
-        env: {
-            type: 'object',
-            description: 'Optional env override map. Values must be strings.',
-            additionalProperties: { type: 'string' },
-        },
-    },
-};
-export const serverStopJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['pid'],
-    properties: {
-        pid: {
-            type: 'integer',
-            minimum: 1,
-            description: 'Process id of a server started via `server_start`.',
-        },
-        graceMs: {
-            type: 'number',
-            minimum: 0,
-            description: `SIGTERM → SIGKILL grace window in ms. Default ${SERVER_STOP_DEFAULT_GRACE_MS}, max ${SERVER_STOP_MAX_GRACE_MS}.`,
-        },
-    },
-};
-export const serverHealthJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['url'],
-    properties: {
-        url: {
-            type: 'string',
-            description: 'Fully-qualified HTTP/HTTPS URL to probe.',
-        },
-        timeoutMs: {
-            type: 'number',
-            description: `Single-shot probe timeout in ms. Default ${SERVER_HEALTH_DEFAULT_TIMEOUT_MS}, max ${SERVER_HEALTH_MAX_TIMEOUT_MS}.`,
-        },
-        expectStatus: {
-            type: 'integer',
-            minimum: 100,
-            maximum: 599,
-            description: 'Expected HTTP status. Default 200.',
-        },
-    },
-};
-export const serverLogsJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    properties: {
-        runId: {
-            type: 'string',
-            description: 'Run identifier returned by `server_start`. Falls back to the latest run when omitted.',
-        },
-        pid: {
-            type: 'integer',
-            minimum: 1,
-            description: 'Optional process id; the dispatcher finds the matching run dir.',
-        },
-        tail: {
-            type: 'number',
-            minimum: 1,
-            description: `Trailing lines to return. Default ${SERVER_LOGS_DEFAULT_TAIL}, max ${SERVER_LOGS_MAX_TAIL}.`,
-        },
-    },
-};
-//# sourceMappingURL=server-tools.js.map