@havesomecode/kibana-mcp-server 0.1.0

package/dist/src/kibana_client.js

@@ -0,0 +1,441 @@
+const DEFAULT_META_FIELDS = ["_source", "_id", "_index", "_score"];
+class KibanaHttpError extends Error {
+    status;
+    responseBody;
+    constructor(status, responseBody) {
+        super(`Kibana request failed with status ${status}: ${responseBody}`);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.name = "KibanaHttpError";
+    }
+}
+function joinUrl(baseUrl, path) {
+    return path.startsWith("http://") || path.startsWith("https://")
+        ? path
+        : `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function encodeBasicAuth(username, password) {
+    return Buffer.from(`${username}:${password}`).toString("base64");
+}
+function unwrapSearchResponse(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Unexpected Kibana search response shape");
+    }
+    const record = raw;
+    if (record.rawResponse && typeof record.rawResponse === "object") {
+        return record.rawResponse;
+    }
+    if (record.response && typeof record.response === "object") {
+        const responseRecord = record.response;
+        if (responseRecord.rawResponse && typeof responseRecord.rawResponse === "object") {
+            return responseRecord.rawResponse;
+        }
+        if (responseRecord.hits || responseRecord.aggregations || responseRecord.aggs) {
+            return responseRecord;
+        }
+    }
+    if (record.hits || record.aggregations || record.aggs) {
+        return record;
+    }
+    throw new Error("Unexpected Kibana search response shape");
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function normalizeFieldCapsResponse(raw) {
+    const fields = asRecord(asRecord(raw).fields);
+    return Object.entries(fields)
+        .map(([name, typeEntries]) => {
+        const typeRecord = asRecord(typeEntries);
+        const firstEntry = Object.values(typeRecord)[0];
+        const fieldCaps = asRecord(firstEntry);
+        return {
+            name,
+            type: typeof fieldCaps.type === "string" ? fieldCaps.type : Object.keys(typeRecord)[0],
+            searchable: typeof fieldCaps.searchable === "boolean" ? fieldCaps.searchable : undefined,
+            aggregatable: typeof fieldCaps.aggregatable === "boolean" ? fieldCaps.aggregatable : undefined,
+            subfields: [],
+        };
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function normalizeKibanaFieldsResponse(raw) {
+    const rawFields = Array.isArray(raw) ? raw : asArray(asRecord(raw).fields);
+    return rawFields
+        .map((field) => {
+        const fieldRecord = asRecord(field);
+        const name = fieldRecord.name;
+        if (typeof name !== "string") {
+            return null;
+        }
+        const subType = asRecord(fieldRecord.subType);
+        const nested = asRecord(subType.nested);
+        const multi = asRecord(subType.multi);
+        return {
+            name,
+            type: typeof fieldRecord.type === "string" ? fieldRecord.type : undefined,
+            searchable: typeof fieldRecord.searchable === "boolean" ? fieldRecord.searchable : undefined,
+            aggregatable: typeof fieldRecord.aggregatable === "boolean" ? fieldRecord.aggregatable : undefined,
+            nested_path: typeof nested.path === "string" ? nested.path : undefined,
+            multi_field_parent: typeof multi.parent === "string" ? multi.parent : undefined,
+            subfields: [],
+        };
+    })
+        .filter((field) => field !== null)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function resolveSchemaIndexPatterns(source, schemaBackend) {
+    const schemaIndex = schemaBackend.index ?? source.backend.index;
+    if (!schemaIndex) {
+        throw new Error(`Source '${source.id}' does not declare schema index patterns. Configure source.schema.index or backend.index.`);
+    }
+    return Array.isArray(schemaIndex) ? schemaIndex.join(",") : schemaIndex;
+}
+function dedupePaths(paths) {
+    return [...new Set(paths.filter((path) => Boolean(path?.trim())))];
+}
+function resolveSchemaPaths(source, schemaBackend, patterns) {
+    if (schemaBackend.kind === "elasticsearch_field_caps") {
+        return [schemaBackend.path ?? `/${patterns}/_field_caps`];
+    }
+    if (schemaBackend.kind === "kibana_data_views_fields") {
+        return dedupePaths([
+            schemaBackend.path,
+            "/internal/data_views/_fields_for_wildcard",
+            "/api/data_views/fields_for_wildcard",
+            "/api/index_patterns/_fields_for_wildcard",
+        ]);
+    }
+    return dedupePaths([
+        schemaBackend.path,
+        "/api/index_patterns/_fields_for_wildcard",
+        "/internal/data_views/_fields_for_wildcard",
+        "/api/data_views/fields_for_wildcard",
+    ]);
+}
+function buildKibanaSchemaUrl(baseUrl, schemaPath, patterns) {
+    const url = new URL(joinUrl(baseUrl, schemaPath));
+    url.searchParams.set("pattern", patterns);
+    url.searchParams.set("allow_no_index", "true");
+    for (const metaField of DEFAULT_META_FIELDS) {
+        url.searchParams.append("meta_fields", metaField);
+    }
+    return url.toString();
+}
+function inferPrimitiveFieldType(value, fieldName) {
+    if (typeof value === "boolean") {
+        return "boolean";
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? "long" : "double";
+    }
+    if (typeof value === "string") {
+        if (fieldName?.endsWith(".keyword")) {
+            return "keyword";
+        }
+        return "text";
+    }
+    return undefined;
+}
+function upsertFieldDescriptor(fieldMap, field) {
+    const existing = fieldMap.get(field.name);
+    if (!existing) {
+        fieldMap.set(field.name, {
+            ...field,
+            subfields: [...new Set(field.subfields)],
+        });
+        return;
+    }
+    fieldMap.set(field.name, {
+        ...existing,
+        type: existing.type ?? field.type,
+        description: existing.description ?? field.description,
+        searchable: existing.searchable ?? field.searchable,
+        aggregatable: existing.aggregatable ?? field.aggregatable,
+        nested_path: existing.nested_path ?? field.nested_path,
+        object_array_path: existing.object_array_path ?? field.object_array_path,
+        multi_field_parent: existing.multi_field_parent ?? field.multi_field_parent,
+        preferred_exact_field: existing.preferred_exact_field ?? field.preferred_exact_field,
+        subfields: [...new Set([...(existing.subfields ?? []), ...(field.subfields ?? [])])],
+    });
+}
+function normalizeInferredNestedPath(nestedPath, objectArrayPath) {
+    // Sampled hits cannot prove Elasticsearch nested mappings. Once a field is inferred under an
+    // array-of-objects path, keep that shape explicit and never mark it as nested.
+    return objectArrayPath ? undefined : nestedPath;
+}
+function collectFieldsFromSourceDocument(value, fieldMap, path, nestedPath, objectArrayPath) {
+    if (value === null || value === undefined) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        const objectValues = value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry));
+        if (path && objectValues.length > 0) {
+            for (const entry of objectValues) {
+                for (const [key, childValue] of Object.entries(entry)) {
+                    collectFieldsFromSourceDocument(childValue, fieldMap, `${path}.${key}`, undefined, path);
+                }
+            }
+            return;
+        }
+        const primitiveSample = value.find((entry) => entry !== null && entry !== undefined && typeof entry !== "object");
+        if (path && primitiveSample !== undefined) {
+            upsertFieldDescriptor(fieldMap, {
+                name: path,
+                type: inferPrimitiveFieldType(primitiveSample, path),
+                searchable: true,
+                aggregatable: typeof primitiveSample !== "string",
+                nested_path: normalizeInferredNestedPath(nestedPath, objectArrayPath),
+                object_array_path: objectArrayPath,
+                subfields: [],
+            });
+        }
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [key, childValue] of Object.entries(value)) {
+            const childPath = path ? `${path}.${key}` : key;
+            collectFieldsFromSourceDocument(childValue, fieldMap, childPath, nestedPath, objectArrayPath);
+        }
+        return;
+    }
+    if (!path) {
+        return;
+    }
+    upsertFieldDescriptor(fieldMap, {
+        name: path,
+        type: inferPrimitiveFieldType(value, path),
+        searchable: true,
+        aggregatable: typeof value !== "string",
+        nested_path: normalizeInferredNestedPath(nestedPath, objectArrayPath),
+        object_array_path: objectArrayPath,
+        subfields: [],
+    });
+}
+function collectFieldsFromSearchHit(hit, fieldMap) {
+    collectFieldsFromSourceDocument(asRecord(hit._source), fieldMap);
+    const fieldValues = asRecord(hit.fields);
+    for (const [fieldName, values] of Object.entries(fieldValues)) {
+        const firstValue = Array.isArray(values) ? values.find((value) => value !== undefined) : values;
+        const multiFieldParent = fieldName.includes(".")
+            ? fieldName.slice(0, fieldName.lastIndexOf("."))
+            : undefined;
+        const inferredType = inferPrimitiveFieldType(firstValue, fieldName);
+        upsertFieldDescriptor(fieldMap, {
+            name: fieldName,
+            type: inferredType,
+            searchable: true,
+            aggregatable: true,
+            multi_field_parent: multiFieldParent,
+            preferred_exact_field: inferredType === "keyword" && multiFieldParent ? fieldName : undefined,
+            subfields: [],
+        });
+        if (inferredType === "keyword" && multiFieldParent) {
+            upsertFieldDescriptor(fieldMap, {
+                name: multiFieldParent,
+                type: fieldMap.get(multiFieldParent)?.type ?? "text",
+                searchable: true,
+                aggregatable: false,
+                preferred_exact_field: fieldName,
+                subfields: [fieldName],
+            });
+        }
+    }
+}
+function normalizeSearchSampleFields(raw) {
+    const hitsRecord = asRecord(asRecord(raw).hits);
+    const hits = asArray(hitsRecord.hits);
+    const fieldMap = new Map();
+    for (const hit of hits) {
+        collectFieldsFromSearchHit(asRecord(hit), fieldMap);
+    }
+    return [...fieldMap.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+export class KibanaClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async requestJson(url, options = {}) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: options.method ?? "GET",
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Basic ${encodeBasicAuth(this.config.username, this.config.password)}`,
+                    "Content-Type": "application/json",
+                    ...options.headers,
+                },
+                ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new KibanaHttpError(response.status, errorBody);
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async execute(compiledQuery) {
+        const source = compiledQuery.source;
+        const endpoint = joinUrl(this.config.baseUrl, source.backend.path);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const body = source.backend.kind === "kibana_internal_search_es"
+                ? {
+                    params: {
+                        ...(source.backend.index ? { index: source.backend.index } : {}),
+                        body: compiledQuery.request.body,
+                    },
+                }
+                : compiledQuery.request.body;
+            const response = await fetch(endpoint, {
+                method: "POST",
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Basic ${encodeBasicAuth(this.config.username, this.config.password)}`,
+                    "Content-Type": "application/json",
+                    ...(source.backend.kind === "kibana_internal_search_es"
+                        ? { "kbn-xsrf": "kibana-mcp-server" }
+                        : {}),
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new Error(`Kibana request failed for source '${source.id}' with status ${response.status}: ${errorBody}`);
+            }
+            const responseJson = (await response.json());
+            return {
+                source,
+                rawResponse: unwrapSearchResponse(responseJson),
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async executeMany(sourceQueries) {
+        return Promise.all(sourceQueries.map((sourceQuery) => this.execute(sourceQuery)));
+    }
+    async describeFieldsViaSearchBackend(source) {
+        const endpoint = joinUrl(this.config.baseUrl, source.backend.path);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const body = source.backend.kind === "kibana_internal_search_es"
+                ? {
+                    params: {
+                        ...(source.backend.index ? { index: source.backend.index } : {}),
+                        body: {
+                            size: 20,
+                            sort: [{ [source.timeField]: { order: "desc" } }],
+                            fields: ["*"],
+                            _source: true,
+                            track_total_hits: false,
+                        },
+                    },
+                }
+                : {
+                    size: 20,
+                    sort: [{ [source.timeField]: { order: "desc" } }],
+                    fields: ["*"],
+                    _source: true,
+                    track_total_hits: false,
+                };
+            const response = await fetch(endpoint, {
+                method: "POST",
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Basic ${encodeBasicAuth(this.config.username, this.config.password)}`,
+                    "Content-Type": "application/json",
+                    ...(source.backend.kind === "kibana_internal_search_es"
+                        ? { "kbn-xsrf": "kibana-mcp-server" }
+                        : {}),
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new Error(`Search transport fallback failed for source '${source.id}' with status ${response.status}: ${errorBody}`);
+            }
+            const responseJson = (await response.json());
+            const rawResponse = unwrapSearchResponse(responseJson);
+            const fields = normalizeSearchSampleFields(rawResponse);
+            if (fields.length === 0) {
+                throw new Error(`Search transport fallback returned no fields for source '${source.id}'. Sample hits may be empty for the requested index pattern.`);
+            }
+            return fields;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async describeFields(source) {
+        const schemaBackend = source.schema;
+        if (!schemaBackend) {
+            throw new Error(`Source '${source.id}' does not configure a schema backend. Add source.schema before using describe_fields or schema-dependent query features.`);
+        }
+        const patterns = resolveSchemaIndexPatterns(source, schemaBackend);
+        const schemaPaths = resolveSchemaPaths(source, schemaBackend, patterns);
+        if (schemaBackend.kind === "elasticsearch_field_caps") {
+            const schemaPath = schemaPaths[0];
+            if (!schemaPath) {
+                throw new Error(`Schema backend '${schemaBackend.kind}' does not have a usable path for source '${source.id}'`);
+            }
+            const separator = schemaPath.includes("?") ? "&" : "?";
+            const url = joinUrl(this.config.baseUrl, `${schemaPath}${separator}fields=*`);
+            let responseJson;
+            try {
+                responseJson = await this.requestJson(url, {
+                    method: "GET",
+                });
+            }
+            catch (error) {
+                throw new Error(`Schema backend '${schemaBackend.kind}' request failed for source '${source.id}' at '${schemaPath}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                return normalizeFieldCapsResponse(responseJson);
+            }
+            catch (error) {
+                throw new Error(`Schema backend '${schemaBackend.kind}' returned an unexpected field capabilities payload for source '${source.id}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const attempts = [];
+        for (const schemaPath of schemaPaths) {
+            const url = buildKibanaSchemaUrl(this.config.baseUrl, schemaPath, patterns);
+            try {
+                const responseJson = await this.requestJson(url, {
+                    method: "GET",
+                    headers: {
+                        "kbn-xsrf": "kibana-mcp-server",
+                    },
+                });
+                try {
+                    return normalizeKibanaFieldsResponse(responseJson);
+                }
+                catch (error) {
+                    throw new Error(`Schema backend '${schemaBackend.kind}' returned an unexpected Kibana field payload for source '${source.id}' from '${schemaPath}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof KibanaHttpError && error.status === 404) {
+                    attempts.push(`${schemaPath} -> 404`);
+                    continue;
+                }
+                throw new Error(`Schema backend '${schemaBackend.kind}' request failed for source '${source.id}' at '${schemaPath}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return this.describeFieldsViaSearchBackend(source).catch((fallbackError) => {
+            throw new Error(`Schema backend '${schemaBackend.kind}' returned 404 for source '${source.id}' on every known Kibana field-discovery path (${attempts.join(", ")}). Search transport fallback also failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+        });
+    }
+}

package/dist/src/mcp_entry.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startMcpServer } from "./mcp_runtime.js";
+startMcpServer().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/src/mcp_runtime.js

@@ -0,0 +1,23 @@
+import { StdioServerTransport } from "@modelcontextprotocol/server";
+import { NoSavedProfileError, PROFILE_NAME_ENV, loadConfigFromEnvironment } from "./config.js";
+import { createApplication } from "./server.js";
+function hasBootstrapConfig(env) {
+    return Boolean(env.KIBANA_BASE_URL && env.KIBANA_USERNAME && env.KIBANA_PASSWORD);
+}
+export async function startMcpServer(envInput = process.env) {
+    let config = undefined;
+    try {
+        config = await loadConfigFromEnvironment(envInput);
+    }
+    catch (error) {
+        if (hasBootstrapConfig(envInput) || envInput[PROFILE_NAME_ENV]?.trim()) {
+            throw error;
+        }
+        if (!(error instanceof NoSavedProfileError)) {
+            throw error;
+        }
+    }
+    const { server } = createApplication(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/profile_paths.js

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const MACHINE_STATE_DIR_ENV = "KIBANA_STATE_DIR";
+export const APP_STATE_DIRECTORY_NAME = "kibana-mcp-server";
+export function resolveMachineStateRoot(envInput = process.env, platform = process.platform, homeDirectory = homedir()) {
+    const explicitRoot = envInput[MACHINE_STATE_DIR_ENV]?.trim();
+    if (explicitRoot) {
+        return explicitRoot;
+    }
+    switch (platform) {
+        case "darwin":
+            return join(homeDirectory, "Library", "Application Support", APP_STATE_DIRECTORY_NAME);
+        case "win32": {
+            const appData = envInput.APPDATA?.trim();
+            if (appData) {
+                return join(appData, APP_STATE_DIRECTORY_NAME);
+            }
+            return join(homeDirectory, "AppData", "Roaming", APP_STATE_DIRECTORY_NAME);
+        }
+        default: {
+            const xdgConfigHome = envInput.XDG_CONFIG_HOME?.trim();
+            if (xdgConfigHome) {
+                return join(xdgConfigHome, APP_STATE_DIRECTORY_NAME);
+            }
+            return join(homeDirectory, ".config", APP_STATE_DIRECTORY_NAME);
+        }
+    }
+}
+export function resolveProfilePaths(envInput = process.env, platform = process.platform, homeDirectory = homedir()) {
+    const stateRoot = resolveMachineStateRoot(envInput, platform, homeDirectory);
+    return {
+        stateRoot,
+        profilesPath: join(stateRoot, "profiles.json"),
+        sourceCatalogsDir: join(stateRoot, "source-catalogs"),
+    };
+}

package/dist/src/profile_store.js

@@ -0,0 +1,136 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { resolveProfilePaths } from "./profile_paths.js";
+const PROFILE_STORE_VERSION = 1;
+const savedProfileSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    baseUrl: z.url(),
+    timeoutMs: z.number().int().positive().max(120000),
+    sourceCatalogPath: z.string().min(1),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+const savedProfileStoreStateSchema = z.object({
+    version: z.literal(PROFILE_STORE_VERSION),
+    defaultProfileId: z.string().min(1).nullable(),
+    profiles: z.array(savedProfileSchema),
+});
+const EMPTY_PROFILE_STORE = {
+    version: PROFILE_STORE_VERSION,
+    defaultProfileId: null,
+    profiles: [],
+};
+export class ProfileStore {
+    paths;
+    io;
+    constructor(paths = resolveProfilePaths(), io = {}) {
+        this.paths = paths;
+        this.io = io;
+    }
+    async load() {
+        try {
+            const raw = await (this.io.readFile ?? readFile)(this.paths.profilesPath, "utf8");
+            return savedProfileStoreStateSchema.parse(JSON.parse(raw));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return EMPTY_PROFILE_STORE;
+            }
+            throw error;
+        }
+    }
+    async listProfiles() {
+        return (await this.load()).profiles;
+    }
+    async getDefaultProfile() {
+        const state = await this.load();
+        if (!state.defaultProfileId) {
+            return null;
+        }
+        return state.profiles.find((profile) => profile.id === state.defaultProfileId) ?? null;
+    }
+    async findProfile(query) {
+        const normalizedQuery = query.trim().toLowerCase();
+        if (!normalizedQuery) {
+            return null;
+        }
+        const state = await this.load();
+        return (state.profiles.find((profile) => profile.id.toLowerCase() === normalizedQuery ||
+            profile.name.toLowerCase() === normalizedQuery) ?? null);
+    }
+    async upsertProfile(input, options = {}) {
+        const state = await this.load();
+        const now = (options.now ?? new Date()).toISOString();
+        const existing = state.profiles.find((profile) => profile.name.toLowerCase() === input.name.trim().toLowerCase());
+        const profile = existing
+            ? {
+                ...existing,
+                name: input.name.trim(),
+                baseUrl: input.baseUrl,
+                timeoutMs: input.timeoutMs,
+                sourceCatalogPath: input.sourceCatalogPath,
+                updatedAt: now,
+            }
+            : {
+                id: input.id ??
+                    deriveProfileId(input.name, state.profiles.map((profile) => profile.id)),
+                name: input.name.trim(),
+                baseUrl: input.baseUrl,
+                timeoutMs: input.timeoutMs,
+                sourceCatalogPath: input.sourceCatalogPath,
+                createdAt: now,
+                updatedAt: now,
+            };
+        const nextProfiles = existing
+            ? state.profiles.map((candidate) => (candidate.id === profile.id ? profile : candidate))
+            : [...state.profiles, profile];
+        const nextState = {
+            version: PROFILE_STORE_VERSION,
+            defaultProfileId: options.makeDefault || !state.defaultProfileId ? profile.id : state.defaultProfileId,
+            profiles: nextProfiles,
+        };
+        await this.save(nextState);
+        return profile;
+    }
+    async setDefaultProfile(profileId) {
+        const state = await this.load();
+        const profileExists = state.profiles.some((profile) => profile.id === profileId);
+        if (!profileExists) {
+            throw new Error(`Cannot set default profile. Unknown profile id '${profileId}'.`);
+        }
+        await this.save({
+            ...state,
+            defaultProfileId: profileId,
+        });
+    }
+    async save(state) {
+        const mkdirImpl = this.io.mkdir ?? mkdir;
+        const writeFileImpl = this.io.writeFile ?? writeFile;
+        await mkdirImpl(dirname(this.paths.profilesPath), { recursive: true });
+        await writeFileImpl(this.paths.profilesPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    }
+}
+export function normalizeProfileId(name) {
+    const normalized = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || "default";
+}
+export function deriveProfileId(name, existingIds) {
+    const baseId = normalizeProfileId(name);
+    if (!existingIds.includes(baseId)) {
+        return baseId;
+    }
+    let index = 2;
+    while (existingIds.includes(`${baseId}-${index}`)) {
+        index += 1;
+    }
+    return `${baseId}-${index}`;
+}
+function isMissingFileError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}