@nextclaw/service 0.1.1

package/dist/cli/commands/cron/services/cron-commands.service.d.ts

@@ -0,0 +1,22 @@
+import { CronAddOptions } from "../../../../shared/types/cli.types.js";
+import { CronLocalService } from "./cron-local.service.js";
+
+//#region src/cli/commands/cron/services/cron-commands.service.d.ts
+declare class CronCommands {
+  private local;
+  constructor(local?: CronLocalService);
+  private createApiClient;
+  list: (opts: {
+    enabledOnly?: boolean;
+  }) => Promise<void>;
+  add: (opts: CronAddOptions) => Promise<void>;
+  remove: (jobId: string) => Promise<void>;
+  enable: (jobId: string, opts: {
+    disable?: boolean;
+  }) => Promise<void>;
+  run: (jobId: string, opts: {
+    force?: boolean;
+  }) => Promise<void>;
+}
+//#endregion
+export { CronCommands };

package/dist/cli/commands/cron/services/cron-commands.service.js

@@ -0,0 +1,107 @@
+import { UiBridgeApiClient, resolveLocalUiApiBase } from "../../../../shared/services/ui/ui-bridge-api.service.js";
+import { printCronJobs } from "../utils/cron-job.utils.js";
+import { CronLocalService, createCronCreateRequest } from "./cron-local.service.js";
+//#region src/cli/commands/cron/services/cron-commands.service.ts
+function readErrorMessage(error) {
+	if (error instanceof Error && error.message.trim().length > 0) return error.message.trim();
+	return String(error ?? "unknown error");
+}
+var CronCommands = class {
+	constructor(local = new CronLocalService()) {
+		this.local = local;
+	}
+	createApiClient = () => {
+		const apiBase = resolveLocalUiApiBase();
+		if (!apiBase) return null;
+		return new UiBridgeApiClient(apiBase);
+	};
+	list = async (opts) => {
+		const includeDisabled = opts.enabledOnly !== true;
+		const apiClient = this.createApiClient();
+		if (apiClient) try {
+			const query = includeDisabled ? "" : "?enabledOnly=1";
+			printCronJobs((await apiClient.request({ path: `/api/cron${query}` })).jobs);
+			return;
+		} catch {}
+		printCronJobs(this.local.list(includeDisabled));
+	};
+	add = async (opts) => {
+		const request = createCronCreateRequest(opts);
+		if (!request.request) {
+			console.error(request.error ?? "Error: Failed to add job");
+			return;
+		}
+		const apiClient = this.createApiClient();
+		if (apiClient) try {
+			const data = await apiClient.request({
+				path: "/api/cron",
+				method: "POST",
+				body: request.request
+			});
+			console.log(`✓ Added job '${data.job.name}' (${data.job.id})`);
+			return;
+		} catch (error) {
+			console.error(`Error: ${readErrorMessage(error)}`);
+			return;
+		}
+		const job = this.local.addRequest(request.request);
+		console.log(`✓ Added job '${job.name}' (${job.id})`);
+	};
+	remove = async (jobId) => {
+		const apiClient = this.createApiClient();
+		if (apiClient) try {
+			if ((await apiClient.request({
+				path: `/api/cron/${encodeURIComponent(jobId)}`,
+				method: "DELETE"
+			})).deleted) {
+				console.log(`✓ Removed job ${jobId}`);
+				return;
+			}
+		} catch (error) {
+			console.error(`Error: ${readErrorMessage(error)}`);
+			return;
+		}
+		if (this.local.remove(jobId)) console.log(`✓ Removed job ${jobId}`);
+		else console.log(`Job ${jobId} not found`);
+	};
+	enable = async (jobId, opts) => {
+		const apiClient = this.createApiClient();
+		const enabled = !opts.disable;
+		if (apiClient) try {
+			const data = await apiClient.request({
+				path: `/api/cron/${encodeURIComponent(jobId)}/enable`,
+				method: "PUT",
+				body: { enabled }
+			});
+			if (data.job) {
+				console.log(`✓ Job '${data.job.name}' ${opts.disable ? "disabled" : "enabled"}`);
+				return;
+			}
+		} catch (error) {
+			console.error(`Error: ${readErrorMessage(error)}`);
+			return;
+		}
+		const job = this.local.enable(jobId, enabled);
+		if (job) console.log(`✓ Job '${job.name}' ${opts.disable ? "disabled" : "enabled"}`);
+		else console.log(`Job ${jobId} not found`);
+	};
+	run = async (jobId, opts) => {
+		const apiClient = this.createApiClient();
+		if (apiClient) try {
+			const data = await apiClient.request({
+				path: `/api/cron/${encodeURIComponent(jobId)}/run`,
+				method: "POST",
+				body: { force: Boolean(opts.force) }
+			});
+			console.log(data.executed ? "✓ Job executed" : `Failed to run job ${jobId}`);
+			return;
+		} catch (error) {
+			console.error(`Error: ${readErrorMessage(error)}`);
+			return;
+		}
+		const ok = await this.local.run(jobId, Boolean(opts.force));
+		console.log(ok ? "✓ Job executed" : `Failed to run job ${jobId}`);
+	};
+};
+//#endregion
+export { CronCommands };

package/dist/cli/commands/cron/services/cron-local.service.d.ts

@@ -0,0 +1,25 @@
+import { CronAddOptions } from "../../../../shared/types/cli.types.js";
+import { CronJobView } from "../utils/cron-job.utils.js";
+import { CronCreateRequest } from "@nextclaw/server";
+import { AutomationManager } from "@nextclaw/kernel";
+
+//#region src/cli/commands/cron/services/cron-local.service.d.ts
+declare function createCronCreateRequest(opts: CronAddOptions): {
+  request?: CronCreateRequest;
+  error?: string;
+};
+declare class CronLocalService {
+  private readonly automation;
+  constructor(automation?: AutomationManager);
+  readonly list: (all: boolean) => CronJobView[];
+  readonly addRequest: (request: CronCreateRequest) => CronJobView;
+  readonly add: (opts: CronAddOptions) => {
+    job: CronJobView | null;
+    error?: string;
+  };
+  readonly remove: (jobId: string) => boolean;
+  readonly enable: (jobId: string, enabled: boolean) => CronJobView | null;
+  readonly run: (jobId: string, force: boolean) => Promise<boolean>;
+}
+//#endregion
+export { CronLocalService, createCronCreateRequest };

package/dist/cli/commands/cron/services/cron-local.service.js

@@ -0,0 +1,95 @@
+import { resolve } from "node:path";
+import { getDataDir } from "@nextclaw/core";
+import { AutomationManager } from "@nextclaw/kernel";
+//#region src/cli/commands/cron/services/cron-local.service.ts
+function readTrimmed(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function toSchedule(opts) {
+	const every = readTrimmed(opts.every);
+	const cron = readTrimmed(opts.cron);
+	const at = readTrimmed(opts.at);
+	if ([
+		every,
+		cron,
+		at
+	].filter((value) => value !== void 0).length !== 1) return { error: "Error: Must specify exactly one of --every, --cron, or --at" };
+	if (every) {
+		const everySeconds = Number(every);
+		if (!Number.isFinite(everySeconds) || everySeconds <= 0) return { error: "Error: --every must be a positive number of seconds" };
+		return { schedule: {
+			kind: "every",
+			everyMs: everySeconds * 1e3
+		} };
+	}
+	if (cron) return { schedule: {
+		kind: "cron",
+		expr: cron
+	} };
+	const atMs = Date.parse(String(at));
+	if (!Number.isFinite(atMs)) return { error: "Error: --at must be a valid ISO datetime" };
+	return { schedule: {
+		kind: "at",
+		atMs
+	} };
+}
+function createCronCreateRequest(opts) {
+	const name = readTrimmed(opts.name);
+	const message = readTrimmed(opts.message);
+	if (!name || !message) return { error: "Error: name and message are required" };
+	const schedule = toSchedule(opts);
+	if (!schedule.schedule) return { error: schedule.error ?? "Error: Must specify --every, --cron, or --at" };
+	return { request: {
+		name,
+		message,
+		schedule: schedule.schedule,
+		agentId: readTrimmed(opts.agent),
+		sessionId: readTrimmed(opts.session),
+		deliver: Boolean(opts.deliver),
+		channel: readTrimmed(opts.channel),
+		to: readTrimmed(opts.to),
+		accountId: readTrimmed(opts.account)
+	} };
+}
+var CronLocalService = class {
+	constructor(automation = new AutomationManager({ storePath: resolve(getDataDir(), "cron", "jobs.json") })) {
+		this.automation = automation;
+	}
+	list = (all) => {
+		return this.automation.listJobs(all);
+	};
+	addRequest = (request) => {
+		return this.automation.addJob({
+			name: request.name,
+			schedule: request.schedule,
+			message: request.message,
+			agentId: request.agentId ?? void 0,
+			sessionId: request.sessionId ?? void 0,
+			deliver: request.deliver === true,
+			channel: request.channel ?? void 0,
+			to: request.to ?? void 0,
+			accountId: request.accountId ?? void 0,
+			deleteAfterRun: request.deleteAfterRun === true
+		});
+	};
+	add = (opts) => {
+		const request = createCronCreateRequest(opts);
+		if (!request.request) return {
+			job: null,
+			error: request.error
+		};
+		return { job: this.addRequest(request.request) };
+	};
+	remove = (jobId) => {
+		return this.automation.removeJob(jobId);
+	};
+	enable = (jobId, enabled) => {
+		return this.automation.enableJob(jobId, enabled) ?? null;
+	};
+	run = async (jobId, force) => {
+		return this.automation.runJob(jobId, force);
+	};
+};
+//#endregion
+export { CronLocalService, createCronCreateRequest };

package/dist/cli/commands/cron/utils/cron-job.utils.d.ts

@@ -0,0 +1,31 @@
+//#region src/cli/commands/cron/utils/cron-job.utils.d.ts
+type CronSchedule = {
+  kind: "every";
+  everyMs?: number | null;
+} | {
+  kind: "cron";
+  expr?: string | null;
+} | {
+  kind: "at";
+  atMs?: number | null;
+};
+type CronPayload = {
+  message: string;
+  agentId?: string | null;
+  sessionId?: string | null;
+  deliver?: boolean;
+  channel?: string | null;
+  to?: string | null;
+  accountId?: string | null;
+};
+type CronJobView = {
+  id: string;
+  name: string;
+  enabled: boolean;
+  schedule: CronSchedule;
+  payload: CronPayload;
+};
+declare function formatCronSchedule(schedule: CronSchedule): string;
+declare function printCronJobs(jobs: CronJobView[]): void;
+//#endregion
+export { CronJobView, CronPayload, CronSchedule, formatCronSchedule, printCronJobs };

package/dist/cli/commands/cron/utils/cron-job.utils.js

@@ -0,0 +1,15 @@
+//#region src/cli/commands/cron/utils/cron-job.utils.ts
+function formatCronSchedule(schedule) {
+	if (schedule.kind === "every") return `every ${Math.round((schedule.everyMs ?? 0) / 1e3)}s`;
+	if (schedule.kind === "cron") return schedule.expr ?? "";
+	return schedule.atMs ? new Date(schedule.atMs).toISOString() : "";
+}
+function printCronJobs(jobs) {
+	if (!jobs.length) {
+		console.log("No scheduled jobs.");
+		return;
+	}
+	for (const job of jobs) console.log(`${job.id} [${job.enabled ? "enabled" : "disabled"}] ${job.name} ${formatCronSchedule(job.schedule)}`);
+}
+//#endregion
+export { formatCronSchedule, printCronJobs };

package/dist/cli/commands/diagnostics/index.d.ts

@@ -0,0 +1,2 @@
+import { DiagnosticsCommands } from "./services/diagnostics-commands.service.js";
+export { DiagnosticsCommands };

package/dist/cli/commands/diagnostics/index.js

@@ -0,0 +1,2 @@
+import { DiagnosticsCommands } from "./services/diagnostics-commands.service.js";
+export { DiagnosticsCommands };

package/dist/cli/commands/diagnostics/services/diagnostics-commands.service.d.ts

@@ -0,0 +1,22 @@
+import { DoctorCommandOptions, StatusCommandOptions } from "../../../../shared/types/cli.types.js";
+
+//#region src/cli/commands/diagnostics/services/diagnostics-commands.service.d.ts
+declare class DiagnosticsCommands {
+  private deps;
+  constructor(deps: {
+    logo: string;
+  });
+  readonly status: (opts?: StatusCommandOptions) => Promise<void>;
+  readonly doctor: (opts?: DoctorCommandOptions) => Promise<void>;
+  private readonly resolveDoctorPortCheckTarget;
+  private readonly buildDoctorChecks;
+  private readonly resolveDoctorExitCode;
+  private readonly collectRuntimeStatus;
+  private readonly probeApiHealth;
+  private readonly listProviderStatuses;
+  private readonly collectRuntimeIssues;
+  private readonly readLogTail;
+  private readonly checkPortAvailability;
+}
+//#endregion
+export { DiagnosticsCommands };

package/dist/cli/commands/diagnostics/services/diagnostics-commands.service.js

@@ -0,0 +1,319 @@
+import { isProcessRunning, resolveUiApiBase, resolveUiConfig } from "../../../../shared/utils/cli.utils.js";
+import { managedServiceStateStore } from "../../../../shared/stores/managed-service-state.store.js";
+import { resolveNextclawRemoteStatusSnapshot } from "../../../../commands/remote/services/remote-runtime-support.service.js";
+import "../../../../commands/remote/index.js";
+import { printDoctorReport, printStatusReport } from "../utils/diagnostics-render.utils.js";
+import { APP_NAME, getConfigPath, getWorkspacePath, hasSecretRef, loadConfig, resolveAppLogPath } from "@nextclaw/core";
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { listBuiltinProviders } from "@nextclaw/runtime";
+//#region src/cli/commands/diagnostics/services/diagnostics-commands.service.ts
+var DiagnosticsCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	status = async (opts = {}) => {
+		const report = await this.collectRuntimeStatus({
+			verbose: Boolean(opts.verbose),
+			fix: Boolean(opts.fix)
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(report, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		printStatusReport({
+			logo: this.deps.logo,
+			report,
+			verbose: Boolean(opts.verbose)
+		});
+		process.exitCode = 0;
+	};
+	doctor = async (opts = {}) => {
+		const report = await this.collectRuntimeStatus({
+			verbose: Boolean(opts.verbose),
+			fix: Boolean(opts.fix)
+		});
+		const checkPort = await this.checkPortAvailability(this.resolveDoctorPortCheckTarget(report));
+		const checks = this.buildDoctorChecks(report, checkPort);
+		const exitCode = this.resolveDoctorExitCode(checks);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				generatedAt: report.generatedAt,
+				checks,
+				status: report,
+				exitCode
+			}, null, 2));
+			process.exitCode = exitCode;
+			return;
+		}
+		printDoctorReport({
+			logo: this.deps.logo,
+			generatedAt: report.generatedAt,
+			checks,
+			recommendations: report.recommendations,
+			verbose: Boolean(opts.verbose),
+			logTail: report.logTail
+		});
+		process.exitCode = exitCode;
+	};
+	resolveDoctorPortCheckTarget = (report) => {
+		const host = report.process.running && report.endpoints.uiUrl ? new URL(report.endpoints.uiUrl).hostname : "127.0.0.1";
+		try {
+			const base = report.process.running && report.endpoints.uiUrl ? report.endpoints.uiUrl : report.endpoints.configuredUiUrl;
+			return {
+				host,
+				port: Number(new URL(base).port || 80)
+			};
+		} catch {
+			return {
+				host,
+				port: 55667
+			};
+		}
+	};
+	buildDoctorChecks = (report, checkPort) => {
+		const providerConfigured = report.providers.some((provider) => provider.configured);
+		return [
+			{
+				name: "config-file",
+				status: report.configExists ? "pass" : "fail",
+				detail: report.configPath
+			},
+			{
+				name: "workspace-dir",
+				status: report.workspaceExists ? "pass" : "warn",
+				detail: report.workspacePath
+			},
+			{
+				name: "service-state",
+				status: report.process.staleState ? "fail" : report.process.running ? "pass" : "warn",
+				detail: report.process.running ? `PID ${report.process.pid}` : report.process.staleState ? "state exists but process is not running" : "service not running"
+			},
+			{
+				name: "service-health",
+				status: report.process.running ? report.health.managed.state === "ok" ? "pass" : "fail" : "warn",
+				detail: report.process.running ? `${report.health.managed.state}: ${report.health.managed.detail}` : `${report.health.configured.state}: ${report.health.configured.detail}`
+			},
+			{
+				name: "ui-port-availability",
+				status: report.process.running || checkPort.available ? "pass" : "fail",
+				detail: report.process.running ? "managed by running service" : checkPort.available ? "available" : checkPort.detail
+			},
+			{
+				name: "provider-config",
+				status: providerConfigured ? "pass" : "warn",
+				detail: providerConfigured ? "at least one provider configured" : "no provider api key configured"
+			}
+		];
+	};
+	resolveDoctorExitCode = (checks) => {
+		if (checks.some((check) => check.status === "fail")) return 1;
+		if (checks.some((check) => check.status === "warn")) return 1;
+		return 0;
+	};
+	collectRuntimeStatus = async (params) => {
+		const configPath = getConfigPath();
+		const config = loadConfig();
+		const workspacePath = getWorkspacePath(config.agents.defaults.workspace);
+		const serviceStatePath = managedServiceStateStore.path;
+		const fixActions = [];
+		let serviceState = managedServiceStateStore.read();
+		if (params.fix && serviceState && !isProcessRunning(serviceState.pid)) {
+			managedServiceStateStore.clear();
+			fixActions.push("Cleared stale service state file.");
+			serviceState = managedServiceStateStore.read();
+		}
+		const managedByState = Boolean(serviceState);
+		const running = Boolean(serviceState && isProcessRunning(serviceState.pid));
+		const staleState = Boolean(serviceState && !running);
+		const configuredUi = resolveUiConfig(config, {
+			enabled: true,
+			host: config.ui.host,
+			port: config.ui.port
+		});
+		const configuredUiUrl = resolveUiApiBase(configuredUi.host, configuredUi.port);
+		const configuredApiUrl = `${configuredUiUrl}/api`;
+		const managedUiUrl = serviceState?.uiUrl ?? null;
+		const managedApiUrl = serviceState?.apiUrl ?? null;
+		const managedHealth = running && managedApiUrl ? await this.probeApiHealth(`${managedApiUrl}/health`) : {
+			state: "unreachable",
+			detail: "service not running"
+		};
+		const configuredHealth = await this.probeApiHealth(`${configuredApiUrl}/health`, 900);
+		const remote = resolveNextclawRemoteStatusSnapshot(config);
+		const orphanSuspected = !running && configuredHealth.state === "ok";
+		const providers = this.listProviderStatuses(config);
+		const issues = [];
+		const recommendations = [];
+		this.collectRuntimeIssues({
+			configPath,
+			workspacePath,
+			staleState,
+			running,
+			managedHealth,
+			serviceState,
+			orphanSuspected,
+			providers,
+			issues,
+			recommendations
+		});
+		const logTail = params.verbose ? this.readLogTail(serviceState?.logPath ?? resolveAppLogPath("service"), 25) : [];
+		const level = running ? managedHealth.state === "ok" ? issues.length > 0 ? "degraded" : "healthy" : "degraded" : "stopped";
+		return {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			configPath,
+			configExists: existsSync(configPath),
+			workspacePath,
+			workspaceExists: existsSync(workspacePath),
+			model: config.agents.defaults.model,
+			providers,
+			serviceStatePath,
+			serviceStateExists: existsSync(serviceStatePath),
+			fixActions,
+			process: {
+				managedByState,
+				pid: serviceState?.pid ?? null,
+				running,
+				staleState,
+				orphanSuspected,
+				startedAt: serviceState?.startedAt ?? null
+			},
+			endpoints: {
+				uiUrl: managedUiUrl,
+				apiUrl: managedApiUrl,
+				configuredUiUrl,
+				configuredApiUrl
+			},
+			health: {
+				managed: managedHealth,
+				configured: configuredHealth
+			},
+			issues,
+			recommendations,
+			logTail,
+			remote,
+			level,
+			exitCode: 0
+		};
+	};
+	probeApiHealth = async (url, timeoutMs = 1500) => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await fetch(url, {
+				method: "GET",
+				signal: controller.signal
+			});
+			if (!response.ok) return {
+				state: "invalid-response",
+				detail: `HTTP ${response.status}`
+			};
+			const payload = await response.json();
+			if (payload?.ok === true && payload?.data?.status === "ok") return {
+				state: "ok",
+				detail: "health endpoint returned ok",
+				payload
+			};
+			return {
+				state: "invalid-response",
+				detail: "unexpected health payload",
+				payload
+			};
+		} catch (error) {
+			return {
+				state: "unreachable",
+				detail: String(error)
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	listProviderStatuses = (config) => {
+		return listBuiltinProviders().map((spec) => {
+			const provider = config.providers[spec.name];
+			const apiKeyRefSet = hasSecretRef(config, `providers.${spec.name}.apiKey`);
+			if (!provider) return {
+				name: spec.displayName ?? spec.name,
+				configured: false,
+				detail: "missing config"
+			};
+			if (provider.enabled === false) return {
+				name: spec.displayName ?? spec.name,
+				configured: false,
+				detail: "disabled"
+			};
+			if (spec.isLocal) return {
+				name: spec.displayName ?? spec.name,
+				configured: Boolean(provider.apiBase),
+				detail: provider.apiBase ? provider.apiBase : "apiBase not set"
+			};
+			return {
+				name: spec.displayName ?? spec.name,
+				configured: Boolean(provider.apiKey) || apiKeyRefSet,
+				detail: provider.apiKey ? "apiKey set" : apiKeyRefSet ? "apiKey ref set" : "apiKey not set"
+			};
+		});
+	};
+	collectRuntimeIssues = (params) => {
+		const { configPath, issues, managedHealth, orphanSuspected, providers, recommendations, running, serviceState, staleState, workspacePath } = params;
+		if (!existsSync(configPath)) {
+			issues.push("Config file is missing.");
+			recommendations.push(`Run ${APP_NAME} init to create config files.`);
+		}
+		if (!existsSync(workspacePath)) {
+			issues.push("Workspace directory does not exist.");
+			recommendations.push(`Run ${APP_NAME} init to create workspace templates.`);
+		}
+		if (staleState) {
+			issues.push("Service state is stale (state exists but process is not running).");
+			recommendations.push(`Run ${APP_NAME} status --fix to clean stale state.`);
+		}
+		if (running && managedHealth.state !== "ok") {
+			issues.push(`Managed service health check failed: ${managedHealth.detail}`);
+			recommendations.push(`Check logs at ${serviceState?.logPath ?? resolveAppLogPath("service")}.`);
+		}
+		if (running && serviceState?.startupState === "degraded" && managedHealth.state !== "ok") {
+			const startupHint = serviceState.startupLastProbeError ? ` (${serviceState.startupLastProbeError})` : "";
+			issues.push(`Service is in degraded startup state${startupHint}.`);
+			recommendations.push(`Wait and re-check ${APP_NAME} status; if it does not recover, inspect logs and restart.`);
+		}
+		if (!running) recommendations.push(`Run ${APP_NAME} start to launch the service.`);
+		if (orphanSuspected) {
+			issues.push("A service appears healthy on configured API endpoint, but state is missing/stale.");
+			recommendations.push("Another process may be occupying the UI port; stop it or use --ui-port with a free port.");
+		}
+		if (!providers.some((provider) => provider.configured)) recommendations.push("Configure at least one provider API key in UI or config before expecting agent replies.");
+	};
+	readLogTail = (path, maxLines = 25) => {
+		if (!existsSync(path)) return [];
+		try {
+			const lines = readFileSync(path, "utf-8").split(/\r?\n/).filter(Boolean);
+			if (lines.length <= maxLines) return lines;
+			return lines.slice(lines.length - maxLines);
+		} catch {
+			return [];
+		}
+	};
+	checkPortAvailability = async (params) => {
+		return await new Promise((resolve) => {
+			const server = createServer();
+			server.once("error", (error) => {
+				resolve({
+					available: false,
+					detail: `bind failed on ${params.host}:${params.port} (${String(error)})`
+				});
+			});
+			server.listen(params.port, params.host, () => {
+				server.close(() => {
+					resolve({
+						available: true,
+						detail: `bind ok on ${params.host}:${params.port}`
+					});
+				});
+			});
+		});
+	};
+};
+//#endregion
+export { DiagnosticsCommands };

package/dist/cli/commands/diagnostics/utils/diagnostics-render.utils.d.ts

@@ -0,0 +1,23 @@
+import { RuntimeStatusReport } from "../../../../shared/types/cli.types.js";
+
+//#region src/cli/commands/diagnostics/utils/diagnostics-render.utils.d.ts
+type DoctorCheck = {
+  name: string;
+  status: "pass" | "warn" | "fail";
+  detail: string;
+};
+declare function printStatusReport(params: {
+  logo: string;
+  report: RuntimeStatusReport;
+  verbose: boolean;
+}): void;
+declare function printDoctorReport(params: {
+  logo: string;
+  generatedAt: string;
+  checks: DoctorCheck[];
+  recommendations: string[];
+  verbose: boolean;
+  logTail: string[];
+}): void;
+//#endregion
+export { DoctorCheck, printDoctorReport, printStatusReport };