@majkapp/plugin-kit 3.7.9 → 3.7.10

package/bin/promptable-cli.js

@@ -179,7 +179,7 @@ cli.addCommand('--tasks',
 // Knowledge API
 cli.addCommand('--knowledge',
   cli.createFullDocCommand('KNOWLEDGE.md'),
-  { description: 'Knowledge trees and search' }
+  { description: 'Knowledge Fabric for semantic search and contribution' }
 );
 
 // Agents API

package/dist/generator/cli.js

@@ -79,7 +79,7 @@ if (!isHelpRequest) {
 // Normal commander behavior (generator commands)
 commander_1.program
     .name('plugin-kit')
-    .version('1.0.20')
+    .version('3.7.10')
     .description('Plugin Kit CLI - Generate TypeScript clients from plugin definitions');
 commander_1.program
     .command('generate')
@@ -211,7 +211,7 @@ commander_1.program
     .option('--llm:config-api', 'Access MAJK configuration')
     .option('--llm:plugins', 'Plugin lifecycle management')
     .option('--llm:tasks', 'Start and monitor async tasks')
-    .option('--llm:knowledge', 'Knowledge trees and search')
+    .option('--llm:knowledge', 'Knowledge Fabric for semantic search and contribution')
     .option('--llm:agents', 'Agent configuration and testing')
     .option('--llm:conversations', 'Conversation access and management');
 commander_1.program.parse();

package/dist/majk-interface-types.d.ts

@@ -1035,11 +1035,428 @@ export interface KnowledgeSearchOptions {
     tree?: string;
     limit?: number;
 }
+/**
+ * System-reserved prefixes that plugins cannot use for contributions.
+ */
+export declare const RESERVED_PREFIXES: readonly ["/projects", "/teammates", "/tools", "/skills", "/reports", "/characterizations"];
+/**
+ * Node status in the Knowledge Fabric.
+ */
+export type FabricNodeStatus = 'active' | 'pending' | 'inactive';
+/**
+ * A node in the Knowledge Fabric.
+ *
+ * This is the API-facing representation of a fabric node.
+ */
+export interface KnowledgeFabricNode {
+    /** Hierarchical key path (e.g., "/plugins/my-plugin/entities/item-1") */
+    key: string;
+    /** Human-readable title */
+    title: string;
+    /** The searchable content */
+    content: string;
+    /** Child node keys */
+    children: string[];
+    /** Metadata and source references */
+    refs: Record<string, unknown>;
+    /** Who contributed this node */
+    contributorId: string;
+    /** Current lifecycle status */
+    status: FabricNodeStatus;
+    /** When this node was created (timestamp) */
+    createdAt: number;
+    /** When this node was last contributed (timestamp) */
+    lastContributed: number;
+}
+/**
+ * Input for contributing a node to the fabric.
+ */
+export interface ContributeNodeInput {
+    /**
+     * Key for this node (relative to the contribution prefix).
+     *
+     * Will be combined with the contribution prefix:
+     *   prefix: "/plugins/my-plugin/entities"
+     *   key: "item-1"
+     *   → full key: "/plugins/my-plugin/entities/item-1"
+     */
+    key: string;
+    /** Human-readable title */
+    title: string;
+    /** Searchable content (what gets embedded for semantic search) */
+    content: string;
+    /** Optional child keys (relative to prefix) */
+    children?: string[];
+    /** Optional metadata/references */
+    refs?: Record<string, unknown>;
+}
+/**
+ * Options for semantic search.
+ */
+export interface FabricSearchOptions {
+    /**
+     * Scope search to this key prefix.
+     *
+     * @example
+     * // Search only within your plugin's knowledge
+     * { under: handle.prefix }
+     *
+     * // Search within a specific project
+     * { under: '/projects/project-abc123' }
+     */
+    under?: string;
+    /** Maximum number of results (default: 10, max: 100) */
+    limit?: number;
+    /** Minimum similarity score 0-1 */
+    minScore?: number;
+}
+/**
+ * A single search result.
+ */
+export interface FabricSearchResult {
+    /** The matching node */
+    node: KnowledgeFabricNode;
+    /** Similarity score 0-1 (1 = most similar) */
+    score: number;
+}
+/**
+ * Response from a search operation.
+ */
+export interface FabricSearchResponse {
+    /** Search results ordered by relevance */
+    results: FabricSearchResult[];
+    /** Current indexing status */
+    indexingStatus: {
+        /** Are all nodes in scope fully indexed? */
+        complete: boolean;
+        /** Number of nodes still being indexed */
+        pendingCount: number;
+    };
+}
+/**
+ * Result of expanding a node to see its children.
+ */
+export interface FabricExpandResult {
+    /** The expanded node */
+    node: KnowledgeFabricNode;
+    /** Direct children of this node */
+    children: KnowledgeFabricNode[];
+}
+/**
+ * Overall status of the Knowledge Fabric.
+ */
+export interface FabricStatus {
+    /** Total number of nodes in the fabric */
+    totalNodes: number;
+    /** Number of active, searchable nodes */
+    activeNodes: number;
+    /** Number of nodes awaiting embedding */
+    pendingNodes: number;
+    /** Total number of unique embeddings */
+    totalEmbeddings: number;
+    /** Whether semantic search is available */
+    searchAvailable: boolean;
+}
+/**
+ * Options for registering a knowledge contribution.
+ */
+export interface RegisterContributionOptions {
+    /**
+     * Custom prefix for this contribution.
+     *
+     * DEFAULT: `/plugins/{pluginId}/{subPrefix}`
+     *
+     * CUSTOM: Any prefix except:
+     *   - Reserved system prefixes: /projects, /teammates, /tools, /skills, /reports
+     *   - Other plugins' namespaces: /plugins/{otherPluginId}/...
+     *
+     * Prefixes are EXCLUSIVE - first to register owns it.
+     * To share a namespace with other plugins, use sub-prefixes:
+     *   Plugin A: /contacts/hubspot
+     *   Plugin B: /contacts/salesforce
+     */
+    prefix?: string;
+    /**
+     * Initial nodes to contribute on registration.
+     *
+     * These are contributed before the handle is returned,
+     * so they're immediately available for search (after indexing).
+     */
+    initialNodes?: ContributeNodeInput[];
+    /**
+     * Optional label resolver for virtual nodes in the hierarchy.
+     *
+     * Called when the fabric needs a human-readable label for a path segment.
+     *
+     * @param key - The full key path
+     * @param segment - The specific segment to label
+     * @param depth - The depth of the segment (1-indexed)
+     * @returns Display label, or null to use default formatting
+     */
+    resolveLabel?: (key: string, segment: string, depth: number) => string | null;
+}
+/**
+ * Handle for managing a knowledge contribution.
+ *
+ * Returned by `registerContribution()`. Use this to add, update,
+ * and remove nodes from your contribution.
+ */
+export interface KnowledgeContributionHandle {
+    /**
+     * The full key prefix for this contribution.
+     *
+     * All nodes you contribute will be under this prefix.
+     */
+    readonly prefix: string;
+    /**
+     * The contributor ID for this contribution.
+     *
+     * Format: `plugin:{pluginId}:{subPrefix}`
+     */
+    readonly contributorId: string;
+    /**
+     * Contribute a single node.
+     *
+     * If a node with this key already exists (from this contributor),
+     * it will be updated. The node will be queued for embedding.
+     *
+     * @param node - The node to contribute
+     */
+    contribute(node: ContributeNodeInput): Promise<void>;
+    /**
+     * Contribute multiple nodes in batch.
+     *
+     * More efficient than calling contribute() multiple times.
+     *
+     * @param nodes - The nodes to contribute
+     */
+    contributeBatch(nodes: ContributeNodeInput[]): Promise<void>;
+    /**
+     * Remove a node by key.
+     *
+     * The key is relative to the contribution prefix.
+     *
+     * @param key - The key of the node to remove (relative to prefix)
+     * @returns true if the node was found and removed
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * Get the current number of nodes in this contribution.
+     */
+    getNodeCount(): Promise<number>;
+    /**
+     * List all keys in this contribution.
+     *
+     * @param options - Optional filtering options
+     * @returns Array of full keys
+     */
+    listKeys(options?: {
+        status?: 'active' | 'pending' | 'all';
+    }): Promise<string[]>;
+    /**
+     * Reconcile this contribution.
+     *
+     * This re-syncs the contribution by:
+     * 1. Marking all existing nodes as inactive
+     * 2. Re-contributing all nodes from the source
+     * 3. Nodes not re-contributed stay inactive (will be GC'd)
+     *
+     * Useful when the underlying data source may have changed.
+     *
+     * @returns Statistics about what changed
+     */
+    reconcile(): Promise<{
+        added: number;
+        updated: number;
+        deactivated: number;
+    }>;
+    /**
+     * Unregister this contribution.
+     *
+     * All nodes from this contribution will be marked inactive
+     * and eventually garbage collected.
+     *
+     * After calling this, the handle is no longer usable.
+     */
+    unregister(): Promise<void>;
+}
+/**
+ * Summary of a contribution for listing.
+ */
+export interface ContributionSummary {
+    /** The full key prefix */
+    prefix: string;
+    /** The contributor ID */
+    contributorId: string;
+    /** Number of active nodes */
+    nodeCount: number;
+    /** Number of pending nodes */
+    pendingCount: number;
+    /** Current status */
+    status: 'ready' | 'indexing' | 'unregistered';
+}
+/**
+ * Events emitted by the fabric that plugins can subscribe to.
+ */
+export type FabricNodeEvent = {
+    type: 'indexed';
+    key: string;
+} | {
+    type: 'activated';
+    key: string;
+} | {
+    type: 'deactivated';
+    key: string;
+} | {
+    type: 'reindexed';
+    key: string;
+};
+/**
+ * Knowledge Fabric API for plugins.
+ *
+ * Provides unified access to the Knowledge Fabric for:
+ * - Semantic search across all knowledge
+ * - Browsing the knowledge hierarchy
+ * - Contributing plugin-specific knowledge
+ *
+ * Access via `ctx.majk.knowledge.fabric`
+ */
+export interface KnowledgeFabricAPI {
+    /**
+     * Semantic search across all knowledge in the system.
+     *
+     * Searches:
+     * - Project notes (knowledge trees)
+     * - Teammates
+     * - Tools
+     * - Plugins
+     * - Skills
+     * - Reports
+     * - Plugin-contributed knowledge
+     *
+     * @param query - Natural language search query
+     * @param options - Search options (scope, limit, min score)
+     * @returns Matching nodes ordered by relevance
+     *
+     * @example
+     * // Search all knowledge
+     * const results = await fabric.search('authentication patterns');
+     *
+     * // Search within a specific scope
+     * const results = await fabric.search('authentication', {
+     *   under: '/projects/my-project',
+     *   limit: 5,
+     *   minScore: 0.3
+     * });
+     */
+    search(query: string, options?: FabricSearchOptions): Promise<FabricSearchResponse>;
+    /**
+     * Get root nodes of the knowledge hierarchy.
+     *
+     * @returns Top-level nodes (/projects, /plugins, /teammates, etc.)
+     */
+    getRoots(): Promise<KnowledgeFabricNode[]>;
+    /**
+     * Expand a node to see its children.
+     *
+     * @param key - The node key to expand
+     * @returns The node and its direct children, or null if not found
+     *
+     * @example
+     * const result = await fabric.expand('/plugins');
+     * console.log(result.children); // All plugin nodes
+     */
+    expand(key: string): Promise<FabricExpandResult | null>;
+    /**
+     * Get a single node by key.
+     *
+     * @param key - The node key
+     * @returns The node or null if not found
+     */
+    getNode(key: string): Promise<KnowledgeFabricNode | null>;
+    /**
+     * Get the current status of the Knowledge Fabric.
+     *
+     * @returns Status including node counts and search availability
+     */
+    getStatus(): Promise<FabricStatus>;
+    /**
+     * Register a knowledge contribution for this plugin.
+     *
+     * Creates a scoped namespace for the plugin to contribute knowledge.
+     * Returns a handle for managing nodes in the contribution.
+     *
+     * @param subPrefix - Sub-namespace name (e.g., "entities", "docs")
+     * @param options - Configuration including custom prefix and initial nodes
+     * @returns Handle for managing the contribution
+     *
+     * @example
+     * // Using default prefix (recommended)
+     * const handle = await fabric.registerContribution('contacts', {
+     *   initialNodes: [
+     *     { key: 'john', title: 'John Doe', content: 'CEO at Acme Corp...' }
+     *   ]
+     * });
+     * // Prefix: /plugins/{pluginId}/contacts
+     *
+     * // Using custom prefix
+     * const handle = await fabric.registerContribution('contacts', {
+     *   prefix: '/crm/contacts'
+     * });
+     * // Prefix: /crm/contacts
+     */
+    registerContribution(subPrefix: string, options?: RegisterContributionOptions): Promise<KnowledgeContributionHandle>;
+    /**
+     * List all contributions registered by this plugin.
+     *
+     * @returns Array of contribution summaries
+     */
+    listContributions(): Promise<ContributionSummary[]>;
+    /**
+     * Subscribe to node change events.
+     *
+     * Events are filtered to this plugin's contributions by default.
+     *
+     * @param handler - Event handler function
+     * @param options - Optional filter options
+     * @returns Unsubscribe function
+     *
+     * @example
+     * const unsub = fabric.onNodeChange((event) => {
+     *   console.log(`Node ${event.key} was ${event.type}`);
+     * });
+     *
+     * // Later: unsub();
+     */
+    onNodeChange(handler: (event: FabricNodeEvent) => void, options?: {
+        allNodes?: boolean;
+    }): () => void;
+}
 export interface KnowledgeAPI {
+    /**
+     * Access to the unified Knowledge Fabric.
+     *
+     * Provides semantic search across all knowledge and
+     * the ability to contribute plugin-specific knowledge.
+     *
+     * @example
+     * // Search all knowledge
+     * const results = await ctx.majk.knowledge.fabric.search('authentication');
+     *
+     * // Contribute knowledge
+     * const handle = await ctx.majk.knowledge.fabric.registerContribution('contacts');
+     * await handle.contribute({ key: 'c1', title: 'Contact', content: '...' });
+     */
+    readonly fabric: KnowledgeFabricAPI;
+    /** @deprecated Use fabric.search() for semantic search */
     add(input: AddKnowledgeInput): Promise<void>;
+    /** @deprecated Use fabric.search() for semantic search */
     search(query: string, options?: KnowledgeSearchOptions): Promise<KnowledgeNode[]>;
+    /** @deprecated Use fabric for knowledge operations */
     getByReference(ref: string): Promise<KnowledgeNode[]>;
+    /** @deprecated Use fabric for knowledge operations */
     getTree(conversationId: string, treeName: string): Promise<KnowledgeTree>;
+    /** @deprecated Use fabric for knowledge operations */
     listTrees(conversationId: string): Promise<string[]>;
 }
 /**