@kb-labs/mind-entry 2.14.0

package/README.md

@@ -0,0 +1,218 @@
+# @kb-labs/mind-cli
+
+CLI commands for KB Labs Mind.
+
+## Vision & Purpose
+
+**@kb-labs/mind-cli** provides CLI commands for KB Labs Mind. It includes commands for indexing, querying, packing, and verifying Mind indexes, plus REST handlers and Studio widgets.
+
+### Core Goals
+
+- **Indexing Commands**: Index codebase and update indexes
+- **Query Commands**: Query Mind indexes
+- **Pack Commands**: Build context packs
+- **Verify Commands**: Verify Mind indexes
+- **REST Handlers**: REST API handlers
+- **Studio Widgets**: Studio widget implementations
+
+## Package Status
+
+- **Version**: 0.1.0
+- **Stage**: Stable
+- **Status**: Production Ready ✅
+
+## Architecture
+
+### High-Level Overview
+
+```
+Mind CLI
+    │
+    ├──► CLI Commands
+    ├──► Application Layer
+    ├──► Domain Layer
+    ├──► Infrastructure Layer
+    ├──► REST Handlers
+    └──► Studio Widgets
+```
+
+### Key Components
+
+1. **CLI Commands** (`cli/`): CLI command implementations
+2. **Application Layer** (`application/`): Use cases and services
+3. **Domain Layer** (`domain/`): Domain logic
+4. **Infrastructure Layer** (`infra/`): Adapters and infrastructure
+5. **REST Handlers** (`rest/`): REST API handlers
+6. **Studio Widgets** (`studio/`): Studio widget implementations
+
+## ✨ Features
+
+- **Indexing Commands**: Index codebase and update indexes
+- **Query Commands**: Query Mind indexes
+- **Pack Commands**: Build context packs
+- **Verify Commands**: Verify Mind indexes
+- **REST Handlers**: REST API handlers
+- **Studio Widgets**: Query and verify widgets for Studio
+
+## 📦 API Reference
+
+### Main Exports
+
+#### CLI Commands
+
+- `index`: Index codebase command
+- `query`: Query Mind index command
+- `pack`: Build context pack command
+- `verify`: Verify Mind index command
+
+#### Manifest
+
+- `manifest`: Plugin manifest V2
+
+## 🔧 Configuration
+
+### Configuration Options
+
+All configuration via CLI flags and kb-labs.config.json.
+
+### CLI Flags
+
+- `--json`: Output JSON format
+- `--quiet`: Quiet mode
+- `--verbose`: Verbose output
+
+## 🔗 Dependencies
+
+### Runtime Dependencies
+
+- `@byjohann/toon` (`0.4.0`): Terminal UI library
+- `@kb-labs/analytics-sdk-node` (`link:../../../kb-labs-analytics/packages/analytics-sdk-node`): Analytics SDK
+- `@kb-labs/core` (`link:../../../kb-labs-core`): Core package
+- `@kb-labs/plugin-manifest` (`link:../../../kb-labs-plugin/packages/manifest`): Plugin manifest
+- `@kb-labs/plugin-adapter-studio` (`link:../../../kb-labs-plugin/packages/adapters/studio`): Studio adapter
+- `@kb-labs/mind-contracts` (`link:../contracts`): Mind contracts
+- `@kb-labs/mind-gateway` (`link:../mind-gateway`): Mind gateway
+- `@kb-labs/mind-core` (`link:../mind-core`): Mind core
+- `@kb-labs/mind-indexer` (`link:../mind-indexer`): Mind indexer
+- `@kb-labs/mind-pack` (`link:../mind-pack`): Mind pack
+- `@kb-labs/mind-query` (`link:../mind-query`): Mind query
+- `@kb-labs/mind-types` (`link:../mind-types`): Mind types
+- `@kb-labs/shared-cli-ui` (`link:../../../kb-labs-shared/packages/cli-ui`): Shared CLI UI
+- `@tanstack/react-query` (`^5.0.0`): React Query
+- `@aws-sdk/client-s3` (`^3.929.0`): AWS S3 client
+- `ajv` (`^8.17.1`): JSON schema validation
+- `ajv-formats` (`^3.0.1`): AJV formats
+- `glob` (`^11.0.0`): File globbing
+- `react` (`^18.0.0`): React
+- `uuidv7` (`^1.0.0`): UUID v7 generation
+- `yaml` (`^2.8.0`): YAML parsing
+- `zod` (`^3.23.8`): Schema validation
+
+### Development Dependencies
+
+- `@kb-labs/devkit` (`link:../../../kb-labs-devkit`): DevKit presets
+- `@types/node` (`^24.7.0`): Node.js types
+- `@types/react` (`^18.3.18`): React types
+- `tsup` (`^8.5.0`): TypeScript bundler
+- `typescript` (`^5.6.3`): TypeScript compiler
+- `vitest` (`^3.2.4`): Test runner
+
+## 🧪 Testing
+
+### Test Structure
+
+```
+src/__tests__/
+└── (13 test files)
+```
+
+### Test Coverage
+
+- **Current Coverage**: ~75%
+- **Target Coverage**: 90%
+
+## 📈 Performance
+
+### Performance Characteristics
+
+- **Time Complexity**: O(1) for command registration, O(n) for command execution
+- **Space Complexity**: O(1)
+- **Bottlenecks**: Indexing and query operations
+
+## 🔒 Security
+
+### Security Considerations
+
+- **Input Validation**: Command input validation
+- **Path Validation**: Path validation for file operations
+
+### Known Vulnerabilities
+
+- None
+
+## 🐛 Known Issues & Limitations
+
+### Known Issues
+
+- None currently
+
+### Limitations
+
+## Breaking changes (no legacy compatibility)
+
+- `runRagQuery` response field `knowledge` renamed to `result`.
+- Runtime wrappers `createKnowledgeService/createKnowledgeEngineRegistry` removed from `mind-cli`.
+- Config resolution now supports only `.kb/kb.config.json` and `kb.config.json` with `profiles[].products.mind` (or root `mind`).
+- Legacy `knowledge.json` and top-level `knowledge` config are rejected.
+
+- **Command Types**: Fixed command types
+- **Output Formats**: Fixed output formats
+
+### Future Improvements
+
+- **More Commands**: Additional commands
+- **Custom Output Formats**: Custom output format support
+
+## 🔄 Migration & Breaking Changes
+
+### Migration from Previous Versions
+
+No breaking changes in current version (0.1.0).
+
+### Breaking Changes in Future Versions
+
+- None planned
+
+## 📚 Examples
+
+### Example 1: Index Codebase
+
+```bash
+kb mind:index
+```
+
+### Example 2: Query Mind Index
+
+```bash
+kb mind:query --query impact --params '{"symbol":"MyFunction"}'
+```
+
+### Example 3: Build Context Pack
+
+```bash
+kb mind:pack --intent "Review this code change"
+```
+
+### Example 4: Verify Index
+
+```bash
+kb mind:verify
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,24 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * Mind init command (V3)
+ *
+ * V3 Migration:
+ * - Default export with defineCommand
+ * - handler: { execute(ctx, input) }
+ * - NO permissions (inherited from manifest)
+ * - ctx.ui, ctx.logger, ctx.state (flat structure)
+ */
+interface InitInput {
+    argv: string[];
+    flags: {
+        cwd?: string;
+        force?: boolean;
+        json?: boolean;
+        verbose?: boolean;
+        quiet?: boolean;
+    };
+}
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, InitInput, unknown>;
+
+export { _default as default };

package/dist/cli/commands/init.js

@@ -0,0 +1,114 @@
+import { defineCommand } from '@kb-labs/sdk';
+import { initMindStructure } from '@kb-labs/mind-indexer';
+import { join } from 'path';
+import { promises } from 'fs';
+
+// src/cli/commands/init.ts
+var init_default = defineCommand({
+  id: "mind:init",
+  description: "Initialize mind workspace",
+  // ❌ NO permissions here - they are in manifest.v3.ts!
+  // Permissions are manifest-wide in V3
+  handler: {
+    async execute(ctx, input) {
+      const startTime = Date.now();
+      const { flags } = input;
+      const cwd = flags.cwd || ctx.cwd;
+      ctx.trace?.addEvent?.("mind.init.start", {
+        cwd,
+        command: "mind:init",
+        force: flags.force
+      });
+      ctx.trace?.addEvent?.("mind.init.initializing", { cwd, force: flags.force });
+      const mindDir = await initMindStructure({
+        cwd,
+        force: flags.force,
+        log: (entry) => {
+          if (!flags.quiet && !flags.json) {
+            ctx.ui.info(`Init: ${entry.msg || entry}`);
+          }
+          ctx.trace?.addEvent?.("mind.init.step", { msg: entry.msg || entry });
+        }
+      });
+      ctx.trace?.addEvent?.("mind.init.complete", {
+        mindDir,
+        cwd
+      });
+      const artifacts = [];
+      const artifactPatterns = [
+        { name: "Index", pattern: "index.json", description: "Main Mind index" },
+        { name: "API Index", pattern: "api-index.json", description: "API index" },
+        { name: "Dependencies", pattern: "deps.json", description: "Dependencies graph" },
+        { name: "Recent Diff", pattern: "recent-diff.json", description: "Recent changes diff" }
+      ];
+      for (const { name, pattern, description } of artifactPatterns) {
+        const artifactPath = join(mindDir, pattern);
+        try {
+          const stats = await promises.stat(artifactPath);
+          artifacts.push({
+            name,
+            path: artifactPath,
+            size: stats.size,
+            modified: stats.mtime,
+            description
+          });
+        } catch {
+        }
+      }
+      ctx.trace?.addEvent?.("mind.init.artifacts", {
+        mindDir,
+        artifactsCount: artifacts.length
+      });
+      const timing = Date.now() - startTime;
+      if (flags.json) {
+        ctx.ui.info(JSON.stringify({
+          ok: true,
+          summary: {
+            Workspace: mindDir,
+            Status: "Initialized"
+          },
+          artifacts,
+          timingMs: timing,
+          data: {
+            mindDir,
+            cwd
+          }
+        }));
+      } else if (!flags.quiet) {
+        const artifactItems = [];
+        for (const artifact of artifacts) {
+          artifactItems.push(`\u2713 ${artifact.name}: ${artifact.description}`);
+        }
+        const sections = [
+          {
+            header: "Summary",
+            items: [
+              `Workspace: ${mindDir}`,
+              `Status: Initialized`
+            ]
+          }
+        ];
+        if (artifacts.length > 0) {
+          sections.push({
+            header: "Created Artifacts",
+            items: artifactItems
+          });
+        }
+        ctx.ui.success("Mind workspace initialized", {
+          title: "Mind Init",
+          sections,
+          timing
+        });
+      }
+      return {
+        exitCode: 0,
+        mindDir,
+        artifacts
+      };
+    }
+  }
+});
+
+export { init_default as default };
+//# sourceMappingURL=init.js.map
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/commands/init.ts"],"names":["fsp"],"mappings":"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","file":"init.js","sourcesContent":["/**\n * Mind init command (V3)\n *\n * V3 Migration:\n * - Default export with defineCommand\n * - handler: { execute(ctx, input) }\n * - NO permissions (inherited from manifest)\n * - ctx.ui, ctx.logger, ctx.state (flat structure)\n */\n\nimport { defineCommand, type PluginContextV3 } from '@kb-labs/sdk';\nimport { initMindStructure } from '@kb-labs/mind-indexer';\nimport { join } from 'node:path';\nimport { promises as fsp } from 'node:fs';\n\ninterface InitInput {\n  argv: string[];\n  flags: {\n    cwd?: string;\n    force?: boolean;\n    json?: boolean;\n    verbose?: boolean;\n    quiet?: boolean;\n  };\n}\n\ninterface InitResult {\n  exitCode: number;\n  mindDir?: string;\n  artifacts?: Array<{\n    name: string;\n    path: string;\n    size: number;\n    modified: Date;\n    description: string;\n  }>;\n}\n\n// V3: Default export - REQUIRED\nexport default defineCommand({\n  id: 'mind:init',\n  description: 'Initialize mind workspace',\n\n  // ❌ NO permissions here - they are in manifest.v3.ts!\n  // Permissions are manifest-wide in V3\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: InitInput): Promise<InitResult> {\n      const startTime = Date.now();\n      const { flags } = input;\n\n      const cwd = flags.cwd || ctx.cwd;\n\n      // V3 API: Use trace for logging (logger not yet in runtime)\n      ctx.trace?.addEvent?.('mind.init.start', {\n        cwd,\n        command: 'mind:init',\n        force: flags.force,\n      });\n\n      ctx.trace?.addEvent?.('mind.init.initializing', { cwd, force: flags.force });\n\n      // Initialize Mind structure\n      const mindDir = await initMindStructure({\n        cwd,\n        force: flags.force,\n        log: (entry: any) => {\n          if (!flags.quiet && !flags.json) {\n            // V3 API: ctx.ui (not ctx.output.ui)\n            ctx.ui.info(`Init: ${entry.msg || entry}`);\n          }\n          ctx.trace?.addEvent?.('mind.init.step', { msg: entry.msg || entry });\n        },\n      });\n\n      ctx.trace?.addEvent?.('mind.init.complete', {\n        mindDir,\n        cwd,\n      });\n\n      // Discover created artifacts\n      const artifacts: InitResult['artifacts'] = [];\n\n      const artifactPatterns = [\n        { name: 'Index', pattern: 'index.json', description: 'Main Mind index' },\n        { name: 'API Index', pattern: 'api-index.json', description: 'API index' },\n        { name: 'Dependencies', pattern: 'deps.json', description: 'Dependencies graph' },\n        { name: 'Recent Diff', pattern: 'recent-diff.json', description: 'Recent changes diff' },\n      ];\n\n      for (const { name, pattern, description } of artifactPatterns) {\n        const artifactPath = join(mindDir, pattern);\n        try {\n          const stats = await fsp.stat(artifactPath);\n          artifacts.push({\n            name,\n            path: artifactPath,\n            size: stats.size,\n            modified: stats.mtime,\n            description,\n          });\n        } catch {\n          // Artifact doesn't exist, skip\n        }\n      }\n\n      ctx.trace?.addEvent?.('mind.init.artifacts', {\n        mindDir,\n        artifactsCount: artifacts.length,\n      });\n\n      const timing = Date.now() - startTime;\n\n      // Output result\n      if (flags.json) {\n        // V3 API: Write JSON to stdout directly\n        ctx.ui.info(JSON.stringify({\n          ok: true,\n          summary: {\n            Workspace: mindDir,\n            Status: 'Initialized',\n          },\n          artifacts,\n          timingMs: timing,\n          data: {\n            mindDir,\n            cwd,\n          },\n        }));\n      } else if (!flags.quiet) {\n        // V3 API: Enhanced UI with MessageOptions\n        const artifactItems: string[] = [];\n        for (const artifact of artifacts) {\n          artifactItems.push(`✓ ${artifact.name}: ${artifact.description}`);\n        }\n\n        const sections: Array<{ header?: string; items: string[] }> = [\n          {\n            header: 'Summary',\n            items: [\n              `Workspace: ${mindDir}`,\n              `Status: Initialized`,\n            ],\n          },\n        ];\n\n        if (artifacts.length > 0) {\n          sections.push({\n            header: 'Created Artifacts',\n            items: artifactItems,\n          });\n        }\n\n        // V3 API: ctx.ui.success with MessageOptions (enhanced UI)\n        ctx.ui.success('Mind workspace initialized', {\n          title: 'Mind Init',\n          sections,\n          timing,\n        });\n      }\n\n      // V3: Return structured result with exitCode\n      return {\n        exitCode: 0,\n        mindDir,\n        artifacts,\n      };\n    },\n  },\n});\n"]}

package/dist/cli/commands/rag-index.d.ts

@@ -0,0 +1,20 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * Mind rag-index command - build Mind indexes (V3)
+ */
+interface RagIndexInput {
+    argv: string[];
+    flags: {
+        cwd?: string;
+        scope?: string;
+        include?: string;
+        exclude?: string;
+        skipDeduplication?: boolean;
+        json?: boolean;
+        quiet?: boolean;
+    };
+}
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, RagIndexInput, unknown>;
+
+export { _default as default };