**feat(cli, scripts): introduce CLI package and automated publishing process**

- Added a new `@soulcraft/brainy-cli` package to provide a dedicated CLI interface for the Brainy database.
- Implemented a CLI wrapper script (`cli-wrapper.js`) to manage global package execution and version handling.
- Introduced `scripts/publish-cli.js` to automate synchronized publishing of the main package and CLI, ensuring version consistency.
- Created documentation for CLI usage and publishing workflow (`publishing-cli.md`).
- Updated `package.json` to include CLI-related build and deploy scripts.
- Adjusted `README.md` to document the CLI package, usage instructions, and build separation.

This feature introduces a standalone CLI package, improves deployment automation, and enhances documentation to align with the updated architecture.

scripts/generate-version.js

@@ -7,7 +7,8 @@
  * This allows the CLI to access the version without having to read package.json directly,
  * which can be problematic when the package is installed globally.
  *
- * It also updates the version in the README.md file to ensure it stays in sync with package.json.
+ * It also updates the version in the README.md file and CLI package.json to ensure they
+ * stay in sync with the main package.json.
  */
 
 import fs from 'fs'
@@ -33,6 +34,9 @@ const outputFile = path.join(outputDir, 'version.ts')
 // Path to README.md
 const readmePath = path.join(rootDir, 'README.md')
 
+// Path to CLI package.json
+const cliPackageJsonPath = path.join(rootDir, 'cli-package', 'package.json')
+
 // Read package.json
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
 const version = packageJson.version
@@ -105,3 +109,23 @@ try {
 } catch (error) {
   console.error('Error updating README.md:', error)
 }
+
+// Update CLI package.json with the same version
+try {
+  // Read CLI package.json
+  const cliPackageJson = JSON.parse(fs.readFileSync(cliPackageJsonPath, 'utf8'))
+
+  // Update version
+  cliPackageJson.version = version
+
+  // Update dependency on main package to be exact
+  if (cliPackageJson.dependencies && cliPackageJson.dependencies['@soulcraft/brainy']) {
+    cliPackageJson.dependencies['@soulcraft/brainy'] = version
+  }
+
+  // Write the updated CLI package.json back to disk
+  fs.writeFileSync(cliPackageJsonPath, JSON.stringify(cliPackageJson, null, 2))
+  console.log(`Updated CLI package.json with version ${version} and exact dependency on main package`)
+} catch (error) {
+  console.error('Error updating CLI package.json:', error)
+}

scripts/publish-cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * Script to build and publish both the main package and CLI package
+ *
+ * This script:
+ * 1. Ensures versions are in sync by running generate-version.js
+ * 2. Builds the main package
+ * 3. Builds the CLI
+ * 4. Publishes the main package
+ * 5. Publishes the CLI package
+ * 
+ * This ensures both packages are always published together with the same version.
+ */
+
+import { execSync } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const rootDir = path.join(__dirname, '..')
+const cliPackageDir = path.join(rootDir, 'cli-package')
+
+// Ensure the CLI package directory exists
+if (!fs.existsSync(cliPackageDir)) {
+  console.error(`Error: CLI package directory not found at ${cliPackageDir}`)
+  process.exit(1)
+}
+
+try {
+  // Step 1: Ensure versions are in sync
+  console.log('Ensuring versions are in sync...')
+  execSync('node scripts/generate-version.js', { stdio: 'inherit', cwd: rootDir })
+
+  // Step 2: Build the main package
+  console.log('Building main package...')
+  execSync('npm run build', { stdio: 'inherit', cwd: rootDir })
+
+  // Step 3: Build the CLI
+  console.log('Building CLI...')
+  execSync('npm run build:cli', { stdio: 'inherit', cwd: rootDir })
+
+  // Step 4: Verify the CLI was built successfully
+  const cliPath = path.join(rootDir, 'dist', 'cli.js')
+  if (!fs.existsSync(cliPath)) {
+    console.error(`Error: CLI build failed. File not found at ${cliPath}`)
+    process.exit(1)
+  }
+
+  // Step 5: Publish the main package
+  console.log('Publishing main package...')
+  execSync('npm publish', { stdio: 'inherit', cwd: rootDir })
+
+  // Step 6: Publish the CLI package
+  console.log('Publishing CLI package...')
+  execSync('npm publish', { stdio: 'inherit', cwd: cliPackageDir })
+
+  console.log('Both packages published successfully!')
+} catch (error) {
+  console.error('Error:', error.message)
+  process.exit(1)
+}