@soulcraft/brainy 0.9.16 → 0.9.19

package/README.md

@@ -6,7 +6,7 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.1.6-blue.svg)](https://www.typescriptlang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![npm](https://img.shields.io/badge/npm-v0.9.16-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy)
+[![npm](https://img.shields.io/badge/npm-v0.9.19-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy)
 
 [//]: # ([![Cartographer](https://img.shields.io/badge/Cartographer-Official%20Standard-brightgreen)](https://github.com/sodal-project/cartographer))
 
@@ -110,8 +110,15 @@ import { BrainyData } from '@soulcraft/brainy'
 
 // Minified version for production
 import { BrainyData } from '@soulcraft/brainy/min'
+
+// CLI functionality (only imported when needed)
+import '@soulcraft/brainy/cli'
 ```
 
+> **Note**: The CLI functionality (4MB) is not included in the standard import, reducing the bundle size for browser and
+> Node.js applications. The CLI is only built and loaded when explicitly imported or when using the command-line
+> interface.
+
 ### Browser Usage
 
 ```html
@@ -285,23 +292,30 @@ Brainy uses a modern build system that optimizes for both Node.js and browser en
 2. **Environment-Specific Builds**
     - **Node.js Build**: Optimized for server environments with full functionality
     - **Browser Build**: Optimized for browser environments with reduced bundle size
+    - **CLI Build**: Separate build for command-line interface functionality
     - Conditional exports in package.json for automatic environment detection
 
-3. **Environment Detection**
+3. **Modular Architecture**
+    - Core functionality and CLI are built separately
+    - CLI (4MB) is only included when explicitly imported or used from command line
+    - Reduced bundle size for browser and Node.js applications
+
+4. **Environment Detection**
     - Automatically detects whether it's running in a browser or Node.js
     - Loads appropriate dependencies and functionality based on the environment
     - Provides consistent API across all environments
 
-4. **TypeScript**
+5. **TypeScript**
     - Written in TypeScript for type safety and better developer experience
     - Generates type definitions for TypeScript users
     - Compiled to ES2020 for modern JavaScript environments
 
-5. **Build Scripts**
-    - `npm run build`: Builds the Node.js version
+6. **Build Scripts**
+    - `npm run build`: Builds the core library without CLI
     - `npm run build:browser`: Builds the browser-optimized version
-    - `npm run build:cli`: Builds the CLI version
-    - `npm run demo`: Builds both Node.js and browser versions and starts a demo server
+    - `npm run build:cli`: Builds the CLI version (only needed for CLI usage)
+    - `npm run prepare:cli`: Builds the CLI for command-line usage
+    - `npm run demo`: Builds both core library and browser versions and starts a demo server
     - GitHub Actions workflow: Automatically deploys the demo directory to GitHub Pages when pushing to the main branch
 
 ### Running the Pipeline
@@ -412,11 +426,14 @@ Connections between nouns (edges in the graph):
 
 ## Command Line Interface
 
-Brainy includes a powerful CLI for managing your data:
+Brainy includes a powerful CLI for managing your data. The CLI is available as a separate package
+`@soulcraft/brainy-cli` to reduce the bundle size of the main package.
+
+### Installing and Using the CLI
 
 ```bash
-# Install globally
-npm install -g @soulcraft/brainy --legacy-peer-deps
+# Install the CLI globally
+npm install -g @soulcraft/brainy-cli
 
 # Initialize a database
 brainy init
@@ -436,6 +453,26 @@ brainy visualize
 brainy visualize --root <id> --depth 3
 ```
 
+### Publishing the CLI Package
+
+If you need to publish the CLI package to npm, please refer to the [CLI Publishing Guide](docs/publishing-cli.md) for
+detailed instructions.
+
+### Using the CLI in Your Code
+
+If you need to use the CLI functionality in your code, you can import it explicitly:
+
+```typescript
+// Import the CLI functionality
+import '@soulcraft/brainy/cli'
+
+// Now you can use the CLI programmatically
+// ...
+```
+
+This will only build and load the CLI when you explicitly import it, keeping your bundle size small when you don't need
+the CLI.
+
 ### Development Usage
 
 ```bash
@@ -1270,17 +1307,24 @@ comprehensive [Scaling Strategy](scalingStrategy.md) document.
 
 Brainy takes advantage of several optimizations available in Node.js 24:
 
-1. **Improved Worker Threads Performance**: The multithreading system has been completely rewritten to leverage Node.js 24's enhanced Worker Threads API, resulting in better performance for compute-intensive operations like embedding generation and vector similarity calculations.
+1. **Improved Worker Threads Performance**: The multithreading system has been completely rewritten to leverage Node.js
+   24's enhanced Worker Threads API, resulting in better performance for compute-intensive operations like embedding
+   generation and vector similarity calculations.
 
-2. **Worker Pool Management**: A sophisticated worker pool system reuses worker threads to minimize the overhead of creating and destroying threads, leading to more efficient resource utilization.
+2. **Worker Pool Management**: A sophisticated worker pool system reuses worker threads to minimize the overhead of
+   creating and destroying threads, leading to more efficient resource utilization.
 
-3. **Dynamic Module Imports**: Uses the new `node:` protocol prefix for importing core modules, which provides better performance and more reliable module resolution.
+3. **Dynamic Module Imports**: Uses the new `node:` protocol prefix for importing core modules, which provides better
+   performance and more reliable module resolution.
 
-4. **ES Modules Optimizations**: Takes advantage of Node.js 24's improved ESM implementation for faster module loading and execution.
+4. **ES Modules Optimizations**: Takes advantage of Node.js 24's improved ESM implementation for faster module loading
+   and execution.
 
-5. **Enhanced Error Handling**: Implements more robust error handling patterns available in Node.js 24 for better stability and debugging.
+5. **Enhanced Error Handling**: Implements more robust error handling patterns available in Node.js 24 for better
+   stability and debugging.
 
 These optimizations are particularly beneficial for:
+
 - Large-scale vector operations
 - Batch processing of embeddings
 - Real-time data processing pipelines

package/dist/cli.js

@@ -13426,7 +13426,7 @@ var omelette = /*@__PURE__*/getDefaultExportFromCjs(omeletteExports);
  * This file is auto-generated during the build process.
  * Do not modify this file directly.
  */
-const VERSION = '0.9.16';
+const VERSION = '0.9.17';
 
 /**
  * Brainy CLI

package/dist/utils/version.d.ts

@@ -2,5 +2,5 @@
  * This file is auto-generated during the build process.
  * Do not modify this file directly.
  */
-export declare const VERSION = "0.9.16";
+export declare const VERSION = "0.9.19";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "0.9.16",
+  "version": "0.9.19",
   "description": "A vector graph database using HNSW indexing with Origin Private File System storage",
   "main": "dist/unified.js",
   "module": "dist/unified.js",
@@ -31,10 +31,8 @@
     "prebuild": "node scripts/generate-version.js",
     "build": "BUILD_TYPE=unified rollup -c rollup.config.js",
     "build:browser": "BUILD_TYPE=browser rollup -c rollup.config.js",
-    "build:cli": "BUILD_TYPE=cli rollup -c rollup.config.js",
     "start": "node dist/unified.js",
     "demo": "npm run build && npm run build:browser && npx http-server -o /index.html",
-    "cli": "npm run build:cli && node ./cli-wrapper.js",
     "version": "node scripts/generate-version.js",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
@@ -44,8 +42,9 @@
     "format": "prettier --write \"src/**/*.{ts,js}\"",
     "check-format": "prettier --check \"src/**/*.{ts,js}\"",
     "check-style": "node scripts/check-code-style.js",
-    "prepare": "npm run build && npm run build:cli",
+    "prepare": "npm run build",
     "deploy": "npm run build && npm publish",
+    "deploy:both": "node scripts/publish-cli.js",
     "deploy:cloud:aws": "cd cloud-wrapper && npm run build && npm run deploy:aws",
     "deploy:cloud:gcp": "cd cloud-wrapper && npm run build && npm run deploy:gcp",
     "deploy:cloud:cloudflare": "cd cloud-wrapper && npm run build && npm run deploy:cloudflare",
@@ -53,9 +52,6 @@
     "postinstall": "echo 'Note: If you encounter dependency conflicts with TensorFlow.js packages, please use: npm install --legacy-peer-deps'",
     "dry-run": "npm pack --dry-run"
   },
-  "bin": {
-    "brainy": "cli-wrapper.js"
-  },
   "keywords": [
     "vector-database",
     "hnsw",
@@ -85,7 +81,6 @@
     "dist/types/",
     "LICENSE",
     "README.md",
-    "cli-wrapper.js",
     "brainy.png"
   ],
   "devDependencies": {
@@ -95,7 +90,6 @@
     "@rollup/plugin-replace": "^5.0.5",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^20.4.5",
-    "@types/omelette": "^0.4.5",
     "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
@@ -114,8 +108,6 @@
     "@tensorflow/tfjs-converter": "^4.22.0",
     "@tensorflow/tfjs-core": "^4.22.0",
     "buffer": "^6.0.3",
-    "commander": "^14.0.0",
-    "omelette": "^0.4.17",
     "uuid": "^9.0.0"
   },
   "prettier": {

package/cli-wrapper.js

@@ -1,56 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * CLI Wrapper Script
- *
- * This script serves as a wrapper for the Brainy CLI, ensuring that command-line arguments
- * are properly passed to the CLI when invoked through npm scripts.
- */
-
-import { spawn } from 'child_process'
-import { fileURLToPath } from 'url'
-import { dirname, join } from 'path'
-import fs from 'fs'
-
-// Get the directory of the current module
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-// Path to the actual CLI script
-const cliPath = join(__dirname, 'dist', 'cli.js')
-
-// Check if the CLI script exists
-if (!fs.existsSync(cliPath)) {
-  console.error(`Error: CLI script not found at ${cliPath}`)
-  console.error('Make sure you have built the project with "npm run build"')
-  process.exit(1)
-}
-
-// Special handling for version flags
-if (process.argv.includes('--version') || process.argv.includes('-V')) {
-  // Read version directly from package.json to ensure it's always correct
-  try {
-    const packageJsonPath = join(__dirname, 'package.json')
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
-    console.log(packageJson.version)
-    process.exit(0)
-  } catch (error) {
-    console.error('Error loading version information:', error.message)
-    process.exit(1)
-  }
-}
-
-// Forward all arguments to the CLI script
-const args = process.argv.slice(2)
-
-// Check if npm is passing --force flag
-// When npm runs with --force, it sets the npm_config_force environment variable
-if (process.env.npm_config_force === 'true' && args.includes('clear') && !args.includes('--force') && !args.includes('-f')) {
-  args.push('--force')
-}
-
-const cli = spawn('node', [cliPath, ...args], { stdio: 'inherit' })
-
-cli.on('close', (code) => {
-  process.exit(code)
-})