@nextclaw/server 0.15.5 → 0.15.6

package/dist/index.js

@@ -1,15 +1,15 @@
 import { Hono } from "hono";
 import { compress } from "hono/compress";
 import { serve } from "@hono/node-server";
-import { AccessManager, PanelAppError, isPanelAppError, isPreferenceError, isServiceAppError } from "@nextclaw/kernel";
+import { AccessManager, PanelAppError, isPanelAppError, isPreferenceError, isProjectError, isServiceAppError, isSessionSettingsError } from "@nextclaw/kernel";
 import { WebSocket, WebSocketServer } from "ws";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { open, readFile, readdir, realpath, stat } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, join, parse, resolve } from "node:path";
+import { mkdir, open, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import * as NextclawCore from "@nextclaw/core";
-import { ConfigSchema, DEFAULT_WORKSPACE_PATH, buildConfigSchema, createAgentProfile, expandHome, findEffectiveAgentProfile, getDataDir, getPackageVersion, getProviderName, hasSecretRef, isSensitiveConfigPath, loadConfig, mergeExtensionConfigView, normalizeModelThinkingCapability, normalizeProviderModelConfig, parseThinkingLevel, probeFeishu, readAgentAvatarContent, removeAgentProfile, resolveEffectiveAgentProfiles, saveConfig, toExtensionConfigView, updateAgentProfile } from "@nextclaw/core";
-import { homedir } from "node:os";
+import { ConfigSchema, DEFAULT_WORKSPACE_PATH, buildConfigSchema, createAgentProfile, expandHome, findEffectiveAgentProfile, getDataDir, getPackageVersion, getProviderName, hasSecretRef, isSensitiveConfigPath, loadConfig, mergeExtensionConfigView, normalizeModelThinkingCapability, normalizeProviderModelConfig, probeFeishu, readAgentAvatarContent, removeAgentProfile, resolveEffectiveAgentProfiles, saveConfig, toExtensionConfigView, updateAgentProfile } from "@nextclaw/core";
+import { homedir, platform } from "node:os";
 import { findBuiltinProviderByName, listBuiltinProviders } from "@nextclaw/runtime";
 import { McpInstalledViewService } from "@nextclaw/mcp";
 import { serveStatic } from "hono/serve-static";
@@ -2495,22 +2495,23 @@ function buildScopedProviderModel(providerName, model, spec) {
 	if (!prefix) return trimmed;
 	return `${prefix}/${trimmed}`;
 }
-function stripProviderIdPrefix(providerId, model) {
+function rewriteProviderRoutePrefix(providerId, targetPrefix, model) {
 	const prefix = `${providerId}/`;
 	if (!model.startsWith(prefix)) return model;
-	return model.slice(prefix.length).trim() || model;
+	const stripped = model.slice(prefix.length).trim();
+	return stripped ? targetPrefix ? `${targetPrefix}/${stripped}` : stripped : model;
 }
 function resolveTestModel(config, providerId, requestedModel, provider, spec) {
-	if (requestedModel) return spec ? requestedModel.replace(`${providerId}/`, `${spec.name}/`) : stripProviderIdPrefix(providerId, requestedModel);
+	if (requestedModel) return rewriteProviderRoutePrefix(providerId, spec?.name ?? null, requestedModel);
 	const providerModels = normalizeModelList(provider.models ?? []).map((modelId) => {
-		const providerModel = stripProviderIdPrefix(providerId, modelId);
+		const providerModel = rewriteProviderRoutePrefix(providerId, null, modelId);
 		return spec ? buildScopedProviderModel(spec.name, providerModel, spec) : providerModel;
 	}).filter((modelId) => modelId.length > 0);
 	if (providerModels.length > 0) return providerModels[0];
 	const defaultModel = normalizeOptionalString(config.agents.defaults.model);
 	if (defaultModel) {
 		const routedProvider = getProviderName(config, defaultModel);
-		if (!routedProvider || routedProvider === providerId) return spec ? defaultModel.replace(`${providerId}/`, `${spec.name}/`) : stripProviderIdPrefix(providerId, defaultModel);
+		if (!routedProvider || routedProvider === providerId) return rewriteProviderRoutePrefix(providerId, spec?.name ?? null, defaultModel);
 	}
 	if (!spec) return null;
 	return normalizeModelList(spec?.defaultModels ?? [])[0] ?? null ?? defaultModel ?? null;
@@ -2930,67 +2931,6 @@ var NcpAssetRoutesController = class {
 		} });
 	};
 };
-//#endregion
-//#region src/features/sessions/utils/session-preference-patch.utils.ts
-function applySessionPreferencePatch(params) {
-	const nextMetadata = params.metadata;
-	const { patch } = params;
-	if (Object.prototype.hasOwnProperty.call(patch, "label")) {
-		const label = typeof patch.label === "string" ? patch.label.trim() : "";
-		if (label) nextMetadata.label = label;
-		else delete nextMetadata.label;
-	}
-	if (Object.prototype.hasOwnProperty.call(patch, "preferredModel")) {
-		const preferredModel = typeof patch.preferredModel === "string" ? patch.preferredModel.trim() : "";
-		if (preferredModel) {
-			nextMetadata.preferred_model = preferredModel;
-			nextMetadata.model = preferredModel;
-		} else {
-			delete nextMetadata.preferred_model;
-			delete nextMetadata.model;
-		}
-	}
-	if (Object.prototype.hasOwnProperty.call(patch, "preferredThinking")) {
-		const preferredThinking = typeof patch.preferredThinking === "string" ? patch.preferredThinking.trim() : "";
-		if (!preferredThinking) delete nextMetadata.preferred_thinking;
-		else {
-			const normalizedThinking = parseThinkingLevel(preferredThinking);
-			if (!normalizedThinking) throw params.createInvalidThinkingError("preferredThinking must be a supported thinking level");
-			nextMetadata.preferred_thinking = normalizedThinking;
-		}
-	}
-	return nextMetadata;
-}
-//#endregion
-//#region src/features/sessions/utils/session-project-root.utils.ts
-var SessionProjectRootValidationError = class extends Error {
-	constructor(code, message) {
-		super(message);
-		this.code = code;
-		this.name = "SessionProjectRootValidationError";
-	}
-};
-function resolveCandidateProjectRoot(value) {
-	return resolve(expandHome(value));
-}
-async function normalizeSessionProjectRoot(value) {
-	if (value == null) return null;
-	if (typeof value !== "string") throw new SessionProjectRootValidationError("PROJECT_ROOT_INVALID_TYPE", "projectRoot must be a string or null");
-	const trimmed = value.trim();
-	if (!trimmed) return null;
-	const candidate = resolveCandidateProjectRoot(trimmed);
-	let canonicalPath;
-	try {
-		canonicalPath = await realpath(candidate);
-	} catch {
-		throw new SessionProjectRootValidationError("PROJECT_ROOT_NOT_FOUND", "projectRoot directory does not exist");
-	}
-	if (!(await stat(canonicalPath)).isDirectory()) throw new SessionProjectRootValidationError("PROJECT_ROOT_NOT_DIRECTORY", "projectRoot must point to a directory");
-	return canonicalPath;
-}
-function isSessionProjectRootValidationError(error) {
-	return error instanceof SessionProjectRootValidationError;
-}
 const DEFAULT_MARKETPLACE_READ_API_BASES = ["https://api.nextclaw.net", "https://marketplace-api.nextclaw.io"];
 const MARKETPLACE_ZH_COPY_BY_SLUG = {
 	weather: {
@@ -3812,6 +3752,23 @@ var SessionSkillsViewBuilder = class {
 //#endregion
 //#region src/features/sessions/controllers/sessions.controller.ts
 const INTERRUPTED_SESSION_STATUS_TEXT = "Run interrupted: no completion or error event was recorded. Please send the message again.";
+function sessionProjectError(error) {
+	switch (error.code) {
+		case "PROJECT_PATH_INVALID_TYPE": return {
+			code: "PROJECT_ROOT_INVALID_TYPE",
+			message: "projectRoot must be a string or null"
+		};
+		case "PROJECT_PATH_NOT_FOUND": return {
+			code: "PROJECT_ROOT_NOT_FOUND",
+			message: "projectRoot directory does not exist"
+		};
+		case "PROJECT_PATH_NOT_DIRECTORY": return {
+			code: "PROJECT_ROOT_NOT_DIRECTORY",
+			message: "projectRoot must point to a directory"
+		};
+		default: return error;
+	}
+}
 function readPositiveInt(value) {
 	if (typeof value !== "string") return;
 	const parsed = Number.parseInt(value, 10);
@@ -3845,49 +3802,6 @@ function normalizeSessionActivityPreview(session) {
 		}
 	};
 }
-function applySessionTypePatch(metadata, patch) {
-	if (!Object.prototype.hasOwnProperty.call(patch, "sessionType")) return metadata;
-	const sessionType = typeof patch.sessionType === "string" ? patch.sessionType.trim() : "";
-	if (sessionType) {
-		const { sessionType: _removed, ...nextMetadata } = metadata;
-		return {
-			...nextMetadata,
-			session_type: sessionType,
-			runtime: sessionType
-		};
-	}
-	const { runtime: _runtime, session_type: _sessionType, sessionType: _camelSessionType, ...nextMetadata } = metadata;
-	return nextMetadata;
-}
-function applyUiReadAtPatch(metadata, patch) {
-	if (!Object.prototype.hasOwnProperty.call(patch, "uiReadAt")) return metadata;
-	const uiReadAt = typeof patch.uiReadAt === "string" ? patch.uiReadAt.trim() : "";
-	if (uiReadAt) return {
-		...metadata,
-		ui_last_read_at: uiReadAt
-	};
-	const { ui_last_read_at: _removed, ...nextMetadata } = metadata;
-	return nextMetadata;
-}
-function applyProjectRootPatch(metadata, projectRoot) {
-	if (projectRoot === void 0) return metadata;
-	if (projectRoot) {
-		const { projectRoot: _removed, ...nextMetadata } = metadata;
-		return {
-			...nextMetadata,
-			project_root: projectRoot
-		};
-	}
-	const { project_root: _projectRoot, projectRoot: _camelProjectRoot, ...nextMetadata } = metadata;
-	return nextMetadata;
-}
-function buildPatchedSessionMetadata(metadata, patch, projectRootPatch) {
-	return applyProjectRootPatch(applyUiReadAtPatch(applySessionTypePatch(applySessionPreferencePatch({
-		metadata: structuredClone(metadata),
-		patch,
-		createInvalidThinkingError: () => /* @__PURE__ */ new Error("PREFERRED_THINKING_INVALID")
-	}), patch), patch), projectRootPatch);
-}
 var NcpSessionRoutesController = class {
 	sessionSkillsViewBuilder;
 	constructor(options) {
@@ -3943,14 +3857,17 @@ var NcpSessionRoutesController = class {
 		const hasProjectRootOverride = Object.prototype.hasOwnProperty.call(query, "projectRoot");
 		const metadata = readSessionMetadata((await sessionManager.getSession(sessionId))?.metadata);
 		if (hasProjectRootOverride) try {
-			const projectRoot = await normalizeSessionProjectRoot(query.projectRoot);
+			const projectRoot = await this.options.kernel.projectManager.resolveExistingProjectRoot(query.projectRoot);
 			if (projectRoot) metadata.project_root = projectRoot;
 			else {
 				delete metadata.project_root;
 				delete metadata.projectRoot;
 			}
 		} catch (error) {
-			if (isSessionProjectRootValidationError(error)) return c.json(err(error.code, error.message), 400);
+			if (isProjectError(error)) {
+				const mapped = sessionProjectError(error);
+				return c.json(err(mapped.code, mapped.message), 400);
+			}
 			throw error;
 		}
 		return c.json(ok(this.sessionSkillsViewBuilder.build({
@@ -3965,19 +3882,17 @@ var NcpSessionRoutesController = class {
 		if (!body.ok || !body.data || typeof body.data !== "object") return c.json(err("INVALID_BODY", "invalid json body"), 400);
 		const patch = body.data;
 		if (patch.clearHistory) return c.json(err("UNSUPPORTED_PATCH", "clearHistory is not supported for ncp sessions"), 400);
-		let patched;
+		let updated;
 		try {
-			const projectRootPatch = Object.prototype.hasOwnProperty.call(patch, "projectRoot") ? await normalizeSessionProjectRoot(patch.projectRoot) : void 0;
-			const existing = await sessionManager.getSessionRecord(sessionId);
-			const metadata = buildPatchedSessionMetadata(readSessionMetadata(existing?.metadata), patch, projectRootPatch);
-			patched = existing ? await sessionManager.setSessionMetadata(sessionId, metadata) : Boolean(await sessionManager.updateSession(sessionId, { metadata }));
+			updated = await sessionManager.patchSessionSettings(sessionId, patch, { createIfMissing: true });
 		} catch (error) {
-			if (error instanceof Error && error.message === "PREFERRED_THINKING_INVALID") return c.json(err("PREFERRED_THINKING_INVALID", "preferredThinking must be a supported thinking level"), 400);
-			if (isSessionProjectRootValidationError(error)) return c.json(err(error.code, error.message), 400);
+			if (isSessionSettingsError(error)) return c.json(err(error.code, error.message), 400);
+			if (isProjectError(error)) {
+				const mapped = sessionProjectError(error);
+				return c.json(err(mapped.code, mapped.message), 400);
+			}
 			throw error;
 		}
-		if (!patched) return c.json(err("NOT_FOUND", `ncp session not found: ${sessionId}`), 404);
-		const updated = await sessionManager.getSession(sessionId);
 		if (!updated) return c.json(err("NOT_FOUND", `ncp session not found: ${sessionId}`), 404);
 		return c.json(ok(this.withRuntimeStatus(updated)));
 	};
@@ -4452,6 +4367,31 @@ var PreferencesRoutesController = class {
 	};
 };
 //#endregion
+//#region src/features/projects/controllers/projects.controller.ts
+var ProjectsRoutesController = class {
+	constructor(projectManager) {
+		this.projectManager = projectManager;
+	}
+	list = async (c) => {
+		const projects = await this.projectManager.listProjects();
+		return c.json(ok({
+			projects,
+			templates: this.projectManager.listTemplates(),
+			total: projects.length
+		}));
+	};
+	create = async (c) => {
+		const body = await readJson(c.req.raw);
+		if (!body.ok || !isRecord$2(body.data) || typeof body.data.name !== "string") return c.json(err("INVALID_PROJECT", "project name is required"), 400);
+		try {
+			return c.json(ok(await this.projectManager.createProject(body.data)), 201);
+		} catch (error) {
+			if (isProjectError(error)) return c.json(err(error.code, error.message), 400);
+			throw error;
+		}
+	};
+};
+//#endregion
 //#region src/features/service-apps/controllers/service-apps.controller.ts
 const PANEL_BRIDGE_SESSION_HEADER = "x-nextclaw-panel-bridge-session";
 function statusForServiceAppError(code) {
@@ -4652,6 +4592,100 @@ function createNcpSessionEventStreamResponse(eventBus, payload, signal) {
 	} });
 }
 //#endregion
+//#region src/features/server-path/utils/server-path-locations.utils.ts
+const xdgLocationKinds = {
+	XDG_DESKTOP_DIR: "desktop",
+	XDG_DOCUMENTS_DIR: "documents",
+	XDG_DOWNLOAD_DIR: "downloads"
+};
+function readAbsoluteEnvironmentPath(name) {
+	const value = process.env[name]?.trim();
+	return value && isAbsolute(value) ? resolve(value) : null;
+}
+function parseXdgLocationPath(value, homePath) {
+	const expanded = value.trim().replace(/^(['"])(.*)\1$/, "$2").replace(/^\$(?:HOME|\{HOME\})(?=\/|$)/, homePath);
+	const resolvedPath = isAbsolute(expanded) ? resolve(expanded) : null;
+	return resolvedPath && resolvedPath !== homePath ? resolvedPath : null;
+}
+async function readXdgLocationPaths(homePath) {
+	const configRoot = readAbsoluteEnvironmentPath("XDG_CONFIG_HOME") ?? join(homePath, ".config");
+	let content;
+	try {
+		content = await readFile(join(configRoot, "user-dirs.dirs"), "utf8");
+	} catch {
+		return {};
+	}
+	const locations = {};
+	for (const line of content.split(/\r?\n/)) {
+		const separatorIndex = line.indexOf("=");
+		if (separatorIndex < 1) continue;
+		const kind = xdgLocationKinds[line.slice(0, separatorIndex).trim()];
+		if (!kind) continue;
+		const path = parseXdgLocationPath(line.slice(separatorIndex + 1), homePath);
+		if (path) locations[kind] = path;
+	}
+	return locations;
+}
+async function resolveFirstDirectory(kind, candidatePaths) {
+	const uniquePaths = [...new Set(candidatePaths.filter((path) => Boolean(path)))];
+	for (const path of uniquePaths) try {
+		if ((await stat(path)).isDirectory()) return {
+			kind,
+			path
+		};
+	} catch {}
+	return null;
+}
+async function resolveServerPathLocations(homePath) {
+	const serverPlatform = platform();
+	const xdgLocations = serverPlatform === "linux" ? await readXdgLocationPaths(homePath) : {};
+	const oneDriveRoots = serverPlatform === "win32" ? [
+		"OneDrive",
+		"OneDriveConsumer",
+		"OneDriveCommercial"
+	].map(readAbsoluteEnvironmentPath).filter((path) => path !== null) : [];
+	const homeLocations = await Promise.all([
+		resolveFirstDirectory("desktop", [
+			xdgLocations.desktop,
+			...oneDriveRoots.map((path) => join(path, "Desktop")),
+			join(homePath, "Desktop")
+		]),
+		resolveFirstDirectory("documents", [
+			xdgLocations.documents,
+			...oneDriveRoots.map((path) => join(path, "Documents")),
+			join(homePath, "Documents")
+		]),
+		resolveFirstDirectory("downloads", [xdgLocations.downloads, join(homePath, "Downloads")])
+	]);
+	const macLocations = serverPlatform === "darwin" ? await Promise.all([
+		resolveFirstDirectory("icloud-drive", [join(homePath, "Library", "Mobile Documents", "com~apple~CloudDocs")]),
+		resolveFirstDirectory("applications", ["/Applications"]),
+		resolveFirstDirectory("volumes", ["/Volumes"])
+	]) : [];
+	return [...homeLocations, ...macLocations].filter((location) => location !== null);
+}
+//#endregion
+//#region src/features/server-path/utils/server-path-resolution.utils.ts
+var ServerPathResolutionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ServerPathResolutionError";
+	}
+};
+function resolveServerPath(params) {
+	const { path, basePath: rawBasePath, defaultToHome } = params;
+	const rawPath = typeof path === "string" ? path.trim() : "";
+	const basePath = typeof rawBasePath === "string" ? rawBasePath.trim() : "";
+	if (!rawPath) {
+		if (defaultToHome) return resolve(expandHome(basePath || homedir()));
+		throw new ServerPathResolutionError("server path is required");
+	}
+	const expandedPath = expandHome(rawPath);
+	if (isAbsolute(expandedPath)) return resolve(expandedPath);
+	if (!basePath) throw new ServerPathResolutionError("relative server path requires a base path");
+	return resolve(expandHome(basePath), expandedPath);
+}
+//#endregion
 //#region src/features/server-path/utils/server-path-browse.utils.ts
 var ServerPathBrowseError = class extends Error {
 	constructor(code, message) {
@@ -4660,15 +4694,16 @@ var ServerPathBrowseError = class extends Error {
 		this.name = "ServerPathBrowseError";
 	}
 };
-function normalizeBrowsePath(options) {
-	const { basePath, path } = options;
-	const rawPath = typeof path === "string" ? path.trim() : "";
-	const normalizedBasePath = typeof basePath === "string" ? basePath.trim() : "";
-	if (!rawPath) return resolve(expandHome(normalizedBasePath || homedir()));
-	const expandedPath = expandHome(rawPath);
-	if (expandedPath.startsWith("/")) return resolve(expandedPath);
-	if (!normalizedBasePath) throw new ServerPathBrowseError("SERVER_PATH_BASE_REQUIRED", "relative server path requires a base path");
-	return resolve(expandHome(normalizedBasePath), expandedPath);
+function resolveBrowsePath(options) {
+	try {
+		return resolveServerPath({
+			...options,
+			defaultToHome: true
+		});
+	} catch (error) {
+		if (error instanceof ServerPathResolutionError) throw new ServerPathBrowseError("SERVER_PATH_BASE_REQUIRED", error.message);
+		throw error;
+	}
 }
 function readRootLabel(rootPath) {
 	return rootPath.replace(/[\\/]+$/, "") || rootPath;
@@ -4714,7 +4749,7 @@ function sortEntryViews(left, right) {
 	return left.name.localeCompare(right.name);
 }
 async function browseServerPath(options = {}) {
-	const currentPath = normalizeBrowsePath(options);
+	const currentPath = resolveBrowsePath(options);
 	let currentPathStats;
 	try {
 		currentPathStats = await stat(currentPath);
@@ -4734,37 +4769,59 @@ async function browseServerPath(options = {}) {
 		includeFiles: options.includeFiles ?? false
 	})))).filter((entry) => entry !== null).sort(sortEntryViews);
 	const parentPath = dirname(currentPath);
+	const homePath = resolve(homedir());
 	return {
 		currentPath,
 		parentPath: parentPath === currentPath ? null : parentPath,
-		homePath: resolve(homedir()),
+		homePath,
 		breadcrumbs: buildBreadcrumbs(currentPath),
-		entries
+		entries,
+		locations: await resolveServerPathLocations(homePath)
 	};
 }
 function isServerPathBrowseError(error) {
 	return error instanceof ServerPathBrowseError;
 }
 //#endregion
-//#region src/features/server-path/utils/server-path-resolution.utils.ts
-var ServerPathResolutionError = class extends Error {
-	constructor(message) {
+//#region src/features/server-path/utils/server-path-directory.utils.ts
+var ServerPathDirectoryCreateError = class extends Error {
+	constructor(code, message) {
 		super(message);
-		this.name = "ServerPathResolutionError";
+		this.code = code;
+		this.name = "ServerPathDirectoryCreateError";
 	}
 };
-function resolveServerPath(params) {
-	const { path, basePath: rawBasePath, defaultToHome } = params;
-	const rawPath = typeof path === "string" ? path.trim() : "";
-	const basePath = typeof rawBasePath === "string" ? rawBasePath.trim() : "";
-	if (!rawPath) {
-		if (defaultToHome) return resolve(expandHome(basePath || homedir()));
-		throw new ServerPathResolutionError("server path is required");
+function normalizeDirectoryName(value) {
+	const name = typeof value === "string" ? value.trim() : "";
+	if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\")) throw new ServerPathDirectoryCreateError("SERVER_PATH_DIRECTORY_NAME_INVALID", "directory name is invalid");
+	return name;
+}
+function readFileErrorCode(error) {
+	return typeof error === "object" && error !== null && "code" in error ? String(error.code ?? "") : void 0;
+}
+async function createServerPathDirectory(input) {
+	let parentPath;
+	try {
+		parentPath = resolveServerPath({ path: typeof input.parentPath === "string" ? input.parentPath : null });
+	} catch (error) {
+		if (error instanceof ServerPathResolutionError) throw new ServerPathDirectoryCreateError("SERVER_PATH_PARENT_INVALID", error.message);
+		throw error;
+	}
+	const directoryPath = join(parentPath, normalizeDirectoryName(input.name));
+	try {
+		await mkdir(directoryPath);
+		return { path: directoryPath };
+	} catch (error) {
+		const code = readFileErrorCode(error);
+		if (code === "EEXIST") throw new ServerPathDirectoryCreateError("SERVER_PATH_DIRECTORY_EXISTS", "directory already exists");
+		if (code === "ENOENT") throw new ServerPathDirectoryCreateError("SERVER_PATH_PARENT_NOT_FOUND", "parent directory does not exist");
+		if (code === "ENOTDIR") throw new ServerPathDirectoryCreateError("SERVER_PATH_PARENT_NOT_DIRECTORY", "parent path must point to a directory");
+		if (code === "EACCES" || code === "EPERM" || code === "EROFS") throw new ServerPathDirectoryCreateError("SERVER_PATH_PARENT_NOT_WRITABLE", "parent directory is not writable");
+		throw error;
 	}
-	const expandedPath = expandHome(rawPath);
-	if (expandedPath.startsWith("/") || /^[a-z]:[\\/]/i.test(expandedPath)) return resolve(expandedPath);
-	if (!basePath) throw new ServerPathResolutionError("relative server path requires a base path");
-	return resolve(expandHome(basePath), expandedPath);
+}
+function isServerPathDirectoryCreateError(error) {
+	return error instanceof ServerPathDirectoryCreateError;
 }
 //#endregion
 //#region src/features/server-path/utils/server-path-read.utils.ts
@@ -5055,6 +5112,215 @@ function isServerPathContentError(error) {
 	return error instanceof ServerPathContentError;
 }
 //#endregion
+//#region src/features/server-path/utils/server-path-search.utils.ts
+function isServerPathInside(basePath, candidatePath) {
+	const relativePath = relative(basePath, candidatePath);
+	return relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+function normalizeServerPathRelativePath(value) {
+	return value.split(sep).join("/");
+}
+function resolveServerPathSearchScore(entry, query) {
+	if (!query) return 1;
+	const normalizedQuery = query.toLocaleLowerCase();
+	const normalizedName = entry.name.toLocaleLowerCase();
+	const normalizedPath = entry.relativePath.toLocaleLowerCase();
+	if (!normalizedQuery.split(/\s+/).filter(Boolean).every((term) => normalizedPath.includes(term))) return 0;
+	if (normalizedName === normalizedQuery) return 1e3;
+	if (normalizedName.startsWith(normalizedQuery)) return 850;
+	if (normalizedName.includes(normalizedQuery)) return 700;
+	if (normalizedPath.startsWith(normalizedQuery)) return 600;
+	if (normalizedPath.split("/").some((segment) => segment.startsWith(normalizedQuery))) return 550;
+	return 400 - Math.min(normalizedPath.length, 300);
+}
+//#endregion
+//#region src/features/server-path/services/server-path-search.service.ts
+const DEFAULT_RESULT_LIMIT = 50;
+const MAX_RESULT_LIMIT = 100;
+const MAX_SCANNED_ENTRIES = 2e4;
+const MAX_SEARCH_DEPTH = 24;
+const IGNORED_DIRECTORY_NAMES = new Set([
+	".git",
+	".cache",
+	".next",
+	".nuxt",
+	".output",
+	".parcel-cache",
+	".turbo",
+	".vite",
+	"build",
+	"coverage",
+	"dist",
+	"node_modules",
+	"out",
+	"target",
+	"ui-dist",
+	"vendor"
+]);
+var ServerPathSearchError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ServerPathSearchError";
+	}
+};
+var ServerPathSearchService = class {
+	search = async (options) => {
+		const basePath = await this.resolveBasePath(options.basePath);
+		const query = options.query?.trim() ?? "";
+		const limit = Math.min(Math.max(options.limit ?? DEFAULT_RESULT_LIMIT, 1), MAX_RESULT_LIMIT);
+		const { candidates, scanLimitReached } = await this.scanCandidates({
+			basePath,
+			query
+		});
+		candidates.sort((left, right) => {
+			if (right.score !== left.score) return right.score - left.score;
+			if (left.entry.kind !== right.entry.kind) return left.entry.kind === "directory" ? -1 : 1;
+			return left.entry.relativePath.localeCompare(right.entry.relativePath, void 0, {
+				numeric: true,
+				sensitivity: "base"
+			});
+		});
+		return {
+			basePath,
+			query,
+			entries: candidates.slice(0, limit).map(({ entry }) => entry),
+			truncated: scanLimitReached || candidates.length > limit
+		};
+	};
+	scanCandidates = async (params) => {
+		const { basePath, query } = params;
+		const queue = [{
+			absolutePath: basePath,
+			depth: 0
+		}];
+		const candidates = [];
+		let scannedEntries = 0;
+		let scanLimitReached = false;
+		while (queue.length > 0 && !scanLimitReached) {
+			const current = queue.shift();
+			if (!current) break;
+			const scan = await this.scanDirectory({
+				basePath,
+				directory: current,
+				query,
+				remainingEntries: MAX_SCANNED_ENTRIES - scannedEntries
+			});
+			scannedEntries += scan.scannedEntries;
+			candidates.push(...scan.candidates);
+			queue.push(...scan.directories);
+			scanLimitReached = scan.limitReached;
+			if (!query) break;
+		}
+		return {
+			candidates,
+			scanLimitReached
+		};
+	};
+	scanDirectory = async (params) => {
+		const { basePath, directory, query, remainingEntries } = params;
+		const entries = await this.readDirectory({
+			path: directory.absolutePath,
+			required: directory.depth === 0
+		});
+		const candidates = [];
+		const directories = [];
+		let scannedEntries = 0;
+		for (const dirent of entries) {
+			if (scannedEntries >= remainingEntries) return {
+				candidates,
+				directories,
+				limitReached: true,
+				scannedEntries
+			};
+			scannedEntries += 1;
+			const result = await this.resolveEntry({
+				basePath,
+				directory,
+				dirent
+			});
+			if (!result) continue;
+			const score = resolveServerPathSearchScore(result.entry, query);
+			if (score > 0) candidates.push({
+				entry: result.entry,
+				score
+			});
+			if (query && result.canTraverse && directory.depth < MAX_SEARCH_DEPTH && !IGNORED_DIRECTORY_NAMES.has(dirent.name)) directories.push({
+				absolutePath: result.entry.path,
+				depth: directory.depth + 1
+			});
+		}
+		return {
+			candidates,
+			directories,
+			limitReached: false,
+			scannedEntries
+		};
+	};
+	resolveBasePath = async (value) => {
+		let resolvedPath;
+		try {
+			resolvedPath = resolveServerPath({ path: value });
+		} catch (error) {
+			if (error instanceof ServerPathResolutionError) throw new ServerPathSearchError("SERVER_PATH_BASE_REQUIRED", error.message);
+			throw error;
+		}
+		let stats;
+		try {
+			stats = await stat(resolvedPath);
+		} catch {
+			throw new ServerPathSearchError("SERVER_PATH_NOT_FOUND", "server path does not exist");
+		}
+		if (!stats.isDirectory()) throw new ServerPathSearchError("SERVER_PATH_NOT_DIRECTORY", "server path must point to a directory");
+		return await realpath(resolvedPath);
+	};
+	readDirectory = async (params) => {
+		try {
+			return (await readdir(params.path, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name, void 0, {
+				numeric: true,
+				sensitivity: "base"
+			}));
+		} catch {
+			if (!params.required) return [];
+			throw new ServerPathSearchError("SERVER_PATH_NOT_READABLE", "server path is not readable");
+		}
+	};
+	resolveEntry = async (params) => {
+		const { basePath, directory, dirent } = params;
+		const entryPath = resolve(directory.absolutePath, dirent.name);
+		let kind = dirent.isDirectory() ? "directory" : dirent.isFile() ? "file" : null;
+		let canTraverse = kind === "directory";
+		if (dirent.isSymbolicLink()) {
+			let targetPath;
+			try {
+				targetPath = await realpath(entryPath);
+			} catch {
+				return null;
+			}
+			if (!isServerPathInside(basePath, targetPath)) return null;
+			const targetStats = await stat(targetPath).catch(() => null);
+			kind = targetStats?.isDirectory() ? "directory" : targetStats?.isFile() ? "file" : null;
+			canTraverse = false;
+		}
+		if (!kind) return null;
+		const relativePath = normalizeServerPathRelativePath(relative(basePath, entryPath));
+		return {
+			entry: {
+				name: basename(entryPath),
+				path: entryPath,
+				relativePath,
+				parentRelativePath: normalizeServerPathRelativePath(dirname(relativePath)) === "." ? "" : normalizeServerPathRelativePath(dirname(relativePath)),
+				kind,
+				hidden: dirent.name.startsWith(".")
+			},
+			canTraverse
+		};
+	};
+};
+function isServerPathSearchError(error) {
+	return error instanceof ServerPathSearchError;
+}
+//#endregion
 //#region src/features/server-path/controllers/server-path.controller.ts
 function readIncludeFilesFlag(value) {
 	return value === "1" || value === "true";
@@ -5070,6 +5336,7 @@ function statusForServerPathContentError(code) {
 	return code === "SERVER_PATH_NOT_FOUND" ? 404 : 400;
 }
 var ServerPathRoutesController = class {
+	searchService = new ServerPathSearchService();
 	browse = async (c) => {
 		try {
 			const payload = await browseServerPath({
@@ -5083,6 +5350,32 @@ var ServerPathRoutesController = class {
 			throw error;
 		}
 	};
+	search = async (c) => {
+		try {
+			const payload = await this.searchService.search({
+				basePath: c.req.query("basePath"),
+				query: c.req.query("query"),
+				limit: readPositiveInteger(c.req.query("limit"))
+			});
+			return c.json(ok(payload));
+		} catch (error) {
+			if (isServerPathSearchError(error)) return c.json(err(error.code, error.message), 400);
+			throw error;
+		}
+	};
+	createDirectory = async (c) => {
+		const body = await readJson(c.req.raw);
+		if (!body.ok || !isRecord$2(body.data)) return c.json(err("INVALID_SERVER_PATH_DIRECTORY", "directory input is required"), 400);
+		try {
+			return c.json(ok(await createServerPathDirectory({
+				parentPath: body.data.parentPath,
+				name: body.data.name
+			})), 201);
+		} catch (error) {
+			if (isServerPathDirectoryCreateError(error)) return c.json(err(error.code, error.message), 400);
+			throw error;
+		}
+	};
 	read = async (c) => {
 		try {
 			const payload = await readServerPath({
@@ -5131,6 +5424,7 @@ function createUiRouteControllers(options, authService, marketplaceBaseUrls) {
 		ncpAsset: new NcpAssetRoutesController(options),
 		panelApps: new PanelAppsRoutesController(kernel.panelAppManager, { panelAppClientSdkScript }),
 		preferences: new PreferencesRoutesController(kernel.preferenceManager),
+		projects: new ProjectsRoutesController(kernel.projectManager),
 		serviceApps: new ServiceAppsRoutesController({
 			panelAppManager: kernel.panelAppManager,
 			serviceAppManager: kernel.serviceAppManager
@@ -5218,7 +5512,7 @@ var UiRouteRegistry = class {
 		]]);
 	};
 	mountResourceRoutes = () => {
-		const { ncpSession, panelApps, preferences, serviceApps, serverPath } = this.controllers;
+		const { ncpSession, panelApps, preferences, projects, serviceApps, serverPath } = this.controllers;
 		this.mountRoutes([
 			[
 				"get",
@@ -5325,6 +5619,16 @@ var UiRouteRegistry = class {
 				"/api/preferences/:key",
 				preferences.delete
 			],
+			[
+				"get",
+				"/api/projects",
+				projects.list
+			],
+			[
+				"post",
+				"/api/projects",
+				projects.create
+			],
 			[
 				"delete",
 				"/api/panel-apps/:id",
@@ -5415,6 +5719,16 @@ var UiRouteRegistry = class {
 				"/api/server-paths/browse",
 				serverPath.browse
 			],
+			[
+				"get",
+				"/api/server-paths/search",
+				serverPath.search
+			],
+			[
+				"post",
+				"/api/server-paths/directory",
+				serverPath.createDirectory
+			],
 			[
 				"get",
 				"/api/server-paths/read",