@nextclaw/service 0.1.1

package/dist/shared/utils/config-path.js

@@ -0,0 +1,167 @@
+//#region src/shared/utils/config-path.ts
+function isIndexSegment(raw) {
+	return /^[0-9]+$/.test(raw);
+}
+function parseConfigPath(raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) return [];
+	const parts = [];
+	let current = "";
+	let i = 0;
+	while (i < trimmed.length) {
+		const ch = trimmed[i];
+		if (ch === "\\") {
+			const next = trimmed[i + 1];
+			if (next) current += next;
+			i += 2;
+			continue;
+		}
+		if (ch === ".") {
+			if (current) parts.push(current);
+			current = "";
+			i += 1;
+			continue;
+		}
+		if (ch === "[") {
+			if (current) parts.push(current);
+			current = "";
+			const close = trimmed.indexOf("]", i);
+			if (close === -1) throw new Error(`Invalid path (missing "]"): ${raw}`);
+			const inside = trimmed.slice(i + 1, close).trim();
+			if (!inside) throw new Error(`Invalid path (empty "[]"): ${raw}`);
+			parts.push(inside);
+			i = close + 1;
+			continue;
+		}
+		current += ch;
+		i += 1;
+	}
+	if (current) parts.push(current);
+	return parts.map((part) => part.trim()).filter(Boolean);
+}
+function parseRequiredConfigPath(raw) {
+	const parsedPath = parseConfigPath(raw);
+	if (parsedPath.length === 0) throw new Error("Path is empty.");
+	return parsedPath;
+}
+function parseConfigSetValue(raw, opts) {
+	const trimmed = raw.trim();
+	if (opts.json) return JSON.parse(trimmed);
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return raw;
+	}
+}
+function getAtConfigPath(root, pathSegments) {
+	let current = root;
+	for (const segment of pathSegments) {
+		if (!current || typeof current !== "object") return { found: false };
+		if (Array.isArray(current)) {
+			if (!isIndexSegment(segment)) return { found: false };
+			const index = Number.parseInt(segment, 10);
+			if (!Number.isFinite(index) || index < 0 || index >= current.length) return { found: false };
+			current = current[index];
+			continue;
+		}
+		const record = current;
+		if (!Object.prototype.hasOwnProperty.call(record, segment)) return { found: false };
+		current = record[segment];
+	}
+	return {
+		found: true,
+		value: current
+	};
+}
+function setAtConfigPath(root, pathSegments, value) {
+	let current = root;
+	for (let i = 0; i < pathSegments.length - 1; i += 1) {
+		const segment = pathSegments[i];
+		const next = pathSegments[i + 1];
+		const nextIsIndex = Boolean(next && isIndexSegment(next));
+		if (Array.isArray(current)) {
+			current = getOrCreateArraySegment(current, segment, nextIsIndex, pathSegments.slice(0, i));
+			continue;
+		}
+		current = getOrCreateObjectSegment(current, segment, nextIsIndex);
+	}
+	setConfigPathValue(current, pathSegments[pathSegments.length - 1], value, pathSegments.slice(0, -1));
+}
+function ensureWritableArrayIndex(current, index, parentPath) {
+	if (!Number.isFinite(index) || index < 0) throw new Error(`Invalid array index "${index}"`);
+	if (index <= current.length) return;
+	const parentPathExpr = formatConfigPath(parentPath);
+	const parentLabel = parentPathExpr ? `"${parentPathExpr}"` : "the root array";
+	throw new Error(`Cannot set sparse array index ${index} under ${parentLabel}. Set indices in order.`);
+}
+function getOrCreateArraySegment(current, segment, nextIsIndex, parentPath) {
+	const index = parseArrayIndexSegment(segment);
+	ensureWritableArrayIndex(current, index, parentPath);
+	const existing = current[index];
+	if (!existing || typeof existing !== "object") current[index] = nextIsIndex ? [] : {};
+	return current[index];
+}
+function getOrCreateObjectSegment(current, segment, nextIsIndex) {
+	if (!current || typeof current !== "object") throw new Error(`Cannot traverse into "${segment}" (not an object)`);
+	const record = current;
+	const existing = record[segment];
+	if (!existing || typeof existing !== "object") record[segment] = nextIsIndex ? [] : {};
+	return record[segment];
+}
+function setConfigPathValue(current, last, value, parentPath) {
+	if (Array.isArray(current)) {
+		const index = parseArrayIndexSegment(last);
+		ensureWritableArrayIndex(current, index, parentPath);
+		current[index] = value;
+		return;
+	}
+	if (!current || typeof current !== "object") throw new Error(`Cannot set "${last}" (parent is not an object)`);
+	current[last] = value;
+}
+function parseArrayIndexSegment(segment) {
+	if (!isIndexSegment(segment)) throw new Error(`Expected numeric index for array segment "${segment}"`);
+	return Number.parseInt(segment, 10);
+}
+function formatConfigPath(pathSegments) {
+	let expr = "";
+	for (const segment of pathSegments) {
+		if (isIndexSegment(segment)) {
+			expr += `[${segment}]`;
+			continue;
+		}
+		expr += expr ? `.${segment}` : segment;
+	}
+	return expr;
+}
+function unsetAtConfigPath(root, pathSegments) {
+	let current = root;
+	for (let i = 0; i < pathSegments.length - 1; i += 1) {
+		const segment = pathSegments[i];
+		if (!current || typeof current !== "object") return false;
+		if (Array.isArray(current)) {
+			if (!isIndexSegment(segment)) return false;
+			const index = Number.parseInt(segment, 10);
+			if (!Number.isFinite(index) || index < 0 || index >= current.length) return false;
+			current = current[index];
+			continue;
+		}
+		const record = current;
+		if (!Object.prototype.hasOwnProperty.call(record, segment)) return false;
+		current = record[segment];
+	}
+	const last = pathSegments[pathSegments.length - 1];
+	if (Array.isArray(current)) {
+		if (!isIndexSegment(last)) return false;
+		const index = Number.parseInt(last, 10);
+		if (!Number.isFinite(index) || index < 0 || index >= current.length) return false;
+		current.splice(index, 1);
+		return true;
+	}
+	if (!current || typeof current !== "object") return false;
+	const record = current;
+	if (!Object.prototype.hasOwnProperty.call(record, last)) return false;
+	delete record[last];
+	return true;
+}
+//#endregion
+export { getAtConfigPath, isIndexSegment, parseConfigPath, parseConfigSetValue, parseRequiredConfigPath, setAtConfigPath, unsetAtConfigPath };

package/dist/shared/utils/marketplace/cli-subcommand-launch.utils.d.ts

@@ -0,0 +1,16 @@
+//#region src/shared/utils/marketplace/cli-subcommand-launch.utils.d.ts
+declare const resolveCliSubcommandEntry: (params: {
+  argvEntry?: string;
+  importMetaUrl: string;
+}) => string;
+declare const resolveCliSubcommandLaunch: (params: {
+  argvEntry?: string;
+  importMetaUrl: string;
+  cliArgs: string[];
+  nodePath?: string;
+}) => {
+  command: string;
+  args: string[];
+};
+//#endregion
+export { resolveCliSubcommandEntry, resolveCliSubcommandLaunch };

package/dist/shared/utils/marketplace/cli-subcommand-launch.utils.js

@@ -0,0 +1,46 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { extname, resolve } from "node:path";
+//#region src/shared/utils/marketplace/cli-subcommand-launch.utils.ts
+const require = createRequire(import.meta.url);
+const TYPESCRIPT_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts"
+]);
+const isTypeScriptEntry = (entry) => TYPESCRIPT_EXTENSIONS.has(extname(entry).toLowerCase());
+const resolveTsxCliEntry = () => require.resolve("tsx/cli");
+const resolveCliAppEntryFromImportMeta = (importMetaUrl) => {
+	const modulePath = fileURLToPath(importMetaUrl);
+	const cliRootIndex = modulePath.replace(/\\/g, "/").lastIndexOf("/cli/");
+	if (cliRootIndex === -1) return fileURLToPath(new URL("../../../app/index.js", importMetaUrl));
+	const extension = extname(modulePath) || ".js";
+	return resolve(modulePath.slice(0, cliRootIndex + 5), "app", `index${extension}`);
+};
+const resolveCliSubcommandEntry = (params) => {
+	const argvEntry = params.argvEntry?.trim();
+	if (argvEntry) return resolve(argvEntry);
+	return resolveCliAppEntryFromImportMeta(params.importMetaUrl);
+};
+const resolveCliSubcommandLaunch = (params) => {
+	const cliEntry = resolveCliSubcommandEntry({
+		argvEntry: params.argvEntry,
+		importMetaUrl: params.importMetaUrl
+	});
+	const command = params.nodePath?.trim() || process.execPath;
+	if (isTypeScriptEntry(cliEntry)) return {
+		command,
+		args: [
+			resolveTsxCliEntry(),
+			cliEntry,
+			...params.cliArgs
+		]
+	};
+	return {
+		command,
+		args: [cliEntry, ...params.cliArgs]
+	};
+};
+//#endregion
+export { resolveCliSubcommandEntry, resolveCliSubcommandLaunch };

package/dist/shared/utils/marketplace/service-marketplace-helpers.utils.d.ts

@@ -0,0 +1,9 @@
+//#region src/shared/utils/marketplace/service-marketplace-helpers.utils.d.ts
+declare const pickUserFacingCommandSummary: (output: string, fallback: string) => string;
+declare const buildMarketplaceSkillInstallArgs: (params: {
+  slug: string;
+  workspace: string;
+  force?: boolean;
+}) => string[];
+//#endregion
+export { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary };

package/dist/shared/utils/marketplace/service-marketplace-helpers.utils.js

@@ -0,0 +1,33 @@
+//#region src/shared/utils/marketplace/service-marketplace-helpers.utils.ts
+const containsAbsoluteFsPath = (line) => {
+	const normalized = line.trim();
+	if (!normalized) return false;
+	const lowered = normalized.toLowerCase();
+	if (lowered.includes("http://") || lowered.includes("https://")) return false;
+	if (/^[A-Za-z]:\\/.test(normalized)) return true;
+	return /(?:^|\s)(?:~\/|\/[^\s]+)/.test(normalized);
+};
+const pickUserFacingCommandSummary = (output, fallback) => {
+	const lines = output.split("\n").map((line) => line.trim()).filter(Boolean);
+	if (lines.length === 0) return fallback;
+	const visibleLines = lines.filter((line) => {
+		if (/^(path|install path|source path|destination|location)\s*:/i.test(line)) return false;
+		if (containsAbsoluteFsPath(line)) return false;
+		return true;
+	});
+	if (visibleLines.length === 0) return fallback;
+	return [...visibleLines].reverse().find((line) => /\b(installed|enabled|disabled|uninstalled|published|updated|already installed|removed)\b/i.test(line)) ?? visibleLines[visibleLines.length - 1] ?? fallback;
+};
+const buildMarketplaceSkillInstallArgs = (params) => {
+	const args = [
+		"skills",
+		"install",
+		params.slug,
+		"--workdir",
+		params.workspace
+	];
+	if (params.force) args.push("--force");
+	return args;
+};
+//#endregion
+export { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary };

package/dist/shared/utils/package/package-manifest.utils.d.ts

@@ -0,0 +1,8 @@
+//#region src/shared/utils/package/package-manifest.utils.d.ts
+declare function findNearestPackageManifest(startDir: string, expectedName?: string): {
+  rootDir: string;
+  version?: string;
+} | null;
+declare function getPackageVersion(importMetaUrl?: string): string;
+//#endregion
+export { findNearestPackageManifest, getPackageVersion };

package/dist/shared/utils/package/package-manifest.utils.js

@@ -0,0 +1,48 @@
+import { fileURLToPath } from "node:url";
+import { join, resolve } from "node:path";
+import { getPackageVersion as getPackageVersion$1 } from "@nextclaw/core";
+import { readFileSync } from "node:fs";
+//#region src/shared/utils/package/package-manifest.utils.ts
+function readPackageManifest(pkgPath) {
+	try {
+		const raw = readFileSync(pkgPath, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+function findNearestPackageManifest(startDir, expectedName) {
+	let current = resolve(startDir);
+	while (current.length > 0) {
+		const parsed = readPackageManifest(join(current, "package.json"));
+		if (parsed && (!expectedName || parsed.name === expectedName)) return {
+			rootDir: current,
+			version: typeof parsed.version === "string" ? parsed.version : void 0
+		};
+		const parent = resolve(current, "..");
+		if (parent === current) break;
+		current = parent;
+	}
+	return null;
+}
+function findWorkspacePackageManifest(startDir, packageName) {
+	let current = resolve(startDir);
+	while (current.length > 0) {
+		const rootDir = join(current, "packages", packageName);
+		const parsed = readPackageManifest(join(rootDir, "package.json"));
+		if (parsed?.name === packageName) return {
+			rootDir,
+			version: typeof parsed.version === "string" ? parsed.version : void 0
+		};
+		const parent = resolve(current, "..");
+		if (parent === current) break;
+		current = parent;
+	}
+	return null;
+}
+function getPackageVersion(importMetaUrl = import.meta.url) {
+	const cliDir = resolve(fileURLToPath(new URL(".", importMetaUrl)));
+	return findNearestPackageManifest(cliDir, "nextclaw")?.version ?? findWorkspacePackageManifest(cliDir, "nextclaw")?.version ?? findNearestPackageManifest(cliDir)?.version ?? getPackageVersion$1();
+}
+//#endregion
+export { findNearestPackageManifest, getPackageVersion };

package/dist/shared/utils/runtime-helpers.d.ts

@@ -0,0 +1,14 @@
+import { Config } from "@nextclaw/core";
+
+//#region src/shared/utils/runtime-helpers.d.ts
+declare function resolveSkillsInstallWorkdir(params: {
+  explicitWorkdir?: string;
+  configuredWorkspace?: string;
+}): string;
+declare function parseStartTimeoutMs(value: string | number | undefined): number | undefined;
+declare function resolveManagedServiceUiOverrides(params: {
+  uiPort: string | number | undefined;
+  forcedPublicHost: string;
+}): Partial<Config["ui"]>;
+//#endregion
+export { parseStartTimeoutMs, resolveManagedServiceUiOverrides, resolveSkillsInstallWorkdir };

package/dist/shared/utils/runtime-helpers.js

@@ -0,0 +1,26 @@
+import { expandHome, getWorkspacePath } from "@nextclaw/core";
+//#region src/shared/utils/runtime-helpers.ts
+function resolveSkillsInstallWorkdir(params) {
+	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
+	return getWorkspacePath(params.configuredWorkspace);
+}
+function parseStartTimeoutMs(value) {
+	if (value === void 0) return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
+		process.exit(1);
+	}
+	return Math.floor(parsed);
+}
+function resolveManagedServiceUiOverrides(params) {
+	const uiOverrides = {
+		enabled: true,
+		host: params.forcedPublicHost,
+		open: false
+	};
+	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
+	return uiOverrides;
+}
+//#endregion
+export { parseStartTimeoutMs, resolveManagedServiceUiOverrides, resolveSkillsInstallWorkdir };

package/dist/shared/utils/service-port-probe.utils.d.ts

@@ -0,0 +1,41 @@
+import { Config } from "@nextclaw/core";
+
+//#region src/shared/utils/service-port-probe.utils.d.ts
+declare function checkPortAvailability(params: {
+  host: string;
+  port: number;
+}): Promise<{
+  available: boolean;
+  detail: string;
+}>;
+declare function probeHealthEndpoint(healthUrl: string): Promise<{
+  healthy: boolean;
+  error: string | null;
+}>;
+type UiTargetProbeResult = {
+  state: "available";
+  availabilityDetail: string;
+  probeError: null;
+} | {
+  state: "healthy-existing";
+  availabilityDetail: string;
+  probeError: null;
+} | {
+  state: "occupied-unhealthy";
+  availabilityDetail: string;
+  probeError: string | null;
+};
+declare function inspectUiTarget(params: {
+  host: string;
+  port: number;
+  healthUrl: string;
+  checkPortAvailabilityFn?: typeof checkPortAvailability;
+  probeHealthEndpointFn?: typeof probeHealthEndpoint;
+}): Promise<UiTargetProbeResult>;
+declare function describeUnmanagedHealthyTargetMessage(params: {
+  uiOverrides: Partial<Config["ui"]>;
+  checkPortAvailabilityFn?: typeof checkPortAvailability;
+  probeHealthEndpointFn?: typeof probeHealthEndpoint;
+}): Promise<string | null>;
+//#endregion
+export { UiTargetProbeResult, checkPortAvailability, describeUnmanagedHealthyTargetMessage, inspectUiTarget, probeHealthEndpoint };

package/dist/shared/utils/service-port-probe.utils.js

@@ -0,0 +1,164 @@
+import { resolveUiApiBase, resolveUiConfig } from "./cli.utils.js";
+import { managedServiceStateStore } from "../stores/managed-service-state.store.js";
+import { APP_NAME, loadConfig } from "@nextclaw/core";
+import { createServer } from "node:net";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+//#region src/shared/utils/service-port-probe.utils.ts
+function getHeaderValue(headers, key) {
+	const value = headers[key];
+	if (typeof value === "string") {
+		const normalized = value.trim();
+		return normalized.length > 0 ? normalized : null;
+	}
+	if (Array.isArray(value)) {
+		const joined = value.map((item) => item.trim()).filter(Boolean).join(", ");
+		return joined.length > 0 ? joined : null;
+	}
+	return null;
+}
+function formatProbeBodySnippet(raw, maxLength = 180) {
+	const normalized = raw.replace(/\s+/g, " ").trim();
+	if (!normalized) return null;
+	const clipped = normalized.length > maxLength ? `${normalized.slice(0, maxLength)}...` : normalized;
+	return JSON.stringify(clipped);
+}
+async function checkPortAvailability(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}`
+				});
+			});
+		});
+	});
+}
+async function probeHealthEndpoint(healthUrl) {
+	let parsed;
+	try {
+		parsed = new URL(healthUrl);
+	} catch {
+		return {
+			healthy: false,
+			error: "invalid health URL"
+		};
+	}
+	const requestImpl = parsed.protocol === "https:" ? request$1 : request;
+	return await new Promise((resolve) => {
+		const req = requestImpl({
+			protocol: parsed.protocol,
+			hostname: parsed.hostname,
+			port: parsed.port ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80,
+			method: "GET",
+			path: `${parsed.pathname}${parsed.search}`,
+			timeout: 1e3,
+			headers: { Accept: "application/json" }
+		}, (res) => {
+			const chunks = [];
+			res.on("data", (chunk) => {
+				if (typeof chunk === "string") {
+					chunks.push(Buffer.from(chunk));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			res.on("end", () => {
+				const responseText = Buffer.concat(chunks).toString("utf-8");
+				if ((res.statusCode ?? 0) < 200 || (res.statusCode ?? 0) >= 300) {
+					const serverHeader = getHeaderValue(res.headers, "server");
+					const contentType = getHeaderValue(res.headers, "content-type");
+					const bodySnippet = formatProbeBodySnippet(responseText);
+					const details = [`http ${res.statusCode ?? "unknown"}`];
+					if (serverHeader) details.push(`server=${serverHeader}`);
+					if (contentType) details.push(`content-type=${contentType}`);
+					if (bodySnippet) details.push(`body=${bodySnippet}`);
+					resolve({
+						healthy: false,
+						error: details.join("; ")
+					});
+					return;
+				}
+				try {
+					const payload = JSON.parse(responseText);
+					if (!(payload?.ok === true && payload?.data?.status === "ok")) {
+						resolve({
+							healthy: false,
+							error: "health payload not ok"
+						});
+						return;
+					}
+					resolve({
+						healthy: true,
+						error: null
+					});
+				} catch {
+					resolve({
+						healthy: false,
+						error: "invalid health JSON response"
+					});
+				}
+			});
+		});
+		req.on("timeout", () => {
+			req.destroy(/* @__PURE__ */ new Error("probe timeout"));
+		});
+		req.on("error", (error) => {
+			resolve({
+				healthy: false,
+				error: error.message || String(error)
+			});
+		});
+		req.end();
+	});
+}
+async function inspectUiTarget(params) {
+	const { checkPortAvailabilityFn, healthUrl, host, port, probeHealthEndpointFn } = params;
+	const availability = await (checkPortAvailabilityFn ?? checkPortAvailability)({
+		host,
+		port
+	});
+	if (availability.available) return {
+		state: "available",
+		availabilityDetail: availability.detail,
+		probeError: null
+	};
+	const probe = await (probeHealthEndpointFn ?? probeHealthEndpoint)(healthUrl);
+	if (probe.healthy) return {
+		state: "healthy-existing",
+		availabilityDetail: availability.detail,
+		probeError: null
+	};
+	return {
+		state: "occupied-unhealthy",
+		availabilityDetail: availability.detail,
+		probeError: probe.error
+	};
+}
+async function describeUnmanagedHealthyTargetMessage(params) {
+	const uiConfig = resolveUiConfig(loadConfig(), params.uiOverrides);
+	const healthUrl = `${resolveUiApiBase(uiConfig.host, uiConfig.port)}/api/health`;
+	if ((await inspectUiTarget({
+		host: uiConfig.host,
+		port: uiConfig.port,
+		healthUrl,
+		checkPortAvailabilityFn: params.checkPortAvailabilityFn,
+		probeHealthEndpointFn: params.probeHealthEndpointFn
+	})).state !== "healthy-existing") return null;
+	return [
+		`Target UI health: ${healthUrl}`,
+		`A healthy ${APP_NAME} service is already responding on this port, but it is not tracked by ${managedServiceStateStore.path}.`,
+		`${APP_NAME} restart only stops the background service recorded in managed state; it will not auto-kill Docker or other external listeners.`,
+		`Fix: stop that external service first or rerun with --ui-port <port>.`
+	].join("\n");
+}
+//#endregion
+export { checkPortAvailability, describeUnmanagedHealthyTargetMessage, inspectUiTarget, probeHealthEndpoint };

package/dist/shared/utils/startup-trace.d.ts

@@ -0,0 +1,7 @@
+//#region src/shared/utils/startup-trace.d.ts
+type TraceFields = Record<string, string | number | boolean | null | undefined>;
+declare function logStartupTrace(step: string, fields?: TraceFields): void;
+declare function measureStartupSync<T>(step: string, fn: () => T, fields?: TraceFields): T;
+declare function measureStartupAsync<T>(step: string, fn: () => Promise<T>, fields?: TraceFields): Promise<T>;
+//#endregion
+export { logStartupTrace, measureStartupAsync, measureStartupSync };

package/dist/shared/utils/startup-trace.js

@@ -0,0 +1,37 @@
+//#region src/shared/utils/startup-trace.ts
+const STARTUP_TRACE_ENABLED = process.env.NEXTCLAW_STARTUP_TRACE === "1";
+const STARTUP_TRACE_ORIGIN_MS = Date.now();
+function formatFields(fields) {
+	if (!fields) return "";
+	const parts = Object.entries(fields).filter(([, value]) => value !== void 0).map(([key, value]) => `${key}=${String(value)}`);
+	return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+function logStartupTrace(step, fields) {
+	if (!STARTUP_TRACE_ENABLED) return;
+	const elapsedMs = Date.now() - STARTUP_TRACE_ORIGIN_MS;
+	console.log(`[startup-trace] +${elapsedMs}ms ${step}${formatFields(fields)}`);
+}
+function measureStartupSync(step, fn, fields) {
+	const startedAt = Date.now();
+	try {
+		return fn();
+	} finally {
+		logStartupTrace(step, {
+			...fields,
+			duration_ms: Date.now() - startedAt
+		});
+	}
+}
+async function measureStartupAsync(step, fn, fields) {
+	const startedAt = Date.now();
+	try {
+		return await fn();
+	} finally {
+		logStartupTrace(step, {
+			...fields,
+			duration_ms: Date.now() - startedAt
+		});
+	}
+}
+//#endregion
+export { logStartupTrace, measureStartupAsync, measureStartupSync };

package/dist/shared/utils/top-level-nextclaw-command-env.utils.d.ts

@@ -0,0 +1,4 @@
+//#region src/shared/utils/top-level-nextclaw-command-env.utils.d.ts
+declare function createTopLevelNextclawCommandEnv(baseEnv?: NodeJS.ProcessEnv, extraEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//#endregion
+export { createTopLevelNextclawCommandEnv };

package/dist/shared/utils/top-level-nextclaw-command-env.utils.js

@@ -0,0 +1,10 @@
+import { createExternalCommandEnv } from "@nextclaw/core";
+//#region src/shared/utils/top-level-nextclaw-command-env.utils.ts
+const NEXTCLAW_RUNTIME_BUNDLE_ENV_KEYS = ["NEXTCLAW_RUNTIME_BUNDLE_CHILD", "NEXTCLAW_DISABLE_RUNTIME_BUNDLE_LAUNCHER"];
+function createTopLevelNextclawCommandEnv(baseEnv = process.env, extraEnv = {}) {
+	const env = createExternalCommandEnv(baseEnv, extraEnv);
+	for (const key of NEXTCLAW_RUNTIME_BUNDLE_ENV_KEYS) delete env[key];
+	return env;
+}
+//#endregion
+export { createTopLevelNextclawCommandEnv };