@kb-labs/marketplace-contracts 0.1.1

package/README.md

@@ -0,0 +1,75 @@
+# @product-name/package-name
+
+Baseline library package inside KB Labs Product Template.
+
+## Vision & Purpose
+
+**@product-name/package-name** is a minimal example library shipped with `kb-labs-product-template`.  
+It shows how a typical package is structured (source, tests, types) and is intended to be **renamed or removed** when creating a real product.
+
+### Core Goals
+
+- Demonstrate the standard KB Labs package layout (src/types/tests/build tooling)
+- Provide a simple, testable function (`hello`) as a starting point
+- Act as a safe playground for verifying DevKit configs (tsup, Vitest, ESLint)
+
+## Package Status
+
+- **Version**: 0.1.0  
+- **Stage**: Template / Example  
+- **Status**: Not for Production ⚠️
+
+## Architecture
+
+### Structure
+
+```
+packages/package-name/
+├── src/
+│   ├── index.ts        # Public entrypoint
+│   └── types/          # Shared types and re-exports
+│       ├── types.ts
+│       └── index.ts
+├── index.test.ts       # Vitest example
+└── tsup.config.ts      # Build configuration
+```
+
+The default implementation is intentionally tiny:
+
+```ts
+export const hello = (name = 'KB Labs') => `Hello, ${name}!`;
+```
+
+## Dependencies
+
+### Runtime
+
+None by default — this is a pure TypeScript example.
+
+### Development
+
+- `@kb-labs/devkit`: shared TS/ESLint/Vitest/TSUP presets
+- `tsup`, `vitest`, `tsx`, `typescript`
+
+## Scripts
+
+From the `kb-labs-product-template` root:
+
+```bash
+pnpm --filter @product-name/package-name build
+pnpm --filter @product-name/package-name test
+pnpm --filter @product-name/package-name lint
+```
+
+## How to Adapt for a Real Package
+
+When using the product template for your own project:
+
+1. Rename the package in `package.json` (e.g. `@kb-labs/my-product-core`).
+2. Replace the `hello` function with your actual public API.
+3. Update tests in `index.test.ts` to cover real behaviour.
+4. Adjust `types/` to expose the correct public types.
+
+This package is meant as a scaffold only; don’t ship it as-is to production.
+
+

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { ManifestV3 } from '@kb-labs/plugin-contracts';
+import { EntitySignature, EntityKind, MarketplaceEntry } from '@kb-labs/core-discovery';
+
+/**
+ * @module @kb-labs/marketplace-contracts/types
+ * Shared types for the KB Labs marketplace ecosystem.
+ */
+
+/**
+ * A resolved package ready to be installed.
+ */
+interface ResolvedPackage {
+    /** Package identifier (@scope/name) */
+    id: string;
+    /** Resolved version (semver) */
+    version: string;
+    /** SRI integrity hash (sha256-...) */
+    integrity: string;
+    /** Platform-issued signature (from registry) */
+    signature?: EntitySignature;
+    /** How this package was sourced */
+    source: 'marketplace' | 'local';
+    /** Download URL (for registry-based sources) */
+    downloadUrl?: string;
+}
+/**
+ * Metadata about a successfully installed package.
+ */
+interface InstalledPackage {
+    /** Package identifier */
+    id: string;
+    /** Installed version */
+    version: string;
+    /** Absolute path to the installed package root */
+    packageRoot: string;
+    /** Computed integrity hash */
+    integrity: string;
+}
+/**
+ * Brief listing entry for search results.
+ */
+interface PackageListing {
+    id: string;
+    version: string;
+    description?: string;
+    primaryKind: EntityKind;
+    provides: EntityKind[];
+    signature?: EntitySignature;
+}
+/**
+ * Metadata required when publishing a package.
+ */
+interface PublishMetadata {
+    id: string;
+    version: string;
+    description?: string;
+    primaryKind: EntityKind;
+    provides: EntityKind[];
+}
+/**
+ * Result of a publish operation.
+ */
+interface PublishResult {
+    id: string;
+    version: string;
+    signature?: EntitySignature;
+    publishedAt: string;
+}
+/**
+ * Abstraction over the source of packages.
+ *
+ * Currently: NpmPackageSource (pnpm add/remove).
+ * Future: RegistryPackageSource (KB Labs marketplace registry API).
+ *
+ * MarketplaceService works through this interface — it never calls
+ * pnpm or any other package manager directly.
+ */
+interface PackageSource {
+    /** Resolve a package spec (e.g., "@scope/pkg@^1.0.0") to installable metadata */
+    resolve(spec: string): Promise<ResolvedPackage>;
+    /** Install a resolved package into the workspace */
+    install(pkg: ResolvedPackage, root: string, opts?: {
+        dev?: boolean;
+    }): Promise<InstalledPackage>;
+    /** Remove a package from the workspace */
+    remove(packageId: string, root: string): Promise<void>;
+    /** Search available packages (optional — not all sources support it) */
+    search?(query: string, filter?: {
+        kind?: EntityKind;
+    }): Promise<PackageListing[]>;
+    /** Publish a package (optional — only registry source supports it) */
+    publish?(tarball: Buffer, metadata: PublishMetadata): Promise<PublishResult>;
+}
+/**
+ * Public read-only API of MarketplaceService exposed to strategies.
+ * Strategies must not depend on the full implementation.
+ */
+/** Marketplace entry with its package ID (key from lock record). */
+type MarketplaceEntryWithId = MarketplaceEntry & {
+    id: string;
+};
+interface MarketplaceServiceAPI {
+    /** List installed entries, optionally filtered by kind */
+    list(filter?: {
+        kind?: EntityKind;
+    }): Promise<MarketplaceEntryWithId[]>;
+    /** Get a single entry by package ID */
+    getEntry(packageId: string): Promise<MarketplaceEntry | null>;
+}
+/**
+ * Strategy for handling a specific entity kind in the marketplace.
+ *
+ * Each entity type (plugin, adapter, workflow, etc.) can have custom
+ * detection, extraction, and lifecycle hooks. Adding a new entity type
+ * means implementing this interface — zero changes to core.
+ */
+interface EntityKindStrategy {
+    /** Which primary kind this strategy handles */
+    kind: EntityKind;
+    /**
+     * Detect whether a package at the given root is of this entity kind.
+     * Returns the kind if detected, null otherwise.
+     */
+    detectKind(packageRoot: string): Promise<EntityKind | null>;
+    /**
+     * Extract all entity kinds this package provides.
+     * Called after detectKind succeeds.
+     */
+    extractProvides(packageRoot: string): Promise<EntityKind[]>;
+    /**
+     * Post-install hook. Called after the package is installed and written to lock.
+     * Example: adapter strategy validates that required adapter dependencies are installed.
+     */
+    afterInstall?(packageId: string, packageRoot: string, service: MarketplaceServiceAPI): 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>;
+}
+/**
+ * Cached manifest entry. Stored in .kb/marketplace.manifests.json.
+ * Different entity types have different manifest shapes (ManifestV3, AdapterManifest).
+ * Caching avoids dynamic import on every discovery cycle.
+ */
+interface ManifestCacheEntry {
+    /** Which manifest type is stored */
+    manifestType: 'plugin' | 'adapter';
+    /** The manifest data. Type depends on manifestType. */
+    manifest: ManifestV3 | Record<string, unknown>;
+    /** ISO timestamp of when this entry was cached */
+    cachedAt: string;
+    /** Integrity hash of the source package when cached. Stale if different from lock. */
+    integrity: string;
+}
+/**
+ * Full manifest cache file schema.
+ */
+interface ManifestCache {
+    schema: 'kb.marketplace.manifests/1';
+    entries: Record<string, ManifestCacheEntry>;
+}
+interface InstallResultEntry {
+    id: string;
+    version: string;
+    primaryKind: EntityKind;
+    provides: EntityKind[];
+    packageRoot: string;
+}
+interface InstallResult {
+    installed: InstallResultEntry[];
+    warnings: string[];
+}
+interface SyncResult {
+    added: Array<{
+        id: string;
+        primaryKind: EntityKind;
+        version: string;
+    }>;
+    skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+    total: number;
+}
+interface DoctorIssue {
+    severity: 'error' | 'warning' | 'info';
+    packageId: string;
+    message: string;
+    remediation?: string;
+}
+interface DoctorReport {
+    ok: boolean;
+    total: number;
+    issues: DoctorIssue[];
+}
+
+export type { DoctorIssue, DoctorReport, EntityKindStrategy, InstallResult, InstallResultEntry, InstalledPackage, ManifestCache, ManifestCacheEntry, MarketplaceEntryWithId, MarketplaceServiceAPI, PackageListing, PackageSource, PublishMetadata, PublishResult, ResolvedPackage, SyncResult };

package/dist/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kb-labs/marketplace-contracts",
+  "version": "0.1.1",
+  "description": "Shared types and interfaces for KB Labs marketplace",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --passWithNoTests -c ../../vitest.config.ts",
+    "test:watch": "vitest -c ../../vitest.config.ts"
+  },
+  "dependencies": {
+    "@kb-labs/core-discovery": "^1.5.0",
+    "@kb-labs/plugin-contracts": "^1.3.0",
+    "@kb-labs/core-platform": "^1.5.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit"
+  }
+}