codexdb-sdk 0.1.6 → 0.1.15

package/PUBLISH.md

@@ -1,21 +1,187 @@
 # Publishing to npm
 
-To publish the CodexDB Node.js SDK to npm:
+## Quick Start (Automated)
 
-1. Make sure you have an npm account: https://www.npmjs.com/signup
-2. Login to npm in your terminal:
-   ```sh
+```bash
+cd /Users/everton/workspace/codex/sdk/nodejs
+npm run publish
+```
+
+This runs a complete automated workflow with validation and confirmation.
+
+## Prerequisites
+
+1. **npm account**: https://www.npmjs.com/signup
+2. **Login locally**:
+   ```bash
    npm login
    ```
-3. In the sdk/nodejs directory, publish the package:
-   ```sh
-   npm publish
+3. **Verify credentials**:
+   ```bash
+   npm whoami
    ```
 
-If you get a name conflict error, choose a unique package name in package.json (e.g., codexdb-sdk-everton) and try again.
+## Publishing Methods
+
+### Method 1: Automated Script (Recommended)
+
+```bash
+npm run publish
+```
+
+This script:
+- ✓ Installs dependencies
+- ✓ Runs tests
+- ✓ Verifies codex-cli binary
+- ✓ Validates npm credentials
+- ✓ Performs dry-run
+- ✓ Asks for confirmation
+- ✓ Publishes to npm
+
+### Method 2: Pre-Publish Checklist
+
+Validate everything before publishing:
+
+```bash
+npm run publish-check
+```
+
+Then publish manually:
+
+```bash
+npm publish
+```
+
+### Method 3: Manual Steps
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Publish
+npm publish
+```
+
+## Version Management
+
+### Automated versioning
+
+```bash
+# Patch (0.1.6 → 0.1.7)
+npm version patch
+
+# Minor (0.1.6 → 0.2.0)
+npm version minor
+
+# Major (0.1.6 → 1.0.0)
+npm version major
+```
+
+Then publish:
+```bash
+npm publish
+```
+
+### Manual versioning
+
+Edit `package.json` and update the `version` field, then publish:
+```bash
+npm publish
+```
+
+## Troubleshooting
+
+### "Not authenticated"
+```bash
+npm login
+npm whoami  # verify
+```
+
+### "Already published at this version"
+```bash
+npm version patch
+npm publish
+```
+
+### "Binary download fails"
+
+The postinstall script downloads codex-cli from GitHub releases. Verify:
+- Version in package.json matches a GitHub release tag
+- GitHub release contains the binary files
+
+### "Tests fail"
+```bash
+npm test  # See detailed errors
+```
+
+## Verification After Publishing
+
+```bash
+# Check latest version
+npm view codexdb-sdk@latest
+
+# Test installation
+npm install codexdb-sdk@latest
+
+# View on npm
+open https://www.npmjs.com/package/codexdb-sdk
+```
+
+## Files Included in npm Package
+
+Included (via package.json + files field or .npmignore):
+- index.js
+- package.json
+- README.md
+- LICENSE
+- codex-cli (binary)
+- node_modules/
+
+Excluded:
+- test.js
+- example_app.js
+- scripts/
+- .npmignore
+- IDE config
+- OS files
+
+## Automated Publishing (CI/CD)
+
+Example GitHub Actions workflow:
+
+```yaml
+name: Publish to npm
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+      - run: cd sdk/nodejs && npm install
+      - run: cd sdk/nodejs && npm test
+      - run: cd sdk/nodejs && npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Setup:
+1. Create npm token: https://www.npmjs.com/settings/~/tokens
+2. Add to GitHub: Settings → Secrets → `NPM_TOKEN`
+
+## Additional Resources
 
-## Versioning
-- Update the version field in package.json before publishing a new release.
+- npm docs: https://docs.npmjs.com/cli/
+- GitHub releases: https://github.com/evertonmj/codex/releases
+- Main README: ../../README.md
 
-## Automated Publishing (optional)
-You can automate npm publishing using GitHub Actions or another CI/CD tool. Let me know if you want a workflow example!

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "codexdb-sdk",
-  "version": "0.1.6",
+  "version": "0.1.15",
   "description": "Node.js SDK for CodexDB (wrapper around codex-cli)",
   "main": "index.js",
   "scripts": {
     "test": "node test.js",
-    "postinstall": "node scripts/postinstall.js"
+    "postinstall": "node scripts/postinstall.js",
+    "publish-check": "node scripts/publish-check.js",
+    "release": "bash scripts/publish.sh"
   },
   "dependencies": {
     "follow-redirects": "^1.16.0"

package/example_app.js

@@ -1,26 +0,0 @@
-const path = require('path');
-const CodexClient = require('./index');
-
-const dbPath = path.resolve(__dirname, 'example-db.db');
-const client = new CodexClient({ file: dbPath });
-
-(async () => {
-  // Set a value
-  await client.set('greeting', { msg: 'Hello from Node.js!' });
-
-  // Get the value
-  const value = await client.get('greeting');
-  console.log('Greeting:', value.msg);
-
-  // List all keys
-  const keys = await client.keys();
-  console.log('All keys:', keys);
-
-  // Delete the key
-  const deleted = await client.delete('greeting');
-  console.log('Deleted:', deleted);
-
-  // Cleanup
-  const fs = require('fs');
-  try { fs.unlinkSync(dbPath); } catch (e) {}
-})();

package/scripts/postinstall.js

@@ -1,39 +0,0 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { https } = require('follow-redirects');
-
-// Map OS/platform to binary URLs
-const BINARIES = {
-  darwin: 'https://github.com/evertonmj/codex/releases/latest/download/codex-cli-macos',
-  linux: 'https://github.com/evertonmj/codex/releases/latest/download/codex-cli-linux',
-  win32: 'https://github.com/evertonmj/codex/releases/latest/download/codex-cli-win.exe'
-};
-
-const platform = os.platform();
-const url = BINARIES[platform];
-if (!url) {
-  console.error(`No binary available for platform: ${platform}`);
-  process.exit(1);
-}
-
-const dest = path.join(__dirname, '..', 'codex-cli' + (platform === 'win32' ? '.exe' : ''));
-
-console.log(`Downloading codex-cli for ${platform}...`);
-
-https.get(url, (res) => {
-  if (res.statusCode !== 200) {
-    console.error(`Failed to download binary: ${res.statusCode}`);
-    process.exit(1);
-  }
-  const file = fs.createWriteStream(dest, { mode: 0o755 });
-  res.pipe(file);
-  file.on('finish', () => {
-    file.close(() => {
-      console.log('codex-cli downloaded to', dest);
-    });
-  });
-}).on('error', (err) => {
-  console.error('Download error:', err);
-  process.exit(1);
-});

package/test.js

@@ -1,34 +0,0 @@
-const path = require('path');
-const fs = require('fs');
-const CodexClient = require('./index');
-
-(async () => {
-  const dbPath = path.resolve(__dirname, 'test-db.db');
-
-  // cleanup before test
-  try { fs.unlinkSync(dbPath); } catch (e) {}
-
-  const client = new CodexClient({ file: dbPath });
-
-  await client.set('test-key', { hello: 'world' });
-  const value = await client.get('test-key');
-
-  if (value.hello !== 'world') throw new Error('value mismatch');
-
-  const hasKey = await client.has('test-key');
-  if (!hasKey) throw new Error('expected key to exist');
-
-  const keys = await client.keys();
-  if (!keys.includes('test-key')) throw new Error('expected keys to include test-key');
-
-  await client.delete('test-key');
-  const hasAfterDelete = await client.has('test-key');
-  if (hasAfterDelete) throw new Error('expected key to be deleted');
-
-  await client.clear();
-
-  // cleanup after test
-  try { fs.unlinkSync(dbPath); } catch (e) {}
-
-  console.log('Node.js SDK smoke test passed');
-})();