nextclaw 0.20.5 → 0.21.0

package/dist/cli/app/index.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import { t as createNextclawDistribution } from "../../nextclaw-distribution.utils-BJZhAnGk.js";
 import { createRequire } from "node:module";
-import { APP_NAME, APP_TAGLINE, loadConfig } from "@nextclaw/core";
+import { APP_NAME, APP_TAGLINE, getConfigPath, loadConfig, resolveConfigSecrets } from "@nextclaw/core";
 import { Command } from "commander";
-import "node:fs";
-import "node:path";
+import { constants } from "node:fs";
+import path from "node:path";
 import "@nextclaw/server";
 import { NextclawDistributionService, NextclawServiceRuntime, readLearningLoopRuntimeConfig } from "@nextclaw/service";
+import { McpServiceAppRuntimeService, buildServiceActionId, getServiceAppManifestPath, mergeServiceAppRuntimeActions, readServiceAppManifest } from "@nextclaw/kernel";
+import { access, readFile, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
@@ -3619,6 +3623,810 @@ const registerHostServiceControls = ({ program, nextclaw }) => {
 	autostart.command("doctor").description("Diagnose host autostart setup").option("--user", "Inspect the user-level autostart owner", false).option("--system", "Inspect the system-level autostart owner", false).option("--json", "Output JSON", false).action(async (opts) => serviceCommands.autostartDoctor(opts));
 };
 //#endregion
+//#region src/cli/app/services/service-app-dev.service.ts
+var ServiceAppDevService = class {
+	constructor(params = {}) {
+		this.params = params;
+	}
+	inspect = async (target) => {
+		const appPath = path.resolve(target);
+		const issues = [];
+		const loaded = await this.loadServiceApp(appPath, issues);
+		if (!loaded) return this.buildDevReport(appPath, void 0, [], issues);
+		if (this.hasErrors(issues)) return this.buildDevReport(appPath, this.toServiceAppRecord(appPath, loaded.manifest, this.idleRuntimeStatus), [], issues);
+		const runtime = this.createRuntimeService();
+		try {
+			const startRecord = this.toServiceAppRecord(appPath, loaded.manifest, runtime);
+			const runtimeActions = await runtime.listActions({
+				app: startRecord,
+				manifest: loaded.manifest
+			});
+			const record = this.toServiceAppRecord(appPath, loaded.manifest, runtime);
+			const actions = mergeServiceAppRuntimeActions({
+				record,
+				manifest: loaded.manifest,
+				runtimeActions
+			});
+			this.collectRuntimeIssues(record, actions, issues);
+			return this.buildDevReport(appPath, record, actions, issues);
+		} finally {
+			await runtime.dispose();
+		}
+	};
+	call = async (target, actionName, input) => {
+		const appPath = path.resolve(target);
+		const issues = [];
+		const loaded = await this.loadServiceApp(appPath, issues);
+		if (!loaded) return this.buildCallReport(appPath, void 0, void 0, void 0, issues);
+		if (this.hasErrors(issues)) return this.buildCallReport(appPath, this.toServiceAppRecord(appPath, loaded.manifest, this.idleRuntimeStatus), void 0, void 0, issues);
+		const action = actionName.trim();
+		if (!Object.hasOwn(loaded.manifest.actions, action)) {
+			issues.push({
+				severity: "error",
+				code: "service.action.notDeclared",
+				message: `service-app.json does not declare action: ${action || "(empty)"}.`
+			});
+			const record = this.toServiceAppRecord(appPath, loaded.manifest, this.idleRuntimeStatus);
+			return this.buildCallReport(appPath, record, void 0, void 0, issues);
+		}
+		const runtime = this.createRuntimeService();
+		try {
+			const record = this.toServiceAppRecord(appPath, loaded.manifest, runtime);
+			const result = await runtime.invokeAction({
+				app: record,
+				manifest: loaded.manifest,
+				actionName: action,
+				input
+			});
+			const nextRecord = this.toServiceAppRecord(appPath, loaded.manifest, runtime);
+			return this.buildCallReport(appPath, nextRecord, buildServiceActionId(loaded.manifest.id, action), result, issues);
+		} catch (error) {
+			const record = this.toServiceAppRecord(appPath, loaded.manifest, runtime);
+			issues.push({
+				severity: "error",
+				code: "service.runtime.callFailed",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return this.buildCallReport(appPath, record, buildServiceActionId(loaded.manifest.id, action), void 0, issues);
+		} finally {
+			await runtime.dispose();
+		}
+	};
+	loadServiceApp = async (appPath, issues) => {
+		try {
+			const manifest = await readServiceAppManifest(appPath);
+			if (manifest.id !== path.basename(appPath)) issues.push({
+				severity: "error",
+				code: "service.id.invalid",
+				message: `service-app.json id must equal directory name: ${path.basename(appPath)}.`
+			});
+			if (!manifest.enabled) issues.push({
+				severity: "error",
+				code: "service.disabled",
+				message: "Service App is disabled and cannot be started by app dev."
+			});
+			return { manifest };
+		} catch (error) {
+			issues.push({
+				severity: "error",
+				code: "service.manifest.readFailed",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return null;
+		}
+	};
+	createRuntimeService = () => this.params.runtimeService ?? new McpServiceAppRuntimeService({ getConfig: this.params.getConfig ?? this.loadRuntimeConfig });
+	loadRuntimeConfig = () => {
+		const configPath = getConfigPath();
+		return resolveConfigSecrets(loadConfig(configPath), { configPath });
+	};
+	idleRuntimeStatus = { getStatus: () => ({ status: "idle" }) };
+	toServiceAppRecord = (dirPath, manifest, runtime) => {
+		const runtimeStatus = runtime.getStatus(manifest.id);
+		const record = {
+			id: manifest.id,
+			title: manifest.title,
+			dirPath,
+			manifestPath: getServiceAppManifestPath(dirPath),
+			command: manifest.command,
+			args: manifest.args,
+			cwd: dirPath,
+			enabled: manifest.enabled,
+			protocol: manifest.protocol,
+			status: manifest.enabled ? runtimeStatus.status : "stopped"
+		};
+		if (manifest.description) record.description = manifest.description;
+		if (runtimeStatus.lastError) record.lastError = runtimeStatus.lastError;
+		if (runtimeStatus.lastStartedAt) record.lastStartedAt = runtimeStatus.lastStartedAt;
+		if (runtimeStatus.lastReadyAt) record.lastReadyAt = runtimeStatus.lastReadyAt;
+		if (runtimeStatus.lastFailedAt) record.lastFailedAt = runtimeStatus.lastFailedAt;
+		return record;
+	};
+	collectRuntimeIssues = (record, actions, issues) => {
+		if (record.status === "failed") issues.push({
+			severity: "error",
+			code: "service.runtime.startFailed",
+			message: record.lastError ?? "Service App runtime failed to start."
+		});
+		for (const action of actions) {
+			if (action.runtimeState === "missing") issues.push({
+				severity: "error",
+				code: "service.action.runtimeMissing",
+				message: `Declared action is missing from runtime tools/list: ${action.name}.`
+			});
+			if (action.runtimeState === "undeclared") issues.push({
+				severity: "error",
+				code: "service.action.runtimeUndeclared",
+				message: `Runtime exposes an undeclared action: ${action.name}.`,
+				fixHint: `Add "${action.name}" to service-app.json actions or remove it from the MCP server.`
+			});
+		}
+	};
+	buildDevReport = (target, app, actions, issues) => ({
+		ok: !issues.some((issue) => issue.severity === "error"),
+		target,
+		app,
+		actions,
+		issues
+	});
+	buildCallReport = (target, app, actionId, result, issues) => ({
+		ok: !issues.some((issue) => issue.severity === "error"),
+		target,
+		actionId,
+		app,
+		result,
+		issues
+	});
+	hasErrors = (issues) => issues.some((issue) => issue.severity === "error");
+};
+//#endregion
+//#region src/cli/app/controllers/app-call-command.controller.ts
+var AppCallCommandController = class {
+	constructor(serviceAppDevService = new ServiceAppDevService()) {
+		this.serviceAppDevService = serviceAppDevService;
+	}
+	call = async (target, actionName, options) => {
+		const input = this.parseInput(options.input);
+		if (!input.ok) {
+			this.writeInputError(input.message, Boolean(options.json));
+			process.exitCode = 1;
+			return;
+		}
+		const report = await this.serviceAppDevService.call(target, actionName, input.value);
+		process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : this.format(report));
+		if (!report.ok) process.exitCode = 1;
+	};
+	parseInput = (raw) => {
+		if (!raw) return {
+			ok: true,
+			value: {}
+		};
+		try {
+			const parsed = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {
+				ok: false,
+				message: "--input must be a JSON object."
+			};
+			return {
+				ok: true,
+				value: parsed
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				message: `--input is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+	};
+	writeInputError = (message, json) => {
+		if (json) {
+			process.stdout.write(`${JSON.stringify({
+				ok: false,
+				issues: [{
+					severity: "error",
+					code: "input.invalid",
+					message
+				}]
+			}, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(`NextClaw service app call failed\n\nErrors:\n- [input.invalid] ${message}\n`);
+	};
+	format = (report) => {
+		return [
+			report.ok ? `NextClaw service app call passed: ${report.actionId ?? "(unknown)"}\n` : `NextClaw service app call failed: ${report.actionId ?? "(unknown)"}\n`,
+			report.app ? [
+				`App: ${report.app.title} (${report.app.id})`,
+				`Status: ${report.app.status}`,
+				report.app.lastError ? `Last error: ${report.app.lastError}` : ""
+			].filter(Boolean).join("\n") : "",
+			report.result === void 0 ? "" : `Result:\n${JSON.stringify(report.result, null, 2)}\n`,
+			this.formatIssueSection("Errors", report.issues.filter((issue) => issue.severity === "error")),
+			this.formatIssueSection("Warnings", report.issues.filter((issue) => issue.severity === "warning"))
+		].filter(Boolean).join("\n");
+	};
+	formatIssueSection = (title, issues) => {
+		if (issues.length === 0) return "";
+		return `${title}:\n${issues.flatMap((issue) => [`- [${issue.code}] ${issue.message}`, issue.fixHint ? `  Fix: ${issue.fixHint}` : ""].filter(Boolean)).join("\n")}\n`;
+	};
+};
+//#endregion
+//#region src/cli/app/utils/app-check.utils.ts
+const PANEL_MANIFEST_FILE = "panel-app.json";
+const SERVICE_MANIFEST_FILE = "service-app.json";
+const VALID_AGENT_CAPABILITIES = new Set(["agent:send", "agent:generateObject"]);
+const VALID_SERVICE_ACTION_RISKS = new Set([
+	"read",
+	"write",
+	"external",
+	"dangerous"
+]);
+const KEBAB_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SERVICE_ACTION_ID_PATTERN = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.(.+)$/;
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString(record, key) {
+	return typeof record[key] === "string" && record[key].trim() ? record[key].trim() : void 0;
+}
+function readRequiredString(record, key, prefix) {
+	const value = readOptionalString(record, key);
+	if (!value) return { issue: {
+		severity: "error",
+		code: `${prefix}.${key}.missing`,
+		message: `${prefix}-app.json ${key} is required.`
+	} };
+	return { value };
+}
+function getRecommendedStringIssue(record, key, prefix) {
+	if (!readOptionalString(record, key)) return {
+		severity: "warning",
+		code: `${prefix}.${key}.missing`,
+		message: `${prefix}-app.json ${key} is recommended.`
+	};
+}
+function readStringArray(value, key) {
+	if (value === void 0) return { values: [] };
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) return {
+		values: [],
+		issue: {
+			severity: "error",
+			code: `${key}.invalid`,
+			message: `${key} must be a string array.`
+		}
+	};
+	return { values: [...new Set(value.map((entry) => entry.trim()).filter(Boolean))] };
+}
+async function getTargetDirectoryIssue(appPath) {
+	try {
+		if ((await stat(appPath)).isDirectory()) return;
+		return {
+			severity: "error",
+			code: "app.target.notDirectory",
+			message: "App check target must be a directory."
+		};
+	} catch {
+		return {
+			severity: "error",
+			code: "app.target.missing",
+			message: "App check target directory does not exist."
+		};
+	}
+}
+async function readJsonObject(filePath) {
+	try {
+		const parsed = JSON.parse(await readFile(filePath, "utf8"));
+		if (isRecord(parsed)) return { value: parsed };
+		return {
+			value: null,
+			issue: {
+				severity: "error",
+				code: "manifest.notObject",
+				message: `${path.basename(filePath)} must contain a JSON object.`
+			}
+		};
+	} catch (error) {
+		return {
+			value: null,
+			issue: {
+				severity: "error",
+				code: "manifest.jsonInvalid",
+				message: `${path.basename(filePath)} is not valid JSON.`,
+				fixHint: error instanceof Error ? error.message : String(error)
+			}
+		};
+	}
+}
+async function fileExists(filePath) {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function getMissingRelativeFileIssue(appPath, relativePath, code, message) {
+	const resolved = resolveRelativeFile(appPath, relativePath);
+	if (!resolved || !await fileExists(resolved)) return {
+		severity: "error",
+		code,
+		message: `${message}: ${relativePath}.`
+	};
+}
+function resolveRelativeFile(appPath, relativePath) {
+	if (!isRelativeResource(relativePath)) return null;
+	const resolved = path.resolve(appPath, relativePath);
+	return resolved === appPath || resolved.startsWith(`${appPath}${path.sep}`) ? resolved : null;
+}
+function isRelativeResource(value) {
+	return Boolean(value) && !value.startsWith("/") && !/^(?:[a-z]+:|#)/i.test(value);
+}
+function extractHtmlAssetPaths(html) {
+	return [...html.matchAll(/<(?:img|link)\b[^>]*(?:src|href)\s*=\s*["']([^"']+)["']/gi)].map((match) => match[1] ?? "").filter(isRelativeResource);
+}
+function extractScriptSrcs(html) {
+	return [...html.matchAll(/<script\b[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi)].map((match) => match[1] ?? "");
+}
+function inferWorkspaceRoot(appPath, containerName) {
+	const container = path.dirname(appPath);
+	return path.basename(container) === containerName ? path.dirname(container) : null;
+}
+function isNodeCommand(command) {
+	const name = path.basename(command).toLowerCase();
+	return name === "node" || name === "node.exe";
+}
+//#endregion
+//#region src/cli/app/services/panel-app-check.service.ts
+var PanelAppCheckService = class {
+	check = async (appPath) => {
+		const issues = [];
+		this.checkDirectoryName(appPath, issues);
+		const manifestResult = await readJsonObject(path.join(appPath, PANEL_MANIFEST_FILE));
+		this.pushIssue(issues, manifestResult.issue);
+		if (!manifestResult.value) return issues;
+		const entry = this.checkManifestFields(appPath, manifestResult.value, issues);
+		this.checkCapabilities(manifestResult.value.capabilities, issues);
+		const declaredActions = this.checkActions(manifestResult.value.actions, issues);
+		await this.checkWorkspaceServiceActions(appPath, declaredActions, issues);
+		await this.checkEntry(appPath, entry, manifestResult.value, declaredActions, issues);
+		return issues;
+	};
+	checkDirectoryName = (appPath, issues) => {
+		if (!path.basename(appPath).endsWith(".panel")) issues.push({
+			severity: "error",
+			code: "panel.directory.invalid",
+			message: "Panel App directory name must end with .panel.",
+			fixHint: "Rename the directory to <app-id>.panel."
+		});
+	};
+	checkManifestFields = (appPath, manifest, issues) => {
+		const appId = path.basename(appPath).replace(/\.panel$/, "");
+		const id = readOptionalString(manifest, "id");
+		if (id && (!KEBAB_ID_PATTERN.test(id) || id !== appId)) issues.push({
+			severity: "error",
+			code: "panel.id.invalid",
+			message: `panel-app.json id must equal directory app id: ${appId}.`,
+			fixHint: "Remove id or set it to the directory name without .panel."
+		});
+		const title = readRequiredString(manifest, "title", "panel");
+		this.pushIssue(issues, title.issue);
+		this.pushIssue(issues, getRecommendedStringIssue(manifest, "description", "panel"));
+		this.pushIssue(issues, getRecommendedStringIssue(manifest, "icon", "panel"));
+		const entry = readRequiredString(manifest, "entry", "panel");
+		this.pushIssue(issues, entry.issue);
+		return entry.value;
+	};
+	checkCapabilities = (value, issues) => {
+		const capabilities = readStringArray(value, "panel.capabilities");
+		this.pushIssue(issues, capabilities.issue);
+		for (const capability of capabilities.values) {
+			if (VALID_AGENT_CAPABILITIES.has(capability)) continue;
+			issues.push({
+				severity: "error",
+				code: "panel.capability.invalid",
+				message: `Invalid agent capability: ${capability}.`,
+				fixHint: capability.includes(".") ? "Use agent:send or agent:generateObject, with a colon." : "Allowed values are agent:send and agent:generateObject."
+			});
+		}
+	};
+	checkActions = (value, issues) => {
+		const actions = readStringArray(value, "panel.actions");
+		this.pushIssue(issues, actions.issue);
+		for (const action of actions.values) {
+			if (SERVICE_ACTION_ID_PATTERN.test(action)) continue;
+			issues.push({
+				severity: "error",
+				code: "panel.action.invalid",
+				message: `Invalid service action id: ${action}.`,
+				fixHint: "Use <service-app-id>.<tool-name>, for example workspace-files.list."
+			});
+		}
+		return actions.values;
+	};
+	checkWorkspaceServiceActions = async (appPath, actions, issues) => {
+		const workspaceRoot = inferWorkspaceRoot(appPath, "panels");
+		if (!workspaceRoot || actions.length === 0) return;
+		const cache = /* @__PURE__ */ new Map();
+		for (const action of actions) {
+			const match = action.match(SERVICE_ACTION_ID_PATTERN);
+			if (!match) continue;
+			await this.checkWorkspaceServiceAction(workspaceRoot, match[1] ?? "", match[2] ?? "", cache, issues);
+		}
+	};
+	checkWorkspaceServiceAction = async (workspaceRoot, serviceId, actionName, cache, issues) => {
+		const manifest = await this.readCachedServiceManifest(workspaceRoot, serviceId, cache, issues);
+		if (!manifest) return;
+		const actions = manifest.actions;
+		if (!isRecord(actions) || !isRecord(actions[actionName])) issues.push({
+			severity: "error",
+			code: "panel.action.missingServiceAction",
+			message: `Declared service action does not exist: ${serviceId}.${actionName}.`,
+			fixHint: `Add "${actionName}" to service-apps/${serviceId}/service-app.json actions or fix panel-app.json actions.`
+		});
+	};
+	checkEntry = async (appPath, entry, manifest, declaredActions, issues) => {
+		if (!entry) return;
+		const entryPath = resolveRelativeFile(appPath, entry);
+		if (!entryPath) {
+			issues.push({
+				severity: "error",
+				code: "panel.entry.invalid",
+				message: `Panel entry must be a relative file inside the app directory: ${entry}.`
+			});
+			return;
+		}
+		if (!await fileExists(entryPath)) {
+			issues.push({
+				severity: "error",
+				code: "panel.entry.missing",
+				message: `Panel entry file does not exist: ${entry}.`
+			});
+			return;
+		}
+		await this.checkEntryContent(appPath, entryPath, manifest, declaredActions, issues);
+	};
+	checkEntryContent = async (appPath, entryPath, manifest, declaredActions, issues) => {
+		const html = await readFile(entryPath, "utf8");
+		this.checkLegacyMeta(html, issues);
+		await this.checkIcon(appPath, manifest.icon, issues);
+		await this.checkRelativeAssets(appPath, html, issues);
+		const scripts = await this.readReferencedScripts(appPath, html, issues);
+		this.checkBridgeUsage([html, ...scripts].join("\n"), manifest, declaredActions, issues);
+	};
+	checkLegacyMeta = (html, issues) => {
+		if (/name\s*=\s*["']nextclaw-panel-(actions|capabilities)["']/i.test(html)) issues.push({
+			severity: "error",
+			code: "panel.meta.deprecated",
+			message: "Directory Panel Apps must not declare NextClaw actions or capabilities in HTML meta tags.",
+			fixHint: "Move actions and capabilities into panel-app.json."
+		});
+	};
+	checkIcon = async (appPath, icon, issues) => {
+		if (typeof icon !== "string" || !this.isRelativeIconFile(icon)) return;
+		this.pushIssue(issues, await getMissingRelativeFileIssue(appPath, icon, "panel.icon.missing", "Panel icon file does not exist"));
+	};
+	isRelativeIconFile = (icon) => isRelativeResource(icon) && (icon.includes("/") || /\.(?:svg|png|jpe?g|gif|webp|ico)$/i.test(icon));
+	checkRelativeAssets = async (appPath, html, issues) => {
+		for (const asset of extractHtmlAssetPaths(html)) this.pushIssue(issues, await getMissingRelativeFileIssue(appPath, asset, "panel.asset.missing", "Panel asset file does not exist"));
+	};
+	readReferencedScripts = async (appPath, html, issues) => {
+		const scripts = [];
+		for (const src of extractScriptSrcs(html)) {
+			if (!isRelativeResource(src)) continue;
+			const scriptPath = resolveRelativeFile(appPath, src);
+			if (scriptPath && await fileExists(scriptPath)) scripts.push(await readFile(scriptPath, "utf8"));
+			else issues.push({
+				severity: "error",
+				code: "panel.script.missing",
+				message: `Panel script file does not exist: ${src}.`
+			});
+		}
+		return scripts;
+	};
+	checkBridgeUsage = (code, manifest, declaredActions, issues) => {
+		const capabilities = readStringArray(manifest.capabilities, "panel.capabilities");
+		this.checkRequiredCapability(code, "generateObject", "agent:generateObject", capabilities.values, issues);
+		this.checkRequiredCapability(code, "send", "agent:send", capabilities.values, issues);
+		this.checkServiceActionInvocations(code, declaredActions, issues);
+	};
+	checkRequiredCapability = (code, method, capability, declared, issues) => {
+		if (new RegExp(`nextclaw\\s*\\.\\s*agent\\s*\\.\\s*${method}\\b`).test(code) && !declared.includes(capability)) issues.push({
+			severity: "error",
+			code: "panel.capability.missing",
+			message: `Panel code calls window.nextclaw.agent.${method} but panel-app.json does not declare ${capability}.`,
+			fixHint: `Add "${capability}" to panel-app.json capabilities.`
+		});
+	};
+	checkServiceActionInvocations = (code, declaredActions, issues) => {
+		const literalActions = [...code.matchAll(/serviceActions\s*\.\s*invoke\s*\(\s*["']([^"']+)["']/g)].map((match) => match[1] ?? "");
+		if (literalActions.length === 0 && /serviceActions\s*\.\s*invoke\s*\(/.test(code)) issues.push({
+			severity: "warning",
+			code: "panel.action.dynamicInvoke",
+			message: "Panel code calls serviceActions.invoke with a dynamic action id.",
+			fixHint: "Make sure every possible action id is declared in panel-app.json actions."
+		});
+		for (const action of literalActions) if (!declaredActions.includes(action)) issues.push({
+			severity: "error",
+			code: "panel.action.missingDeclaration",
+			message: `Panel code invokes ${action} but panel-app.json actions does not declare it.`,
+			fixHint: `Add "${action}" to panel-app.json actions or update the invoke call.`
+		});
+	};
+	readCachedServiceManifest = async (workspaceRoot, serviceId, cache, issues) => {
+		if (cache.has(serviceId)) return cache.get(serviceId) ?? null;
+		const manifestPath = path.join(workspaceRoot, "service-apps", serviceId, SERVICE_MANIFEST_FILE);
+		if (!await fileExists(manifestPath)) {
+			issues.push({
+				severity: "error",
+				code: "panel.action.serviceMissing",
+				message: `Declared service app does not exist: ${serviceId}.`,
+				fixHint: `Create service-apps/${serviceId}/service-app.json or remove actions for ${serviceId}.`
+			});
+			cache.set(serviceId, null);
+			return null;
+		}
+		const manifestResult = await readJsonObject(manifestPath);
+		if (!manifestResult.value) {
+			if (manifestResult.issue) issues.push({
+				...manifestResult.issue,
+				code: `panel.action.${manifestResult.issue.code}`
+			});
+			cache.set(serviceId, null);
+			return null;
+		}
+		cache.set(serviceId, manifestResult.value);
+		return manifestResult.value;
+	};
+	pushIssue = (issues, issue) => {
+		if (issue) issues.push(issue);
+	};
+};
+//#endregion
+//#region src/cli/app/services/service-app-check.service.ts
+const execFileAsync = promisify(execFile);
+var ServiceAppCheckService = class {
+	check = async (appPath) => {
+		const issues = [];
+		const manifestResult = await readJsonObject(path.join(appPath, SERVICE_MANIFEST_FILE));
+		this.pushIssue(issues, manifestResult.issue);
+		if (!manifestResult.value) return issues;
+		const serviceId = this.checkManifestFields(appPath, manifestResult.value, issues);
+		const command = readOptionalString(manifestResult.value, "command");
+		const args = readStringArray(manifestResult.value.args, "service.args");
+		this.pushIssue(issues, args.issue);
+		this.checkActions(serviceId, manifestResult.value.actions, issues);
+		await this.checkCommand(appPath, command, args.values, issues);
+		return issues;
+	};
+	checkManifestFields = (appPath, manifest, issues) => {
+		const id = readRequiredString(manifest, "id", "service");
+		this.pushIssue(issues, id.issue);
+		if (id.value && (!KEBAB_ID_PATTERN.test(id.value) || id.value !== path.basename(appPath))) issues.push({
+			severity: "error",
+			code: "service.id.invalid",
+			message: `service-app.json id must be kebab-case and equal directory name: ${path.basename(appPath)}.`
+		});
+		this.pushIssue(issues, readRequiredString(manifest, "title", "service").issue);
+		this.pushIssue(issues, readRequiredString(manifest, "command", "service").issue);
+		if ((readOptionalString(manifest, "protocol") ?? "mcp") !== "mcp") issues.push({
+			severity: "error",
+			code: "service.protocol.invalid",
+			message: "Service App protocol must be mcp."
+		});
+		return id.value;
+	};
+	checkActions = (serviceId, value, issues) => {
+		if (!isRecord(value) || Object.keys(value).length === 0) {
+			issues.push({
+				severity: "error",
+				code: "service.actions.invalid",
+				message: "service-app.json actions must be a non-empty object."
+			});
+			return;
+		}
+		for (const [name, action] of Object.entries(value)) {
+			this.checkActionName(serviceId, name, issues);
+			this.checkActionManifest(name, action, issues);
+		}
+	};
+	checkActionName = (serviceId, name, issues) => {
+		if (!name.trim()) issues.push({
+			severity: "error",
+			code: "service.action.nameEmpty",
+			message: "Service App action name cannot be empty."
+		});
+		if (serviceId && name.startsWith(`${serviceId}.`)) issues.push({
+			severity: "error",
+			code: "service.action.nameContainsServiceId",
+			message: `Service App action key should not include the service id prefix: ${name}.`,
+			fixHint: `Use "${name.slice(serviceId.length + 1)}" as the action key; Panel App actions use "${name}".`
+		});
+	};
+	checkActionManifest = (name, action, issues) => {
+		if (!isRecord(action)) {
+			issues.push({
+				severity: "error",
+				code: "service.action.invalid",
+				message: `Service App action ${name} must be an object.`
+			});
+			return;
+		}
+		const risk = readOptionalString(action, "risk");
+		if (!risk || !VALID_SERVICE_ACTION_RISKS.has(risk)) issues.push({
+			severity: "error",
+			code: "service.action.riskInvalid",
+			message: `Service App action ${name} must declare risk: read, write, external, or dangerous.`
+		});
+		if (action.inputSchema !== void 0 && !isRecord(action.inputSchema)) issues.push({
+			severity: "error",
+			code: "service.action.inputSchemaInvalid",
+			message: `Service App action ${name} inputSchema must be an object.`
+		});
+	};
+	checkCommand = async (appPath, command, args, issues) => {
+		if (!command || !isNodeCommand(command)) return;
+		const script = args.find((arg) => !arg.startsWith("-"));
+		if (!script) {
+			issues.push({
+				severity: "error",
+				code: "service.command.scriptMissing",
+				message: "Node Service App command must point to a script file in args.",
+				fixHint: "Use args like [\"server.mjs\"]."
+			});
+			return;
+		}
+		const scriptPath = resolveRelativeFile(appPath, script);
+		if (!scriptPath || !await fileExists(scriptPath)) {
+			issues.push({
+				severity: "error",
+				code: "service.command.scriptNotFound",
+				message: `Service App script does not exist: ${script}.`
+			});
+			return;
+		}
+		await this.checkNodeSyntax(scriptPath, issues);
+	};
+	checkNodeSyntax = async (scriptPath, issues) => {
+		if (!/\.(?:cjs|js|mjs)$/i.test(scriptPath)) return;
+		try {
+			await execFileAsync(process.execPath, ["--check", scriptPath], { timeout: 5e3 });
+		} catch (error) {
+			issues.push({
+				severity: "error",
+				code: "service.command.syntaxInvalid",
+				message: `Service App script has a JavaScript syntax error: ${path.basename(scriptPath)}.`,
+				fixHint: this.readExecError(error)
+			});
+		}
+	};
+	readExecError = (error) => {
+		const stderr = isRecord(error) && typeof error.stderr === "string" ? error.stderr.trim() : "";
+		if (stderr) return stderr;
+		return error instanceof Error ? error.message : String(error);
+	};
+	pushIssue = (issues, issue) => {
+		if (issue) issues.push(issue);
+	};
+};
+//#endregion
+//#region src/cli/app/services/app-check.service.ts
+var AppCheckService = class {
+	constructor(panelAppCheckService = new PanelAppCheckService(), serviceAppCheckService = new ServiceAppCheckService()) {
+		this.panelAppCheckService = panelAppCheckService;
+		this.serviceAppCheckService = serviceAppCheckService;
+	}
+	check = async (target) => {
+		const appPath = path.resolve(target);
+		const issues = [];
+		const directoryIssue = await getTargetDirectoryIssue(appPath);
+		this.pushIssue(issues, directoryIssue);
+		if (directoryIssue) return this.buildReport(appPath, "unknown", issues);
+		const hasPanelManifest = await fileExists(path.join(appPath, PANEL_MANIFEST_FILE));
+		const hasServiceManifest = await fileExists(path.join(appPath, SERVICE_MANIFEST_FILE));
+		if (hasPanelManifest && hasServiceManifest) {
+			issues.push({
+				severity: "error",
+				code: "app.manifest.mixed",
+				message: "App directory contains both panel-app.json and service-app.json.",
+				fixHint: "Keep Panel App and Service App in separate directories."
+			});
+			return this.buildReport(appPath, "mixed", issues);
+		}
+		if (hasPanelManifest) {
+			issues.push(...await this.panelAppCheckService.check(appPath));
+			return this.buildReport(appPath, "panel", issues);
+		}
+		if (hasServiceManifest) {
+			issues.push(...await this.serviceAppCheckService.check(appPath));
+			return this.buildReport(appPath, "service", issues);
+		}
+		issues.push({
+			severity: "error",
+			code: "app.manifest.missing",
+			message: "App directory must contain panel-app.json or service-app.json.",
+			fixHint: "Run this command on a Panel App directory or a Service App directory."
+		});
+		return this.buildReport(appPath, "unknown", issues);
+	};
+	buildReport = (target, kind, issues) => ({
+		ok: !issues.some((issue) => issue.severity === "error"),
+		kind,
+		target,
+		issues
+	});
+	pushIssue = (issues, issue) => {
+		if (issue) issues.push(issue);
+	};
+};
+//#endregion
+//#region src/cli/app/controllers/app-check-command.controller.ts
+var AppCheckCommandController = class {
+	constructor(appCheckService = new AppCheckService()) {
+		this.appCheckService = appCheckService;
+	}
+	check = async (target, options) => {
+		const report = await this.appCheckService.check(target);
+		const output = options.json ? `${JSON.stringify(report, null, 2)}\n` : this.formatReport(report);
+		process.stdout.write(output);
+		if (!report.ok) process.exitCode = 1;
+	};
+	formatReport = (report) => {
+		const heading = report.ok ? `NextClaw app check passed: ${report.target}\n` : `NextClaw app check failed: ${report.target}\n`;
+		const errors = report.issues.filter((issue) => issue.severity === "error");
+		const warnings = report.issues.filter((issue) => issue.severity === "warning");
+		if (report.issues.length === 0) return `${heading}\nNo issues found.\n`;
+		return [
+			heading,
+			this.formatIssueSection("Errors", errors),
+			this.formatIssueSection("Warnings", warnings)
+		].filter(Boolean).join("\n");
+	};
+	formatIssueSection = (title, issues) => {
+		if (issues.length === 0) return "";
+		return `${title}:\n${issues.flatMap((issue) => [`- [${issue.code}] ${issue.message}`, issue.fixHint ? `  Fix: ${issue.fixHint}` : ""].filter(Boolean)).join("\n")}\n`;
+	};
+};
+//#endregion
+//#region src/cli/app/controllers/app-dev-command.controller.ts
+var AppDevCommandController = class {
+	constructor(serviceAppDevService = new ServiceAppDevService()) {
+		this.serviceAppDevService = serviceAppDevService;
+	}
+	dev = async (target, options) => {
+		const report = await this.serviceAppDevService.inspect(target);
+		process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : this.format(report));
+		if (!report.ok) process.exitCode = 1;
+	};
+	format = (report) => {
+		return [
+			report.ok ? `NextClaw service app dev passed: ${report.target}\n` : `NextClaw service app dev failed: ${report.target}\n`,
+			report.app ? [
+				`App: ${report.app.title} (${report.app.id})`,
+				`Status: ${report.app.status}`,
+				report.app.lastError ? `Last error: ${report.app.lastError}` : ""
+			].filter(Boolean).join("\n") : "",
+			report.actions.length ? `Actions:\n${report.actions.map((action) => `- ${action.id} [${action.runtimeState ?? "declared"}] risk=${action.risk}`).join("\n")}\n` : "Actions: none\n",
+			this.formatIssueSection("Errors", report.issues.filter((issue) => issue.severity === "error")),
+			this.formatIssueSection("Warnings", report.issues.filter((issue) => issue.severity === "warning"))
+		].filter(Boolean).join("\n");
+	};
+	formatIssueSection = (title, issues) => {
+		if (issues.length === 0) return "";
+		return `${title}:\n${issues.flatMap((issue) => [`- [${issue.code}] ${issue.message}`, issue.fixHint ? `  Fix: ${issue.fixHint}` : ""].filter(Boolean)).join("\n")}\n`;
+	};
+};
+//#endregion
+//#region src/cli/app/register-app-commands.ts
+function registerAppCommands(program) {
+	const app = program.command("app").description("Inspect and validate lightweight NextClaw apps");
+	const appCheck = new AppCheckCommandController();
+	const appDev = new AppDevCommandController();
+	const appCall = new AppCallCommandController();
+	app.command("check <app-dir>").description("Check a Panel App or Service App directory").option("--json", "Output JSON", false).action(async (target, opts) => appCheck.check(target, opts));
+	app.command("dev <service-app-dir>").description("Start a Service App through the real runtime and inspect its actions").option("--json", "Output JSON", false).action(async (target, opts) => appDev.dev(target, opts));
+	app.command("call <service-app-dir> <action-name>").description("Call a Service App action through the real runtime").option("--input <json>", "JSON object input for the action").option("--json", "Output JSON", false).action(async (target, actionName, opts) => appCall.call(target, actionName, opts));
+}
+//#endregion
 //#region src/cli/app/index.ts
 const LOGO = "🤖";
 const program = new Command();
@@ -3650,6 +4458,7 @@ program.command("agent").description("Interact with the agent directly").option(
 program.command("update").description(`Update the ${APP_NAME} runtime`).option("--check", "Only check for a runtime update", false).option("--download-only", "Download an available runtime update without applying it", false).option("--download", "Alias for --download-only").option("--apply", "Apply the downloaded runtime update", false).option("--channel <channel>", "Update channel (stable or beta)").option("--manifest-url <url>", "Explicit runtime update manifest URL").option("--json", "Output JSON", false).action(async (opts) => runtime.update(opts));
 registerSkillsCommands(program, runtime);
 registerAgentsCommands(program, runtime);
+registerAppCommands(program);
 const config = program.command("config").description("Manage config values");
 config.command("get <path>").description("Get a config value by dot path").option("--json", "Output JSON", false).action((path, opts) => runtime.commands.config.get(path, opts));
 config.command("set <path> <value>").description("Set a config value by dot path").option("--json", "Parse value as JSON", false).action((path, value, opts) => runtime.commands.config.set(path, value, opts));