@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/normalise/sub-agents.ts

@@ -0,0 +1,184 @@
+/**
+ * Sub-agent files (`agents/*.md`) into the shape `SubAgent` takes.
+ *
+ * Cursor and Claude Code define this component; the open format does not,
+ * so `agents/` is read only when a vendor manifest is present (`detect.ts`
+ * decides) and recorded as ignored otherwise. Files come from the default
+ * `agents/` directory or, when any manifest declares `agents`, from the
+ * declared paths only (Claude's "replaces the default"), each of which may
+ * be one `.md` file or a directory of them.
+ *
+ * The body of the file is the sub-agent's prompt. A body under
+ * `SUB_AGENT_INSTRUCTIONS_MIN` characters is refused, because that is the
+ * proto's floor for `SubAgent.instructions` and a parser that let it through
+ * would add a second silent path after the runner's own (which drops a
+ * sub-agent whose model is unregistered). Frontmatter is optional (a bare
+ * prompt is named after its file, Claude's rule) but must parse when
+ * present: Claude degrades an unparseable header to a file-named agent with
+ * every field ignored, and a faithful install is better refused than
+ * quietly stripped.
+ *
+ * `model` is classified into an alias, never a model id (see `ModelHint`).
+ * Claude `skills:` names are matched against the plugin's own skills. Every
+ * other frontmatter field (`tools`, `disallowedTools`, `effort`, `maxTurns`,
+ * `readonly`, `is_background`, `memory`, `isolation`, ...) is a warning,
+ * once per field per agent: they configure the IDE's loop, not the
+ * sub-agent's prompt.
+ */
+
+import type { ManifestSet } from "../detect.js";
+import { readText } from "../documents.js";
+import { basename, comparePaths, joinPath, type PluginFileIndex } from "../files.js";
+import { extractFrontmatter, parseFrontmatter } from "../frontmatter.js";
+import type { Findings } from "../messages.js";
+import type { ModelAlias, ModelHint, PluginSkill, PluginSubAgent } from "../types.js";
+
+export const DEFAULT_AGENTS_DIR = "agents";
+
+/** The proto's `SubAgent.instructions` `min_len`. */
+export const SUB_AGENT_INSTRUCTIONS_MIN = 10;
+
+const READ_FIELDS: ReadonlySet<string> = new Set(["name", "description", "model", "skills"]);
+
+export function normaliseSubAgents(
+  index: PluginFileIndex,
+  set: ManifestSet,
+  skills: readonly PluginSkill[],
+  findings: Findings,
+): readonly PluginSubAgent[] {
+  if (!set.readsAgents) return [];
+  const skillNames = new Set(skills.map((skill) => skill.name));
+  const agents: PluginSubAgent[] = [];
+  const seen = new Set<string>();
+  for (const path of discoverAgentFiles(index, set, findings)) {
+    const agent = readSubAgent(index, path, skillNames, findings);
+    if (agent === undefined) continue;
+    if (seen.has(agent.name)) {
+      findings.error("sub-agent-name-duplicate", { subject: agent.name, path });
+      continue;
+    }
+    seen.add(agent.name);
+    agents.push(agent);
+  }
+  return agents;
+}
+
+function discoverAgentFiles(index: PluginFileIndex, set: ManifestSet, findings: Findings): readonly string[] {
+  const files = new Set<string>();
+  const addMarkdownUnder = (dir: string): void => {
+    for (const name of index.childFiles(dir)) {
+      if (name.endsWith(".md")) files.add(joinPath(dir, name));
+    }
+  };
+
+  const declared = set.manifests.flatMap((m) => m.agentPaths ?? []);
+  if (set.manifests.every((m) => m.agentPaths === undefined)) {
+    addMarkdownUnder(DEFAULT_AGENTS_DIR);
+  }
+  for (const { path, manifest } of declared) {
+    if (path !== "" && index.has(path) && path.endsWith(".md")) {
+      files.add(path);
+    } else if (index.isDirectory(path)) {
+      addMarkdownUnder(path);
+    } else {
+      findings.warn("path-missing", { path: manifest, subject: path === "" ? "." : `./${path}` });
+    }
+  }
+  return [...files].sort(comparePaths);
+}
+
+function readSubAgent(
+  index: PluginFileIndex,
+  path: string,
+  skillNames: ReadonlySet<string>,
+  findings: Findings,
+): PluginSubAgent | undefined {
+  const text = readText(index, path, "subAgent", findings);
+  if (text === undefined) return undefined;
+
+  const extracted = extractFrontmatter(text);
+  let fieldsMap: Readonly<Record<string, unknown>> = {};
+  let body = text;
+  if (extracted.ok) {
+    const parsed = parseFrontmatter(extracted.yaml);
+    if (!parsed.ok) {
+      findings.error("sub-agent-frontmatter-unreadable", { path, detail: parsed.detail });
+      return undefined;
+    }
+    fieldsMap = parsed.fields;
+    body = extracted.body;
+  } else if (extracted.reason === "unclosed") {
+    findings.error("sub-agent-frontmatter-unreadable", { path, detail: "the frontmatter is not closed (missing the closing '---')" });
+    return undefined;
+  }
+
+  const stem = basename(path).replace(/\.md$/, "");
+  let name: string;
+  if (typeof fieldsMap["name"] === "string" && fieldsMap["name"] !== "") {
+    name = fieldsMap["name"];
+  } else {
+    name = stem;
+    findings.warn("sub-agent-name-defaulted", { path, subject: name });
+  }
+
+  const instructions = body.trim();
+  if (instructions.length < SUB_AGENT_INSTRUCTIONS_MIN) {
+    findings.error("sub-agent-instructions-short", { path, subject: name, detail: String(SUB_AGENT_INSTRUCTIONS_MIN) });
+    return undefined;
+  }
+
+  const description = fieldsMap["description"];
+  const requested = fieldsMap["skills"];
+  const matchedSkills: string[] = [];
+  if (Array.isArray(requested)) {
+    for (const skill of requested) {
+      if (typeof skill !== "string") continue;
+      if (skillNames.has(skill)) matchedSkills.push(skill);
+      else findings.warn("sub-agent-skill-unknown", { path, subject: name, detail: skill });
+    }
+  }
+
+  let modelHint: ModelHint | undefined;
+  const model = fieldsMap["model"];
+  if (typeof model === "string" && model.trim() !== "") {
+    modelHint = classifyModel(model);
+    if (modelHint.alias === "unknown") findings.warn("sub-agent-model-unknown", { path, subject: name, detail: model });
+  }
+
+  for (const field of Object.keys(fieldsMap)) {
+    if (!READ_FIELDS.has(field)) findings.warn("sub-agent-field-ignored", { path, subject: name, detail: field });
+  }
+
+  return {
+    name,
+    ...(typeof description === "string" && description !== "" && { description }),
+    instructions,
+    skillNames: matchedSkills,
+    ...(modelHint !== undefined && { modelHint }),
+    path,
+  };
+}
+
+/**
+ * A dialect's `model` value to an alias. Cursor writes `fast` and
+ * `inherit`; Claude writes `sonnet`, `opus`, `haiku`, `inherit` or a full
+ * model id, which contains one of those family names. Anything else
+ * (Cursor's `grok-4.6[effort=xhigh]`, a vendor id Stigmer does not serve)
+ * is `unknown` with the raw text kept for the installer's warning.
+ */
+export function classifyModel(raw: string): ModelHint {
+  const value = raw.trim().toLowerCase();
+  const alias: ModelAlias =
+    value === "inherit"
+      ? "inherit"
+      : value === "fast"
+        ? "fast"
+        : value.includes("haiku")
+          ? "haiku"
+          : value.includes("sonnet")
+            ? "sonnet"
+            : value.includes("opus")
+              ? "opus"
+              : "unknown";
+  return { raw, alias };
+}

package/src/normalise/variables.ts

@@ -0,0 +1,161 @@
+/**
+ * Variable declarations, from the dialects that have them, reconciled with
+ * the references the servers make.
+ *
+ * Cursor declares `variables` as a JSON Schema object with no sensitivity
+ * flag, so every Cursor variable is a secret on Stigmer (a token treated as
+ * plain text is the costly mistake; a region name treated as a secret is
+ * an inconvenience). Claude declares `userConfig` entries with `sensitive`
+ * and `required`, plus `default`, `options`, `multiple`, `min`, `max` and
+ * the `directory`, `file`, `number`, `boolean` types, none of which a
+ * Stigmer variable carries (values are strings supplied by the user, and a
+ * local path means nothing in the sandbox); each is warned once.
+ *
+ * Reconciliation is what makes an imported server start: the runner
+ * filters a stdio server's environment to its declared keys and resolves
+ * `${VAR}` in headers and arguments strictly, so a variable a server
+ * references but no manifest declares would never reach it. Such a variable
+ * is declared here as a required secret, with a warning naming the server.
+ * A declared variable no server references is warned too; it is not wrong,
+ * only useless.
+ */
+
+import type { ManifestSet } from "../detect.js";
+import { describeValue, fields, isJsonObject, isStringArray, type JsonObject } from "../documents.js";
+import type { Findings } from "../messages.js";
+import { VARIABLE_NAME_PATTERN } from "../placeholders.js";
+import type { PluginVariable } from "../types.js";
+import type { McpServersResult } from "./mcp-servers.js";
+
+export function normaliseVariables(set: ManifestSet, servers: McpServersResult, findings: Findings): readonly PluginVariable[] {
+  const declared = new Map<string, PluginVariable>();
+  const declaredIn = new Map<string, string>();
+  for (const manifest of set.manifests) {
+    const declaration = manifest.variables;
+    if (declaration === undefined) continue;
+    const variables =
+      declaration.dialect === "cursor"
+        ? readCursorVariables(declaration.value, declaration.manifest, findings)
+        : readClaudeVariables(declaration.value, declaration.manifest, findings);
+    for (const variable of variables) {
+      // Two manifests declaring one name: the identity manifest's wins.
+      if (declared.has(variable.name)) continue;
+      declared.set(variable.name, variable);
+      declaredIn.set(variable.name, declaration.manifest);
+    }
+  }
+
+  const referencedBy = new Map<string, string>();
+  for (const server of servers.servers) {
+    for (const name of server.env) {
+      if (!referencedBy.has(name)) referencedBy.set(name, server.name);
+    }
+  }
+
+  // A refused server's references are unknown, so an "unreferenced"
+  // warning would be a consequence of the refusal, not advice.
+  if (servers.refused === 0) {
+    for (const [name, variable] of declared) {
+      if (!referencedBy.has(name)) {
+        findings.warn("variable-unreferenced", { subject: variable.name, path: declaredIn.get(name) });
+      }
+    }
+  }
+
+  const inferred: PluginVariable[] = [];
+  for (const [name, server] of [...referencedBy].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    if (declared.has(name)) continue;
+    findings.warn("variable-inferred", { subject: name, detail: server });
+    inferred.push({ name, isSecret: true, optional: false, declaredBy: "inferred" });
+  }
+
+  return [...declared.values(), ...inferred];
+}
+
+/**
+ * Cursor: `{ type: "object", properties: { NAME: { type, title, description } }, required: [NAME] }`.
+ */
+function readCursorVariables(value: unknown, manifest: string, findings: Findings): readonly PluginVariable[] {
+  if (!isJsonObject(value) || value["type"] !== "object") {
+    findings.error("manifest-field-type", { path: manifest, subject: "variables", detail: "a JSON Schema object with type 'object'" });
+    return [];
+  }
+  const properties = value["properties"] ?? {};
+  if (!isJsonObject(properties)) {
+    findings.error("manifest-field-type", { path: manifest, subject: "variables.properties", detail: "an object" });
+    return [];
+  }
+  const required = value["required"] ?? [];
+  if (!isStringArray(required)) {
+    findings.error("manifest-field-type", { path: manifest, subject: "variables.required", detail: "an array of strings" });
+    return [];
+  }
+
+  const variables: PluginVariable[] = [];
+  for (const [name, schema] of fields(properties)) {
+    if (!VARIABLE_NAME_PATTERN.test(name)) {
+      findings.error("variable-name-invalid", { subject: name, path: manifest });
+      continue;
+    }
+    const property = isJsonObject(schema) ? schema : {};
+    const type = property["type"];
+    if (type !== undefined && type !== "string") {
+      findings.warn("variable-type-narrowed", { subject: name, path: manifest, detail: describeValue(type) });
+    }
+    if (property["default"] !== undefined) findings.warn("variable-default-dropped", { subject: name, path: manifest });
+    if (property["enum"] !== undefined) findings.warn("variable-option-dropped", { subject: name, path: manifest, detail: "enum" });
+    const description = describe(property);
+    variables.push({
+      name,
+      ...(description !== undefined && { description }),
+      isSecret: true,
+      optional: !required.includes(name),
+      declaredBy: "cursor",
+    });
+  }
+  return variables;
+}
+
+/**
+ * Claude: `{ KEY: { type, title, description, sensitive, required, default, options, multiple, min, max } }`.
+ */
+function readClaudeVariables(value: unknown, manifest: string, findings: Findings): readonly PluginVariable[] {
+  if (!isJsonObject(value)) {
+    findings.error("manifest-field-type", { path: manifest, subject: "userConfig", detail: "an object" });
+    return [];
+  }
+  const variables: PluginVariable[] = [];
+  for (const [name, entry] of fields(value)) {
+    if (!VARIABLE_NAME_PATTERN.test(name)) {
+      findings.error("variable-name-invalid", { subject: name, path: manifest });
+      continue;
+    }
+    if (!isJsonObject(entry)) {
+      findings.error("manifest-field-type", { path: manifest, subject: `userConfig.${name}`, detail: "an object" });
+      continue;
+    }
+    const type = entry["type"];
+    if (type !== undefined && type !== "string") {
+      findings.warn("variable-type-narrowed", { subject: name, path: manifest, detail: describeValue(type) });
+    }
+    if (entry["default"] !== undefined) findings.warn("variable-default-dropped", { subject: name, path: manifest });
+    for (const option of ["options", "multiple", "min", "max"]) {
+      if (entry[option] !== undefined) findings.warn("variable-option-dropped", { subject: name, path: manifest, detail: option });
+    }
+    const description = describe(entry);
+    variables.push({
+      name,
+      ...(description !== undefined && { description }),
+      isSecret: entry["sensitive"] === true,
+      optional: entry["required"] !== true,
+      declaredBy: "claude",
+    });
+  }
+  return variables;
+}
+
+/** `title` and `description` joined, whichever are present. */
+function describe(entry: JsonObject): string | undefined {
+  const parts = [entry["title"], entry["description"]].filter((part): part is string => typeof part === "string" && part !== "");
+  return parts.length === 0 ? undefined : parts.join(": ");
+}

package/src/outcome.ts

@@ -0,0 +1,122 @@
+/**
+ * The outcome of reading a package and the closed vocabulary of findings.
+ *
+ * The shape is the server's `ConnectRunOutcome`: a discriminated union on
+ * `ok`, with a closed `kind` union behind the failure arm, so a consumer
+ * switches on kinds and the compiler closes the switch. An error refuses the
+ * package; a warning never does. Both are `PluginFinding`s with the same
+ * fields, so one renderer prints both.
+ *
+ * Two error postures meet here and the header of each module states which
+ * applies. Where the open format tells a client to skip a broken component
+ * and keep loading, Stigmer refuses the package: an installed agent that
+ * quietly lacks a server or a sub-agent is worse than a refused install.
+ * But the reader keeps scanning past a fatal finding so one run reports
+ * every problem and an author fixes them in one pass.
+ *
+ * Every kind has exactly one sentence, in `messages.ts`, and the adversarial
+ * suite has exactly one fixture per kind. Adding a kind means adding both.
+ */
+
+import type { PluginPackage } from "./types.js";
+
+export type PluginErrorKind =
+  // Manifests
+  | "no-manifest"
+  | "manifest-unreadable"
+  | "manifest-schema-missing"
+  | "manifest-schema-unsupported"
+  | "manifest-name-missing"
+  | "manifest-name-invalid"
+  | "manifest-name-conflict"
+  | "manifest-field-type"
+  // Paths
+  | "path-not-relative"
+  | "path-escapes-root"
+  | "path-glob-unsupported"
+  | "path-uncontained"
+  | "document-too-large"
+  // Skills
+  | "skill-frontmatter-missing"
+  | "skill-frontmatter-unclosed"
+  | "skill-frontmatter-unreadable"
+  | "skill-name-invalid"
+  | "skill-name-duplicate"
+  // MCP configuration files
+  | "mcp-config-unreadable"
+  | "mcp-config-shape"
+  | "mcp-config-schema-missing"
+  | "mcp-config-schema-unsupported"
+  | "mcp-config-field-unknown"
+  // MCP server entries
+  | "mcp-server-shape"
+  | "mcp-server-type-missing"
+  | "mcp-server-transport-unknown"
+  | "mcp-server-type-ambiguous"
+  | "mcp-server-type-unknown"
+  | "mcp-server-field-unknown"
+  | "mcp-server-field-type"
+  | "mcp-server-url-missing"
+  | "mcp-server-url-invalid"
+  | "mcp-server-url-variable"
+  | "mcp-server-command-missing"
+  | "mcp-server-command-invalid"
+  | "mcp-server-command-relative"
+  | "mcp-server-plugin-root-reference"
+  | "mcp-server-cwd-unsupported"
+  | "mcp-server-env-literal"
+  | "mcp-server-env-rename"
+  | "mcp-server-name-duplicate"
+  | "mcp-server-header-duplicate"
+  | "mcp-server-header-invalid"
+  // Sub-agents
+  | "sub-agent-frontmatter-unreadable"
+  | "sub-agent-instructions-short"
+  | "sub-agent-name-duplicate"
+  // Variables
+  | "variable-name-invalid"
+  // The ai.stigmer/ overlay
+  | "overlay-server-unknown"
+  | "overlay-document-unknown";
+
+export type PluginWarningKind =
+  | "manifest-field-unknown"
+  | "manifest-extensions-invalid"
+  | "path-missing"
+  | "skill-name-defaulted"
+  | "skill-name-differs-from-directory"
+  | "skill-description-missing"
+  | "mcp-config-field-ignored"
+  | "mcp-server-sse-mapped"
+  | "mcp-server-field-ignored"
+  | "mcp-server-auth-ignored"
+  | "variable-inferred"
+  | "variable-unreferenced"
+  | "variable-default-dropped"
+  | "variable-type-narrowed"
+  | "variable-option-dropped"
+  | "sub-agent-name-defaulted"
+  | "sub-agent-skill-unknown"
+  | "sub-agent-model-unknown"
+  | "sub-agent-field-ignored";
+
+export type PluginFindingKind = PluginErrorKind | PluginWarningKind;
+
+export interface PluginFinding {
+  readonly kind: PluginFindingKind;
+  /** The file, or the declared path, the finding is about. */
+  readonly path?: string;
+  /** The skill, server, sub-agent, variable or field the finding names. */
+  readonly subject?: string;
+  /** A second identifier the sentence needs (a field name, a parser's own message). */
+  readonly detail?: string;
+  /** The one sentence for this kind, from `messages.ts`. */
+  readonly message: string;
+}
+
+/** What `read` needs to compose a finding: everything but the sentence. */
+export type FindingContext = Pick<PluginFinding, "path" | "subject" | "detail">;
+
+export type PluginReadOutcome =
+  | { readonly ok: true; readonly plugin: PluginPackage; readonly warnings: readonly PluginFinding[] }
+  | { readonly ok: false; readonly errors: readonly PluginFinding[]; readonly warnings: readonly PluginFinding[] };

package/src/placeholders.ts

@@ -0,0 +1,74 @@
+/**
+ * The `${VAR}` vocabulary: what counts as a variable reference, what counts
+ * as a reference to the plugin's own files, and the Claude rewrite.
+ *
+ * `PLACEHOLDER_PATTERN` is the runner's own scanner, verbatim: the runner
+ * resolves `${VAR}` strictly in a server's headers and arguments and refuses
+ * to start a server with an unresolved one, so this is the definition of "a
+ * reference" in every dialect, including the open format whose text forbids
+ * expansion in headers. A plugin's `${API_KEY}` in a header means "the
+ * caller's API_KEY" on Stigmer whichever tool wrote it.
+ *
+ * Claude's `${user_config.KEY}` carries a dot the runner's scanner would
+ * never match, so it is rewritten to `${KEY}` before anything reads it; the
+ * rewrite is what makes a Claude plugin's server start, not a courtesy.
+ *
+ * The plugin-root placeholders are the one class the library refuses: the
+ * runner mounts nothing from a plugin, so a server that reaches for
+ * `${PLUGIN_ROOT}` (any dialect's spelling) can never find what it points
+ * at. The set is checked before the generic scan because `${PLUGIN_ROOT}`
+ * also matches the generic pattern.
+ */
+
+/** The runner's `${VAR_NAME}` scanner (`shared/placeholder-resolver.ts`). */
+export const PLACEHOLDER_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/** A variable name the runner's scanner can reference. */
+export const VARIABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const USER_CONFIG_PATTERN = /\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/**
+ * Every spelling of "the plugin's own directory" across the dialects:
+ * the open format's, Claude Code's (plus its project directory), Cursor's.
+ */
+export const PLUGIN_ROOT_PLACEHOLDERS: ReadonlySet<string> = new Set([
+  "${PLUGIN_ROOT}",
+  "${PLUGIN_DATA}",
+  "${CLAUDE_PLUGIN_ROOT}",
+  "${CLAUDE_PLUGIN_DATA}",
+  "${CLAUDE_PROJECT_DIR}",
+  "${CURSOR_PLUGIN_ROOT}",
+]);
+
+/** The reserved environment names the open format forbids a server's `env` to set. */
+export const PLUGIN_ROOT_ENV_NAMES: ReadonlySet<string> = new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
+
+/** `${user_config.KEY}` -> `${KEY}`. */
+export function rewriteUserConfig(value: string): string {
+  return value.replace(USER_CONFIG_PATTERN, (_match, key: string) => `\${${key}}`);
+}
+
+/** The first plugin-root placeholder in `value`, or `undefined`. */
+export function findPluginRootPlaceholder(value: string): string | undefined {
+  for (const placeholder of PLUGIN_ROOT_PLACEHOLDERS) {
+    if (value.includes(placeholder)) return placeholder;
+  }
+  return undefined;
+}
+
+/** The variable names referenced in `value`, in order of appearance, deduplicated. */
+export function referencedVariables(value: string): readonly string[] {
+  const names: string[] = [];
+  for (const match of value.matchAll(PLACEHOLDER_PATTERN)) {
+    const name = match[1];
+    if (name !== undefined && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/** The variable name when `value` is exactly one placeholder and nothing else; otherwise `undefined`. */
+export function singlePlaceholderName(value: string): string | undefined {
+  const match = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(value);
+  return match?.[1];
+}

package/src/read-plugin-package.ts

@@ -0,0 +1,74 @@
+/**
+ * The one entry: a `PluginFiles` in, a `PluginReadOutcome` out.
+ *
+ * The read is a fixed sequence, each stage a pure function over the index
+ * and the stages before it: containment of the listed paths; manifest
+ * detection and identity; skills; MCP servers; variables (which need the
+ * servers' references); sub-agents (which need the skills' names); the
+ * `ai.stigmer/` overlay (which needs the servers' names); the ignored
+ * components. Every stage records findings and keeps going, so the outcome
+ * names every problem in the package at once, and the plugin is returned
+ * only when no stage refused.
+ *
+ * Nothing here throws on a plugin's content. A throw means a reader broke
+ * its contract (a listed path that cannot be read) or the library has a bug.
+ */
+
+import { detectManifests } from "./detect.js";
+import { isContainedPath, PluginFileIndex, type PluginFiles } from "./files.js";
+import { Findings } from "./messages.js";
+import { dedupeIgnored, ignoredOnDisk } from "./normalise/ignored.js";
+import { normaliseMcpServers } from "./normalise/mcp-servers.js";
+import { normaliseOverlay } from "./normalise/overlay.js";
+import { normaliseSkills } from "./normalise/skills.js";
+import { normaliseSubAgents } from "./normalise/sub-agents.js";
+import { normaliseVariables } from "./normalise/variables.js";
+import type { PluginReadOutcome } from "./outcome.js";
+import type { PluginPackage } from "./types.js";
+
+export function readPluginPackage(files: PluginFiles): PluginReadOutcome {
+  const findings = new Findings();
+
+  for (const entry of files.entries) {
+    if (!isContainedPath(entry.path)) findings.error("path-uncontained", { path: entry.path });
+  }
+  const index = new PluginFileIndex(files);
+
+  const set = detectManifests(index, findings);
+  if (set === undefined) {
+    return { ok: false, errors: findings.errors, warnings: findings.warnings };
+  }
+
+  const skills = normaliseSkills(index, set, findings);
+  const servers = normaliseMcpServers(index, set.mcpSources, findings);
+  const mcpServers = servers.servers;
+  const variables = normaliseVariables(set, servers, findings);
+  const subAgents = normaliseSubAgents(index, set, skills, findings);
+  const overlay = normaliseOverlay(index, servers.declaredNames, findings);
+  const ignored = dedupeIgnored([ignoredOnDisk(index, set.readsAgents), ...set.manifests.map((m) => m.ignored)]);
+
+  if (findings.errors.length > 0 || set.name === undefined) {
+    return { ok: false, errors: findings.errors, warnings: findings.warnings };
+  }
+
+  const identity = set.manifests[0]?.identity ?? {};
+  const plugin: PluginPackage = {
+    name: set.name,
+    ...(identity.version !== undefined && { version: identity.version }),
+    ...(identity.description !== undefined && { description: identity.description }),
+    ...(identity.author !== undefined && { author: identity.author }),
+    ...(identity.homepage !== undefined && { homepage: identity.homepage }),
+    ...(identity.repository !== undefined && { repository: identity.repository }),
+    ...(identity.license !== undefined && { license: identity.license }),
+    keywords: identity.keywords ?? [],
+    dialect: set.dialect,
+    manifestsFound: set.manifests.map((m) => m.path),
+    skills,
+    mcpServers,
+    subAgents,
+    variables,
+    overlay,
+    ignored,
+  };
+  return { ok: true, plugin, warnings: findings.warnings };
+}