@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/frontmatter.ts

@@ -0,0 +1,70 @@
+/**
+ * YAML frontmatter extraction for `SKILL.md` and sub-agent files, and the
+ * skill name rule.
+ *
+ * The delimiter discipline is the server's skill push gate's: the file must
+ * open with `---` on its first line and close with `---` on a line of its
+ * own, both compared after trimming whitespace. Extraction and parsing are
+ * separate steps because the two callers differ on what a missing block
+ * means: a `SKILL.md` without frontmatter is refused (the Agent Skills
+ * format requires it), while a sub-agent file without frontmatter is a
+ * prompt named after its file (the Claude Code posture).
+ *
+ * `SKILL_NAME_PATTERN` is the server's rule for a skill name (kebab-case,
+ * optionally dot-scoped), a strict superset of the Agent Skills rule
+ * (lowercase alphanumerics and hyphens), so no skill valid under the open
+ * format is refused here. This module is meant to become the pattern's one
+ * home; the server's `frontmatter.ts` carries the same regex today.
+ */
+
+import { parse as parseYaml } from "yaml";
+
+import { isJsonObject, type JsonObject } from "./documents.js";
+
+/**
+ * Kebab-case, optionally scoped with dot-separated namespaces. Every
+ * segment between separators is alphanumeric, so a name cannot start or end
+ * with a separator or contain consecutive separators. The derived slug
+ * renders dots as hyphens.
+ */
+export const SKILL_NAME_PATTERN = /^[a-z0-9]+([.-][a-z0-9]+)*$/;
+
+export type FrontmatterExtraction =
+  | { readonly ok: true; readonly yaml: string; readonly body: string }
+  | { readonly ok: false; readonly reason: "missing" | "unclosed" };
+
+/** Split a document into its frontmatter YAML and its body. */
+export function extractFrontmatter(content: string): FrontmatterExtraction {
+  const lines = content.split(/\r?\n/);
+  if (lines.length === 0 || lines[0]?.trim() !== "---") {
+    return { ok: false, reason: "missing" };
+  }
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      return { ok: true, yaml: lines.slice(1, i).join("\n"), body: lines.slice(i + 1).join("\n") };
+    }
+  }
+  return { ok: false, reason: "unclosed" };
+}
+
+export type FrontmatterParse =
+  | { readonly ok: true; readonly fields: JsonObject }
+  | { readonly ok: false; readonly detail: string };
+
+/**
+ * Parse frontmatter YAML into a field map. An empty block is an empty map
+ * (the caller decides whether required fields are missing); a scalar or a
+ * list where a map was expected is a parse failure with its own detail.
+ * `yaml`'s defaults are the safe ones: no custom tags, aliases capped.
+ */
+export function parseFrontmatter(yaml: string): FrontmatterParse {
+  let value: unknown;
+  try {
+    value = parseYaml(yaml);
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+  if (value === null || value === undefined) return { ok: true, fields: {} };
+  if (!isJsonObject(value)) return { ok: false, detail: "the frontmatter is not a mapping" };
+  return { ok: true, fields: value };
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `@stigmer/plugin-package`: the public surface.
+ *
+ * `readPluginPackage` is the entry; everything else here is what a consumer
+ * needs to supply its input (`PluginFiles`, the caps), route a directory
+ * (`MANIFEST_LOCATIONS`, `hasPluginManifest`), or render the outcome (the
+ * finding kinds and `isErrorKind`). The dialect readers and normalisers are
+ * internal: a consumer never composes a partial read.
+ */
+
+export { hasPluginManifest, isValidPluginName } from "./detect.js";
+export {
+  comparePaths,
+  inMemoryPluginFiles,
+  isContainedPath,
+  PLUGIN_DOCUMENT_LIMITS,
+  resolveDeclaredPath,
+  type DeclaredPathOutcome,
+  type PluginDocumentClass,
+  type PluginFileEntry,
+  type PluginFiles,
+} from "./files.js";
+export { SKILL_NAME_PATTERN } from "./frontmatter.js";
+export {
+  AGENT_PLUGINS_MANIFEST_SCHEMA,
+  AGENT_PLUGINS_MCP_SCHEMA,
+  errorMessage,
+  isErrorKind,
+  MANIFEST_LOCATIONS,
+  warningMessage,
+} from "./messages.js";
+export { SUB_AGENT_INSTRUCTIONS_MIN, classifyModel } from "./normalise/sub-agents.js";
+export { PLACEHOLDER_PATTERN, VARIABLE_NAME_PATTERN } from "./placeholders.js";
+export type {
+  FindingContext,
+  PluginErrorKind,
+  PluginFinding,
+  PluginFindingKind,
+  PluginReadOutcome,
+  PluginWarningKind,
+} from "./outcome.js";
+export { readPluginPackage } from "./read-plugin-package.js";
+export type {
+  IgnoredComponent,
+  IgnoredComponentKind,
+  ModelAlias,
+  ModelHint,
+  OverlayDocument,
+  OverlayNamedDocument,
+  OverlayServerDocument,
+  PluginAuthor,
+  PluginDialect,
+  PluginMcpServer,
+  PluginPackage,
+  PluginSkill,
+  PluginSubAgent,
+  PluginVariable,
+  StigmerOverlay,
+} from "./types.js";

package/src/messages.ts

@@ -0,0 +1,206 @@
+/**
+ * The one sentence for every finding kind, and the collector that composes
+ * findings from a kind and its context.
+ *
+ * Copy lives here and nowhere else: the CLI and the server print these
+ * sentences verbatim, so a plugin refused offline is refused by the server
+ * with the same words, and a consumer never composes refusal copy of its
+ * own. Every sentence says what is wrong and, where the fix is not obvious,
+ * what Stigmer needs instead. Identifiers are single-quoted (the ts-server
+ * quoting rule for new copy). The `Record` types are exhaustive over the
+ * kind unions, so a kind without a sentence does not compile.
+ */
+
+import type {
+  FindingContext,
+  PluginErrorKind,
+  PluginFinding,
+  PluginFindingKind,
+  PluginWarningKind,
+} from "./outcome.js";
+
+/** The canonical `$schema` identifiers the open format pins per version. */
+export const AGENT_PLUGINS_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export const AGENT_PLUGINS_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+
+/** The four manifest locations, in the precedence the reader applies when there is no root manifest. */
+export const MANIFEST_LOCATIONS = {
+  "agent-plugins": "plugin.json",
+  claude: ".claude-plugin/plugin.json",
+  cursor: ".cursor-plugin/plugin.json",
+  codex: ".codex-plugin/plugin.json",
+} as const;
+
+const q = (value: string | undefined): string => `'${value ?? ""}'`;
+const at = (path: string | undefined): string => (path === undefined ? "" : ` in ${q(path)}`);
+
+type Sentence = (ctx: FindingContext) => string;
+
+const ERROR_MESSAGES: Record<PluginErrorKind, Sentence> = {
+  "no-manifest": () =>
+    `no plugin manifest found: expected one of ${Object.values(MANIFEST_LOCATIONS)
+      .map((p) => q(p))
+      .join(", ")}`,
+  "manifest-unreadable": (c) => `manifest ${q(c.path)} is not valid JSON: ${c.detail ?? "parse error"}`,
+  "manifest-schema-missing": (c) =>
+    `manifest ${q(c.path)} is missing the required '$schema' field; an Agent Plugins manifest declares ${q(AGENT_PLUGINS_MANIFEST_SCHEMA)}`,
+  "manifest-schema-unsupported": (c) =>
+    `manifest ${q(c.path)} declares an unsupported '$schema' ${q(c.detail)}; this reader supports ${q(AGENT_PLUGINS_MANIFEST_SCHEMA)}`,
+  "manifest-name-missing": (c) => `manifest ${q(c.path)} is missing the required 'name' field`,
+  "manifest-name-invalid": (c) =>
+    `plugin name ${q(c.subject)}${at(c.path)} is invalid: 1 to 64 characters of lowercase letters, digits, hyphens and periods, starting and ending alphanumeric, with no '--' or '..'`,
+  "manifest-name-conflict": (c) =>
+    `manifests disagree on the plugin name: ${q(c.subject)} in ${q(c.path)} versus ${c.detail ?? "another manifest"}`,
+  "manifest-field-type": (c) => `field ${q(c.subject)}${at(c.path)} has the wrong type: expected ${c.detail ?? "a different type"}`,
+
+  "path-not-relative": (c) =>
+    `path ${q(c.subject)}${at(c.path)} must be plugin-relative and begin with './'`,
+  "path-escapes-root": (c) => `path ${q(c.subject)}${at(c.path)} escapes the plugin root`,
+  "path-glob-unsupported": (c) =>
+    `path ${q(c.subject)}${at(c.path)} is a glob pattern; declare directories and files by path`,
+  "path-uncontained": (c) => `the reader listed a path outside the plugin root: ${q(c.path)}`,
+  "document-too-large": (c) =>
+    `${q(c.path)} is ${c.subject ?? "too many"} bytes, over the ${c.detail ?? ""}-byte limit for this kind of document`,
+
+  "skill-frontmatter-missing": (c) => `${q(c.path)} must start with YAML frontmatter ('---')`,
+  "skill-frontmatter-unclosed": (c) => `${q(c.path)} frontmatter is not closed (missing the closing '---')`,
+  "skill-frontmatter-unreadable": (c) => `${q(c.path)} frontmatter is not valid YAML: ${c.detail ?? "parse error"}`,
+  "skill-name-invalid": (c) =>
+    `skill name ${q(c.subject)}${at(c.path)} is invalid: lowercase letters, digits and hyphens, optionally dot-scoped, with every segment alphanumeric`,
+  "skill-name-duplicate": (c) => `skill name ${q(c.subject)} appears more than once (again${at(c.path)})`,
+
+  "mcp-config-unreadable": (c) => `MCP configuration ${q(c.path)} is not valid JSON: ${c.detail ?? "parse error"}`,
+  "mcp-config-shape": (c) => `MCP configuration ${q(c.path)} must be an object with an 'mcpServers' object`,
+  "mcp-config-schema-missing": (c) =>
+    `MCP configuration ${q(c.path)} is missing the required '$schema' field; an Agent Plugins configuration declares ${q(AGENT_PLUGINS_MCP_SCHEMA)}`,
+  "mcp-config-schema-unsupported": (c) =>
+    `MCP configuration ${q(c.path)} declares an unsupported '$schema' ${q(c.detail)}; this reader supports ${q(AGENT_PLUGINS_MCP_SCHEMA)}`,
+  "mcp-config-field-unknown": (c) =>
+    `MCP configuration ${q(c.path)} has an unexpected top-level field ${q(c.subject)}; only '$schema' and 'mcpServers' are allowed`,
+
+  "mcp-server-shape": (c) => `MCP server ${q(c.subject)}${at(c.path)} must be an object`,
+  "mcp-server-type-missing": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} is missing the 'type' field the Agent Plugins format requires ('stdio', 'streamable-http' or 'sse')`,
+  "mcp-server-transport-unknown": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has no 'type' and neither a 'command' nor a 'url' to infer it from`,
+  "mcp-server-type-ambiguous": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} declares both 'command' and 'url'; a server is either stdio or HTTP`,
+  "mcp-server-type-unknown": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has an unknown 'type' ${q(c.detail)}; expected 'stdio', 'http', 'streamable-http' or 'sse'`,
+  "mcp-server-field-unknown": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has a field ${q(c.detail)} that its transport does not define`,
+  "mcp-server-field-type": (c) => `MCP server ${q(c.subject)}${at(c.path)} field ${q(c.detail)} has the wrong type`,
+  "mcp-server-url-missing": (c) => `MCP server ${q(c.subject)}${at(c.path)} is missing the 'url' its HTTP transport requires`,
+  "mcp-server-url-invalid": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has an invalid 'url' ${q(c.detail)}: expected an absolute HTTPS URL (HTTP only for localhost) with no user information or fragment`,
+  "mcp-server-url-variable": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has a variable in its 'url'; Stigmer sends the URL as written, so write the URL out and put variables in 'headers'`,
+  "mcp-server-command-missing": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} is missing the 'command' its stdio transport requires`,
+  "mcp-server-command-invalid": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has a 'command' that is not a single executable name; put arguments in 'args'`,
+  "mcp-server-command-relative": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} runs a command bundled in the plugin ${q(c.detail)}; Stigmer runs only commands on the runner's PATH (for example 'npx' or 'uvx')`,
+  "mcp-server-plugin-root-reference": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} references the plugin's own files through ${q(c.detail)}; Stigmer does not mount plugin files into the runner`,
+  "mcp-server-cwd-unsupported": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} sets a working directory; Stigmer does not mount plugin files, so a bundled directory cannot be reached`,
+  "mcp-server-env-literal": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} sets environment variable ${q(c.detail)} to a literal value; Stigmer passes declared variables by name, so write ${q(`${c.detail ?? "KEY"}: "\${${c.detail ?? "KEY"}}"`)} and declare the variable`,
+  "mcp-server-env-rename": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} maps environment variable ${q(c.detail)} to a differently named variable; Stigmer passes declared variables by name, so use the same name on both sides`,
+  "mcp-server-name-duplicate": (c) => `MCP server name ${q(c.subject)} appears more than once (again${at(c.path)})`,
+  "mcp-server-header-duplicate": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} declares header ${q(c.detail)} more than once (header names are case-insensitive)`,
+  "mcp-server-header-invalid": (c) => `MCP server ${q(c.subject)}${at(c.path)} has an invalid header name ${q(c.detail)}`,
+
+  "sub-agent-frontmatter-unreadable": (c) => `${q(c.path)} frontmatter is not valid YAML: ${c.detail ?? "parse error"}`,
+  "sub-agent-instructions-short": (c) =>
+    `sub-agent ${q(c.subject)}${at(c.path)} has instructions under ${c.detail ?? ""} characters; the body of the file is the sub-agent's prompt`,
+  "sub-agent-name-duplicate": (c) => `sub-agent name ${q(c.subject)} appears more than once (again${at(c.path)})`,
+
+  "variable-name-invalid": (c) =>
+    `variable name ${q(c.subject)}${at(c.path)} is invalid: an environment variable name is letters, digits and underscores, not starting with a digit`,
+
+  "overlay-server-unknown": (c) =>
+    `${q(c.path)} overlays MCP server ${q(c.subject)}, which the plugin does not declare`,
+  "overlay-document-unknown": (c) =>
+    `${q(c.path)} is not a document Stigmer reads; the 'ai.stigmer/' folder holds 'agent.yaml', 'workflows/<name>.yaml' and 'mcp-servers/<server>.yaml'`,
+};
+
+const WARNING_MESSAGES: Record<PluginWarningKind, Sentence> = {
+  "manifest-field-unknown": (c) => `manifest ${q(c.path)} has an unknown field ${q(c.subject)}, ignored`,
+  "manifest-extensions-invalid": (c) => `manifest ${q(c.path)} has an 'extensions' field that is not an object, ignored`,
+  "path-missing": (c) => `path ${q(c.subject)} declared${at(c.path)} does not exist in the plugin`,
+  "skill-name-defaulted": (c) =>
+    `${q(c.path)} has no 'name' in its frontmatter; the skill is named after its directory, ${q(c.subject)}`,
+  "skill-name-differs-from-directory": (c) =>
+    `skill ${q(c.subject)}${at(c.path)} is named differently from its directory ${q(c.detail)}`,
+  "skill-description-missing": (c) => `skill ${q(c.subject)}${at(c.path)} has no 'description'`,
+  "mcp-config-field-ignored": (c) =>
+    `MCP configuration ${q(c.path)} has a top-level field ${q(c.subject)} Stigmer does not read, ignored`,
+  "mcp-server-sse-mapped": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} declares the legacy 'sse' transport; Stigmer connects over Streamable HTTP and falls back to SSE only when the server rejects it`,
+  "mcp-server-field-ignored": (c) => `MCP server ${q(c.subject)}${at(c.path)} has a field ${q(c.detail)} Stigmer does not read, ignored`,
+  "mcp-server-auth-ignored": (c) =>
+    `MCP server ${q(c.subject)}${at(c.path)} has an 'auth' block Stigmer does not read; OAuth for a server is declared in 'ai.stigmer/mcp-servers/${c.subject ?? "<server>"}.yaml'`,
+  "variable-inferred": (c) =>
+    `variable ${q(c.subject)} is referenced by MCP server ${q(c.detail)} but not declared; it is declared as a required secret`,
+  "variable-unreferenced": (c) => `variable ${q(c.subject)}${at(c.path)} is declared but no MCP server references it`,
+  "variable-default-dropped": (c) =>
+    `variable ${q(c.subject)}${at(c.path)} has a default value, which Stigmer does not carry; the user supplies the value`,
+  "variable-type-narrowed": (c) =>
+    `variable ${q(c.subject)}${at(c.path)} is typed ${q(c.detail)}; Stigmer variables are strings`,
+  "variable-option-dropped": (c) =>
+    `variable ${q(c.subject)}${at(c.path)} has a ${q(c.detail)} constraint, which Stigmer does not carry`,
+  "sub-agent-name-defaulted": (c) =>
+    `${q(c.path)} has no 'name' in its frontmatter; the sub-agent is named after the file, ${q(c.subject)}`,
+  "sub-agent-skill-unknown": (c) =>
+    `sub-agent ${q(c.subject)}${at(c.path)} asks for skill ${q(c.detail)}, which the plugin does not ship`,
+  "sub-agent-model-unknown": (c) =>
+    `sub-agent ${q(c.subject)}${at(c.path)} names model ${q(c.detail)}, which Stigmer cannot map; the sub-agent runs on the session's model`,
+  "sub-agent-field-ignored": (c) => `sub-agent ${q(c.subject)}${at(c.path)} has a field ${q(c.detail)} Stigmer does not read, ignored`,
+};
+
+export function errorMessage(kind: PluginErrorKind, ctx: FindingContext): string {
+  return ERROR_MESSAGES[kind](ctx);
+}
+
+export function warningMessage(kind: PluginWarningKind, ctx: FindingContext): string {
+  return WARNING_MESSAGES[kind](ctx);
+}
+
+/** True for the kinds that refuse a package. */
+export function isErrorKind(kind: PluginFindingKind): kind is PluginErrorKind {
+  return kind in ERROR_MESSAGES;
+}
+
+/**
+ * Collects findings while a read proceeds. The reader never throws on a
+ * plugin's content: every problem becomes a finding here, and the read
+ * continues so the outcome carries them all.
+ */
+export class Findings {
+  readonly errors: PluginFinding[] = [];
+  readonly warnings: PluginFinding[] = [];
+
+  error(kind: PluginErrorKind, ctx: FindingContext = {}): void {
+    this.errors.push(compose(kind, ctx, errorMessage(kind, ctx)));
+  }
+
+  warn(kind: PluginWarningKind, ctx: FindingContext = {}): void {
+    this.warnings.push(compose(kind, ctx, warningMessage(kind, ctx)));
+  }
+}
+
+// Optional fields are omitted rather than set to `undefined` so a finding
+// serialises to JSON without `null`s and compares structurally in tests.
+function compose(kind: PluginFindingKind, ctx: FindingContext, message: string): PluginFinding {
+  return {
+    kind,
+    ...(ctx.path !== undefined && { path: ctx.path }),
+    ...(ctx.subject !== undefined && { subject: ctx.subject }),
+    ...(ctx.detail !== undefined && { detail: ctx.detail }),
+    message,
+  };
+}

package/src/normalise/ignored.ts

@@ -0,0 +1,70 @@
+/**
+ * The components Stigmer reads past, found on disk.
+ *
+ * Every dialect ships things that configure the IDE rather than describe
+ * knowledge or tools: rules, hooks, slash commands, canvases, output styles,
+ * themes, monitors, LSP servers, Codex apps, bundled binaries, a settings
+ * file, a logo. Stigmer installs none of them, and says so once per
+ * component (a directory or a file, never per file inside), so an author
+ * knows what an install leaves behind. Manifest fields that name the same
+ * components are recorded by the dialect readers; the two lists are merged
+ * and deduplicated by kind and path in `read-plugin-package.ts`.
+ *
+ * `agents/` joins the list only when no vendor manifest is present: the
+ * open format defines no sub-agent component, so a root-manifest-only
+ * plugin with an `agents/` folder is told the folder is not read rather
+ * than having semantics assigned to it. `README`, `CHANGELOG`, `LICENSE`
+ * and dotfiles are not components and pass silently.
+ */
+
+import type { PluginFileIndex } from "../files.js";
+import type { IgnoredComponent, IgnoredComponentKind } from "../types.js";
+
+const IGNORED_DIRECTORIES: Readonly<Record<string, IgnoredComponentKind>> = {
+  rules: "rules",
+  hooks: "hooks",
+  commands: "commands",
+  canvases: "canvases",
+  workflows: "workflows",
+  "output-styles": "output-styles",
+  themes: "themes",
+  monitors: "monitors",
+  bin: "bin",
+  assets: "assets",
+  evals: "evals",
+};
+
+const IGNORED_FILES: Readonly<Record<string, IgnoredComponentKind>> = {
+  ".lsp.json": "lsp-servers",
+  "settings.json": "settings",
+  ".app.json": "apps",
+};
+
+export function ignoredOnDisk(index: PluginFileIndex, readsAgents: boolean): readonly IgnoredComponent[] {
+  const ignored: IgnoredComponent[] = [];
+  for (const dir of index.childDirectories("")) {
+    const kind = IGNORED_DIRECTORIES[dir];
+    if (kind !== undefined) ignored.push({ kind, path: `${dir}/` });
+    if (dir === "agents" && !readsAgents) ignored.push({ kind: "agents", path: `${dir}/` });
+  }
+  for (const file of index.childFiles("")) {
+    const kind = IGNORED_FILES[file];
+    if (kind !== undefined) ignored.push({ kind, path: file });
+  }
+  return ignored;
+}
+
+/** One entry per (kind, path), in first-seen order. */
+export function dedupeIgnored(lists: readonly (readonly IgnoredComponent[])[]): readonly IgnoredComponent[] {
+  const seen = new Set<string>();
+  const out: IgnoredComponent[] = [];
+  for (const list of lists) {
+    for (const component of list) {
+      const key = `${component.kind}\u0000${component.path}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(component);
+    }
+  }
+  return out;
+}