@pulsemcp/air-core 0.0.2 → 0.0.4

package/dist/config.d.ts

@@ -17,11 +17,36 @@ export interface ResolveOptions {
  * Resolve all artifacts from an air.json file.
  * Each artifact property is an array of paths; files merge in order.
  * Remote URIs are delegated to the matching CatalogProvider.
+ *
+ * All `path` and `file` fields in resolved entries are absolute paths,
+ * making artifacts self-contained regardless of source location.
  */
 export declare function resolveArtifacts(airJsonPath: string, options?: ResolveOptions): Promise<ResolvedArtifacts>;
 /**
  * Merge two resolved artifact sets. Override wins for matching IDs.
+ * Composite plugins are re-expanded after merging so that newly
+ * added plugins that reference existing ones are fully resolved.
  */
 export declare function mergeArtifacts(base: ResolvedArtifacts, override: ResolvedArtifacts): ResolvedArtifacts;
+/**
+ * Recursively expand plugin references.
+ *
+ * Each plugin may declare a `plugins` array referencing other plugins by ID.
+ * This function resolves those references recursively, merging child plugins'
+ * primitives (skills, mcp_servers, hooks) into the parent. The result is a
+ * flat set of primitive IDs on each plugin — nesting is author convenience,
+ * not a runtime concept.
+ *
+ * Semantics:
+ * - Child plugins are expanded depth-first in declaration order
+ * - Parent's direct declarations override children (later wins via dedup)
+ * - Circular references are rejected with a clear error message
+ * - Plugins without a `plugins` field are returned unchanged
+ * - The `plugins` array on each entry is preserved as metadata (e.g., for
+ *   UI display of the dependency graph) even though primitives are inlined
+ *
+ * Returns a new ResolvedArtifacts object; the input is not mutated.
+ */
+export declare function expandPlugins(artifacts: ResolvedArtifacts): ResolvedArtifacts;
 export declare function emptyArtifacts(): ResolvedArtifacts;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAiEpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAqC5B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CASnB;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAmGpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAuC5B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CASnB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAiF7E;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}

package/dist/config.js

@@ -24,16 +24,39 @@ function getScheme(path) {
         return null;
     return scheme;
 }
+/**
+ * Resolve relative `path` and `file` fields in artifact entries to absolute paths.
+ * sourceDir is the directory containing the index file (local or remote clone).
+ */
+function resolveEntryPaths(entries, sourceDir) {
+    const resolved = {};
+    for (const [key, entry] of Object.entries(entries)) {
+        const e = entry;
+        const updated = { ...e };
+        if (typeof e.path === "string" && !e.path.startsWith("/")) {
+            updated.path = resolve(sourceDir, e.path);
+        }
+        if (typeof e.file === "string" && !e.file.startsWith("/")) {
+            updated.file = resolve(sourceDir, e.file);
+        }
+        resolved[key] = updated;
+    }
+    return resolved;
+}
 /**
  * Load and merge entries from an array of index file paths.
  * Local paths are resolved relative to baseDir.
  * URI paths (with schemes) are delegated to the matching CatalogProvider.
+ *
+ * After loading, relative `path` and `file` fields in entries are resolved
+ * to absolute paths, so downstream consumers don't need source directory context.
  */
 async function loadAndMerge(paths, baseDir, providers) {
     let merged = {};
     for (const p of paths) {
         const scheme = getScheme(p);
         let data;
+        let sourceDir;
         if (scheme) {
             const provider = providers.find((prov) => prov.scheme === scheme);
             if (!provider) {
@@ -41,12 +64,17 @@ async function loadAndMerge(paths, baseDir, providers) {
                     `Install an extension that handles this scheme.`);
             }
             data = await provider.resolve(p, baseDir);
+            // Use provider's resolveSourceDir if available, otherwise fall back to baseDir
+            sourceDir = provider.resolveSourceDir?.(p) ?? baseDir;
         }
         else {
-            data = loadJsonFile(resolve(baseDir, p));
+            const resolvedPath = resolve(baseDir, p);
+            data = loadJsonFile(resolvedPath);
+            sourceDir = dirname(resolvedPath);
         }
         const entries = stripSchema(data);
-        merged = { ...merged, ...entries };
+        const resolved = resolveEntryPaths(entries, sourceDir);
+        merged = { ...merged, ...resolved };
     }
     return merged;
 }
@@ -72,12 +100,15 @@ export function getAirJsonPath() {
  * Resolve all artifacts from an air.json file.
  * Each artifact property is an array of paths; files merge in order.
  * Remote URIs are delegated to the matching CatalogProvider.
+ *
+ * All `path` and `file` fields in resolved entries are absolute paths,
+ * making artifacts self-contained regardless of source location.
  */
 export async function resolveArtifacts(airJsonPath, options) {
     const airConfig = loadAirConfig(airJsonPath);
     const baseDir = dirname(resolve(airJsonPath));
     const providers = options?.providers || [];
-    return {
+    const resolved = {
         skills: await loadAndMerge(airConfig.skills || [], baseDir, providers),
         references: await loadAndMerge(airConfig.references || [], baseDir, providers),
         mcp: await loadAndMerge(airConfig.mcp || [], baseDir, providers),
@@ -85,18 +116,127 @@ export async function resolveArtifacts(airJsonPath, options) {
         roots: await loadAndMerge(airConfig.roots || [], baseDir, providers),
         hooks: await loadAndMerge(airConfig.hooks || [], baseDir, providers),
     };
+    return expandPlugins(resolved);
 }
 /**
  * Merge two resolved artifact sets. Override wins for matching IDs.
+ * Composite plugins are re-expanded after merging so that newly
+ * added plugins that reference existing ones are fully resolved.
  */
 export function mergeArtifacts(base, override) {
-    return {
+    return expandPlugins({
         skills: { ...base.skills, ...override.skills },
         references: { ...base.references, ...override.references },
         mcp: { ...base.mcp, ...override.mcp },
         plugins: { ...base.plugins, ...override.plugins },
         roots: { ...base.roots, ...override.roots },
         hooks: { ...base.hooks, ...override.hooks },
+    });
+}
+/**
+ * Deduplicate an array of strings, keeping the last occurrence of each value.
+ * This ensures parent declarations take precedence over child plugin declarations
+ * when arrays are concatenated as [...childIds, ...parentIds].
+ */
+function deduplicateIds(arr) {
+    const seen = new Set();
+    const result = [];
+    for (let i = arr.length - 1; i >= 0; i--) {
+        if (!seen.has(arr[i])) {
+            seen.add(arr[i]);
+            result.unshift(arr[i]);
+        }
+    }
+    return result;
+}
+/**
+ * Recursively expand plugin references.
+ *
+ * Each plugin may declare a `plugins` array referencing other plugins by ID.
+ * This function resolves those references recursively, merging child plugins'
+ * primitives (skills, mcp_servers, hooks) into the parent. The result is a
+ * flat set of primitive IDs on each plugin — nesting is author convenience,
+ * not a runtime concept.
+ *
+ * Semantics:
+ * - Child plugins are expanded depth-first in declaration order
+ * - Parent's direct declarations override children (later wins via dedup)
+ * - Circular references are rejected with a clear error message
+ * - Plugins without a `plugins` field are returned unchanged
+ * - The `plugins` array on each entry is preserved as metadata (e.g., for
+ *   UI display of the dependency graph) even though primitives are inlined
+ *
+ * Returns a new ResolvedArtifacts object; the input is not mutated.
+ */
+export function expandPlugins(artifacts) {
+    const plugins = artifacts.plugins;
+    const expanded = new Map();
+    function expand(pluginId, ancestors) {
+        if (expanded.has(pluginId)) {
+            return expanded.get(pluginId);
+        }
+        const plugin = plugins[pluginId];
+        if (!plugin) {
+            throw new Error(`Plugin "${pluginId}" referenced by "${ancestors[ancestors.length - 1]}" not found in resolved artifacts`);
+        }
+        // Cycle detection
+        const cycleIndex = ancestors.indexOf(pluginId);
+        if (cycleIndex !== -1) {
+            const cycle = [...ancestors.slice(cycleIndex), pluginId].join(" → ");
+            throw new Error(`Circular plugin dependency detected: ${cycle}`);
+        }
+        // No child plugins — return as-is
+        if (!plugin.plugins || plugin.plugins.length === 0) {
+            expanded.set(pluginId, plugin);
+            return plugin;
+        }
+        // Recursively expand child plugins and collect their primitives
+        const childSkills = [];
+        const childMcpServers = [];
+        const childHooks = [];
+        for (const childId of plugin.plugins) {
+            const child = expand(childId, [...ancestors, pluginId]);
+            if (child.skills)
+                childSkills.push(...child.skills);
+            if (child.mcp_servers)
+                childMcpServers.push(...child.mcp_servers);
+            if (child.hooks)
+                childHooks.push(...child.hooks);
+        }
+        // Merge: children first, then parent's direct declarations (parent wins via dedup)
+        const mergedSkills = deduplicateIds([
+            ...childSkills,
+            ...(plugin.skills || []),
+        ]);
+        const mergedMcpServers = deduplicateIds([
+            ...childMcpServers,
+            ...(plugin.mcp_servers || []),
+        ]);
+        const mergedHooks = deduplicateIds([
+            ...childHooks,
+            ...(plugin.hooks || []),
+        ]);
+        const expandedPlugin = {
+            ...plugin,
+            skills: mergedSkills.length > 0 ? mergedSkills : undefined,
+            mcp_servers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined,
+            hooks: mergedHooks.length > 0 ? mergedHooks : undefined,
+        };
+        expanded.set(pluginId, expandedPlugin);
+        return expandedPlugin;
+    }
+    // Expand all plugins
+    for (const pluginId of Object.keys(plugins)) {
+        expand(pluginId, []);
+    }
+    // Build the new plugins record preserving insertion order
+    const expandedPlugins = {};
+    for (const pluginId of Object.keys(plugins)) {
+        expandedPlugins[pluginId] = expanded.get(pluginId);
+    }
+    return {
+        ...artifacts,
+        plugins: expandedPlugins,
     };
 }
 export function emptyArtifacts() {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAaxC,SAAS,YAAY,CAAC,QAAgB;IACpC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,WAAW,CAClB,IAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACtC,+DAA+D;IAC/D,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CACxB,OAA0B,EAC1B,SAAiB;IAEjB,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QAEzB,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,IAAc,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,IAAc,CAAC,CAAC;QACtD,CAAC;QAED,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAY,CAAC;IAC/B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,YAAY,CACzB,KAAe,EACf,OAAe,EACf,SAA4B;IAE5B,IAAI,MAAM,GAAsB,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,IAA6B,CAAC;QAClC,IAAI,SAAiB,CAAC;QAEtB,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;YAClE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CACb,8CAA8C,MAAM,eAAe,CAAC,KAAK;oBACvE,gDAAgD,CACnD,CAAC;YACJ,CAAC;YACD,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC1C,+EAA+E;YAC/E,SAAS,GAAG,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACzC,IAAI,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;YAClC,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAsB,CAAC;QACvD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACvD,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC;IACtC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,OAAO,CACZ,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,EAClD,MAAM,EACN,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,qBAAqB,EAAE,CAAC;IAC/D,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACxC,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,OAAwB;IAExB,MAAM,SAAS,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAE3C,MAAM,QAAQ,GAAsB;QAClC,MAAM,EAAE,MAAM,YAAY,CACxB,SAAS,CAAC,MAAM,IAAI,EAAE,EACtB,OAAO,EACP,SAAS,CACV;QACD,UAAU,EAAE,MAAM,YAAY,CAC5B,SAAS,CAAC,UAAU,IAAI,EAAE,EAC1B,OAAO,EACP,SAAS,CACV;QACD,GAAG,EAAE,MAAM,YAAY,CACrB,SAAS,CAAC,GAAG,IAAI,EAAE,EACnB,OAAO,EACP,SAAS,CACV;QACD,OAAO,EAAE,MAAM,YAAY,CACzB,SAAS,CAAC,OAAO,IAAI,EAAE,EACvB,OAAO,EACP,SAAS,CACV;QACD,KAAK,EAAE,MAAM,YAAY,CACvB,SAAS,CAAC,KAAK,IAAI,EAAE,EACrB,OAAO,EACP,SAAS,CACV;QACD,KAAK,EAAE,MAAM,YAAY,CACvB,SAAS,CAAC,KAAK,IAAI,EAAE,EACrB,OAAO,EACP,SAAS,CACV;KACF,CAAC;IAEF,OAAO,aAAa,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,QAA2B;IAE3B,OAAO,aAAa,CAAC;QACnB,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE;QAC9C,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC,UAAU,EAAE;QAC1D,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE;QACrC,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE;QACjD,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;QAC3C,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;KAC5C,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAa;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACjB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,SAA4B;IACxD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEhD,SAAS,MAAM,CAAC,QAAgB,EAAE,SAAmB;QACnD,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;QACjC,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,WAAW,QAAQ,oBAAoB,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,mCAAmC,CAC1G,CAAC;QACJ,CAAC;QAED,kBAAkB;QAClB,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrE,MAAM,IAAI,KAAK,CAAC,wCAAwC,KAAK,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,kCAAkC;QAClC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/B,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,gEAAgE;QAChE,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,MAAM,eAAe,GAAa,EAAE,CAAC;QACrC,MAAM,UAAU,GAAa,EAAE,CAAC;QAEhC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;YACxD,IAAI,KAAK,CAAC,MAAM;gBAAE,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,KAAK,CAAC,WAAW;gBAAE,eAAe,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;YAClE,IAAI,KAAK,CAAC,KAAK;gBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACnD,CAAC;QAED,mFAAmF;QACnF,MAAM,YAAY,GAAG,cAAc,CAAC;YAClC,GAAG,WAAW;YACd,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;SACzB,CAAC,CAAC;QACH,MAAM,gBAAgB,GAAG,cAAc,CAAC;YACtC,GAAG,eAAe;YAClB,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;SAC9B,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,cAAc,CAAC;YACjC,GAAG,UAAU;YACb,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;SACxB,CAAC,CAAC;QAEH,MAAM,cAAc,GAAgB;YAClC,GAAG,MAAM;YACT,MAAM,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;YAC1D,WAAW,EAAE,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;YACvE,KAAK,EAAE,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;SACxD,CAAC;QAEF,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,qBAAqB;IACrB,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACvB,CAAC;IAED,0DAA0D;IAC1D,MAAM,eAAe,GAAgC,EAAE,CAAC;IACxD,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,eAAe,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;IACtD,CAAC;IAED,OAAO;QACL,GAAG,SAAS;QACZ,OAAO,EAAE,eAAe;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,MAAM,EAAE,EAAE;QACV,UAAU,EAAE,EAAE;QACd,GAAG,EAAE,EAAE;QACP,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,EAAE;QACT,KAAK,EAAE,EAAE;KACV,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { AirConfig, ResolvedArtifacts, SkillEntry, ReferenceEntry, McpOAuthConfig, McpServerEntry, PluginEntry, RootEntry, HookEntry, } from "./types.js";
+export type { AirConfig, ResolvedArtifacts, SkillEntry, ReferenceEntry, McpOAuthConfig, McpServerEntry, PluginAuthor, PluginEntry, RootEntry, HookEntry, } from "./types.js";
 export type { AgentAdapter, CatalogProvider, SecretResolver, AirExtension, AgentSessionConfig, StartCommand, PrepareSessionOptions, PreparedSession, } from "./types.js";
-export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, emptyArtifacts, } from "./config.js";
+export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, expandPlugins, emptyArtifacts, } from "./config.js";
 export type { ResolveOptions } from "./config.js";
 export { validateJson } from "./validator.js";
 export type { ValidationResult, ValidationError } from "./validator.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 // Config resolution
-export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, emptyArtifacts, } from "./config.js";
+export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, expandPlugins, emptyArtifacts, } from "./config.js";
 // Validation
 export { validateJson } from "./validator.js";
 // Schemas

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,UAAU;AACV,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,UAAU;AACV,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -45,15 +45,26 @@ export interface McpServerEntry {
     headers?: Record<string, string>;
     oauth?: McpOAuthConfig;
 }
+export interface PluginAuthor {
+    name?: string;
+    email?: string;
+    url?: string;
+}
 export interface PluginEntry {
     id: string;
     title?: string;
     description: string;
-    type: "command";
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-    timeout_seconds?: number;
+    version?: string;
+    skills?: string[];
+    mcp_servers?: string[];
+    hooks?: string[];
+    plugins?: string[];
+    author?: PluginAuthor;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    logo?: string;
+    keywords?: string[];
 }
 export interface RootEntry {
     name: string;
@@ -110,12 +121,6 @@ export interface PrepareSessionOptions {
     root?: RootEntry;
     /** Secret resolvers for ${VAR} interpolation in MCP configs */
     secretResolvers?: SecretResolver[];
-    /**
-     * Base directory for resolving artifact source paths (skill.path, reference.file).
-     * Defaults to the parent of targetDir. Set this to the directory containing air.json
-     * when air.json lives separately from the target directory (e.g., orchestrator use case).
-     */
-    baseDir?: string;
     /**
      * Override the root's default_skills — only activate these specific skills.
      * When set, this replaces root.default_skills entirely.
@@ -148,6 +153,13 @@ export interface CatalogProvider {
     scheme: string;
     /** Resolve a URI to parsed JSON content */
     resolve(uri: string, baseDir: string): Promise<Record<string, unknown>>;
+    /**
+     * Return the local directory where files from this URI's source can be found.
+     * For git-based providers, this is the clone directory.
+     * Used by loadAndMerge to resolve relative path/file fields in artifact entries
+     * to absolute paths. Returns undefined if the source isn't locally available.
+     */
+    resolveSourceDir?(uri: string): string | undefined;
 }
 /**
  * Secret Resolver — resolves ${VAR} interpolation in config values.

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsemcp/air-core",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "publishConfig": {
     "access": "public"
   },

package/schemas/plugins.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/plugins.schema.json",
   "title": "AIR Plugins Index",
-  "description": "Index of agent plugins available in this AIR configuration. Plugins extend agent capabilities beyond what MCP servers and skills provide. AIR plugins are agent-agnostic and translated to agent-specific formats at session start time.",
+  "description": "Index of agent plugins available in this AIR configuration. A plugin is a named grouping of AIR primitives (skills, MCP servers, hooks) — a compositional unit for bundling and distributing related capabilities. Plugins do not define new artifacts inline; they reference existing artifacts by ID from the corresponding index files.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -20,7 +20,7 @@
   "$defs": {
     "Plugin": {
       "type": "object",
-      "description": "An agent plugin that extends capabilities via external commands.",
+      "description": "A plugin — a named grouping of AIR primitives (skills, MCP servers, hooks) for bundling and distribution. All referenced artifacts must be defined in their respective index files.",
       "properties": {
         "id": {
           "type": "string",
@@ -38,38 +38,88 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 500,
-          "description": "Concise description of what this plugin does."
+          "description": "Concise description of what this plugin provides."
         },
-        "type": {
+        "version": {
           "type": "string",
-          "enum": ["command"],
-          "description": "Plugin type. Currently only 'command' is supported."
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9._-]+)?$",
+          "description": "Semantic version of the plugin (e.g., '1.0.0')."
         },
-        "command": {
-          "type": "string",
-          "description": "Executable command to run for this plugin."
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of skills bundled by this plugin. Must reference skill IDs defined in skills.json indexes."
         },
-        "args": {
+        "mcp_servers": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Command-line arguments for the plugin command."
+          "description": "IDs of MCP servers bundled by this plugin. Must reference server IDs defined in mcp.json indexes."
         },
-        "env": {
-          "type": "object",
-          "additionalProperties": {
+        "hooks": {
+          "type": "array",
+          "items": {
             "type": "string"
           },
-          "description": "Environment variables for the plugin process. Values support ${ENV_VAR} interpolation."
+          "description": "IDs of hooks bundled by this plugin. Must reference hook IDs defined in hooks.json indexes."
+        },
+        "plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other plugins to compose into this plugin. Referenced plugins' primitives (skills, mcp_servers, hooks) are recursively expanded and merged with this plugin's direct declarations. Circular references are rejected at resolution time."
+        },
+        "author": {
+          "type": "object",
+          "description": "Plugin author information.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Author's name."
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Author's email address."
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Author's website or profile URL."
+            }
+          },
+          "additionalProperties": false
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the plugin's homepage or documentation."
+        },
+        "repository": {
+          "type": "string",
+          "description": "URL or identifier for the plugin's source repository."
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier (e.g., 'MIT', 'Apache-2.0')."
+        },
+        "logo": {
+          "type": "string",
+          "description": "Path or URL to the plugin's logo image."
         },
-        "timeout_seconds": {
-          "type": "number",
-          "minimum": 1,
-          "description": "Maximum execution time in seconds before the plugin is killed."
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Keywords for discovery and categorization."
         }
       },
-      "required": ["id", "description", "type", "command"],
+      "required": ["id", "description"],
       "additionalProperties": false
     }
   }

package/schemas/schemas/plugins.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/plugins.schema.json",
   "title": "AIR Plugins Index",
-  "description": "Index of agent plugins available in this AIR configuration. Plugins extend agent capabilities beyond what MCP servers and skills provide. AIR plugins are agent-agnostic and translated to agent-specific formats at session start time.",
+  "description": "Index of agent plugins available in this AIR configuration. A plugin is a named grouping of AIR primitives (skills, MCP servers, hooks) — a compositional unit for bundling and distributing related capabilities. Plugins do not define new artifacts inline; they reference existing artifacts by ID from the corresponding index files.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -20,7 +20,7 @@
   "$defs": {
     "Plugin": {
       "type": "object",
-      "description": "An agent plugin that extends capabilities via external commands.",
+      "description": "A plugin — a named grouping of AIR primitives (skills, MCP servers, hooks) for bundling and distribution. All referenced artifacts must be defined in their respective index files.",
       "properties": {
         "id": {
           "type": "string",
@@ -38,38 +38,88 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 500,
-          "description": "Concise description of what this plugin does."
+          "description": "Concise description of what this plugin provides."
         },
-        "type": {
+        "version": {
           "type": "string",
-          "enum": ["command"],
-          "description": "Plugin type. Currently only 'command' is supported."
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9._-]+)?$",
+          "description": "Semantic version of the plugin (e.g., '1.0.0')."
         },
-        "command": {
-          "type": "string",
-          "description": "Executable command to run for this plugin."
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of skills bundled by this plugin. Must reference skill IDs defined in skills.json indexes."
         },
-        "args": {
+        "mcp_servers": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Command-line arguments for the plugin command."
+          "description": "IDs of MCP servers bundled by this plugin. Must reference server IDs defined in mcp.json indexes."
         },
-        "env": {
-          "type": "object",
-          "additionalProperties": {
+        "hooks": {
+          "type": "array",
+          "items": {
             "type": "string"
           },
-          "description": "Environment variables for the plugin process. Values support ${ENV_VAR} interpolation."
+          "description": "IDs of hooks bundled by this plugin. Must reference hook IDs defined in hooks.json indexes."
+        },
+        "plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other plugins to compose into this plugin. Referenced plugins' primitives (skills, mcp_servers, hooks) are recursively expanded and merged with this plugin's direct declarations. Circular references are rejected at resolution time."
+        },
+        "author": {
+          "type": "object",
+          "description": "Plugin author information.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Author's name."
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Author's email address."
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Author's website or profile URL."
+            }
+          },
+          "additionalProperties": false
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the plugin's homepage or documentation."
+        },
+        "repository": {
+          "type": "string",
+          "description": "URL or identifier for the plugin's source repository."
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier (e.g., 'MIT', 'Apache-2.0')."
+        },
+        "logo": {
+          "type": "string",
+          "description": "Path or URL to the plugin's logo image."
         },
-        "timeout_seconds": {
-          "type": "number",
-          "minimum": 1,
-          "description": "Maximum execution time in seconds before the plugin is killed."
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Keywords for discovery and categorization."
         }
       },
-      "required": ["id", "description", "type", "command"],
+      "required": ["id", "description"],
       "additionalProperties": false
     }
   }