@stigmer/plugin-package 3.15.3-dev.20260916211208

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@stigmer/plugin-package",
+  "version": "3.15.3-dev.20260916211208",
+  "description": "Reads an Agent Plugins package — the open 1.0.0 format and the Cursor, Claude Code and Codex dialects — into one normalised description of what Stigmer would install, refusing with one sentence per problem what Stigmer cannot carry; pure over an in-memory file reader, shared by the CLI's offline validation and the server's install",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stigmer/stigmer.git",
+    "directory": "backend/libs/ts/plugin-package"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=23.4.0"
+  },
+  "keywords": [
+    "stigmer",
+    "agent-plugins",
+    "plugin",
+    "skills",
+    "mcp"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "import": "./testing.js",
+      "default": "./testing.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  }
+}

package/placeholders.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 declare const PLACEHOLDER_PATTERN: RegExp;
+/** A variable name the runner's scanner can reference. */
+export declare const VARIABLE_NAME_PATTERN: RegExp;
+/**
+ * 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 declare const PLUGIN_ROOT_PLACEHOLDERS: ReadonlySet<string>;
+/** The reserved environment names the open format forbids a server's `env` to set. */
+export declare const PLUGIN_ROOT_ENV_NAMES: ReadonlySet<string>;
+/** `${user_config.KEY}` -> `${KEY}`. */
+export declare function rewriteUserConfig(value: string): string;
+/** The first plugin-root placeholder in `value`, or `undefined`. */
+export declare function findPluginRootPlaceholder(value: string): string | undefined;
+/** The variable names referenced in `value`, in order of appearance, deduplicated. */
+export declare function referencedVariables(value: string): readonly string[];
+/** The variable name when `value` is exactly one placeholder and nothing else; otherwise `undefined`. */
+export declare function singlePlaceholderName(value: string): string | undefined;
+//# sourceMappingURL=placeholders.d.ts.map

package/placeholders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../src/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAoC,CAAC;AAErE,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,QAA6B,CAAC;AAIhE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAOvD,CAAC;AAEH,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAA2C,CAAC;AAElG,wCAAwC;AACxC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,oEAAoE;AACpE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK3E;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAOpE;AAED,yGAAyG;AACzG,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE"}

package/placeholders.js

@@ -0,0 +1,68 @@
+/**
+ * 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 = 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 = new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
+/** `${user_config.KEY}` -> `${KEY}`. */
+export function rewriteUserConfig(value) {
+    return value.replace(USER_CONFIG_PATTERN, (_match, key) => `\${${key}}`);
+}
+/** The first plugin-root placeholder in `value`, or `undefined`. */
+export function findPluginRootPlaceholder(value) {
+    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) {
+    const names = [];
+    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) {
+    const match = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(value);
+    return match?.[1];
+}
+//# sourceMappingURL=placeholders.js.map

package/placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.js","sourceRoot":"","sources":["../src/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAErE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAEhE,MAAM,mBAAmB,GAAG,8CAA8C,CAAC;AAE3E;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IACnE,gBAAgB;IAChB,gBAAgB;IAChB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;CACxB,CAAC,CAAC;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC;AAElG,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;AACnF,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,yBAAyB,CAAC,KAAa;IACrD,KAAK,MAAM,WAAW,IAAI,wBAAwB,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,WAAW,CAAC;IACtD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,KAAK,GAAG,kCAAkC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/read-plugin-package.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { type PluginFiles } from "./files.js";
+import type { PluginReadOutcome } from "./outcome.js";
+export declare function readPluginPackage(files: PluginFiles): PluginReadOutcome;
+//# sourceMappingURL=read-plugin-package.d.ts.map

package/read-plugin-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-plugin-package.d.ts","sourceRoot":"","sources":["../src/read-plugin-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAQhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CA6CvE"}

package/read-plugin-package.js

@@ -0,0 +1,67 @@
+/**
+ * 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 } 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";
+export function readPluginPackage(files) {
+    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 = {
+        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 };
+}
+//# sourceMappingURL=read-plugin-package.js.map

package/read-plugin-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-plugin-package.js","sourceRoot":"","sources":["../src/read-plugin-package.ts"],"names":[],"mappings":"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"}

package/src/__test-utils__/directory-files.ts

@@ -0,0 +1,29 @@
+/**
+ * A test-only `PluginFiles` over a directory on disk, for the vendored
+ * fixtures. Sorted, symlinks skipped, sizes from `stat`, the contract the
+ * CLI's walker honours; kept here (not in the library) because the
+ * library's main entry imports no `node:*` module and the CLI owns the
+ * real walker with its ignore rules.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { comparePaths, type PluginFileEntry, type PluginFiles } from "../files.js";
+
+export function directoryPluginFiles(root: string): PluginFiles {
+  const entries: PluginFileEntry[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) walk(join(dir, entry.name), path);
+      else if (entry.isFile()) entries.push({ path, size: statSync(join(dir, entry.name)).size });
+    }
+  };
+  walk(root, "");
+  entries.sort((a, b) => comparePaths(a.path, b.path));
+  return {
+    entries,
+    read: (path) => new Uint8Array(readFileSync(join(root, ...path.split("/")))),
+  };
+}

package/src/__test-utils__/read.ts

@@ -0,0 +1,55 @@
+/**
+ * Test helpers: read a fixture map, name the finding kinds an outcome
+ * carries, and unwrap the arms with a diagnostic when the other arm came
+ * back. Kinds are returned SORTED and complete (errors and warnings both),
+ * so an adversarial test asserts everything the reader said and a warning
+ * that appears beside the error under test is named, never tolerated by
+ * omission.
+ */
+
+import { expect } from "vitest";
+
+import { inMemoryPluginFiles } from "../files.js";
+import type { PluginFinding, PluginReadOutcome } from "../outcome.js";
+import { readPluginPackage } from "../read-plugin-package.js";
+import type { PluginFixture } from "../testing.js";
+import type { PluginPackage } from "../types.js";
+
+export function read(files: PluginFixture): PluginReadOutcome {
+  return readPluginPackage(inMemoryPluginFiles(files));
+}
+
+export interface Kinds {
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export function kindsOf(outcome: PluginReadOutcome): Kinds {
+  const sorted = (findings: readonly PluginFinding[]): string[] => findings.map((f) => f.kind).sort();
+  return outcome.ok
+    ? { errors: [], warnings: sorted(outcome.warnings) }
+    : { errors: sorted(outcome.errors), warnings: sorted(outcome.warnings) };
+}
+
+/** The plugin, failing with every finding's sentence when the read refused. */
+export function accepted(outcome: PluginReadOutcome): PluginPackage {
+  if (!outcome.ok) {
+    expect.fail(`expected an accepted plugin, got refusals:\n${outcome.errors.map((f) => `  ${f.kind}: ${f.message}`).join("\n")}`);
+  }
+  return outcome.plugin;
+}
+
+/** The errors, failing when the read accepted. */
+export function refused(outcome: PluginReadOutcome): readonly PluginFinding[] {
+  if (outcome.ok) {
+    expect.fail(`expected a refusal, got an accepted plugin '${outcome.plugin.name}'`);
+  }
+  return outcome.errors;
+}
+
+/** The one finding of `kind`, failing when it is absent or repeated. */
+export function findingOf(findings: readonly PluginFinding[], kind: string): PluginFinding {
+  const matches = findings.filter((f) => f.kind === kind);
+  expect(matches, `exactly one '${kind}' finding`).toHaveLength(1);
+  return matches[0] as PluginFinding;
+}