zidane 6.4.4 → 6.5.1

package/dist/plugins-2PMTVcp-.js

@@ -0,0 +1,1174 @@
+import { T as parseSkillFile } from "./skills-Cp9vnBwd.js";
+import { t as isAllowedRemoteUrl } from "./origin-pinned-fetch-CqG8VZIq.js";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+//#region src/chat/xdg.ts
+/**
+* XDG Base Directory resolution for zidane.
+*
+* The user's storage spreads across four logical slots:
+*
+*   - **config** — credentials, mcp-credentials, keybindings, config.json,
+*     mcps.json, skills (user-editable surface).
+*   - **data**   — sessions.db (long-lived chat history).
+*   - **state**  — state.json (per-machine UI bookkeeping: last provider,
+*     last model, last agent, settings).
+*   - **cache**  — persisted tool results, background-task logs,
+*     auto-update registry cache (regenerable, safe to wipe).
+*
+* Historically all four collapsed to `~/.zidane/`. This module adds
+* XDG-Base-Directory-aware defaults so a Linux user with no existing
+* `~/.zidane/` lands in the conventional `~/.config/zidane/`,
+* `~/.local/share/zidane/`, `~/.local/state/zidane/`, `~/.cache/zidane/`
+* trio. Existing setups (anyone with a `~/.zidane/` directory or
+* `ZIDANE_STORAGE_DIR` set) keep the single-dir layout unchanged.
+*
+* Resolution flow — applied in this order:
+*
+*   1. Caller passed an explicit `storageDir` (`ChatOptions.storageDir`)
+*      OR `ZIDANE_STORAGE_DIR` is set → **legacy-explicit** single-dir
+*      layout under `<storageDir>/<prefix>`. The four slots collapse to
+*      the same directory.
+*   2. `~/<prefix>/` already exists on disk → **legacy-existing**
+*      single-dir layout under that directory. Upgrades never silently
+*      shift files around.
+*   3. Any `XDG_*_HOME` env var is set OR `process.platform === 'linux'`
+*      → **XDG split**. Each slot lands in its own dir. Per-slot
+*      `ZIDANE_{CONFIG,DATA,CACHE,STATE}_DIR` overrides beat the XDG
+*      vars for surgical tweaks.
+*   4. Otherwise (macOS/Windows, no XDG signal, no existing dir) →
+*      **default** single-dir layout at `~/<prefix>/`. Day-one behavior
+*      on these platforms is unchanged.
+*
+* The `userDir` legacy alias always equals `configDir` so existing code
+* that still references `paths.userDir` keeps reading credentials, mcps,
+* etc. from the right place.
+*/
+/**
+* Resolve the four storage slots according to the precedence above.
+*
+* Pure aside from one filesystem probe (`existsSync(home/<prefix>)`)
+* — the same probe `resolveStoragePaths` would do anyway when
+* computing `paths.userDir`. No directories are created here; the
+* relevant write paths (state store, credentials writer, persist
+* dir) handle their own lazy `mkdirSync` already.
+*/
+function resolveStorageDirs(opts = {}) {
+	const env = opts.env ?? process.env;
+	const home = opts.home ?? homedir();
+	const platform = opts.platform ?? process.platform;
+	const rawPrefix = opts.prefix ?? ".zidane";
+	const prefixBare = rawPrefix.replace(/^\./, "");
+	const explicitStorageDir = opts.storageDir ?? env.ZIDANE_STORAGE_DIR;
+	if (explicitStorageDir) return single(resolve(explicitStorageDir, rawPrefix), "legacy-explicit");
+	const legacyHomeDir = resolve(home, rawPrefix);
+	if (existsSync(legacyHomeDir)) return single(legacyHomeDir, "legacy-existing");
+	if (platform === "linux" || !!env.XDG_CONFIG_HOME || !!env.XDG_DATA_HOME || !!env.XDG_CACHE_HOME || !!env.XDG_STATE_HOME || !!env.ZIDANE_CONFIG_DIR || !!env.ZIDANE_DATA_DIR || !!env.ZIDANE_STATE_DIR || !!env.ZIDANE_CACHE_DIR) return {
+		configDir: env.ZIDANE_CONFIG_DIR ?? resolve(env.XDG_CONFIG_HOME || resolve(home, ".config"), prefixBare),
+		dataDir: env.ZIDANE_DATA_DIR ?? resolve(env.XDG_DATA_HOME || resolve(home, ".local", "share"), prefixBare),
+		stateDir: env.ZIDANE_STATE_DIR ?? resolve(env.XDG_STATE_HOME || resolve(home, ".local", "state"), prefixBare),
+		cacheDir: env.ZIDANE_CACHE_DIR ?? resolve(env.XDG_CACHE_HOME || resolve(home, ".cache"), prefixBare),
+		mode: "xdg"
+	};
+	return single(legacyHomeDir, "default");
+}
+function single(base, mode) {
+	return {
+		configDir: base,
+		dataDir: base,
+		stateDir: base,
+		cacheDir: base,
+		mode
+	};
+}
+//#endregion
+//#region src/plugins/boundary.ts
+/**
+* The Agent Plugins package boundary.
+*
+* The spec's central filesystem rule: "Every package file a client
+* discovers, reads, or executes must remain inside the filesystem-resolved
+* root after resolving symlinks, junctions, reparse points, and equivalent
+* mechanisms."
+*
+* Lexical containment (`../skills/validate.ts`'s `validateResourcePath`) is
+* NOT sufficient here — a `skills` symlink pointing at `~/.ssh` passes every
+* lexical check. So each package path is resolved through `realpath` and
+* re-tested against the realpath-resolved root, and the required filesystem
+* kind is asserted with a symlink-FOLLOWING `stat` (the spec wants
+* `SKILL.md` to be a regular file, not a fifo or a directory wearing the
+* name).
+*
+* Containment is tested with `path.relative` rather than a string prefix so
+* `/plugin-root` vs `/plugin-root-evil` can't be confused and Windows
+* separators are handled by the platform.
+*/
+/**
+* Resolve the plugin root itself. Returns `null` when the root does not
+* exist or is not a directory — the caller turns that into a plugin-level
+* rejection, since there is nothing to load.
+*/
+async function resolvePluginBoundary(dir) {
+	const absolute = resolve(dir);
+	try {
+		const root = await realpath(absolute);
+		if (!(await stat(root)).isDirectory()) return null;
+		return {
+			dir: absolute,
+			root
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* True when `real` (an already symlink-resolved path) lives at or under
+* `root` (likewise resolved).
+*/
+function isWithin(root, real) {
+	const rel = relative(root, real);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+* Symlink-resolve `target` and confirm it stays inside the boundary.
+*
+* Use this for paths whose filesystem kind doesn't matter or that may not
+* exist yet (Phase 3's `cwd` handling); otherwise prefer
+* {@link resolvePackagePath}, which also asserts the kind.
+*/
+async function realPathWithin(boundary, target) {
+	let real;
+	try {
+		real = await realpath(target);
+	} catch {
+		return {
+			ok: false,
+			reason: "missing"
+		};
+	}
+	if (!isWithin(boundary.root, real)) return {
+		ok: false,
+		reason: "escaped"
+	};
+	return {
+		ok: true,
+		real
+	};
+}
+/**
+* Resolve a package path and assert its filesystem kind.
+*
+* `stat` (not `lstat`) is deliberate: a symlink to a regular file INSIDE the
+* root is legitimate packaging, and containment is already enforced against
+* the resolved target. What we reject is the kind mismatch the spec calls
+* out — `skills` as a regular file, `SKILL.md` as a directory or a fifo.
+*/
+async function resolvePackagePath(boundary, target, kind) {
+	const within = await realPathWithin(boundary, target);
+	if (!within.ok) return within;
+	try {
+		const info = await stat(within.real);
+		if (!(kind === "directory" ? info.isDirectory() : info.isFile())) return {
+			ok: false,
+			reason: "wrong-kind"
+		};
+	} catch {
+		return {
+			ok: false,
+			reason: "missing"
+		};
+	}
+	return within;
+}
+//#endregion
+//#region src/plugins/types.ts
+/**
+* Agent Plugins spec versions this loader implements, newest first.
+*
+* The spec requires clients to select validation rules from the manifest's
+* `$schema` WITHOUT retrieving it, and to let plugins keep targeting older
+* versions under a locally supported compatibility policy. Our policy: a
+* version is supported iff it appears in this list. Adding `1.1.0` later
+* means adding it here plus any rule deltas in `./manifest` — never
+* reinterpreting an already-published identifier, which the spec forbids.
+*/
+const SUPPORTED_AGENT_PLUGINS_VERSIONS = ["1.0.0"];
+/**
+* Canonical schema identifier for a given document kind + version. Built
+* rather than hardcoded so the two call sites (manifest, mcp.json) can't
+* drift, and so the version cross-check the spec requires between
+* `plugin.json` and `mcp.json` is a plain string comparison.
+*/
+function agentPluginsSchemaId(kind, version) {
+	return `https://agent-plugins.org/schemas/${version}/${kind}.schema.json`;
+}
+/**
+* Canonical schema identifier grammar. Anchored and exact — a `$schema`
+* that merely looks similar (http, a trailing slash, a different host) is
+* not the canonical identifier and must not select the contract.
+*/
+const SCHEMA_ID_RE = /^https:\/\/agent-plugins\.org\/schemas\/([^/]+)\/(plugin|mcp)\.schema\.json$/;
+/**
+* Split a canonical `$schema` identifier into its document kind + version.
+* Returns `null` for anything that isn't a canonical identifier; the caller
+* decides whether that's fatal (manifest) or component-scoped (mcp.json).
+*
+* Purely syntactic: it never fetches. The spec forbids retrieving a schema
+* during load, so version support is a lookup against
+* {@link SUPPORTED_AGENT_PLUGINS_VERSIONS}, not a download.
+*/
+function parseSchemaId(value) {
+	const match = SCHEMA_ID_RE.exec(value);
+	if (!match) return null;
+	return {
+		kind: match[2],
+		version: match[1]
+	};
+}
+/** True when this loader implements the given Agent Plugins version. */
+function isSupportedAgentPluginsVersion(version) {
+	return SUPPORTED_AGENT_PLUGINS_VERSIONS.includes(version);
+}
+/**
+* Type label for a rejected JSON value, for diagnostic messages.
+*
+* `typeof` alone is useless in a validator that has to tell an author what
+* they got wrong: `null` and `[]` both report `'object'`, and those are two of
+* the most common mistakes in a hand-written manifest. Shared by the manifest
+* and `mcp.json` validators, which produce the same class of message.
+*
+* Internal — not re-exported from the module barrel.
+*/
+function describeJsonType(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+//#endregion
+//#region src/plugins/manifest.ts
+/**
+* Plugin name grammar, lifted from the canonical schema: 1-64 chars,
+* lowercase alphanumerics plus `-` and `.`, alphanumeric at both ends, and
+* no `--` or `..` anywhere (the negative lookahead).
+*
+* Length is checked separately so an over-long name gets a message about
+* length instead of a generic "doesn't match the grammar".
+*/
+const PLUGIN_NAME_RE = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+const NAME_MAX = 64;
+/** Top-level fields the 1.0.0 manifest permits. Anything else is unknown. */
+const KNOWN_FIELDS = /* @__PURE__ */ new Set([
+	"$schema",
+	"name",
+	"version",
+	"description",
+	"author",
+	"homepage",
+	"repository",
+	"license",
+	"keywords",
+	"extensions"
+]);
+/** Optional top-level fields whose value must be a string when present. */
+const STRING_FIELDS = [
+	"version",
+	"description",
+	"homepage",
+	"repository",
+	"license"
+];
+/** Keys the closed `author` object permits. */
+const AUTHOR_FIELDS = /* @__PURE__ */ new Set([
+	"name",
+	"email",
+	"url"
+]);
+/**
+* Parse manifest text, then validate it.
+*
+* A JSON syntax error is fatal — unlike `mcps.json` (where
+* `parseJsonTolerant` repairs copy-paste whitespace artifacts), a plugin
+* manifest is a package file produced by a build or an author's editor, not
+* pasted into a settings box. Repairing it would mean guessing at the
+* contents of a third-party package.
+*/
+function parsePluginManifest(text) {
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		return {
+			ok: false,
+			diagnostics: [{
+				severity: "error",
+				code: "manifest-invalid-json",
+				message: `plugin.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+			}]
+		};
+	}
+	return validatePluginManifest(raw);
+}
+/**
+* Validate an already-parsed manifest value against the closed 1.0.0 schema.
+*
+* Fatal violations short-circuit: `$schema` and `name` are checked first
+* because without them there is no contract to validate against and no
+* identity to report problems under.
+*/
+function validatePluginManifest(raw) {
+	const diagnostics = [];
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		diagnostics: [{
+			severity: "error",
+			code: "manifest-not-object",
+			message: `plugin.json must be a JSON object (got ${Array.isArray(raw) ? "array" : typeof raw}).`
+		}]
+	};
+	const obj = raw;
+	const schema = obj.$schema;
+	if (typeof schema !== "string" || schema.length === 0) return fatal(diagnostics, {
+		code: "manifest-schema-missing",
+		message: `plugin.json is missing the required "$schema" field. Expected "${agentPluginsSchemaId("plugin", SUPPORTED_AGENT_PLUGINS_VERSIONS[0])}".`,
+		field: "$schema"
+	});
+	const parsed = parseSchemaId(schema);
+	if (!parsed || parsed.kind !== "plugin") return fatal(diagnostics, {
+		code: "manifest-schema-unsupported",
+		message: `plugin.json "$schema" is not a canonical Agent Plugins manifest schema identifier: "${schema}".`,
+		field: "$schema"
+	});
+	if (!isSupportedAgentPluginsVersion(parsed.version)) return fatal(diagnostics, {
+		code: "manifest-schema-unsupported",
+		message: `plugin.json targets Agent Plugins ${parsed.version}, which this client does not support (supported: ${SUPPORTED_AGENT_PLUGINS_VERSIONS.join(", ")}).`,
+		field: "$schema"
+	});
+	const name = obj.name;
+	if (typeof name !== "string") return fatal(diagnostics, {
+		code: "manifest-name-missing",
+		message: `plugin.json is missing the required "name" field${name === void 0 ? "" : ` (got ${typeof name})`}.`,
+		field: "name"
+	});
+	if (name.length === 0 || name.length > NAME_MAX) return fatal(diagnostics, {
+		code: "manifest-name-invalid",
+		message: `Plugin name must be 1-${NAME_MAX} characters (got ${name.length}).`,
+		field: "name"
+	});
+	if (!PLUGIN_NAME_RE.test(name)) return fatal(diagnostics, {
+		code: "manifest-name-invalid",
+		message: `Plugin name "${name}" is invalid — use lowercase letters, digits, hyphens and periods, starting and ending alphanumeric, with no "--" or "..".`,
+		field: "name"
+	});
+	const manifest = {
+		specVersion: parsed.version,
+		name
+	};
+	for (const field of STRING_FIELDS) {
+		const value = obj[field];
+		if (value === void 0) continue;
+		if (typeof value !== "string") return fatal(diagnostics, {
+			code: "manifest-field-wrong-type",
+			message: `plugin.json "${field}" must be a string (got ${describeJsonType(value)}).`,
+			field
+		});
+		manifest[field] = value;
+	}
+	if (obj.keywords !== void 0) {
+		if (!Array.isArray(obj.keywords)) return fatal(diagnostics, {
+			code: "manifest-field-wrong-type",
+			message: `plugin.json "keywords" must be an array of strings (got ${describeJsonType(obj.keywords)}).`,
+			field: "keywords"
+		});
+		const bad = obj.keywords.findIndex((entry) => typeof entry !== "string");
+		if (bad !== -1) return fatal(diagnostics, {
+			code: "manifest-field-wrong-type",
+			message: `plugin.json "keywords[${bad}]" must be a string (got ${describeJsonType(obj.keywords[bad])}).`,
+			field: "keywords"
+		});
+		manifest.keywords = [...obj.keywords];
+	}
+	if (obj.author !== void 0) {
+		const author = obj.author;
+		if (typeof author !== "object" || author === null || Array.isArray(author)) return fatal(diagnostics, {
+			code: "manifest-field-wrong-type",
+			message: `plugin.json "author" must be an object (got ${describeJsonType(author)}).`,
+			field: "author"
+		});
+		const out = {};
+		for (const [key, value] of Object.entries(author)) {
+			if (!AUTHOR_FIELDS.has(key)) return fatal(diagnostics, {
+				code: "manifest-author-unknown-field",
+				message: `plugin.json "author.${key}" is not a permitted field (allowed: ${[...AUTHOR_FIELDS].join(", ")}).`,
+				field: "author"
+			});
+			if (typeof value !== "string") return fatal(diagnostics, {
+				code: "manifest-field-wrong-type",
+				message: `plugin.json "author.${key}" must be a string (got ${describeJsonType(value)}).`,
+				field: "author"
+			});
+			out[key] = value;
+		}
+		manifest.author = out;
+	}
+	if (obj.extensions !== void 0) {
+		const ext = obj.extensions;
+		if (typeof ext !== "object" || ext === null || Array.isArray(ext)) diagnostics.push({
+			severity: "warning",
+			code: "manifest-extensions-not-object",
+			message: `plugin.json "extensions" must be an object (got ${describeJsonType(ext)}) — ignoring it and continuing to load components.`,
+			field: "extensions"
+		});
+		else manifest.extensions = { ...ext };
+	}
+	for (const key of Object.keys(obj)) {
+		if (KNOWN_FIELDS.has(key)) continue;
+		diagnostics.push({
+			severity: "warning",
+			code: "manifest-unknown-field",
+			message: `plugin.json has unknown top-level field "${key}" — ignoring it. Client-specific data belongs under "extensions".`,
+			field: key
+		});
+	}
+	return {
+		ok: true,
+		manifest,
+		diagnostics
+	};
+}
+function fatal(diagnostics, detail) {
+	diagnostics.push({
+		severity: "error",
+		...detail
+	});
+	return {
+		ok: false,
+		diagnostics
+	};
+}
+//#endregion
+//#region src/plugins/mcp.ts
+/** Fixed location for the MCP component type. */
+const PLUGIN_MCP_FILE = "mcp.json";
+/** The only placeholders the spec defines. */
+const PLUGIN_ROOT_VAR = "PLUGIN_ROOT";
+const PLUGIN_DATA_VAR = "PLUGIN_DATA";
+/**
+* Placeholder grammar — deliberately narrower than
+* `expandEnvPlaceholders`'s: exactly the two reserved names, no
+* `:-default` form, no `${env:…}` form. Anything else stays literal.
+*/
+const PLUGIN_VAR_RE = /\$\{(PLUGIN_ROOT|PLUGIN_DATA)\}/g;
+/** Closed top-level key set for the document. */
+const DOCUMENT_FIELDS = /* @__PURE__ */ new Set(["$schema", "mcpServers"]);
+/**
+* Closed key set per declared transport.
+*
+* A `Map` rather than an object literal: the keys are attacker-controlled
+* (`type` comes straight out of a third-party `mcp.json`), and `'constructor'
+* in objectLiteral` is `true`, which would sail past the membership check and
+* then blow up on `Object.prototype.constructor.has(...)`.
+*/
+const ENTRY_FIELDS = /* @__PURE__ */ new Map([
+	["stdio", /* @__PURE__ */ new Set([
+		"type",
+		"command",
+		"args",
+		"env",
+		"cwd"
+	])],
+	["streamable-http", /* @__PURE__ */ new Set([
+		"type",
+		"url",
+		"headers"
+	])],
+	["sse", /* @__PURE__ */ new Set([
+		"type",
+		"url",
+		"headers"
+	])]
+]);
+/**
+* Server-name grammar.
+*
+* `connectMcpServers` namespaces tools as `mcp_<server>_<tool>`, and providers
+* reject a tool name outside the letters / digits / underscore / hyphen shape
+* — rejecting the whole REQUEST, not just the offending tool. A user-authored
+* `mcps.json` has the same sharp edge, but there the user owns the file; a
+* plugin is untrusted input, so an unusable name is rejected per-entry instead
+* of poisoning every run.
+*/
+const SERVER_NAME_RE = /^[a-z0-9][\w-]{0,63}$/i;
+/**
+* Keys that hit a prototype setter instead of creating an own property.
+* Same guard the extension registration paths apply to untrusted keys — see
+* `isSafeRecordKey` in `../extensions/register.ts`. Assigning `__proto__` on
+* an object literal silently DISCARDS the value, so without this an env var
+* would just never reach the child process with nothing explaining why.
+*/
+const DANGEROUS_RECORD_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+/**
+* Load and validate the plugin's `mcp.json`.
+*
+* Status semantics mirror `loadPluginSkills`: a missing file is `absent`
+* (valid), a wrong-kind / escaping / malformed document is `invalid` (this
+* component only), and anything else is `loaded` — even when individual
+* entries were rejected, because per-entry isolation is the point.
+*/
+async function loadPluginMcp(opts) {
+	const { boundary, pluginName, dataDir, specVersion, namePrefix } = opts;
+	const diagnostics = [];
+	const path = resolve(boundary.root, PLUGIN_MCP_FILE);
+	const located = await realPathWithin(boundary, path);
+	if (!located.ok) {
+		if (located.reason === "missing") return {
+			status: "absent",
+			servers: [],
+			diagnostics
+		};
+		diagnostics.push({
+			severity: "error",
+			code: "mcp-file-escapes-root",
+			message: `"${PLUGIN_MCP_FILE}" resolves outside the plugin root — the MCP component is disabled for this plugin.`,
+			path
+		});
+		return {
+			status: "invalid",
+			servers: [],
+			diagnostics
+		};
+	}
+	let raw;
+	try {
+		raw = JSON.parse(await readFile(located.real, "utf8"));
+	} catch (err) {
+		diagnostics.push({
+			severity: "error",
+			code: "mcp-invalid-json",
+			message: `"${PLUGIN_MCP_FILE}" could not be read as JSON: ${err instanceof Error ? err.message : String(err)}`,
+			path: located.real
+		});
+		return {
+			status: "invalid",
+			servers: [],
+			diagnostics
+		};
+	}
+	const document = validateDocument(raw, specVersion);
+	if (!document.ok) {
+		diagnostics.push({
+			severity: "error",
+			...document.diagnostic,
+			path: located.real
+		});
+		return {
+			status: "invalid",
+			servers: [],
+			diagnostics
+		};
+	}
+	const servers = [];
+	for (const [name, entry] of Object.entries(document.servers)) {
+		const built = await buildServer({
+			name,
+			entry,
+			boundary,
+			dataDir,
+			pluginName,
+			...namePrefix !== void 0 ? { namePrefix } : {}
+		});
+		if (!built.ok) {
+			diagnostics.push({
+				severity: "error",
+				...built.diagnostic,
+				path: located.real
+			});
+			continue;
+		}
+		servers.push(built.config);
+	}
+	return {
+		status: "loaded",
+		servers,
+		diagnostics
+	};
+}
+function validateDocument(raw, specVersion) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-not-object",
+			message: `"${PLUGIN_MCP_FILE}" must be a JSON object (got ${describeJsonType(raw)}).`
+		}
+	};
+	const obj = raw;
+	const schema = obj.$schema;
+	if (typeof schema !== "string") return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-schema-missing",
+			message: `"${PLUGIN_MCP_FILE}" is missing the required "$schema" field. Expected "${agentPluginsSchemaId("mcp", specVersion)}".`,
+			field: "$schema"
+		}
+	};
+	const parsed = parseSchemaId(schema);
+	if (!parsed || parsed.kind !== "mcp") return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-schema-unsupported",
+			message: `"${PLUGIN_MCP_FILE}" "$schema" is not a canonical Agent Plugins MCP schema identifier: "${schema}".`,
+			field: "$schema"
+		}
+	};
+	if (parsed.version !== specVersion) return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-schema-version-mismatch",
+			message: `"${PLUGIN_MCP_FILE}" targets Agent Plugins ${parsed.version} but plugin.json targets ${specVersion} — the versions must match.`,
+			field: "$schema"
+		}
+	};
+	for (const key of Object.keys(obj)) if (!DOCUMENT_FIELDS.has(key)) return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-unknown-field",
+			message: `"${PLUGIN_MCP_FILE}" has unknown top-level field "${key}".`,
+			field: key
+		}
+	};
+	const servers = obj.mcpServers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return {
+		ok: false,
+		diagnostic: {
+			code: "mcp-servers-wrong-type",
+			message: `"${PLUGIN_MCP_FILE}" "mcpServers" must be an object (got ${describeJsonType(servers)}).`,
+			field: "mcpServers"
+		}
+	};
+	return {
+		ok: true,
+		servers
+	};
+}
+async function buildServer(opts) {
+	const { name, entry, boundary, dataDir, namePrefix } = opts;
+	const reject = (code, message) => ({
+		ok: false,
+		diagnostic: {
+			code,
+			message: `Skipped MCP server "${name}" — ${message}`
+		}
+	});
+	const serverName = namePrefix ? `${namePrefix}-${name}` : name;
+	if (!SERVER_NAME_RE.test(serverName)) return reject("mcp-entry-name-invalid", namePrefix ? `its namespaced name "${serverName}" is not usable as a tool prefix — the "${namePrefix}" namePrefix must be letters, digits, underscores or hyphens, and the two together at most 64 characters.` : "its name must be 1-64 characters of letters, digits, underscores or hyphens, starting alphanumeric.");
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return reject("mcp-entry-not-object", `its value must be an object (got ${describeJsonType(entry)}).`);
+	const obj = entry;
+	const type = typeof obj.type === "string" ? obj.type : void 0;
+	const allowed = type === void 0 ? void 0 : ENTRY_FIELDS.get(type);
+	if (type === void 0 || !allowed) return reject("mcp-entry-transport-invalid", `"type" must be one of stdio, streamable-http, sse (got ${type === void 0 ? describeJsonType(obj.type) : `"${type}"`}).`);
+	for (const key of Object.keys(obj)) if (!allowed.has(key)) return reject("mcp-entry-unknown-field", `"${key}" is not a permitted field for a ${type} server (allowed: ${[...allowed].join(", ")}).`);
+	const vars = {
+		[PLUGIN_ROOT_VAR]: boundary.root,
+		[PLUGIN_DATA_VAR]: dataDir
+	};
+	if (type === "stdio") {
+		const command = obj.command;
+		if (typeof command !== "string" || command.length === 0) return reject("mcp-entry-command-invalid", "a stdio server needs a non-empty \"command\".");
+		if (PLUGIN_VAR_RE.test(command)) {
+			PLUGIN_VAR_RE.lastIndex = 0;
+			return reject("mcp-entry-command-invalid", "placeholders are not expanded in \"command\" — use a \"./\"-relative path or a bare executable name.");
+		}
+		if (/\s/.test(command)) return reject("mcp-entry-command-invalid", `"command" must be a single executable token, not a command line ("${command}").`);
+		const resolvedCommand = await resolveCommand(command, boundary);
+		if (!resolvedCommand.ok) return reject("mcp-entry-command-invalid", resolvedCommand.error);
+		let args;
+		if (obj.args !== void 0) {
+			if (!Array.isArray(obj.args) || obj.args.some((a) => typeof a !== "string")) return reject("mcp-entry-args-invalid", "\"args\" must be an array of strings.");
+			args = obj.args.map((a) => expandPluginVars(a, vars));
+		}
+		let env;
+		if (obj.env !== void 0) {
+			if (typeof obj.env !== "object" || obj.env === null || Array.isArray(obj.env)) return reject("mcp-entry-env-invalid", "\"env\" must be an object of strings.");
+			env = {};
+			for (const [key, value] of Object.entries(obj.env)) {
+				if (typeof value !== "string") return reject("mcp-entry-env-invalid", `"env.${key}" must be a string (got ${describeJsonType(value)}).`);
+				if (key === PLUGIN_ROOT_VAR || key === PLUGIN_DATA_VAR) return reject("mcp-entry-env-invalid", `"env.${key}" is reserved and cannot be set by a plugin.`);
+				if (!isSafeRecordKey(key)) return reject("mcp-entry-env-invalid", `"env.${key}" is not a usable variable name.`);
+				env[key] = expandPluginVars(value, vars);
+			}
+		}
+		const cwdResult = await resolveCwd(obj.cwd, boundary, dataDir, vars);
+		if (!cwdResult.ok) return reject("mcp-entry-cwd-invalid", cwdResult.error);
+		const config = {
+			name: serverName,
+			transport: "stdio",
+			command: resolvedCommand.command,
+			env: {
+				...env,
+				[PLUGIN_ROOT_VAR]: boundary.root,
+				[PLUGIN_DATA_VAR]: dataDir
+			},
+			cwd: cwdResult.cwd,
+			preExpanded: true
+		};
+		if (args) config.args = args;
+		return {
+			ok: true,
+			config
+		};
+	}
+	const url = obj.url;
+	if (typeof url !== "string" || url.length === 0) return reject("mcp-entry-url-invalid", `a ${type} server needs a non-empty "url".`);
+	const checked = validateRemoteUrl(url);
+	if (!checked.ok) return reject("mcp-entry-url-invalid", checked.error);
+	let headers;
+	if (obj.headers !== void 0) {
+		if (typeof obj.headers !== "object" || obj.headers === null || Array.isArray(obj.headers)) return reject("mcp-entry-headers-invalid", "\"headers\" must be an object of strings.");
+		headers = {};
+		for (const [key, value] of Object.entries(obj.headers)) {
+			if (!isSafeRecordKey(key)) return reject("mcp-entry-headers-invalid", `"headers.${key}" is not a usable header name.`);
+			if (typeof value !== "string") return reject("mcp-entry-headers-invalid", `"headers.${key}" must be a string (got ${describeJsonType(value)}).`);
+			headers[key] = value;
+		}
+	}
+	const config = {
+		name: serverName,
+		transport: type === "sse" ? "sse" : "streamable-http",
+		url,
+		preExpanded: true,
+		pinHeaderOrigin: true
+	};
+	if (headers) config.headers = headers;
+	return {
+		ok: true,
+		config
+	};
+}
+/**
+* Substitute the two reserved placeholders in one string.
+*
+* Single-pass by construction (`String.replace` never re-scans its own
+* output), so a `${PLUGIN_ROOT}` whose value somehow contained
+* `${PLUGIN_DATA}` cannot expand twice. Unknown `${...}` text is left
+* verbatim: the spec defines exactly two placeholders, and silently
+* blanking anything else would corrupt legitimate literals.
+*/
+function expandPluginVars(value, vars) {
+	return value.replace(PLUGIN_VAR_RE, (match, name) => vars[name] ?? match);
+}
+/**
+* Resolve the single `command` token.
+*
+* A bare name (`uvx`, `node`) is handed to the OS for PATH lookup — the
+* plugin declares a dependency on the host's toolchain, which is normal. A
+* `./`-relative token is a file the PACKAGE ships, so it resolves against
+* the plugin root and must survive the containment check. An absolute path
+* is refused: it is neither a PATH lookup nor a package file, and it is the
+* shape an escape attempt takes.
+*/
+async function resolveCommand(command, boundary) {
+	if (isAbsolute(command)) return {
+		ok: false,
+		error: `"command" must be a bare executable name or a "./"-relative path inside the plugin, not an absolute path ("${command}").`
+	};
+	if (!command.includes("/") && !command.includes("\\")) return {
+		ok: true,
+		command
+	};
+	const within = await realPathWithin(boundary, resolve(boundary.root, command));
+	if (!within.ok) return {
+		ok: false,
+		error: within.reason === "escaped" ? `"command" resolves outside the plugin root ("${command}").` : `"command" does not exist inside the plugin ("${command}").`
+	};
+	return {
+		ok: true,
+		command: within.real
+	};
+}
+/**
+* Resolve `cwd`, defaulting to the plugin root.
+*
+* The authored form is constrained to `./…`, `${PLUGIN_ROOT}…` or
+* `${PLUGIN_DATA}…`, and containment is then verified against BOTH permitted
+* roots — the data directory legitimately sits outside the package.
+*
+* Both a lexical and a post-symlink check run, because neither alone is
+* sufficient: `cwd` may not exist yet (a server that creates its own working
+* directory on first run), so realpath cannot be the only gate; but the data
+* directory is writable BY the MCP server, so a server can plant a
+* `${PLUGIN_DATA}/work → /` symlink on one run and get `cwd=/` on the next
+* unless the resolved target is re-checked.
+*/
+async function resolveCwd(raw, boundary, dataDir, vars) {
+	if (raw === void 0) return {
+		ok: true,
+		cwd: boundary.root
+	};
+	if (typeof raw !== "string" || raw.length === 0) return {
+		ok: false,
+		error: "\"cwd\" must be a non-empty string."
+	};
+	const startsWithVar = raw.startsWith(`\${${PLUGIN_ROOT_VAR}}`) || raw.startsWith(`\${${PLUGIN_DATA_VAR}}`);
+	if (!raw.startsWith("./") && !startsWithVar) return {
+		ok: false,
+		error: `"cwd" must start with "./", "\${${PLUGIN_ROOT_VAR}}" or "\${${PLUGIN_DATA_VAR}}" (got "${raw}").`
+	};
+	const expanded = expandPluginVars(raw, vars);
+	const absolute = isAbsolute(expanded) ? expanded : resolve(boundary.root, expanded);
+	if (!isWithin(boundary.root, absolute) && !isWithin(dataDir, absolute)) return {
+		ok: false,
+		error: `"cwd" escapes both the plugin root and the plugin data directory ("${raw}").`
+	};
+	const real = await realpathOrNull(absolute);
+	if (real !== null) {
+		const realDataDir = await realpathOrNull(dataDir) ?? dataDir;
+		if (!isWithin(boundary.root, real) && !isWithin(realDataDir, real)) return {
+			ok: false,
+			error: `"cwd" resolves outside the plugin root and the plugin data directory via a symlink ("${raw}").`
+		};
+	}
+	return {
+		ok: true,
+		cwd: absolute
+	};
+}
+/** `realpath`, or `null` when the path doesn't exist yet. */
+async function realpathOrNull(target) {
+	try {
+		return await realpath(target);
+	} catch {
+		return null;
+	}
+}
+/**
+* Enforce the spec's remote-endpoint requirements: parseable, HTTPS unless
+* loopback, no embedded credentials, no fragment.
+*
+* Reachability (scheme + host) is decided by {@link isAllowedRemoteUrl}, the
+* single encoding of that policy — `originPinnedFetch` applies the same
+* predicate per redirect hop, so a URL refused here can't be reached by
+* redirect either. Only the message selection lives here; the userinfo and
+* fragment rules are authoring-only and have no redirect equivalent.
+*/
+function validateRemoteUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		return {
+			ok: false,
+			error: `"url" is not a valid absolute URL ("${raw}").`
+		};
+	}
+	if (!isAllowedRemoteUrl(url)) return {
+		ok: false,
+		error: url.protocol === "http:" ? `"url" must use https for non-loopback hosts ("${raw}").` : `"url" must use http or https (got "${url.protocol}").`
+	};
+	if (url.username !== "" || url.password !== "") return {
+		ok: false,
+		error: "\"url\" must not embed userinfo credentials."
+	};
+	if (url.hash !== "") return {
+		ok: false,
+		error: "\"url\" must not contain a fragment."
+	};
+	return { ok: true };
+}
+/** Reject keys that would hit a prototype setter instead of the record. */
+function isSafeRecordKey(key) {
+	return key.length > 0 && !DANGEROUS_RECORD_KEYS.has(key);
+}
+//#endregion
+//#region src/plugins/skills.ts
+/** Fixed location for the skills component type. */
+const PLUGIN_SKILLS_DIR = "skills";
+/** Spec cap on a skill name, re-checked after a `namePrefix` is applied. */
+const SKILL_NAME_MAX = 64;
+/**
+* Discover every skill in the plugin's `skills/` directory.
+*
+* Status semantics follow the spec's failure ladder:
+*   - `skills/` missing            → `absent` (valid; not an error)
+*   - `skills/` not a directory    → `invalid` (this component type only)
+*   - `skills/` escapes the root   → `invalid` (this component type only)
+*   - otherwise                    → `loaded`, possibly with zero skills
+*/
+async function loadPluginSkills(opts) {
+	const { boundary, pluginName, source = "project", namePrefix } = opts;
+	const diagnostics = [];
+	const dir = join(boundary.root, PLUGIN_SKILLS_DIR);
+	const located = await resolvePackagePath(boundary, dir, "directory");
+	if (!located.ok) {
+		if (located.reason === "missing") return {
+			status: "absent",
+			skills: [],
+			diagnostics
+		};
+		diagnostics.push({
+			severity: "error",
+			code: located.reason === "escaped" ? "skills-dir-escapes-root" : "skills-dir-wrong-kind",
+			message: located.reason === "escaped" ? `"${PLUGIN_SKILLS_DIR}/" resolves outside the plugin root — the skills component is disabled for this plugin.` : `"${PLUGIN_SKILLS_DIR}" exists but is not a directory — the skills component is disabled for this plugin.`,
+			path: dir
+		});
+		return {
+			status: "invalid",
+			skills: [],
+			diagnostics
+		};
+	}
+	let entries;
+	try {
+		entries = await readdir(located.real);
+	} catch (err) {
+		diagnostics.push({
+			severity: "error",
+			code: "skills-dir-unreadable",
+			message: `Could not read "${PLUGIN_SKILLS_DIR}/": ${err instanceof Error ? err.message : String(err)}`,
+			path: located.real
+		});
+		return {
+			status: "invalid",
+			skills: [],
+			diagnostics
+		};
+	}
+	const skills = [];
+	for (const entry of entries.sort()) {
+		const child = join(located.real, entry);
+		const childDir = await resolvePackagePath(boundary, child, "directory");
+		if (!childDir.ok) {
+			if (childDir.reason === "escaped") diagnostics.push({
+				severity: "warning",
+				code: "skill-dir-escapes-root",
+				message: `Skipped "${PLUGIN_SKILLS_DIR}/${entry}" — it resolves outside the plugin root.`,
+				path: child
+			});
+			continue;
+		}
+		const skillFile = join(childDir.real, "SKILL.md");
+		const located2 = await resolvePackagePath(boundary, skillFile, "file");
+		if (!located2.ok) {
+			if (located2.reason === "escaped") diagnostics.push({
+				severity: "error",
+				code: "skill-escapes-root",
+				message: `Skipped skill "${entry}" — its SKILL.md resolves outside the plugin root.`,
+				path: skillFile
+			});
+			else if (located2.reason === "wrong-kind") diagnostics.push({
+				severity: "warning",
+				code: "skill-file-wrong-kind",
+				message: `Skipped "${PLUGIN_SKILLS_DIR}/${entry}" — its SKILL.md is not a regular file.`,
+				path: skillFile
+			});
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = await parseSkillFile(located2.real, { source });
+		} catch (err) {
+			diagnostics.push({
+				severity: "error",
+				code: "skill-unreadable",
+				message: `Skipped skill "${entry}" — its SKILL.md could not be read: ${err instanceof Error ? err.message : String(err)}`,
+				path: located2.real
+			});
+			continue;
+		}
+		if (!parsed) {
+			diagnostics.push({
+				severity: "error",
+				code: "skill-invalid",
+				message: `Skipped skill "${entry}" — its SKILL.md is not a valid Agent Skill (missing description, or unparseable frontmatter).`,
+				path: located2.real
+			});
+			continue;
+		}
+		skills.push(stamp(parsed, {
+			pluginName,
+			namePrefix,
+			entry,
+			diagnostics
+		}));
+	}
+	return {
+		status: "loaded",
+		skills,
+		diagnostics
+	};
+}
+/**
+* Attach plugin provenance and apply the optional name prefix.
+*
+* Provenance goes in `metadata` under the `zidane.` prefix the Agent Skills
+* spec reserves for client-specific keys (see `../skills/types.ts`), so the
+* skill stays spec-conformant while a host UI can still say which plugin
+* shipped it.
+*/
+function stamp(skill, ctx) {
+	const name = ctx.namePrefix ? `${ctx.namePrefix}-${skill.name}` : skill.name;
+	if (name.length > SKILL_NAME_MAX) ctx.diagnostics.push({
+		severity: "warning",
+		code: "skill-name-too-long",
+		message: `Prefixed skill name "${name}" exceeds the ${SKILL_NAME_MAX}-character spec limit. Loading anyway.`
+	});
+	return {
+		...skill,
+		name,
+		metadata: {
+			...skill.metadata,
+			"zidane.plugin": ctx.pluginName
+		}
+	};
+}
+//#endregion
+//#region src/plugins/load.ts
+/** Fixed location of the plugin manifest. */
+const PLUGIN_MANIFEST_FILE = "plugin.json";
+/**
+* Default parent of every plugin's `${PLUGIN_DATA}` directory.
+*
+* Deliberately OUTSIDE any plugin root: the spec requires the data directory
+* to persist across plugin updates, and an update replaces the package tree.
+* Keyed by plugin name so two copies of the same plugin (project + user)
+* share state, which is what an author storing a cache or a token expects.
+*
+* Routed through `resolveStorageDirs` rather than hardcoding `~/.zidane` so it
+* honours `ZIDANE_STORAGE_DIR` and the XDG dirs like every other persisted
+* location — otherwise an XDG-mode install would scatter plugin data into a
+* `~/.zidane` nothing else in the app touches.
+*
+* NB: `resolveStorageDirs` does NOT read `ZIDANE_PREFIX`; it defaults `prefix`
+* to `.zidane`. Callers with a configured prefix must pass it, or plugin data
+* lands beside a prefix the rest of the install doesn't use.
+*/
+function defaultPluginDataRoot(opts = {}) {
+	return join(resolveStorageDirs(opts).dataDir, "plugin-data");
+}
+/**
+* Load an Agent Plugin from `dir`.
+*
+* @returns A {@link LoadedPlugin}. Check `ok` before trusting `manifest`;
+* check `components` to tell "the plugin ships no skills" (`absent`) from
+* "its skills were rejected" (`invalid`).
+*/
+async function loadAgentPlugin(dir, opts = {}) {
+	const diagnostics = [];
+	const boundary = await resolvePluginBoundary(dir);
+	if (!boundary) return rejected(resolve(dir), resolve(dir), [{
+		severity: "error",
+		code: "plugin-root-unreadable",
+		message: `Plugin root "${dir}" does not exist or is not a directory.`,
+		path: resolve(dir)
+	}]);
+	const manifestPath = join(boundary.root, PLUGIN_MANIFEST_FILE);
+	const located = await resolvePackagePath(boundary, manifestPath, "file");
+	if (!located.ok) return rejected(boundary.dir, boundary.root, [{
+		severity: "error",
+		code: located.reason === "escaped" ? "manifest-escapes-root" : "manifest-missing",
+		message: located.reason === "escaped" ? `${PLUGIN_MANIFEST_FILE} resolves outside the plugin root.` : located.reason === "wrong-kind" ? `${PLUGIN_MANIFEST_FILE} exists but is not a regular file.` : `No ${PLUGIN_MANIFEST_FILE} at the plugin root — not an Agent Plugin.`,
+		path: manifestPath
+	}]);
+	let text;
+	try {
+		text = await readFile(located.real, "utf8");
+	} catch (err) {
+		return rejected(boundary.dir, boundary.root, [{
+			severity: "error",
+			code: "manifest-unreadable",
+			message: `Could not read ${PLUGIN_MANIFEST_FILE}: ${err instanceof Error ? err.message : String(err)}`,
+			path: located.real
+		}]);
+	}
+	const validated = parsePluginManifest(text);
+	diagnostics.push(...validated.diagnostics);
+	if (!validated.ok) return rejected(boundary.dir, boundary.root, diagnostics);
+	const { manifest } = validated;
+	const result = {
+		ok: true,
+		dir: boundary.dir,
+		root: boundary.root,
+		manifest,
+		skills: [],
+		mcpServers: [],
+		components: {
+			skills: "unsupported",
+			mcp: "unsupported"
+		},
+		diagnostics
+	};
+	if (opts.skills !== false) await guardComponent(result, "skills", diagnostics, async () => {
+		const skills = await loadPluginSkills({
+			boundary,
+			pluginName: manifest.name,
+			...opts.source !== void 0 ? { source: opts.source } : {},
+			...opts.namePrefix !== void 0 ? { namePrefix: opts.namePrefix } : {}
+		});
+		result.components.skills = skills.status;
+		result.skills = skills.skills;
+		diagnostics.push(...skills.diagnostics);
+	});
+	if (opts.mcp !== false) await guardComponent(result, "mcp", diagnostics, async () => {
+		const mcp = await loadPluginMcp({
+			boundary,
+			pluginName: manifest.name,
+			dataDir: opts.dataDir ?? join(opts.dataRoot ?? defaultPluginDataRoot(), manifest.name),
+			specVersion: manifest.specVersion,
+			...opts.namePrefix !== void 0 ? { namePrefix: opts.namePrefix } : {}
+		});
+		result.components.mcp = mcp.status;
+		result.mcpServers = mcp.servers;
+		diagnostics.push(...mcp.diagnostics);
+	});
+	return result;
+}
+/**
+* Run one component-discovery pass, converting an unexpected throw into an
+* `invalid` component plus a diagnostic. Partial results the pass already
+* assigned are dropped, so a half-discovered component never looks loaded.
+*
+* No input reachable through this module's public API is known to trigger it:
+* both component loaders catch their own filesystem and parse failures, which
+* is exactly the property their tests assert. It is kept deliberately, not
+* abandoned — `loadAgentPlugin` promises never to throw for plugin-level
+* problems, and that promise should survive a future component type whose
+* loader forgets a `try`. The observable half IS tested: see the "never throws"
+* matrix in `test/plugins/load.test.ts`.
+*/
+async function guardComponent(result, component, diagnostics, run) {
+	try {
+		await run();
+	} catch (err) {
+		result.components[component] = "invalid";
+		if (component === "skills") result.skills = [];
+		else result.mcpServers = [];
+		diagnostics.push({
+			severity: "error",
+			code: `${component}-discovery-failed`,
+			message: `Unexpected error while loading the ${component} component: ${err instanceof Error ? err.message : String(err)}`,
+			path: result.root
+		});
+	}
+}
+function rejected(dir, root, diagnostics) {
+	return {
+		ok: false,
+		dir,
+		root,
+		skills: [],
+		mcpServers: [],
+		components: {
+			skills: "unsupported",
+			mcp: "unsupported"
+		},
+		diagnostics
+	};
+}
+//#endregion
+export { PLUGIN_MCP_FILE as a, validatePluginManifest as c, isSupportedAgentPluginsVersion as d, parseSchemaId as f, PLUGIN_SKILLS_DIR as i, SUPPORTED_AGENT_PLUGINS_VERSIONS as l, defaultPluginDataRoot as n, expandPluginVars as o, resolveStorageDirs as p, loadAgentPlugin as r, parsePluginManifest as s, PLUGIN_MANIFEST_FILE as t, agentPluginsSchemaId as u };
+
+//# sourceMappingURL=plugins-2PMTVcp-.js.map