@nordbyte/nordrelay 0.2.1 → 0.3.0

package/dist/channel-adapter.js

@@ -0,0 +1,58 @@
+const TELEGRAM_CAPABILITIES = [
+    "text",
+    "streaming-edits",
+    "typing",
+    "inline-buttons",
+    "files",
+    "photos",
+    "voice",
+    "topics",
+    "webhooks",
+];
+const PLANNED_CHANNELS = [
+    {
+        id: "discord",
+        label: "Discord",
+        capabilities: ["text", "streaming-edits", "typing", "inline-buttons", "files", "photos", "voice"],
+        status: "planned",
+        notes: "Adapter boundary is ready; runtime integration still needs bot credentials and event mapping.",
+    },
+    {
+        id: "whatsapp",
+        label: "WhatsApp",
+        capabilities: ["text", "typing", "files", "photos", "voice", "webhooks"],
+        status: "planned",
+        notes: "Requires a WhatsApp Business provider integration.",
+    },
+    {
+        id: "slack",
+        label: "Slack",
+        capabilities: ["text", "streaming-edits", "typing", "inline-buttons", "files"],
+        status: "planned",
+    },
+    {
+        id: "matrix",
+        label: "Matrix",
+        capabilities: ["text", "files", "photos", "voice"],
+        status: "planned",
+    },
+];
+export class TelegramChannelAdapter {
+    id = "telegram";
+    label = "Telegram";
+    capabilities = new Set(TELEGRAM_CAPABILITIES);
+    describe() {
+        return {
+            id: this.id,
+            label: this.label,
+            capabilities: [...this.capabilities],
+            status: "available",
+        };
+    }
+}
+export function listChannelDescriptors() {
+    return [
+        new TelegramChannelAdapter().describe(),
+        ...PLANNED_CHANNELS,
+    ];
+}

package/dist/config.js

@@ -24,9 +24,16 @@ export function loadConfig() {
     const telegramNotifyMode = parseNotifyMode(optionalString(process.env.TELEGRAM_NOTIFY_MODE), "minimal");
     const telegramQuietHours = parseQuietHours(optionalString(process.env.TELEGRAM_QUIET_HOURS));
     const telegramRedactPatterns = parseOptionalStringList(optionalString(process.env.TELEGRAM_REDACT_PATTERNS));
+    const telegramTransport = parseTelegramTransport(optionalString(process.env.TELEGRAM_TRANSPORT));
+    const telegramWebhookUrl = optionalString(process.env.TELEGRAM_WEBHOOK_URL);
+    const telegramWebhookHost = optionalString(process.env.TELEGRAM_WEBHOOK_HOST) ?? "127.0.0.1";
+    const telegramWebhookPort = parsePositiveIntegerEnv(optionalString(process.env.TELEGRAM_WEBHOOK_PORT), 8080, "TELEGRAM_WEBHOOK_PORT");
+    const telegramWebhookPath = parseWebhookPath(optionalString(process.env.TELEGRAM_WEBHOOK_PATH));
+    const telegramWebhookSecret = optionalString(process.env.TELEGRAM_WEBHOOK_SECRET);
     const workspace = resolveWorkspace();
     const workspaceAllowedRoots = parsePathList(optionalString(process.env.WORKSPACE_ALLOWED_ROOTS));
     const workspaceWarnRoots = parsePathList(optionalString(process.env.WORKSPACE_WARN_ROOTS));
+    const stateBackend = parseStateBackend(optionalString(process.env.NORDRELAY_STATE_BACKEND));
     const maxFileSize = parseMaxFileSize(optionalString(process.env.MAX_FILE_SIZE));
     const artifactRetentionDays = parsePositiveNumberEnv(optionalString(process.env.ARTIFACT_RETENTION_DAYS), 7, "ARTIFACT_RETENTION_DAYS");
     const artifactMaxTurnDirs = parsePositiveIntegerEnv(optionalString(process.env.ARTIFACT_MAX_TURNS), 30, "ARTIFACT_MAX_TURNS");
@@ -60,6 +67,11 @@ export function loadConfig() {
     const voicePreferredBackend = parseVoiceBackendPreference(optionalString(process.env.VOICE_PREFERRED_BACKEND));
     const voiceDefaultLanguage = optionalString(process.env.VOICE_DEFAULT_LANGUAGE);
     const voiceTranscribeOnly = parseBooleanEnv(optionalString(process.env.VOICE_TRANSCRIBE_ONLY), false);
+    const auditMaxEvents = parsePositiveIntegerEnv(optionalString(process.env.NORDRELAY_AUDIT_MAX_EVENTS), 1000, "NORDRELAY_AUDIT_MAX_EVENTS");
+    const sessionLockTtlMs = parseNonNegativeIntegerEnv(optionalString(process.env.NORDRELAY_SESSION_LOCK_TTL_MS), 30 * 60 * 1000, "NORDRELAY_SESSION_LOCK_TTL_MS");
+    if (telegramTransport === "webhook" && !telegramWebhookUrl) {
+        throw new Error("TELEGRAM_TRANSPORT=webhook requires TELEGRAM_WEBHOOK_URL");
+    }
     return {
         telegramBotToken,
         telegramAllowedUserIds,
@@ -79,9 +91,16 @@ export function loadConfig() {
         telegramNotifyMode,
         telegramQuietHours,
         telegramRedactPatterns,
+        telegramTransport,
+        telegramWebhookUrl,
+        telegramWebhookHost,
+        telegramWebhookPort,
+        telegramWebhookPath,
+        telegramWebhookSecret,
         workspace,
         workspaceAllowedRoots,
         workspaceWarnRoots,
+        stateBackend,
         maxFileSize,
         artifactRetentionDays,
         artifactMaxTurnDirs,
@@ -114,6 +133,8 @@ export function loadConfig() {
         voicePreferredBackend,
         voiceDefaultLanguage,
         voiceTranscribeOnly,
+        auditMaxEvents,
+        sessionLockTtlMs,
     };
 }
 /**
@@ -313,6 +334,32 @@ function parseLogFormat(raw) {
     console.warn(`Invalid CONNECTOR_LOG_FORMAT value: "${raw}". Expected text or json. Falling back to "text".`);
     return "text";
 }
+function parseTelegramTransport(raw) {
+    if (!raw) {
+        return "polling";
+    }
+    if (raw === "polling" || raw === "webhook") {
+        return raw;
+    }
+    console.warn(`Invalid TELEGRAM_TRANSPORT value: "${raw}". Expected polling or webhook. Falling back to polling.`);
+    return "polling";
+}
+function parseWebhookPath(raw) {
+    if (!raw) {
+        return "/telegram/webhook";
+    }
+    return raw.startsWith("/") ? raw : `/${raw}`;
+}
+function parseStateBackend(raw) {
+    if (!raw) {
+        return "json";
+    }
+    if (raw === "json" || raw === "sqlite") {
+        return raw;
+    }
+    console.warn(`Invalid NORDRELAY_STATE_BACKEND value: "${raw}". Expected json or sqlite. Falling back to json.`);
+    return "json";
+}
 function parseLaunchProfiles(raw, codexSandboxMode, codexApprovalPolicy, enableUnsafeLaunchProfiles) {
     const defaultProfile = createDefaultLaunchProfile(codexSandboxMode, codexApprovalPolicy);
     const profiles = createBuiltinLaunchProfiles(defaultProfile, {

package/dist/index.js

@@ -1,5 +1,7 @@
+import { createServer } from "node:http";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { webhookCallback } from "grammy";
 import { createBot, registerCommands } from "./bot.js";
 import { checkAuthStatus } from "./codex-auth.js";
 import { describeCodexCli, resolveCodexCli } from "./codex-cli.js";
@@ -12,8 +14,11 @@ import { configureRedaction } from "./redaction.js";
 import { SessionRegistry } from "./session-registry.js";
 let registry;
 let bot;
+let webhookServer;
+let runtimeConfig;
 try {
     const config = loadConfig();
+    runtimeConfig = config;
     configureRedaction(config.telegramRedactPatterns);
     installConsoleLogger(config.logFormat);
     registry = new SessionRegistry(config);
@@ -46,6 +51,7 @@ try {
         }
     }
     console.log("Session mode: per Telegram context");
+    console.log(`Telegram transport: ${config.telegramTransport}`);
     await writeConnectorState({
         status: "ready",
         pid: Number(process.env.NORDRELAY_WRAPPER_PID) || process.pid,
@@ -56,6 +62,7 @@ try {
         authMethod: authStatus.method,
         codexCli: describeCodexCli(codexCli),
         piCli: describePiCli(piCli),
+        telegramTransport: config.telegramTransport,
     });
 }
 catch (error) {
@@ -77,8 +84,9 @@ const shutdown = (signal) => {
     }
     shuttingDown = true;
     console.log(`Received ${signal}, shutting down NordRelay...`);
-    if (bot)
+    if (bot && runtimeConfig?.telegramTransport !== "webhook")
         bot.stop();
+    webhookServer?.close();
     setTimeout(() => {
         registry?.disposeAll();
         void writeConnectorState({
@@ -124,7 +132,44 @@ async function startPolling() {
         process.exit(1);
     }
 }
-await startPolling();
+if (registry && bot) {
+    if (runtimeConfig?.telegramTransport === "webhook") {
+        webhookServer = await startWebhook(bot, runtimeConfig);
+    }
+    else {
+        await startPolling();
+    }
+}
+async function startWebhook(activeBot, config) {
+    const callback = webhookCallback(activeBot, "http", {
+        secretToken: config.telegramWebhookSecret,
+    });
+    const server = createServer((req, res) => {
+        if (req.method === "GET" && req.url === "/healthz") {
+            res.writeHead(200, { "content-type": "text/plain" });
+            res.end("ok\n");
+            return;
+        }
+        if (req.url?.split("?")[0] !== config.telegramWebhookPath) {
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("not found\n");
+            return;
+        }
+        void callback(req, res);
+    });
+    await activeBot.api.setWebhook(joinWebhookUrl(config.telegramWebhookUrl, config.telegramWebhookPath), {
+        secret_token: config.telegramWebhookSecret,
+        drop_pending_updates: process.env.NORDRELAY_DROP_PENDING_UPDATES !== "0",
+    });
+    await new Promise((resolve) => {
+        server.listen(config.telegramWebhookPort, config.telegramWebhookHost, resolve);
+    });
+    console.log(`Webhook listening on ${config.telegramWebhookHost}:${config.telegramWebhookPort}${config.telegramWebhookPath}`);
+    return server;
+}
+function joinWebhookUrl(baseUrl, webhookPath) {
+    return `${baseUrl.replace(/\/+$/, "")}${webhookPath.startsWith("/") ? webhookPath : `/${webhookPath}`}`;
+}
 async function writeConnectorState(payload) {
     const stateFile = process.env.NORDRELAY_STATE_FILE;
     if (!stateFile) {

package/dist/logger.js

@@ -1,9 +1,20 @@
 import { redactUnknown } from "./redaction.js";
 export function installConsoleLogger(format) {
+    const targetLog = console.log.bind(console);
+    const targetWarn = console.warn.bind(console);
+    const targetError = console.error.bind(console);
     if (format !== "json") {
+        console.log = (...args) => {
+            targetLog(toTextRecord("info", args));
+        };
+        console.warn = (...args) => {
+            targetWarn(toTextRecord("warn", args));
+        };
+        console.error = (...args) => {
+            targetError(toTextRecord("error", args));
+        };
         return;
     }
-    const targetLog = console.log.bind(console);
     console.log = (...args) => {
         targetLog(JSON.stringify(toLogRecord("info", args)));
     };
@@ -14,6 +25,9 @@ export function installConsoleLogger(format) {
         targetLog(JSON.stringify(toLogRecord("error", args)));
     };
 }
+function toTextRecord(level, args) {
+    return `[${formatLocalTimestamp(new Date())}] ${level.toUpperCase()} ${args.map(formatArg).join(" ")}`;
+}
 function toLogRecord(level, args) {
     return {
         ts: new Date().toISOString(),
@@ -25,3 +39,12 @@ function toLogRecord(level, args) {
 function formatArg(value) {
     return redactUnknown(value);
 }
+function formatLocalTimestamp(date) {
+    return [
+        `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+        `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`,
+    ].join(" ");
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}

package/dist/operations.js

@@ -1,14 +1,18 @@
-import { spawn } from "node:child_process";
-import { closeSync, existsSync, openSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describeCodexCli, resolveCodexCli } from "./codex-cli.js";
 import { findLatestDatabase } from "./codex-state.js";
 import { describePiCli, resolvePiCli } from "./pi-cli.js";
 const APP_NAME = "nordrelay";
+const PACKAGE_NAME = "@nordbyte/nordrelay";
+const CODEX_PACKAGE_NAME = "@openai/codex";
+const PI_PACKAGE_NAME = "@mariozechner/pi-coding-agent";
 const DEFAULT_HOME = path.join(os.homedir(), ".codex", "nordrelay");
 const SECRET_RE = /(bot|token|api[_-]?key|authorization|bearer|password|secret)(["'=: ]+)([^\s"',]+)/gi;
+const DEFAULT_VERSION_CACHE_TTL_MS = 60 * 60 * 1000;
 export function getConnectorHome() {
     return process.env.NORDRELAY_HOME || DEFAULT_HOME;
 }
@@ -39,6 +43,30 @@ export async function readLogTail(lines = 80, filePath = getConnectorLogPath())
         return `Cannot read log: ${error instanceof Error ? error.message : String(error)}`;
     }
 }
+export async function readFormattedLogTail(lines = 80, filePath = getConnectorLogPath()) {
+    const boundedLines = Math.min(Math.max(lines, 1), 300);
+    try {
+        const [contents, stats] = await Promise.all([readFile(filePath, "utf8"), stat(filePath)]);
+        const rawLines = contents.split(/\r?\n/).filter((line) => line.trim().length > 0).slice(-boundedLines);
+        const formatted = rawLines.map(formatLogLine).join("\n");
+        return {
+            filePath,
+            requestedLines: boundedLines,
+            lineCount: rawLines.length,
+            updatedAt: stats.mtime,
+            plain: redactSecrets(formatted),
+        };
+    }
+    catch (error) {
+        return {
+            filePath,
+            requestedLines: boundedLines,
+            lineCount: 0,
+            updatedAt: null,
+            plain: `Cannot read log: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
 export async function getPackageVersion() {
     try {
         const pkg = JSON.parse(await readFile(path.join(getSourceRoot(), "package.json"), "utf8"));
@@ -48,18 +76,55 @@ export async function getPackageVersion() {
         return "unknown";
     }
 }
+export async function getVersionChecks(options = {}) {
+    const nordrelayVersion = await getPackageVersion();
+    const codexCli = resolveCodexCli();
+    const piCli = resolvePiCli(process.env, options.piCliPath);
+    const codexVersionLabel = codexCli.path
+        ? detectCliVersion(codexCli.path)
+        : readInstalledPackageVersion(CODEX_PACKAGE_NAME) ?? "not installed";
+    const piVersionLabel = piCli.path ? detectCliVersion(piCli.path) : "not installed";
+    return {
+        nordrelay: buildVersionCheck({
+            label: "NordRelay",
+            packageName: PACKAGE_NAME,
+            installedLabel: nordrelayVersion,
+            installedVersion: extractVersion(nordrelayVersion),
+        }),
+        codex: buildVersionCheck({
+            label: "Codex",
+            packageName: CODEX_PACKAGE_NAME,
+            installedLabel: codexVersionLabel,
+            installedVersion: extractVersion(codexVersionLabel),
+            notInstalled: codexVersionLabel === "not installed",
+        }),
+        pi: buildVersionCheck({
+            label: "Pi",
+            packageName: PI_PACKAGE_NAME,
+            installedLabel: piVersionLabel,
+            installedVersion: extractVersion(piVersionLabel),
+            notInstalled: piVersionLabel === "not installed",
+        }),
+    };
+}
 export async function getConnectorHealth() {
     const state = await readConnectorState();
     const version = await getPackageVersion();
     const pidRunning = isProcessRunning(state.pid);
     const appPidRunning = isProcessRunning(state.appPid);
+    const codexCli = resolveCodexCli();
+    const piCli = resolvePiCli();
     return {
         version,
         state,
         pidRunning,
         appPidRunning,
-        codexCli: describeCodexCli(resolveCodexCli()),
-        piCli: describePiCli(resolvePiCli()),
+        codexCli: describeCodexCli(codexCli),
+        codexCliPath: codexCli.path ?? null,
+        codexCliVersion: detectCliVersion(codexCli.path),
+        piCli: describePiCli(piCli),
+        piCliPath: piCli.path ?? null,
+        piCliVersion: detectCliVersion(piCli.path),
         stateFile: getConnectorStatePath(),
         logFile: getConnectorLogPath(),
         databasePath: findLatestDatabase(),
@@ -80,17 +145,15 @@ export function spawnSelfUpdate() {
     const sourceRoot = getSourceRoot();
     const script = getWrapperScriptPath();
     const updateLog = getUpdateLogPath();
+    const method = detectSelfUpdateMethod(sourceRoot);
+    const commands = method === "npm"
+        ? buildNpmSelfUpdateCommands()
+        : buildGitSelfUpdateCommands(script);
     const logFd = openSync(updateLog, "a");
     const command = [
         "set -e",
-        `printf '\\n[%s] Starting connector self-update\\n' "$(date -Is)"`,
-        "git pull --ff-only origin main",
-        "npm install",
-        "npm run check",
-        "npm test",
-        "npm run build",
-        `printf '[%s] Checks passed; restarting connector\\n' "$(date -Is)"`,
-        `${shellQuote(process.execPath)} ${shellQuote(script)} restart --keep-pending-updates`,
+        `printf '\\n[%s] Starting ${method} connector self-update\\n' "$(date -Is)"`,
+        ...commands,
     ].join(" && ");
     const child = spawn("sh", ["-lc", command], {
         cwd: sourceRoot,
@@ -100,11 +163,25 @@ export function spawnSelfUpdate() {
     });
     child.unref();
     closeSync(logFd);
-    return updateLog;
+    return {
+        logPath: updateLog,
+        method,
+        sourceRoot,
+        summary: method === "npm"
+            ? `Install latest ${PACKAGE_NAME} with npm, verify the CLI, and restart.`
+            : "Pull origin/main, install dependencies, run check, tests, build, and restart.",
+    };
 }
 export function getSourceRoot() {
     return process.env.NORDRELAY_SOURCE_ROOT || process.cwd();
 }
+export function detectSelfUpdateMethod(sourceRoot = getSourceRoot()) {
+    const override = process.env.NORDRELAY_UPDATE_METHOD?.trim().toLowerCase();
+    if (override === "npm" || override === "git") {
+        return override;
+    }
+    return existsSync(path.join(sourceRoot, ".git")) ? "git" : "npm";
+}
 function getWrapperScriptPath() {
     const sourceRoot = getSourceRoot();
     const script = path.join(sourceRoot, "plugins", APP_NAME, "scripts", `${APP_NAME}.mjs`);
@@ -128,6 +205,254 @@ function isProcessRunning(pid) {
 function redactSecrets(text) {
     return text.replace(SECRET_RE, "$1$2[redacted]");
 }
+function buildGitSelfUpdateCommands(script) {
+    return [
+        "git pull --ff-only origin main",
+        "npm install",
+        "npm run check",
+        "npm test",
+        "npm run build",
+        `printf '[%s] Checks passed; restarting connector\\n' "$(date -Is)"`,
+        `${shellQuote(process.execPath)} ${shellQuote(script)} restart --keep-pending-updates`,
+    ];
+}
+function buildNpmSelfUpdateCommands() {
+    return [
+        `${resolveNpmCommand()} install -g ${PACKAGE_NAME}@latest`,
+        "nordrelay version",
+        `printf '[%s] npm update finished; restarting connector\\n' "$(date -Is)"`,
+        "nordrelay restart --keep-pending-updates",
+    ];
+}
+function resolveNpmCommand() {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && existsSync(npmExecPath)) {
+        return `${shellQuote(process.execPath)} ${shellQuote(npmExecPath)}`;
+    }
+    return "npm";
+}
+function detectCliVersion(commandPath) {
+    if (!commandPath) {
+        return "not installed";
+    }
+    const result = spawnSync(commandPath, ["--version"], {
+        encoding: "utf8",
+        timeout: 3000,
+        windowsHide: true,
+    });
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    if (result.error) {
+        return `unavailable (${result.error.message})`;
+    }
+    if (result.status !== 0) {
+        return output ? `unavailable (${output})` : `unavailable (exit ${result.status ?? "unknown"})`;
+    }
+    return output || "unknown";
+}
+function buildVersionCheck(options) {
+    if (options.notInstalled) {
+        return {
+            label: options.label,
+            packageName: options.packageName,
+            installedLabel: "not installed",
+            installedVersion: null,
+            latestVersion: null,
+            status: "not-installed",
+        };
+    }
+    const latest = detectLatestNpmVersion(options.packageName);
+    if (!options.installedVersion || !latest.version) {
+        return {
+            label: options.label,
+            packageName: options.packageName,
+            installedLabel: options.installedLabel,
+            installedVersion: options.installedVersion,
+            latestVersion: latest.version,
+            status: "unknown",
+            detail: latest.error ?? "Could not parse installed version",
+        };
+    }
+    return {
+        label: options.label,
+        packageName: options.packageName,
+        installedLabel: options.installedLabel,
+        installedVersion: options.installedVersion,
+        latestVersion: latest.version,
+        status: compareVersions(options.installedVersion, latest.version) < 0 ? "outdated" : "current",
+        detail: latest.error,
+    };
+}
+function detectLatestNpmVersion(packageName) {
+    const cached = readVersionCache(packageName);
+    if (cached) {
+        return cached;
+    }
+    const result = spawnSync("npm", ["view", packageName, "version", "--registry=https://registry.npmjs.org"], {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+    });
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    if (result.error) {
+        return { version: null, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { version: null, error: output || `npm exited ${result.status ?? "unknown"}` };
+    }
+    const resolved = { version: output.split(/\r?\n/).at(-1)?.trim() || null };
+    writeVersionCache(packageName, resolved.version);
+    return resolved;
+}
+function readVersionCache(packageName) {
+    const ttlMs = parseVersionCacheTtlMs();
+    if (ttlMs <= 0) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(readFileSync(getVersionCachePath(), "utf8"));
+        const entry = payload.packages?.[packageName];
+        if (!entry || typeof entry.version !== "string" || typeof entry.checkedAt !== "number") {
+            return null;
+        }
+        if (Date.now() - entry.checkedAt > ttlMs) {
+            return null;
+        }
+        return { version: entry.version };
+    }
+    catch {
+        return null;
+    }
+}
+function writeVersionCache(packageName, version) {
+    if (!version || parseVersionCacheTtlMs() <= 0) {
+        return;
+    }
+    const filePath = getVersionCachePath();
+    try {
+        const existing = existsSync(filePath)
+            ? JSON.parse(readFileSync(filePath, "utf8"))
+            : {};
+        const packages = existing.packages ?? {};
+        packages[packageName] = { version, checkedAt: Date.now() };
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        writeFileSync(filePath, `${JSON.stringify({ packages }, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // Best-effort cache only.
+    }
+}
+function getVersionCachePath() {
+    return path.join(getConnectorHome(), "version-cache.json");
+}
+function parseVersionCacheTtlMs() {
+    const raw = process.env.NORDRELAY_VERSION_CACHE_TTL_MS;
+    if (!raw) {
+        return DEFAULT_VERSION_CACHE_TTL_MS;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed)) : DEFAULT_VERSION_CACHE_TTL_MS;
+}
+function readInstalledPackageVersion(packageName) {
+    try {
+        const packagePath = path.join(getSourceRoot(), "node_modules", ...packageName.split("/"), "package.json");
+        const pkg = JSON.parse(readFileSyncUtf8(packagePath));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readFileSyncUtf8(filePath) {
+    return readFileSync(filePath, "utf8");
+}
+function extractVersion(value) {
+    const match = value.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/);
+    return match?.[0] ?? null;
+}
+function compareVersions(left, right) {
+    const leftParts = parseVersionParts(left);
+    const rightParts = parseVersionParts(right);
+    for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+        const diff = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+function parseVersionParts(value) {
+    return value.split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+}
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function formatLogLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const parsedJson = parseJsonLogLine(trimmed);
+    if (parsedJson) {
+        return parsedJson;
+    }
+    const textRecord = trimmed.match(/^\[(?<timestamp>[^\]]+)\]\s+(?<level>INFO|WARN|ERROR)\s+(?<message>.*)$/i);
+    if (textRecord?.groups) {
+        return [
+            formatLogTimestamp(textRecord.groups.timestamp),
+            textRecord.groups.level.toUpperCase().padEnd(5),
+            textRecord.groups.message,
+        ].join(" ");
+    }
+    const timestampedShellLine = trimmed.match(/^\[(?<timestamp>[^\]]+)\]\s+(?<message>.*)$/);
+    if (timestampedShellLine?.groups) {
+        return [
+            formatLogTimestamp(timestampedShellLine.groups.timestamp),
+            "INFO ".padEnd(5),
+            timestampedShellLine.groups.message,
+        ].join(" ");
+    }
+    return trimmed;
+}
+function parseJsonLogLine(line) {
+    if (!line.startsWith("{")) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(line);
+        const timestamp = typeof parsed.ts === "string"
+            ? parsed.ts
+            : typeof parsed.timestamp === "string"
+                ? parsed.timestamp
+                : null;
+        const level = typeof parsed.level === "string" ? parsed.level.toUpperCase() : "INFO";
+        const message = typeof parsed.message === "string" ? parsed.message : JSON.stringify(parsed);
+        const event = typeof parsed.event === "string" && parsed.event !== "console" ? ` ${parsed.event}` : "";
+        return [
+            formatLogTimestamp(timestamp),
+            `${level}${event}`.slice(0, 12).padEnd(12),
+            message,
+        ].join(" ");
+    }
+    catch {
+        return null;
+    }
+}
+function formatLogTimestamp(value) {
+    if (!value) {
+        return "unknown time".padEnd(25);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        return value.padEnd(25).slice(0, 25);
+    }
+    return formatLocalTimestamp(parsed);
+}
+function formatLocalTimestamp(date) {
+    return [
+        `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+        `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`,
+    ].join(" ");
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}