@dotsetlabs/bellwether 2.1.0 → 2.1.2

package/dist/dashboard/runtime/config-service.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+import { PATHS } from '../../constants.js';
+import { getConfigWarnings, validateConfig } from '../../config/validator.js';
+import { parseYamlSecure } from '../../utils/yaml-parser.js';
+function normalizeWorkspace(path) {
+    return resolve(path);
+}
+function assertWithinWorkspace(workspaceRoot, absolutePath) {
+    const rel = relative(workspaceRoot, absolutePath);
+    if (rel.startsWith('..') || rel.includes('/../') || rel.includes('\\..\\')) {
+        throw new Error('Path is outside the current workspace.');
+    }
+}
+export function resolveWorkspacePath(cwd, targetPath) {
+    const workspaceRoot = normalizeWorkspace(cwd);
+    const resolvedPath = resolve(workspaceRoot, targetPath);
+    assertWithinWorkspace(workspaceRoot, resolvedPath);
+    return resolvedPath;
+}
+export function resolveConfigPath(cwd, explicitPath) {
+    const workspaceRoot = normalizeWorkspace(cwd);
+    if (explicitPath && explicitPath.trim()) {
+        return resolveWorkspacePath(workspaceRoot, explicitPath.trim());
+    }
+    for (const filename of PATHS.CONFIG_FILENAMES) {
+        const candidate = resolve(workspaceRoot, filename);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return resolve(workspaceRoot, PATHS.DEFAULT_CONFIG_FILENAME);
+}
+export function getConfigDocument(cwd, explicitPath) {
+    const absolutePath = resolveConfigPath(cwd, explicitPath);
+    const workspacePath = relative(normalizeWorkspace(cwd), absolutePath) || PATHS.DEFAULT_CONFIG_FILENAME;
+    const exists = existsSync(absolutePath);
+    return {
+        absolutePath,
+        workspacePath,
+        exists,
+        content: exists ? readFileSync(absolutePath, 'utf-8') : '',
+    };
+}
+export function saveConfigDocument(cwd, explicitPath, content) {
+    const absolutePath = resolveConfigPath(cwd, explicitPath);
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, content);
+    return getConfigDocument(cwd, explicitPath);
+}
+function parseConfigContent(content) {
+    const parsed = parseYamlSecure(content);
+    if (parsed === null || parsed === undefined) {
+        return {};
+    }
+    return parsed;
+}
+export function validateConfigSource(cwd, options) {
+    const sourceContent = options.content !== undefined
+        ? options.content
+        : getConfigDocument(cwd, options.path).content;
+    if (!sourceContent || sourceContent.trim().length === 0) {
+        throw new Error('Config content is empty.');
+    }
+    const parsed = parseConfigContent(sourceContent);
+    const config = validateConfig(parsed, options.path);
+    return {
+        valid: true,
+        warnings: getConfigWarnings(config),
+        config,
+    };
+}
+//# sourceMappingURL=config-service.js.map

package/dist/dashboard/runtime/job-runner.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { DashboardRunDetails, DashboardRunSummary, DashboardStartRunRequest } from '../types.js';
+interface DashboardJobRunnerOptions {
+    cwd?: string;
+    cliEntrypoint?: string;
+    maxStoredRuns?: number;
+}
+export declare class DashboardJobRunner {
+    private readonly runs;
+    private readonly cwd;
+    private readonly cliEntrypoint;
+    private readonly maxStoredRuns;
+    constructor(options?: DashboardJobRunnerOptions);
+    listRuns(): DashboardRunSummary[];
+    getRun(runId: string): DashboardRunDetails | null;
+    startRun(request: DashboardStartRunRequest): DashboardRunSummary;
+    cancelRun(runId: string): DashboardRunSummary | null;
+    openEventStream(runId: string, req: IncomingMessage, res: ServerResponse): boolean;
+    shutdown(): Promise<void>;
+    private appendOutput;
+    private finalizeRun;
+    private emit;
+    private pruneFinishedRuns;
+}
+export {};
+//# sourceMappingURL=job-runner.d.ts.map

package/dist/dashboard/runtime/job-runner.js

@@ -0,0 +1,292 @@
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { extname, join } from 'path';
+import { TIMEOUTS } from '../../constants.js';
+import { buildBellwetherArgs, parseDashboardRunRequest } from './command-profiles.js';
+const OUTPUT_CHUNK_LIMIT = 2000;
+function formatCommandLine(command, args) {
+    return [command, ...args]
+        .map((part) => {
+        if (part.includes(' ')) {
+            return `"${part}"`;
+        }
+        return part;
+    })
+        .join(' ');
+}
+function resolveCliLaunchPlan(cwd, cliEntrypoint) {
+    const normalizedEntrypoint = cliEntrypoint?.trim();
+    if (normalizedEntrypoint && existsSync(normalizedEntrypoint)) {
+        const extension = extname(normalizedEntrypoint).toLowerCase();
+        if (extension === '.js' || extension === '.mjs' || extension === '.cjs') {
+            return {
+                command: process.execPath,
+                prefixArgs: [normalizedEntrypoint],
+            };
+        }
+        if (extension === '.ts' || extension === '.mts' || extension === '.cts') {
+            const localTsx = join(cwd, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
+            return {
+                command: existsSync(localTsx) ? localTsx : 'tsx',
+                prefixArgs: [normalizedEntrypoint],
+            };
+        }
+        return {
+            command: process.execPath,
+            prefixArgs: [normalizedEntrypoint],
+        };
+    }
+    return {
+        command: process.platform === 'win32' ? 'bellwether.cmd' : 'bellwether',
+        prefixArgs: [],
+    };
+}
+function toSummary(run) {
+    return {
+        runId: run.runId,
+        profile: run.profile,
+        status: run.status,
+        commandLine: run.commandLine,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        durationMs: run.durationMs,
+        exitCode: run.exitCode,
+        pid: run.pid,
+        errorMessage: run.errorMessage,
+    };
+}
+function toDetails(run) {
+    return {
+        ...toSummary(run),
+        output: [...run.output],
+    };
+}
+function writeSseEvent(res, event, payload) {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+export class DashboardJobRunner {
+    runs = new Map();
+    cwd;
+    cliEntrypoint;
+    maxStoredRuns;
+    constructor(options = {}) {
+        this.cwd = options.cwd ?? process.cwd();
+        this.cliEntrypoint = options.cliEntrypoint ?? process.argv[1];
+        this.maxStoredRuns = options.maxStoredRuns ?? 50;
+    }
+    listRuns() {
+        const summaries = [...this.runs.values()].map((run) => toSummary(run));
+        summaries.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+        return summaries;
+    }
+    getRun(runId) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return null;
+        }
+        return toDetails(run);
+    }
+    startRun(request) {
+        const parsedRequest = parseDashboardRunRequest(request);
+        const profileArgs = buildBellwetherArgs(parsedRequest);
+        const launchPlan = resolveCliLaunchPlan(this.cwd, this.cliEntrypoint);
+        const childArgs = [...launchPlan.prefixArgs, ...profileArgs];
+        const child = spawn(launchPlan.command, childArgs, {
+            cwd: this.cwd,
+            env: process.env,
+            stdio: 'pipe',
+        });
+        const runId = randomUUID();
+        const run = {
+            runId,
+            profile: parsedRequest.profile,
+            status: 'running',
+            commandLine: formatCommandLine(launchPlan.command, childArgs),
+            startedAt: new Date().toISOString(),
+            output: [],
+            process: child,
+            subscribers: new Set(),
+            cancelRequested: false,
+            finalized: false,
+            forceKillTimer: null,
+            pid: child.pid,
+        };
+        this.runs.set(runId, run);
+        this.pruneFinishedRuns();
+        this.emit(run, 'run.start', { run: toSummary(run) });
+        child.stdout.on('data', (chunk) => {
+            this.appendOutput(run, 'stdout', chunk.toString('utf-8'));
+        });
+        child.stderr.on('data', (chunk) => {
+            this.appendOutput(run, 'stderr', chunk.toString('utf-8'));
+        });
+        child.on('error', (error) => {
+            this.appendOutput(run, 'stderr', `${error.message}\n`);
+            this.finalizeRun(run, 1, undefined, error.message);
+        });
+        child.on('close', (exitCode, signal) => {
+            let errorMessage = run.errorMessage;
+            if (!run.cancelRequested && signal && !errorMessage) {
+                errorMessage = `Process terminated by signal ${signal}`;
+            }
+            this.finalizeRun(run, exitCode, signal, errorMessage);
+        });
+        return toSummary(run);
+    }
+    cancelRun(runId) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return null;
+        }
+        if (run.status !== 'running' || !run.process) {
+            return toSummary(run);
+        }
+        run.cancelRequested = true;
+        run.errorMessage = 'Run cancelled by user.';
+        run.process.kill('SIGTERM');
+        run.forceKillTimer = setTimeout(() => {
+            if (!run.finalized && run.process) {
+                run.process.kill('SIGKILL');
+            }
+        }, TIMEOUTS.SHUTDOWN_KILL);
+        this.emit(run, 'run.state', {
+            run: toSummary(run),
+            message: 'Cancellation requested.',
+        });
+        return toSummary(run);
+    }
+    openEventStream(runId, req, res) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return false;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        res.write('\n');
+        writeSseEvent(res, 'run.snapshot', { run: toDetails(run) });
+        if (run.finalized) {
+            writeSseEvent(res, 'run.exit', { run: toSummary(run) });
+            res.end();
+            return true;
+        }
+        run.subscribers.add(res);
+        req.on('close', () => {
+            run.subscribers.delete(res);
+        });
+        return true;
+    }
+    async shutdown() {
+        const shutdownPromises = [];
+        for (const run of this.runs.values()) {
+            if (run.status === 'running' && run.process) {
+                run.cancelRequested = true;
+                run.process.kill('SIGTERM');
+                shutdownPromises.push(new Promise((resolve) => {
+                    const timeout = setTimeout(() => {
+                        if (!run.finalized && run.process) {
+                            run.process.kill('SIGKILL');
+                        }
+                        resolve();
+                    }, TIMEOUTS.SHUTDOWN_KILL);
+                    run.process?.once('close', () => {
+                        clearTimeout(timeout);
+                        resolve();
+                    });
+                }));
+            }
+        }
+        await Promise.allSettled(shutdownPromises);
+        for (const run of this.runs.values()) {
+            for (const subscriber of run.subscribers) {
+                subscriber.end();
+            }
+            run.subscribers.clear();
+        }
+    }
+    appendOutput(run, stream, text) {
+        if (!text) {
+            return;
+        }
+        const chunk = {
+            stream,
+            text,
+            timestamp: new Date().toISOString(),
+        };
+        run.output.push(chunk);
+        if (run.output.length > OUTPUT_CHUNK_LIMIT) {
+            run.output.shift();
+        }
+        this.emit(run, 'run.output', {
+            runId: run.runId,
+            stream,
+            text,
+            timestamp: chunk.timestamp,
+        });
+    }
+    finalizeRun(run, exitCode, signal, errorMessage) {
+        if (run.finalized) {
+            return;
+        }
+        run.finalized = true;
+        run.process = null;
+        if (run.forceKillTimer) {
+            clearTimeout(run.forceKillTimer);
+            run.forceKillTimer = null;
+        }
+        run.exitCode = exitCode ?? null;
+        run.endedAt = new Date().toISOString();
+        run.durationMs = Date.parse(run.endedAt) - Date.parse(run.startedAt);
+        if (run.cancelRequested) {
+            run.status = 'cancelled';
+        }
+        else if (exitCode === 0) {
+            run.status = 'completed';
+        }
+        else {
+            run.status = 'failed';
+        }
+        if (errorMessage) {
+            run.errorMessage = errorMessage;
+        }
+        else if (run.status === 'failed' && signal) {
+            run.errorMessage = `Run terminated by signal ${signal}`;
+        }
+        this.emit(run, 'run.exit', { run: toSummary(run) });
+        for (const subscriber of run.subscribers) {
+            subscriber.end();
+        }
+        run.subscribers.clear();
+    }
+    emit(run, event, payload) {
+        for (const subscriber of run.subscribers) {
+            try {
+                writeSseEvent(subscriber, event, payload);
+            }
+            catch {
+                subscriber.end();
+                run.subscribers.delete(subscriber);
+            }
+        }
+    }
+    pruneFinishedRuns() {
+        if (this.runs.size <= this.maxStoredRuns) {
+            return;
+        }
+        const removable = [...this.runs.values()]
+            .filter((run) => run.status !== 'running')
+            .sort((a, b) => Date.parse(a.startedAt) - Date.parse(b.startedAt));
+        while (this.runs.size > this.maxStoredRuns && removable.length > 0) {
+            const oldest = removable.shift();
+            if (oldest) {
+                this.runs.delete(oldest.runId);
+            }
+        }
+    }
+}
+//# sourceMappingURL=job-runner.js.map

package/dist/dashboard/security/input-validation.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from 'http';
+export declare function readJsonBody(req: IncomingMessage, maxBodyBytes?: number): Promise<unknown>;
+//# sourceMappingURL=input-validation.d.ts.map

package/dist/dashboard/security/input-validation.js

@@ -0,0 +1,27 @@
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+export async function readJsonBody(req, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of req) {
+        const bufferChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += bufferChunk.length;
+        if (totalBytes > maxBodyBytes) {
+            throw new Error('Request body is too large.');
+        }
+        chunks.push(bufferChunk);
+    }
+    if (chunks.length === 0) {
+        return {};
+    }
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (raw.length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Request body must be valid JSON.');
+    }
+}
+//# sourceMappingURL=input-validation.js.map

package/dist/dashboard/security/localhost-guard.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+export declare function isLocalAddress(address: string | undefined): boolean;
+export declare function isAllowedHostHeader(hostHeader: string | undefined): boolean;
+export declare function enforceLocalhostRequest(req: IncomingMessage, res: ServerResponse): boolean;
+//# sourceMappingURL=localhost-guard.d.ts.map

package/dist/dashboard/security/localhost-guard.js

@@ -0,0 +1,52 @@
+const localHosts = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+const localAddresses = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+function extractHostname(hostHeader) {
+    if (!hostHeader) {
+        return undefined;
+    }
+    const host = hostHeader.trim().toLowerCase();
+    if (host.length === 0) {
+        return undefined;
+    }
+    if (host.startsWith('[')) {
+        const closeIndex = host.indexOf(']');
+        if (closeIndex !== -1) {
+            return host.slice(0, closeIndex + 1);
+        }
+        return host;
+    }
+    const colonIndex = host.indexOf(':');
+    if (colonIndex === -1) {
+        return host;
+    }
+    return host.slice(0, colonIndex);
+}
+export function isLocalAddress(address) {
+    if (!address) {
+        return false;
+    }
+    return localAddresses.has(address);
+}
+export function isAllowedHostHeader(hostHeader) {
+    const hostname = extractHostname(hostHeader);
+    if (!hostname) {
+        return false;
+    }
+    return localHosts.has(hostname);
+}
+export function enforceLocalhostRequest(req, res) {
+    if (!isLocalAddress(req.socket.remoteAddress)) {
+        res.statusCode = 403;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({ error: 'Dashboard only accepts localhost requests.' }));
+        return false;
+    }
+    if (!isAllowedHostHeader(req.headers.host)) {
+        res.statusCode = 403;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({ error: 'Invalid host header.' }));
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=localhost-guard.js.map

package/dist/dashboard/server.d.ts

@@ -0,0 +1,14 @@
+import type { DashboardServerOptions, DashboardStartedServer } from './types.js';
+export declare class DashboardServer {
+    private readonly host;
+    private readonly port;
+    private readonly cwd;
+    private readonly runner;
+    private server;
+    private url;
+    constructor(options: DashboardServerOptions);
+    start(): Promise<DashboardStartedServer>;
+    stop(): Promise<void>;
+    private handleRequest;
+}
+//# sourceMappingURL=server.d.ts.map