@kb-labs/marketplace-contracts 2.31.0 → 2.32.0

package/dist/index.d.ts

@@ -91,6 +91,40 @@ interface PackageSource {
     /** Publish a package (optional — only registry source supports it) */
     publish?(tarball: Buffer, metadata: PublishMetadata): Promise<PublishResult>;
 }
+/**
+ * A marketplace scope. Each scope has its own independent `marketplace.lock`
+ * and manifest cache, rooted at a different directory.
+ *
+ * - `platform` — global installs shared across projects (in the platform root).
+ * - `project`  — installs local to a single project (in the project root).
+ * - `all`      — only valid as a query scope (`list`). Returns merged entries
+ *                from both scopes with `scope` field attached to each entry.
+ */
+type MarketplaceScope = 'platform' | 'project';
+type MarketplaceQueryScope = MarketplaceScope | 'all';
+/**
+ * Per-call scope binding for mutating operations (`install`, `link`,
+ * `unlink`, `enable`, `disable`, `update`, `sync`) and for read operations
+ * (`list`, `getEntry`).
+ *
+ * - `scope`       — which lock this call targets.
+ * - `projectRoot` — required for `scope: 'project'` (ignored otherwise).
+ *                   Absolute path. The service validates that this directory
+ *                   exists and contains a `.kb/kb.config.{json,jsonc}` and is
+ *                   not equal to the platform root.
+ */
+interface ScopeContext {
+    scope: MarketplaceScope;
+    projectRoot?: string;
+}
+/**
+ * Read-side context. Same as `ScopeContext`, but also admits `'all'` to merge
+ * platform and project lists.
+ */
+interface QueryScopeContext {
+    scope: MarketplaceQueryScope;
+    projectRoot?: string;
+}
 /**
  * Public read-only API of MarketplaceService exposed to strategies.
  * Strategies must not depend on the full implementation.
@@ -99,13 +133,32 @@ interface PackageSource {
 type MarketplaceEntryWithId = MarketplaceEntry & {
     id: string;
 };
+/**
+ * Marketplace entry annotated with the scope it came from. Returned by
+ * `list()` so callers can always tell where a package was installed, without
+ * having to probe locks themselves.
+ */
+type ScopedMarketplaceEntry = MarketplaceEntryWithId & {
+    scope: MarketplaceScope;
+};
+/**
+ * Non-fatal warning surfaced by a marketplace operation.
+ * Examples: a collision between platform and project lock (platform wins),
+ * a project-scope config ignored because the field is platform-only, etc.
+ */
+interface MarketplaceDiagnostic {
+    code: string;
+    message: string;
+    packageId?: string;
+    scope?: MarketplaceScope;
+}
 interface MarketplaceServiceAPI {
     /** List installed entries, optionally filtered by kind */
-    list(filter?: {
+    list(ctx: QueryScopeContext, filter?: {
         kind?: EntityKind;
-    }): Promise<MarketplaceEntryWithId[]>;
+    }): Promise<ScopedMarketplaceEntry[]>;
     /** Get a single entry by package ID */
-    getEntry(packageId: string): Promise<MarketplaceEntry | null>;
+    getEntry(ctx: ScopeContext, packageId: string): Promise<MarketplaceEntry | null>;
 }
 /**
  * Strategy for handling a specific entity kind in the marketplace.
@@ -136,13 +189,16 @@ interface EntityKindStrategy {
     /**
      * Post-install hook. Called after the package is installed and written to lock.
      * Example: adapter strategy validates that required adapter dependencies are installed.
+     *
+     * The `ctx` argument carries the scope of the triggering install/link so the
+     * strategy can query/modify the correct lock (e.g. via `service.list(ctx)`).
      */
-    afterInstall?(packageId: string, packageRoot: string, service: MarketplaceServiceAPI): Promise<void>;
+    afterInstall?(packageId: string, packageRoot: string, service: MarketplaceServiceAPI, ctx: ScopeContext): Promise<void>;
     /**
      * Pre-uninstall hook. Called before the package is removed.
      * Example: adapter strategy checks if other adapters depend on this one.
      */
-    beforeUninstall?(packageId: string, service: MarketplaceServiceAPI): Promise<void>;
+    beforeUninstall?(packageId: string, service: MarketplaceServiceAPI, ctx: ScopeContext): Promise<void>;
 }
 /**
  * Cached manifest entry. Stored in .kb/marketplace.manifests.json.
@@ -172,10 +228,23 @@ interface InstallResultEntry {
     primaryKind: EntityKind;
     provides: EntityKind[];
     packageRoot: string;
+    /** Scope this entry was written to. */
+    scope: MarketplaceScope;
 }
 interface InstallResult {
     installed: InstallResultEntry[];
     warnings: string[];
+    /**
+     * Scope the install was executed in. Echoed back so callers (API, CLI)
+     * can render scope-aware output without tracking the request side.
+     */
+    scope: MarketplaceScope;
+    /**
+     * Non-fatal diagnostics produced during the operation (e.g. collisions).
+     * Separate from `warnings` (which are free-form strings) so that downstream
+     * consumers can render them uniformly.
+     */
+    diagnostics?: MarketplaceDiagnostic[];
 }
 interface SyncResult {
     added: Array<{
@@ -201,4 +270,4 @@ interface DoctorReport {
     issues: DoctorIssue[];
 }
 
-export type { DoctorIssue, DoctorReport, EntityKindStrategy, InstallResult, InstallResultEntry, InstalledPackage, ManifestCache, ManifestCacheEntry, MarketplaceEntryWithId, MarketplaceServiceAPI, PackageListing, PackageSource, PublishMetadata, PublishResult, ResolvedPackage, SyncResult };
+export type { DoctorIssue, DoctorReport, EntityKindStrategy, InstallResult, InstallResultEntry, InstalledPackage, ManifestCache, ManifestCacheEntry, MarketplaceDiagnostic, MarketplaceEntryWithId, MarketplaceQueryScope, MarketplaceScope, MarketplaceServiceAPI, PackageListing, PackageSource, PublishMetadata, PublishResult, QueryScopeContext, ResolvedPackage, ScopeContext, ScopedMarketplaceEntry, SyncResult };

package/package.json

@@ -1,15 +1,15 @@
 {
   "dependencies": {
-    "@kb-labs/core-discovery": "2.31.0",
-    "@kb-labs/core-platform": "2.31.0",
-    "@kb-labs/plugin-contracts": "2.31.0"
+    "@kb-labs/core-discovery": "2.32.0",
+    "@kb-labs/core-platform": "2.32.0",
+    "@kb-labs/plugin-contracts": "2.32.0"
   },
   "description": "Shared types and interfaces for KB Labs marketplace",
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5",
     "vitest": "^3.2.4",
-    "@kb-labs/devkit": "2.31.0"
+    "@kb-labs/devkit": "2.32.0"
   },
   "engines": {
     "node": ">=20.0.0",
@@ -31,7 +31,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "scripts": {
     "build": "tsup",
     "clean": "rimraf dist",