@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/processSupervisor.js

@@ -0,0 +1,440 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import net from "node:net";
+import path from "node:path";
+export class ProcessSupervisorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProcessSupervisorError";
+    }
+}
+export function isWindowsPlatform(platform = process.platform) {
+    return platform === "win32";
+}
+export function defaultDetachedForReleasedProcess(platform = process.platform) {
+    return !isWindowsPlatform(platform);
+}
+export function defaultDetachedForPersistentService(platform = process.platform) {
+    return isWindowsPlatform(platform);
+}
+export function defaultKillTreeForPlatform(platform = process.platform) {
+    return isWindowsPlatform(platform);
+}
+export function stopMethodForPlatform(killTree, platform = process.platform) {
+    return killTree && isWindowsPlatform(platform) ? "taskkill" : "process.kill";
+}
+function assertNonEmptyString(value, name) {
+    if (value.trim().length === 0) {
+        throw new ProcessSupervisorError(`${name} must be a non-empty string`);
+    }
+}
+function assertPid(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        throw new ProcessSupervisorError("pid must be a positive integer");
+    }
+}
+function sanitizeLogName(value) {
+    const sanitized = value.trim().replace(/[^A-Za-z0-9._-]+/g, "-");
+    return sanitized.replace(/^-+|-+$/g, "") || "process";
+}
+function processLogPaths(logDirectory, name) {
+    const baseName = sanitizeLogName(name);
+    return {
+        stdout: path.join(logDirectory, `${baseName}.stdout.log`),
+        stderr: path.join(logDirectory, `${baseName}.stderr.log`),
+        lifecycle: path.join(logDirectory, `${baseName}.lifecycle.log`),
+    };
+}
+function writeLifecycleEvent(stream, event) {
+    stream.write(`${JSON.stringify({ timestamp: new Date().toISOString(), ...event })}\n`);
+}
+function openLogFile(filePath, appendLogs) {
+    return fs.openSync(filePath, appendLogs ? "a" : "w");
+}
+export function envValue(env, key) {
+    const entry = Object.entries(env).find(([envKey]) => envKey.toLowerCase() === key.toLowerCase());
+    return entry?.[1];
+}
+export function commandHasPathSegment(command) {
+    return command.includes("/") || command.includes("\\");
+}
+export function executableExtensions(env, platform = process.platform) {
+    if (!isWindowsPlatform(platform)) {
+        return [""];
+    }
+    const pathExt = envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD";
+    const extensions = pathExt
+        .split(";")
+        .map((extension) => extension.trim())
+        .filter(Boolean);
+    return [...extensions, ""];
+}
+function isFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function candidateExecutablePaths(command, env, platform = process.platform) {
+    const extensions = executableExtensions(env, platform);
+    const commandExtension = path.extname(command);
+    const candidates = isWindowsPlatform(platform) && commandExtension
+        ? [command]
+        : extensions.map((extension) => `${command}${extension}`);
+    if (commandHasPathSegment(command)) {
+        return candidates.map((candidate) => path.resolve(candidate));
+    }
+    const pathValue = envValue(env, "PATH") ?? "";
+    return pathValue
+        .split(path.delimiter)
+        .filter(Boolean)
+        .flatMap((directory) => candidates.map((candidate) => path.join(directory, candidate)));
+}
+export function findExecutablePath(command, env, platform = process.platform) {
+    return candidateExecutablePaths(command, env, platform).find(isFile);
+}
+function resolveCommandForSpawn(command, env, processName) {
+    const resolved = findExecutablePath(command, env);
+    if (resolved) {
+        const extension = path.extname(resolved).toLowerCase();
+        if (isWindowsPlatform() && [".bat", ".cmd"].includes(extension)) {
+            return {
+                command: envValue(env, "COMSPEC") ?? "cmd.exe",
+                argsPrefix: ["/d", "/s", "/c", resolved],
+                displayCommand: resolved,
+            };
+        }
+        return {
+            command: resolved,
+            argsPrefix: [],
+            displayCommand: resolved,
+        };
+    }
+    throw new ProcessSupervisorError([
+        `Cannot start ${processName}: executable not found: ${command}.`,
+        "Make sure it is installed and available on PATH,",
+        "or update the configured command in dev-nexus.home.json.",
+    ].join(" "));
+}
+function recordChildError(child, lifecycleLog) {
+    child.once("error", (error) => {
+        if (!lifecycleLog.writableEnded) {
+            writeLifecycleEvent(lifecycleLog, {
+                event: "error",
+                message: error.message,
+            });
+        }
+    });
+}
+export function startManagedProcess(options) {
+    assertNonEmptyString(options.name, "name");
+    assertNonEmptyString(options.command, "command");
+    const args = [...(options.args ?? [])];
+    const childEnv = options.env ? { ...process.env, ...options.env } : process.env;
+    const resolvedCommand = resolveCommandForSpawn(options.command, childEnv, options.name);
+    const spawnArgs = [...resolvedCommand.argsPrefix, ...args];
+    const logDirectory = path.resolve(options.logDirectory);
+    fs.mkdirSync(logDirectory, { recursive: true });
+    const logPaths = processLogPaths(logDirectory, options.name);
+    const logFlags = options.appendLogs ? "a" : "w";
+    const release = options.release ?? false;
+    const detached = options.detached ?? (release && defaultDetachedForReleasedProcess());
+    const lifecycleLog = fs.createWriteStream(logPaths.lifecycle, {
+        flags: logFlags,
+    });
+    if (release) {
+        const stdoutFd = openLogFile(logPaths.stdout, options.appendLogs ?? false);
+        const stderrFd = openLogFile(logPaths.stderr, options.appendLogs ?? false);
+        const child = spawn(resolvedCommand.command, spawnArgs, {
+            cwd: options.cwd,
+            env: childEnv,
+            detached,
+            shell: false,
+            stdio: ["ignore", stdoutFd, stderrFd],
+            windowsHide: true,
+        });
+        recordChildError(child, lifecycleLog);
+        fs.closeSync(stdoutFd);
+        fs.closeSync(stderrFd);
+        if (!child.pid) {
+            lifecycleLog.end();
+            throw new ProcessSupervisorError(`Failed to capture pid for process: ${options.name}`);
+        }
+        const startedAt = new Date().toISOString();
+        writeLifecycleEvent(lifecycleLog, {
+            event: "started",
+            name: options.name,
+            command: resolvedCommand.displayCommand,
+            args,
+            spawnCommand: resolvedCommand.command,
+            spawnArgs,
+            pid: child.pid,
+            cwd: options.cwd,
+            released: true,
+            detached,
+        });
+        lifecycleLog.end();
+        child.unref();
+        return {
+            name: options.name,
+            command: resolvedCommand.displayCommand,
+            args,
+            pid: child.pid,
+            startedAt,
+            logPaths,
+            child,
+        };
+    }
+    const stdoutLog = fs.createWriteStream(logPaths.stdout, { flags: logFlags });
+    const stderrLog = fs.createWriteStream(logPaths.stderr, { flags: logFlags });
+    const child = spawn(resolvedCommand.command, spawnArgs, {
+        cwd: options.cwd,
+        env: childEnv,
+        detached,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    recordChildError(child, lifecycleLog);
+    child.stdout?.pipe(stdoutLog);
+    child.stderr?.pipe(stderrLog);
+    if (!child.pid) {
+        stdoutLog.end();
+        stderrLog.end();
+        lifecycleLog.end();
+        throw new ProcessSupervisorError(`Failed to capture pid for process: ${options.name}`);
+    }
+    const startedAt = new Date().toISOString();
+    writeLifecycleEvent(lifecycleLog, {
+        event: "started",
+        name: options.name,
+        command: resolvedCommand.displayCommand,
+        args,
+        spawnCommand: resolvedCommand.command,
+        spawnArgs,
+        pid: child.pid,
+        cwd: options.cwd,
+        detached,
+    });
+    child.once("close", (exitCode, signal) => {
+        writeLifecycleEvent(lifecycleLog, {
+            event: "closed",
+            exitCode,
+            signal,
+        });
+        lifecycleLog.end();
+    });
+    return {
+        name: options.name,
+        command: resolvedCommand.displayCommand,
+        args,
+        pid: child.pid,
+        startedAt,
+        logPaths,
+        child,
+    };
+}
+export function isProcessRunning(pid) {
+    assertPid(pid);
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH") {
+            return false;
+        }
+        if (code === "EPERM") {
+            return true;
+        }
+        return false;
+    }
+}
+function sleep(durationMs) {
+    return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+async function waitForProcessExit(pid, timeoutMs, pollIntervalMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= timeoutMs) {
+        if (!isProcessRunning(pid)) {
+            return true;
+        }
+        await sleep(pollIntervalMs);
+    }
+    return !isProcessRunning(pid);
+}
+function runTaskkill(pid, force) {
+    return new Promise((resolve, reject) => {
+        const args = ["/pid", String(pid), "/t", ...(force ? ["/f"] : [])];
+        const child = spawn("taskkill.exe", args, {
+            shell: false,
+            windowsHide: true,
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.once("error", reject);
+        child.once("close", (exitCode) => {
+            if (exitCode === 0 || !isProcessRunning(pid)) {
+                resolve();
+                return;
+            }
+            reject(new ProcessSupervisorError(`taskkill failed for pid ${pid}: ${stderr.trim() || exitCode}`));
+        });
+    });
+}
+export async function stopProcessByPid(pid, options = {}) {
+    assertPid(pid);
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 100;
+    const killTree = options.killTree ?? defaultKillTreeForPlatform();
+    const method = stopMethodForPlatform(killTree);
+    if (!isProcessRunning(pid)) {
+        return { pid, stopped: true, alreadyExited: true, method };
+    }
+    if (method === "taskkill") {
+        await runTaskkill(pid, options.force ?? true);
+    }
+    else {
+        process.kill(pid, options.signal ?? "SIGTERM");
+    }
+    let stopped = await waitForProcessExit(pid, timeoutMs, pollIntervalMs);
+    if (!stopped && options.force && method === "process.kill") {
+        process.kill(pid, "SIGKILL");
+        stopped = await waitForProcessExit(pid, timeoutMs, pollIntervalMs);
+    }
+    return { pid, stopped, alreadyExited: false, method };
+}
+export function isTcpPortListening(port, timeoutMs = 200) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host: "127.0.0.1", port });
+        let settled = false;
+        const finish = (listening) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            resolve(listening);
+        };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+    });
+}
+function powershellSingleQuotedString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+export function findProcessListeningOnPort(port, options = {}) {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new ProcessSupervisorError("port owner lookup port must be an integer between 1 and 65535");
+    }
+    const platform = options.platform ?? process.platform;
+    if (!isWindowsPlatform(platform)) {
+        return undefined;
+    }
+    const allowedProcessNames = options.allowedProcessNames ?? [];
+    const allowedLiteral = allowedProcessNames
+        .map(powershellSingleQuotedString)
+        .join(", ");
+    const script = [
+        "$ErrorActionPreference = 'SilentlyContinue'",
+        `$allowed = @(${allowedLiteral})`,
+        "function Test-AllowedProcessName($name) {",
+        "  if ($allowed.Count -eq 0) { return $true }",
+        "  foreach ($allowedName in $allowed) {",
+        "    if ($name -eq $allowedName -or $name -like $allowedName) { return $true }",
+        "  }",
+        "  return $false",
+        "}",
+        `$connection = Get-NetTCPConnection -LocalPort ${port} -State Listen | Select-Object -First 1`,
+        "if ($connection) {",
+        "  $owner = Get-Process -Id $connection.OwningProcess",
+        "  if ($owner -and (Test-AllowedProcessName $owner.ProcessName)) {",
+        "    [Console]::Out.Write($connection.OwningProcess)",
+        "  }",
+        "}",
+    ].join("; ");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-Command", script], {
+        encoding: "utf8",
+        shell: false,
+        timeout: options.timeoutMs ?? 2_000,
+        windowsHide: true,
+    });
+    const pid = Number(result.stdout.trim());
+    return Number.isInteger(pid) && pid > 0
+        ? { pid, platform, method: "powershell" }
+        : undefined;
+}
+function healthUrl(options) {
+    const host = options.host ?? "127.0.0.1";
+    const pathName = options.path ?? "/";
+    return `http://${host}:${options.port}${pathName.startsWith("/") ? pathName : `/${pathName}`}`;
+}
+export function checkHttpPort(options) {
+    if (!Number.isInteger(options.port) ||
+        options.port < 1 ||
+        options.port > 65_535) {
+        throw new ProcessSupervisorError("HTTP health check port must be an integer between 1 and 65535");
+    }
+    const url = healthUrl(options);
+    const startedAt = Date.now();
+    const healthyStatusMin = options.healthyStatusMin ?? 200;
+    const healthyStatusMax = options.healthyStatusMax ?? 399;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve({
+                url,
+                durationMs: Date.now() - startedAt,
+                ...result,
+            });
+        };
+        const request = http.get(url, (response) => {
+            response.resume();
+            const statusCode = response.statusCode;
+            finish({
+                ok: statusCode !== undefined &&
+                    statusCode >= healthyStatusMin &&
+                    statusCode <= healthyStatusMax,
+                ...(statusCode !== undefined ? { statusCode } : {}),
+            });
+        });
+        request.setTimeout(options.timeoutMs ?? 1_000, () => {
+            request.destroy();
+            finish({ ok: false, error: "HTTP health check timed out" });
+        });
+        request.once("error", (error) => {
+            finish({ ok: false, error: error.message });
+        });
+    });
+}
+export async function waitForHttpPort(options) {
+    const totalTimeoutMs = options.totalTimeoutMs ?? 30_000;
+    const intervalMs = options.intervalMs ?? 250;
+    const startedAt = Date.now();
+    let lastResult;
+    while (Date.now() - startedAt <= totalTimeoutMs) {
+        lastResult = await checkHttpPort(options);
+        if (lastResult.ok) {
+            return lastResult;
+        }
+        await sleep(intervalMs);
+    }
+    return {
+        ok: false,
+        url: healthUrl(options),
+        durationMs: Date.now() - startedAt,
+        statusCode: lastResult?.statusCode,
+        error: lastResult?.error ?? "Timed out waiting for HTTP port",
+    };
+}

package/dist/vibeKanbanApi.d.ts

@@ -0,0 +1,11 @@
+export declare const defaultVibeKanbanHost = "127.0.0.1";
+export declare const vibeKanbanPinnedVersion = "0.1.43";
+export interface VibeKanbanApiOptions {
+    host?: string;
+    port: number;
+    fetch?: typeof fetch;
+}
+export declare class VibeKanbanApiError extends Error {
+    constructor(message: string);
+}
+export declare function vibeKanbanApiBaseUrl(options: VibeKanbanApiOptions): string;

package/dist/vibeKanbanApi.js

@@ -0,0 +1,14 @@
+export const defaultVibeKanbanHost = "127.0.0.1";
+export const vibeKanbanPinnedVersion = "0.1.43";
+export class VibeKanbanApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VibeKanbanApiError";
+    }
+}
+export function vibeKanbanApiBaseUrl(options) {
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65_535) {
+        throw new VibeKanbanApiError("Vibe Kanban port must be an integer between 1 and 65535");
+    }
+    return `http://${options.host ?? defaultVibeKanbanHost}:${options.port}`;
+}

package/dist/vibeKanbanAuth.d.ts

@@ -0,0 +1,25 @@
+import { type VibeKanbanApiOptions } from "./vibeKanbanApi.js";
+export interface VibeKanbanLocalAuthCredentials {
+    email: string;
+    password: string;
+    envFile?: string;
+}
+export type VibeKanbanAutoLoginStatus = "already-logged-in" | "logged-in" | "skipped";
+export interface VibeKanbanAutoLoginResult {
+    status: VibeKanbanAutoLoginStatus;
+    attempted: boolean;
+    loggedIn: boolean;
+    email?: string;
+    reason?: string;
+    raw?: {
+        status?: unknown;
+        login?: unknown;
+    };
+}
+export interface EnsureVibeKanbanLocalLoginOptions extends VibeKanbanApiOptions {
+    credentials?: VibeKanbanLocalAuthCredentials | null;
+}
+export declare class VibeKanbanAuthError extends Error {
+    constructor(message: string);
+}
+export declare function ensureVibeKanbanLocalLogin(options: EnsureVibeKanbanLocalLoginOptions): Promise<VibeKanbanAutoLoginResult>;

package/dist/vibeKanbanAuth.js

@@ -0,0 +1,101 @@
+import { vibeKanbanApiBaseUrl, } from "./vibeKanbanApi.js";
+export class VibeKanbanAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VibeKanbanAuthError";
+    }
+}
+function assertRecord(value, pathName) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new VibeKanbanAuthError(`${pathName} must be an object`);
+    }
+    return value;
+}
+function parseApiSuccess(value) {
+    const response = assertRecord(value, "response");
+    if (response.success !== true) {
+        const message = typeof response.message === "string"
+            ? response.message
+            : typeof response.error === "string"
+                ? response.error
+                : "Vibe Kanban auth request failed";
+        throw new VibeKanbanAuthError(message);
+    }
+    return response.data;
+}
+async function readJsonResponse(response) {
+    const text = await response.text();
+    if (text.trim().length === 0) {
+        return {};
+    }
+    return JSON.parse(text.replace(/^\uFEFF/u, ""));
+}
+async function requestJson(fetchImpl, url, init) {
+    const response = await fetchImpl(url, init);
+    const body = await readJsonResponse(response);
+    if (!response.ok) {
+        const detail = body && typeof body === "object" ? `: ${JSON.stringify(body)}` : "";
+        throw new VibeKanbanAuthError(`Vibe Kanban auth request failed with HTTP ${response.status}${detail}`);
+    }
+    return body;
+}
+async function getAuthStatus(options, fetchImpl) {
+    const url = new URL("/api/auth/status", vibeKanbanApiBaseUrl(options));
+    const raw = await requestJson(fetchImpl, url.toString());
+    const data = assertRecord(parseApiSuccess(raw), "auth status");
+    if (typeof data.logged_in !== "boolean") {
+        throw new VibeKanbanAuthError("auth status.logged_in must be a boolean");
+    }
+    return {
+        loggedIn: data.logged_in,
+        raw,
+    };
+}
+async function localLogin(options, credentials, fetchImpl) {
+    const url = new URL("/api/auth/local/login", vibeKanbanApiBaseUrl(options));
+    return requestJson(fetchImpl, url.toString(), {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            email: credentials.email,
+            password: credentials.password,
+        }),
+    });
+}
+export async function ensureVibeKanbanLocalLogin(options) {
+    const credentials = options.credentials ?? undefined;
+    if (!credentials) {
+        return {
+            status: "skipped",
+            attempted: false,
+            loggedIn: false,
+            reason: "No Vibe Kanban local-auth credentials were provided.",
+        };
+    }
+    const fetchImpl = options.fetch ?? fetch;
+    const status = await getAuthStatus(options, fetchImpl);
+    if (status.loggedIn) {
+        return {
+            status: "already-logged-in",
+            attempted: false,
+            loggedIn: true,
+            email: credentials.email,
+            raw: {
+                status: status.raw,
+            },
+        };
+    }
+    const login = await localLogin(options, credentials, fetchImpl);
+    return {
+        status: "logged-in",
+        attempted: true,
+        loggedIn: true,
+        email: credentials.email,
+        raw: {
+            status: status.raw,
+            login,
+        },
+    };
+}

package/dist/vibeKanbanBoardAdapter.d.ts

@@ -0,0 +1,36 @@
+import { type VibeKanbanApiOptions } from "./vibeKanbanApi.js";
+export interface VibeKanbanOrganization {
+    id: string;
+    name?: string;
+    is_personal?: boolean;
+    [key: string]: unknown;
+}
+export interface VibeKanbanBoard {
+    id: string;
+    organization_id?: string;
+    name: string;
+    color?: string;
+    [key: string]: unknown;
+}
+export interface EnsureVibeKanbanBoardOptions extends VibeKanbanApiOptions {
+    name: string;
+    organizationId?: string;
+    color?: string;
+    uuid?: () => string;
+}
+export interface EnsureVibeKanbanBoardResult {
+    boardId: string;
+    board: VibeKanbanBoard;
+    organization: VibeKanbanOrganization;
+    created: boolean;
+    raw: {
+        info?: unknown;
+        organizations?: unknown;
+        projects?: unknown;
+        create?: unknown;
+    };
+}
+export declare class VibeKanbanBoardAdapterError extends Error {
+    constructor(message: string);
+}
+export declare function ensureVibeKanbanBoard(options: EnsureVibeKanbanBoardOptions): Promise<EnsureVibeKanbanBoardResult>;