@pulsemcp/air-core 0.0.41 → 0.1.0

package/README.md

@@ -24,8 +24,8 @@ const artifacts = await resolveArtifacts("~/.air/air.json");
 // Validate a JSON file against its AIR schema
 const result = validateJson(data, "skills");
 
-// Merge two artifact sets (later wins for matching IDs)
-const merged = mergeArtifacts(base, override);
+// Merge two artifact sets (additive union — duplicate qualified IDs throw)
+const merged = mergeArtifacts(base, overlay);
 ```
 
 ### With a Catalog Provider (remote URIs)

package/dist/config.d.ts

@@ -18,6 +18,11 @@ export interface ResolveOptions {
      * (e.g., `gitProtocol`). Providers ignore unknown keys.
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Sink for non-fatal warnings (e.g. cross-scope shortname collisions, stale
+     * `exclude` entries). When omitted, core writes warnings to `console.warn`.
+     */
+    onWarning?: (message: string) => void;
 }
 /**
  * Merge air.json-level provider fields with runtime overrides and dispatch
@@ -34,24 +39,40 @@ export interface ResolveOptions {
 export declare function configureProviders(providers: CatalogProvider[], airConfig: AirConfig, providerOptions?: Record<string, unknown>): void;
 /**
  * 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.
  *
- * `catalogs` entries are expanded first into per-type paths following the
- * standard layout (`<catalog>/<type>/<type>.json`), then the explicit
- * per-type arrays layer on top. Missing files within a catalog are
- * silently skipped.
+ * Every artifact is canonically `@scope/id`:
+ *   - Catalog providers supply scope via `getScope(uri)` (e.g. the GitHub
+ *     provider returns `owner/repo`).
+ *   - Local catalogs and per-type arrays default to scope `local`.
+ *
+ * Composition is union-only: catalogs and per-type arrays *contribute*
+ * artifacts. The only way to remove an artifact is via `air.json#exclude`,
+ * which lists qualified IDs to drop from the resolved set. Two contributors
+ * producing the same qualified ID hard-fail; same shortname under different
+ * scopes warns and both qualified IDs appear in the result.
  *
- * All `path` fields in resolved entries are absolute paths,
- * making artifacts self-contained regardless of source location.
+ * Reference fields inside artifact bodies (skill.references, plugin.skills,
+ * root.default_skills, …) are canonicalized to qualified IDs at resolution
+ * time. References inside a catalog's own indexes resolve to that catalog's
+ * scope first; cross-catalog references must use the qualified form when
+ * the shortname is ambiguous.
+ *
+ * All `path` fields are absolute, 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.
+ * Combine two resolved artifact sets by union. Inputs must already be
+ * qualified (`@scope/id`); a duplicate qualified ID across the two inputs
+ * is rejected with a clear diagnostic. Composite plugins are re-expanded
+ * after merging.
+ *
+ * `mergeArtifacts` is a low-level helper used to layer two pre-resolved
+ * sets — for example, an external orchestrator merging a parent session's
+ * artifacts with a subagent's. Most callers should compose at the air.json
+ * level (catalogs + exclude) instead.
  */
-export declare function mergeArtifacts(base: ResolvedArtifacts, override: ResolvedArtifacts): ResolvedArtifacts;
+export declare function mergeArtifacts(base: ResolvedArtifacts, overlay: ResolvedArtifacts): ResolvedArtifacts;
 /**
  * Recursively expand plugin references.
  *
@@ -62,12 +83,12 @@ export declare function mergeArtifacts(base: ResolvedArtifacts, override: Resolv
  * 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
+ * - All IDs are already qualified (`@scope/id`) at this stage.
+ * - Child plugins are expanded depth-first in declaration order.
+ * - Parent's direct declarations come last (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.
  *
  * Returns a new ResolvedArtifacts object; the input is not mutated.
  */

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;AA+FpB,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;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,IAAI,CAwBN;AAmFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAsD5B;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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAkNpB,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;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,IAAI,CAwBN;AAufD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAgF5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CA2BnB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAiF7E;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}