@mclean-capital/neura 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 McLean Capital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @mclean-capital/neura
+
+> Neura CLI — install, manage, and talk to the Neura AI assistant from your terminal.
+
+Neura is a proactive, autonomous AI operating system. It combines real-time voice conversation, continuous visual understanding, and autonomous worker agents. This CLI installs and manages the Neura core service, and also acts as a full client via `neura chat` and `neura listen`.
+
+## Install
+
+```bash
+npm install -g @mclean-capital/neura
+```
+
+Requires Node.js >= 22.
+
+## Quick start
+
+```bash
+neura install     # interactive setup: API keys, auto-port, service registration
+neura start       # start the core service
+neura chat        # text chat with Neura from your terminal
+neura listen      # voice chat (mic + speaker)
+```
+
+## Commands
+
+### Setup & service lifecycle
+
+| Command           | Description                                |
+| ----------------- | ------------------------------------------ |
+| `neura install`   | Interactive setup wizard + service install |
+| `neura start`     | Start the core service                     |
+| `neura stop`      | Stop the core service                      |
+| `neura restart`   | Restart the core service                   |
+| `neura status`    | Show service status, port, uptime, health  |
+| `neura update`    | Download the latest core binary            |
+| `neura uninstall` | Remove service and optionally clean data   |
+
+### Client commands
+
+| Command        | Description                                 |
+| -------------- | ------------------------------------------- |
+| `neura chat`   | Interactive text chat over WebSocket        |
+| `neura listen` | Voice chat (mic capture + speaker playback) |
+| `neura open`   | Open the web UI in your default browser     |
+
+### Configuration & data
+
+| Command                        | Description                  |
+| ------------------------------ | ---------------------------- |
+| `neura config list`            | Show all configuration       |
+| `neura config set <key> <val>` | Set a config value           |
+| `neura config get <key>`       | Get a config value           |
+| `neura logs`                   | Tail core service logs       |
+| `neura backup`                 | Create a memory backup       |
+| `neura restore`                | Restore memories from backup |
+
+## Voice client notes
+
+`neura listen` uses optional native audio dependencies:
+
+- **`decibri`** — microphone capture via PortAudio
+- **`speaker`**, **`@picovoice/pvspeaker-node`**, or **`sox`** — speaker playback
+
+These are marked as `optionalDependencies` so `npm install -g @mclean-capital/neura` won't fail if your platform lacks the required build tools. If audio init fails at runtime, `neura listen` will print install instructions for your platform.
+
+## API keys
+
+Neura uses:
+
+- **xAI (Grok)** — voice conversation. Get a key at [console.x.ai](https://console.x.ai/).
+- **Google (Gemini)** — vision watcher, memory embeddings, wake word transcription. Get a key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).
+
+Both keys are set during `neura install` and stored in `~/.neura/config.json` with restricted file permissions.
+
+## Security
+
+- The core server binds to `localhost` only — not exposed on the LAN.
+- All WebSocket and HTTP requests require a 256-bit bearer token auto-generated on install.
+- The token is stored in `~/.neura/config.json` (Unix `0600` permissions).
+- `neura chat`, `neura listen`, `neura open`, `neura backup`, and `neura restore` automatically load and pass the token.
+
+## Links
+
+- **Full README**: https://github.com/mclean-capital/neura#readme
+- **Roadmap**: https://github.com/mclean-capital/neura/blob/main/docs/roadmap.md
+- **Issues**: https://github.com/mclean-capital/neura/issues
+
+## License
+
+MIT © McLean Capital

package/dist/audio/capture.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Audio capture abstraction for mic input.
+ *
+ * Primary: decibri (PortAudio, prebuilt arm64 binaries)
+ * The implementation lazy-loads decibri so `neura chat` works without it.
+ */
+export interface AudioCapture {
+    start(): void;
+    stop(): void;
+    onData: ((base64Pcm: string) => void) | null;
+}
+export declare function createAudioCapture(): Promise<AudioCapture>;
+/** List available audio input devices */
+export declare function listInputDevices(): Promise<{
+    index: number;
+    name: string;
+    isDefault: boolean;
+}[]>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/audio/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/audio/capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAoChE;AAED,yCAAyC;AACzC,wBAAsB,gBAAgB,IAAI,OAAO,CAC/C;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EAAE,CACtD,CAOA"}

package/dist/audio/capture.js

@@ -0,0 +1,52 @@
+/**
+ * Audio capture abstraction for mic input.
+ *
+ * Primary: decibri (PortAudio, prebuilt arm64 binaries)
+ * The implementation lazy-loads decibri so `neura chat` works without it.
+ */
+import { audioInstallHint } from './install-hints.js';
+export async function createAudioCapture() {
+    try {
+        const { default: Decibri } = await import('decibri');
+        let onData = null;
+        let mic = null;
+        return {
+            get onData() {
+                return onData;
+            },
+            set onData(handler) {
+                onData = handler;
+            },
+            start() {
+                mic = new Decibri({ sampleRate: 24000, channels: 1, format: 'int16' });
+                mic.on('data', (chunk) => {
+                    if (onData) {
+                        onData(chunk.toString('base64'));
+                    }
+                });
+                // Prevent unhandled 'error' from crashing the process
+                mic.on('error', (err) => {
+                    console.error(`Mic error: ${err.message}`);
+                });
+            },
+            stop() {
+                mic?.stop();
+                mic = null;
+            },
+        };
+    }
+    catch {
+        throw new Error('Mic capture requires the "decibri" package.\n' + audioInstallHint('decibri'));
+    }
+}
+/** List available audio input devices */
+export async function listInputDevices() {
+    try {
+        const { default: Decibri } = await import('decibri');
+        return Decibri.devices();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=capture.js.map

package/dist/audio/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/audio/capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQtD,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QAErD,IAAI,MAAM,GAAyC,IAAI,CAAC;QACxD,IAAI,GAAG,GAAwC,IAAI,CAAC;QAEpD,OAAO;YACL,IAAI,MAAM;gBACR,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,IAAI,MAAM,CAAC,OAA6C;gBACtD,MAAM,GAAG,OAAO,CAAC;YACnB,CAAC;YAED,KAAK;gBACH,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;gBACvE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;oBAC/B,IAAI,MAAM,EAAE,CAAC;wBACX,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;oBACnC,CAAC;gBACH,CAAC,CAAC,CAAC;gBACH,sDAAsD;gBACtD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;oBAC7B,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7C,CAAC,CAAC,CAAC;YACL,CAAC;YAED,IAAI;gBACF,GAAG,EAAE,IAAI,EAAE,CAAC;gBACZ,GAAG,GAAG,IAAI,CAAC;YACb,CAAC;SACF,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC;IACjG,CAAC;AACH,CAAC;AAED,yCAAyC;AACzC,MAAM,CAAC,KAAK,UAAU,gBAAgB;IAGpC,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC,OAAO,EAA2D,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/audio/install-hints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Install hint helper for optional native audio dependencies.
+ *
+ * Detects whether the CLI is running from a global npm install or from a
+ * monorepo workspace, and returns the appropriate install instructions.
+ */
+/**
+ * Build an install hint for a missing optional dependency.
+ * Shows instructions appropriate to the user's context (global vs workspace).
+ */
+export declare function audioInstallHint(depName: string): string;
+//# sourceMappingURL=install-hints.d.ts.map

package/dist/audio/install-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hints.d.ts","sourceRoot":"","sources":["../../src/audio/install-hints.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASxD"}

package/dist/audio/install-hints.js

@@ -0,0 +1,29 @@
+/**
+ * Install hint helper for optional native audio dependencies.
+ *
+ * Detects whether the CLI is running from a global npm install or from a
+ * monorepo workspace, and returns the appropriate install instructions.
+ */
+function isGlobalInstall() {
+    try {
+        // If we're inside node_modules/@mclean-capital/*, we're an npm package.
+        // Otherwise we're running from the monorepo (tsx src/ or dist/).
+        return import.meta.url.includes('node_modules') && import.meta.url.includes('mclean-capital');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build an install hint for a missing optional dependency.
+ * Shows instructions appropriate to the user's context (global vs workspace).
+ */
+export function audioInstallHint(depName) {
+    if (isGlobalInstall()) {
+        return ('If installed globally via npm, retry with optional deps enabled:\n' +
+            '  npm install -g @mclean-capital/neura --include=optional\n' +
+            `This requires a C++ build toolchain for ${depName} (Python + gcc/clang/MSVC).`);
+    }
+    return `npm install ${depName} -w @mclean-capital/neura`;
+}
+//# sourceMappingURL=install-hints.js.map

package/dist/audio/install-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hints.js","sourceRoot":"","sources":["../../src/audio/install-hints.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,SAAS,eAAe;IACtB,IAAI,CAAC;QACH,wEAAwE;QACxE,iEAAiE;QACjE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAChG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,eAAe,EAAE,EAAE,CAAC;QACtB,OAAO,CACL,oEAAoE;YACpE,6DAA6D;YAC7D,2CAA2C,OAAO,6BAA6B,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,eAAe,OAAO,2BAA2B,CAAC;AAC3D,CAAC"}

package/dist/audio/playback.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Audio playback abstraction for speaker output.
+ *
+ * Primary: sox via child_process (universal, streaming stdin pipe)
+ * Fallback: @picovoice/pvspeaker-node (prebuilt binaries, no sox needed)
+ */
+export interface AudioPlayback {
+    start(): void;
+    stop(): void;
+    play(base64Pcm: string): void;
+}
+/** Auto-detect and create the best available playback backend.
+ *
+ * Priority depends on platform:
+ *
+ *   **macOS / Linux**:
+ *     1. `speaker` (node-speaker) — native Writable stream, automatic
+ *        backpressure, holds audio device open across turns. Best for bursty
+ *        streaming audio from a voice WebSocket.
+ *     2. `@picovoice/pvspeaker-node` — ring-buffer API, manual drain loop.
+ *     3. `sox` — universal but has tail-sample loss in long-lived bursty
+ *        streams, used only if nothing else is available.
+ *
+ *   **Windows**:
+ *     1. `@picovoice/pvspeaker-node` — preferred because node-speaker relies
+ *        on mpg123's output layer, and its underflow warnings can't be
+ *        reliably silenced on Windows (no `/dev/fd/2` trick). Pvspeaker uses
+ *        WASAPI directly with a clean ring buffer and no noisy stderr.
+ *     2. `speaker` (node-speaker) — fallback if pvspeaker isn't available.
+ *     3. `sox` — last-resort fallback.
+ */
+export declare function createAudioPlayback(): Promise<AudioPlayback>;
+//# sourceMappingURL=playback.d.ts.map

package/dist/audio/playback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/audio/playback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8FH,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AA2QD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC,CAgDlE"}