@nextclaw/service 0.1.1

package/dist/cli/commands/diagnostics/utils/diagnostics-render.utils.js

@@ -0,0 +1,66 @@
+import { APP_NAME } from "@nextclaw/core";
+//#region src/cli/commands/diagnostics/utils/diagnostics-render.utils.ts
+function printStatusReport(params) {
+	const { logo, report, verbose } = params;
+	console.log(`${logo} ${APP_NAME} Status`);
+	console.log(`Level: ${report.level}`);
+	console.log(`Generated: ${report.generatedAt}`);
+	console.log("");
+	printProcessSection(report);
+	printEndpointSection(report);
+	printProviderSection(report);
+	printTextList("Fix actions", report.fixActions);
+	printTextList("Issues", report.issues);
+	printTextList("Recommendations", report.recommendations);
+	if (verbose && report.logTail.length > 0) {
+		console.log("");
+		console.log("Recent logs:");
+		for (const line of report.logTail) console.log(line);
+	}
+}
+function printProcessSection(report) {
+	const processLabel = report.process.running ? `running (PID ${report.process.pid})` : report.process.staleState ? "stale-state" : "stopped";
+	console.log(`Process: ${processLabel}`);
+	console.log(`State file: ${report.serviceStatePath} ${report.serviceStateExists ? "✓" : "✗"}`);
+	if (report.process.startedAt) console.log(`Started: ${report.process.startedAt}`);
+	console.log(`Managed health: ${report.health.managed.state} (${report.health.managed.detail})`);
+	if (!report.process.running) console.log(`Configured health: ${report.health.configured.state} (${report.health.configured.detail})`);
+}
+function printEndpointSection(report) {
+	console.log(`UI: ${report.endpoints.uiUrl ?? report.endpoints.configuredUiUrl}`);
+	console.log(`API: ${report.endpoints.apiUrl ?? report.endpoints.configuredApiUrl}`);
+	console.log(`Remote: ${report.remote.configuredEnabled ? "enabled" : "disabled"}${report.remote.runtime ? ` (${report.remote.runtime.state})` : ""}`);
+	if (report.remote.runtime?.deviceName) console.log(`Remote device: ${report.remote.runtime.deviceName}`);
+	if (report.remote.runtime?.platformBase) console.log(`Remote platform: ${report.remote.runtime.platformBase}`);
+	if (report.remote.runtime?.lastError) console.log(`Remote error: ${report.remote.runtime.lastError}`);
+	console.log(`Config: ${report.configPath} ${report.configExists ? "✓" : "✗"}`);
+	console.log(`Workspace: ${report.workspacePath} ${report.workspaceExists ? "✓" : "✗"}`);
+	console.log(`Model: ${report.model}`);
+}
+function printProviderSection(report) {
+	for (const provider of report.providers) console.log(`${provider.name}: ${provider.configured ? "✓" : "not set"}${provider.detail ? ` (${provider.detail})` : ""}`);
+}
+function printDoctorReport(params) {
+	const { checks, generatedAt, logTail, logo, recommendations, verbose } = params;
+	console.log(`${logo} ${APP_NAME} Doctor`);
+	console.log(`Generated: ${generatedAt}`);
+	console.log("");
+	for (const check of checks) {
+		const icon = check.status === "pass" ? "✓" : check.status === "warn" ? "!" : "✗";
+		console.log(`${icon} ${check.name}: ${check.detail}`);
+	}
+	printTextList("Recommendations", recommendations);
+	if (verbose && logTail.length > 0) {
+		console.log("");
+		console.log("Recent logs:");
+		for (const line of logTail) console.log(line);
+	}
+}
+function printTextList(title, items) {
+	if (items.length === 0) return;
+	console.log("");
+	console.log(`${title}:`);
+	for (const item of items) console.log(`- ${item}`);
+}
+//#endregion
+export { printDoctorReport, printStatusReport };

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

@@ -0,0 +1,14 @@
+import { GatewayCommandOptions } from "../../../shared/types/cli.types.js";
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+
+//#region src/cli/commands/gateway/index.d.ts
+declare class GatewayCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+    forcedPublicHost: string;
+  });
+  run: (opts: GatewayCommandOptions) => Promise<void>;
+}
+//#endregion
+export { GatewayCommands };

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

@@ -0,0 +1,15 @@
+//#region src/cli/commands/gateway/index.ts
+var GatewayCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (opts) => {
+		const uiOverrides = { host: this.deps.forcedPublicHost };
+		if (opts.ui) uiOverrides.enabled = true;
+		if (opts.uiPort) uiOverrides.port = Number(opts.uiPort);
+		if (opts.uiOpen) uiOverrides.open = true;
+		await this.deps.runtimeCommandService.startGateway({ uiOverrides });
+	};
+};
+//#endregion
+export { GatewayCommands };

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

@@ -0,0 +1,12 @@
+import { LogsTailCommandOptions } from "../../../shared/types/cli.types.js";
+import { LoggingRuntime } from "@nextclaw/core";
+
+//#region src/cli/commands/logs/index.d.ts
+declare class LogsCommands {
+  private readonly runtime;
+  constructor(runtime?: LoggingRuntime);
+  path: () => void;
+  tail: (opts?: LogsTailCommandOptions) => void;
+}
+//#endregion
+export { LogsCommands };

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

@@ -0,0 +1,29 @@
+import { getLoggingRuntime } from "@nextclaw/core";
+//#region src/cli/commands/logs/index.ts
+var LogsCommands = class {
+	constructor(runtime = getLoggingRuntime()) {
+		this.runtime = runtime;
+	}
+	path = () => {
+		const paths = this.runtime.getPaths();
+		console.log([
+			`Logs directory: ${paths.logsDir}`,
+			`Service log: ${paths.serviceLogPath}`,
+			`Crash log: ${paths.crashLogPath}`,
+			`Archive: ${paths.archiveDir}`
+		].join("\n"));
+	};
+	tail = (opts = {}) => {
+		const kind = opts.crash ? "crash" : "service";
+		const rawLines = Number(opts.lines);
+		const lines = Number.isFinite(rawLines) && rawLines > 0 ? Math.floor(rawLines) : 40;
+		const output = this.runtime.tail(kind, lines);
+		if (output.length === 0) {
+			console.log(`No log entries found in ${this.runtime.resolveLogPath(kind)}.`);
+			return;
+		}
+		console.log(output.join("\n"));
+	};
+};
+//#endregion
+export { LogsCommands };

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

@@ -0,0 +1,14 @@
+import { McpAddCommandOptions, McpDoctorOptions, McpListOptions } from "../../../shared/types/cli.types.js";
+
+//#region src/cli/commands/mcp/index.d.ts
+declare class McpCommands {
+  list: (opts?: McpListOptions) => void;
+  add: (name: string, command: string[], opts: McpAddCommandOptions) => Promise<void>;
+  remove: (name: string) => Promise<void>;
+  enable: (name: string) => Promise<void>;
+  disable: (name: string) => Promise<void>;
+  doctor: (name?: string, opts?: McpDoctorOptions) => Promise<void>;
+  private toggleEnabled;
+}
+//#endregion
+export { McpCommands };

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

@@ -0,0 +1,193 @@
+import { loadConfig, saveConfig } from "@nextclaw/core";
+import { McpDoctorFacade, McpMutationService, McpRegistryService } from "@nextclaw/mcp";
+//#region src/cli/commands/mcp/index.ts
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function parsePairs(values, label) {
+	const output = {};
+	for (const raw of values ?? []) {
+		const index = raw.indexOf("=");
+		if (index <= 0) throw new Error(`Invalid ${label} entry: ${raw}. Expected key=value.`);
+		const key = raw.slice(0, index).trim();
+		const value = raw.slice(index + 1);
+		if (!key) throw new Error(`Invalid ${label} entry: ${raw}. Expected key=value.`);
+		output[key] = value;
+	}
+	return output;
+}
+function parseTimeoutMs(value) {
+	if (value === void 0 || value === null || value === "") return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid timeout: ${String(value)}`);
+	return Math.trunc(parsed);
+}
+function buildMcpServerDefinition(command, opts) {
+	const transport = (normalizeOptionalString(opts.transport) ?? "stdio").toLowerCase();
+	const disabled = Boolean(opts.disabled);
+	const explicitAgents = Array.from(new Set((opts.agent ?? []).map((agentId) => normalizeOptionalString(agentId)).filter((agentId) => Boolean(agentId))));
+	const allAgents = explicitAgents.length === 0 ? true : Boolean(opts.allAgents);
+	if (transport === "stdio") {
+		if (command.length === 0) throw new Error("stdio transport requires a command after --");
+		return {
+			enabled: !disabled,
+			transport: {
+				type: "stdio",
+				command: command[0],
+				args: command.slice(1),
+				cwd: normalizeOptionalString(opts.cwd),
+				env: parsePairs(opts.env, "env"),
+				stderr: normalizeOptionalString(opts.stderr) ?? "pipe"
+			},
+			scope: {
+				allAgents,
+				agents: allAgents ? [] : explicitAgents
+			},
+			policy: {
+				trust: "explicit",
+				start: "eager"
+			},
+			metadata: {
+				source: "manual",
+				installedAt: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		};
+	}
+	const url = normalizeOptionalString(opts.url);
+	if (!url) throw new Error(`${transport} transport requires --url`);
+	const timeoutMs = parseTimeoutMs(opts.timeoutMs);
+	const shared = {
+		enabled: !disabled,
+		scope: {
+			allAgents,
+			agents: allAgents ? [] : explicitAgents
+		},
+		policy: {
+			trust: "explicit",
+			start: "eager"
+		},
+		metadata: {
+			source: "manual",
+			installedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}
+	};
+	if (transport === "http") return {
+		...shared,
+		transport: {
+			type: "http",
+			url,
+			headers: parsePairs(opts.header, "header"),
+			timeoutMs: timeoutMs ?? 15e3,
+			verifyTls: !opts.insecure
+		}
+	};
+	if (transport === "sse") return {
+		...shared,
+		transport: {
+			type: "sse",
+			url,
+			headers: parsePairs(opts.header, "header"),
+			timeoutMs: timeoutMs ?? 15e3,
+			verifyTls: !opts.insecure,
+			reconnect: {
+				enabled: true,
+				initialDelayMs: 1e3,
+				maxDelayMs: 3e4
+			}
+		}
+	};
+	throw new Error(`Unsupported MCP transport: ${transport}`);
+}
+var McpCommands = class {
+	list = (opts = {}) => {
+		const servers = new McpRegistryService({ getConfig: () => loadConfig() }).listServers().map((server) => ({
+			name: server.name,
+			enabled: server.definition.enabled,
+			transport: server.definition.transport.type,
+			scope: server.definition.scope
+		}));
+		if (opts.json) {
+			console.log(JSON.stringify({ servers }, null, 2));
+			return;
+		}
+		if (servers.length === 0) {
+			console.log("No MCP servers configured.");
+			return;
+		}
+		for (const server of servers) {
+			const scope = server.scope.allAgents ? "all-agents" : server.scope.agents.length > 0 ? `agents=${server.scope.agents.join(",")}` : "default-agent";
+			console.log(`${server.enabled ? "ENABLED " : "DISABLED"} ${server.name} (${server.transport}, ${scope})`);
+		}
+	};
+	add = async (name, command, opts) => {
+		const result = new McpMutationService({
+			getConfig: () => loadConfig(),
+			saveConfig: (config) => saveConfig(config)
+		}).addServer(name, buildMcpServerDefinition(command, opts));
+		if (!result.changed) {
+			reportUserInputIssue(result.message);
+			return;
+		}
+		console.log(result.message);
+	};
+	remove = async (name) => {
+		const result = new McpMutationService({
+			getConfig: () => loadConfig(),
+			saveConfig: (config) => saveConfig(config)
+		}).removeServer(name);
+		if (!result.changed) {
+			reportUserInputIssue(result.message);
+			return;
+		}
+		console.log(result.message);
+	};
+	enable = async (name) => {
+		await this.toggleEnabled(name, true);
+	};
+	disable = async (name) => {
+		await this.toggleEnabled(name, false);
+	};
+	doctor = async (name, opts = {}) => {
+		const registry = new McpRegistryService({ getConfig: () => loadConfig() });
+		const doctor = new McpDoctorFacade({
+			getConfig: () => loadConfig(),
+			registryService: registry
+		});
+		try {
+			const reports = await doctor.inspect(name);
+			if (opts.json) {
+				console.log(JSON.stringify({ reports }, null, 2));
+				return;
+			}
+			if (reports.length === 0) {
+				console.log("No MCP servers matched.");
+				return;
+			}
+			for (const report of reports) {
+				const status = report.error ? "ERROR" : "OK";
+				const detail = report.error ? ` (${report.error})` : "";
+				console.log(`[${status}] ${report.name} enabled=${report.enabled} transport=${report.transport} tools=${report.toolCount}${detail}`);
+			}
+		} finally {
+			await registry.close();
+		}
+	};
+	toggleEnabled = async (name, enabled) => {
+		const result = new McpMutationService({
+			getConfig: () => loadConfig(),
+			saveConfig: (config) => saveConfig(config)
+		}).toggleEnabled(name, enabled);
+		if (!result.changed) {
+			reportUserInputIssue(result.message);
+			return;
+		}
+		console.log(result.message);
+	};
+};
+function reportUserInputIssue(message) {
+	console.error(message);
+	process.exitCode = 1;
+}
+//#endregion
+export { McpCommands };

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

@@ -0,0 +1,20 @@
+import { StartCommandOptions } from "../../../shared/types/cli.types.js";
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+import { StartCommands } from "../start/index.js";
+
+//#region src/cli/commands/restart/index.d.ts
+declare class RestartCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+    startCommands: StartCommands;
+    forcedPublicHost: string;
+    writeRestartSentinelFromExecContext: (reason: string) => Promise<void>;
+  });
+  run: (opts: StartCommandOptions) => Promise<void>;
+  private restartForegroundRuntime;
+  private resolveAdoptableForegroundRuntimePid;
+  private isAdoptableNextclawRuntimeCommand;
+}
+//#endregion
+export { RestartCommands };

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

@@ -0,0 +1,88 @@
+import { findListeningProcessByPort, isProcessRunning, resolveUiConfig, waitForExit } from "../../../shared/utils/cli.utils.js";
+import { localUiRuntimeStore } from "../../../shared/stores/local-ui-runtime.store.js";
+import { managedServiceStateStore } from "../../../shared/stores/managed-service-state.store.js";
+import { describeUnmanagedHealthyTargetMessage } from "../../../shared/utils/service-port-probe.utils.js";
+import { resolveManagedServiceUiOverrides } from "../../../shared/utils/runtime-helpers.js";
+import "../../../shared/services/runtime/runtime-command.service.js";
+import { APP_NAME, loadConfig } from "@nextclaw/core";
+//#region src/cli/commands/restart/index.ts
+var RestartCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (opts) => {
+		await this.deps.writeRestartSentinelFromExecContext("cli.restart");
+		const uiOverrides = resolveManagedServiceUiOverrides({
+			uiPort: opts.uiPort,
+			forcedPublicHost: this.deps.forcedPublicHost
+		});
+		const targetUi = resolveUiConfig(loadConfig(), uiOverrides);
+		const state = managedServiceStateStore.read();
+		if (state && isProcessRunning(state.pid)) {
+			console.log(`Restarting ${APP_NAME}...`);
+			await this.deps.runtimeCommandService.stopService();
+		} else {
+			const foregroundRuntime = localUiRuntimeStore.read();
+			const foregroundMatchesTarget = Boolean(foregroundRuntime && isProcessRunning(foregroundRuntime.pid) && foregroundRuntime.uiPort === targetUi.port);
+			if (foregroundRuntime && foregroundMatchesTarget) {
+				if (!await this.restartForegroundRuntime(foregroundRuntime.pid)) return;
+				await this.deps.startCommands.run(opts);
+				return;
+			}
+			if (state) {
+				managedServiceStateStore.clear();
+				console.log("Service state was stale and has been cleaned up.");
+			}
+			const unmanagedHealthyServiceMessage = await describeUnmanagedHealthyTargetMessage({ uiOverrides });
+			if (unmanagedHealthyServiceMessage) {
+				const adoptedRuntimePid = this.resolveAdoptableForegroundRuntimePid(targetUi.port);
+				if (adoptedRuntimePid) {
+					if (!await this.restartForegroundRuntime(adoptedRuntimePid)) return;
+					await this.deps.startCommands.run(opts);
+					return;
+				}
+				console.error(`Error: Cannot restart ${APP_NAME} because the target UI/API port is already served by a healthy unmanaged instance.`);
+				console.error(unmanagedHealthyServiceMessage);
+				return;
+			}
+			if (!state) console.log("No running service found. Starting a new service.");
+		}
+		await this.deps.startCommands.run(opts);
+	};
+	restartForegroundRuntime = async (pid) => {
+		console.log(`Restarting ${APP_NAME} foreground runtime (PID ${pid})...`);
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch (error) {
+			console.error(`Failed to stop foreground runtime: ${String(error)}`);
+			return false;
+		}
+		if (!await waitForExit(pid, 3e3)) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch (error) {
+				console.error(`Failed to force stop foreground runtime: ${String(error)}`);
+				return false;
+			}
+			if (!await waitForExit(pid, 2e3)) {
+				console.error(`Failed to stop foreground runtime PID ${pid}.`);
+				return false;
+			}
+		}
+		localUiRuntimeStore.clearIfOwnedByProcess(pid);
+		console.log(`✓ ${APP_NAME} foreground runtime stopped`);
+		return true;
+	};
+	resolveAdoptableForegroundRuntimePid = (port) => {
+		const listeningProcess = findListeningProcessByPort(port);
+		if (!listeningProcess || !isProcessRunning(listeningProcess.pid)) return null;
+		return this.isAdoptableNextclawRuntimeCommand(listeningProcess.command) ? listeningProcess.pid : null;
+	};
+	isAdoptableNextclawRuntimeCommand = (command) => {
+		const normalized = command?.trim() ?? "";
+		if (!normalized) return false;
+		return /\bserve\b/.test(normalized) && (normalized.includes("/dist/cli/app/index.js") || normalized.includes("/src/cli/app/index.js") || normalized.includes("/runtime/dist/cli/app/index.js"));
+	};
+};
+//#endregion
+export { RestartCommands };

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

@@ -0,0 +1,22 @@
+import { RequestRestartParams, SecretsApplyOptions, SecretsAuditOptions, SecretsConfigureOptions, SecretsReloadOptions } from "../../../shared/types/cli.types.js";
+
+//#region src/cli/commands/secrets/index.d.ts
+declare class SecretsCommands {
+  private deps;
+  constructor(deps: {
+    requestRestart: (params: RequestRestartParams) => Promise<void>;
+  });
+  audit: (opts?: SecretsAuditOptions) => void;
+  configure: (opts: SecretsConfigureOptions) => Promise<void>;
+  apply: (opts: SecretsApplyOptions) => Promise<void>;
+  reload: (opts?: SecretsReloadOptions) => Promise<void>;
+  private removeProvider;
+  private configureProvider;
+  private buildProviderConfig;
+  private applyEnabledPatch;
+  private applyFilePatch;
+  private applySingleRefPatch;
+  private requestRestartForConfigDiff;
+}
+//#endregion
+export { SecretsCommands };