promptmic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Almeida
+
+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,287 @@
+# TermSpeak
+
+Voice-first web UI for terminal-based AI coding assistants such as Claude Code, Codex CLI, and Aider, while keeping the real CLI session running through a PTY.
+
+TermSpeak is built for developers who already work in the terminal and want a faster way to talk to coding assistants without giving up a real CLI session.
+
+## Why TermSpeak
+
+- Speak prompts instead of typing everything by hand
+- Keep assistants running in a real interactive terminal session through PTY
+- Switch between multiple providers such as Claude Code, Codex CLI, and Aider
+- Choose the working directory before each session
+- Use it alongside VS Code, Cursor, or any editor, as long as your assistant runs in the terminal
+- Run everything locally on your own machine
+
+## Features
+
+- Voice dictation with Web Speech API
+- Text input with prompt history
+- Built-in terminal view with `xterm.js`
+- Multi-provider configuration
+- Per-session working directory selection
+- English and Portuguese (Brazil) UI support
+
+The project now supports two interface languages out of the box:
+
+- English
+- Portuguese (Brazil)
+
+Users can switch the UI language and the dictation language independently inside the app.
+
+## Architecture
+
+- `apps/server`: Node.js server with `node-pty`, Express, WebSocket, and dynamic config loading
+- `apps/web`: React + Vite frontend with `xterm.js` and Web Speech API dictation
+- `packages/shared`: shared types and schemas used by server and web
+
+## Requirements
+
+- Node.js 20+
+- A Chromium-based browser with Web Speech API support, such as Chrome or Edge
+- At least one assistant CLI available in your `PATH`, such as `claude`, `codex`, or `aider`
+
+## Install and run
+
+### From npm / npx
+
+Package name on npm:
+
+```bash
+promptmic
+```
+
+Installed executable:
+
+```bash
+promptmic
+```
+
+After the package is published, the default user flow will be:
+
+```bash
+npx promptmic
+```
+
+This starts TermSpeak locally and prints the URL in the terminal without opening the browser by default.
+
+If you want the browser to open automatically:
+
+```bash
+npx promptmic --open
+```
+
+If you install it globally, the executable name is:
+
+```bash
+promptmic
+```
+
+That means:
+
+- use `npx promptmic` when running directly from the npm package name
+- use `promptmic` after a global install
+
+### Security note
+
+TermSpeak is intended for local use on your own machine.
+
+- by default it binds to `127.0.0.1`
+- do not expose it on `0.0.0.0` or another non-local host unless you explicitly understand the risk
+- non-local binding can expose terminal session control, file-system access, and assistant configuration to other machines
+
+## Quick start
+
+```bash
+git clone git@github.com:lucasaclima03/term-speak.git
+cd term-speak
+npm install
+npm run dev
+```
+
+Then open `http://localhost:5173` in your browser.
+
+The Vite dev server runs on `5173` and proxies API/WebSocket traffic to the local backend on `3001`.
+
+If no providers are configured yet, the app opens the Settings dialog automatically on first launch.
+
+## Run locally
+
+### Development mode
+
+```bash
+npm run dev
+```
+
+- Open the app at `http://localhost:5173`
+- The local API server runs at `http://localhost:3001`
+- In repository development mode, the server will use `./config.json` if it exists
+- On first launch, the Settings dialog opens automatically only if no providers are found in that config
+
+### Production-style local run
+
+This matches the published CLI behavior more closely:
+
+```bash
+npm run build
+npm run start
+```
+
+- The backend serves the built frontend directly on `http://127.0.0.1:3001`
+- By default, this mode uses `~/.term-speak/config.json`
+- If that file does not exist yet, the first run starts with no providers and the onboarding flow begins in the UI
+
+To run the production-style server while still using the repository config file:
+
+```bash
+npm run start:repo
+```
+
+## Configuration
+
+### Published CLI / npx usage
+
+When you run TermSpeak from npm, it stores configuration in:
+
+```bash
+~/.term-speak/config.json
+```
+
+You do not need to create that file manually. On first run, if no providers are configured yet, the UI opens the Settings dialog and saves the configuration there.
+
+### Repository / source usage
+
+If you cloned the repository and want to use a repo-local config file, create:
+
+```bash
+cp config.example.json config.json
+```
+
+In repository development mode, the local server can read `./config.json` and reloads it whenever the UI sends `POST /api/config`.
+
+To actually start a session in any mode, you must have the configured assistant installed locally and available in your shell `PATH`.
+
+If you want to use shell wrappers or functions such as `personal` or `work`, they must be available in your login shell.
+
+### Config locations
+
+- `npm run dev`: prefers `./config.json` in the repository
+- if `./config.json` does not exist in `npm run dev`, the app starts with an empty config for onboarding instead of falling back to `~/.term-speak/config.json`
+- `npm run start`: uses `~/.term-speak/config.json`
+- `npm run start:repo`: forces `./config.json`
+- `npx promptmic`: should behave like `npm run start`
+
+### Provider fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Label shown in the UI |
+| `executionMode` | `"direct" \| "shell"` | No | `direct` runs the executable directly. `shell` runs the command through the user's interactive shell. Defaults to `shell` for backward compatibility. |
+| `command` | `string` | Yes | In `direct`, the executable name available in `PATH`. In `shell`, any shell command, alias, or function available in the user's shell. |
+| `args` | `string[]` | No | Extra command arguments |
+| `env` | `Record<string, string>` | No | Extra environment variables, with `~/` expansion |
+
+### Execution modes
+
+- `direct` is the recommended default for most providers because it runs the CLI directly and avoids shell startup noise
+- `shell` is useful when you rely on shell wrappers, aliases, or functions such as `personal`, `work`, or custom environment bootstrap commands
+- In `shell` mode, anything printed by your shell startup files can appear at the start of the session
+
+### Example: multiple Claude accounts with direct execution
+
+```json
+{
+  "providers": {
+    "claude-personal": {
+      "label": "Claude (Personal)",
+      "executionMode": "direct",
+      "command": "claude",
+      "args": [],
+      "env": { "CLAUDE_CONFIG_DIR": "~/.claude-personal" }
+    },
+    "claude-work": {
+      "label": "Claude (Work)",
+      "executionMode": "direct",
+      "command": "claude",
+      "args": [],
+      "env": { "CLAUDE_CONFIG_DIR": "~/.claude-work" }
+    }
+  },
+  "defaultProvider": "claude-personal"
+}
+```
+
+### Example: shell wrapper commands
+
+```json
+{
+  "providers": {
+    "claude-personal": {
+      "label": "Claude Personal",
+      "executionMode": "shell",
+      "command": "personal",
+      "args": [],
+      "env": {}
+    },
+    "claude-work": {
+      "label": "Claude Work",
+      "executionMode": "shell",
+      "command": "work",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+### Example: Aider + Codex
+
+```json
+{
+  "providers": {
+    "aider": {
+      "label": "Aider",
+      "executionMode": "direct",
+      "command": "aider",
+      "args": ["--no-auto-commits"],
+      "env": {}
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "executionMode": "direct",
+      "command": "codex",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+## Usage
+
+1. Configure one or more assistants.
+2. Choose the assistant in the dropdown.
+3. Choose a working folder.
+4. Start a session.
+5. Speak or type prompts.
+6. Stop the session when finished.
+
+## Who this is for
+
+TermSpeak is a good fit if you:
+
+- use `claude`, `codex`, `aider`, or similar terminal-based assistants
+- want voice input without leaving your local development workflow
+- prefer editing in VS Code, Cursor, Neovim, or another editor while your assistant runs in the terminal
+
+TermSpeak is not an IDE extension. It is a local voice interface for assistant CLIs.
+
+## Development notes
+
+- `config.json` is intentionally ignored and should stay local
+- Do not commit `node_modules`, `dist`, or other generated local assets
+- If you change user-facing copy, update both supported UI languages: English and Portuguese (Brazil)
+
+## Contributing
+
+Contribution guidelines live in [`CONTRIBUTING.md`](https://github.com/lucasaclima03/term-speak/blob/main/CONTRIBUTING.md).

package/apps/server/dist/config-store.js

@@ -0,0 +1,15 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from './runtime-config.js';
+export function createConfigStore(configPath, initialConfig = loadConfig(configPath)) {
+    let currentConfig = initialConfig;
+    return {
+        configPath,
+        getConfig: () => currentConfig,
+        saveConfig: async (nextConfig) => {
+            await mkdir(path.dirname(configPath), { recursive: true });
+            await writeFile(configPath, JSON.stringify(nextConfig, null, 2), 'utf-8');
+            currentConfig = nextConfig;
+        },
+    };
+}

package/apps/server/dist/http/local-only-middleware.js

@@ -0,0 +1,10 @@
+import { isAllowedHostHeader, isLoopbackAddress } from '../runtime-config.js';
+export function registerLocalOnlyMiddleware(app) {
+    app.use((req, res, next) => {
+        if (!isLoopbackAddress(req.socket.remoteAddress) || !isAllowedHostHeader(req.headers.host)) {
+            res.status(403).json({ error: 'Local access only.' });
+            return;
+        }
+        next();
+    });
+}

package/apps/server/dist/http/routes/config-routes.js

@@ -0,0 +1,21 @@
+import { configSchema } from '../../../../../packages/shared/dist/index.js';
+export function registerConfigRoutes(app, configStore) {
+    app.get('/api/config', (_req, res) => {
+        res.json(configStore.getConfig());
+    });
+    app.post('/api/config', async (req, res) => {
+        const parsed = configSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: parsed.error.issues });
+            return;
+        }
+        try {
+            await configStore.saveConfig(parsed.data);
+            res.json({ ok: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Could not write config file.';
+            res.status(500).json({ error: message });
+        }
+    });
+}

package/apps/server/dist/http/routes/filesystem-routes.js

@@ -0,0 +1,28 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+export function registerFilesystemRoutes(app, defaultCwd) {
+    app.get('/api/fs/list', async (req, res) => {
+        try {
+            const requestedPath = typeof req.query.path === 'string' ? req.query.path : defaultCwd;
+            const resolvedPath = path.resolve(requestedPath);
+            const entries = await readdir(resolvedPath, { withFileTypes: true });
+            const directories = entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => ({
+                name: entry.name,
+                path: path.join(resolvedPath, entry.name),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            const parent = path.dirname(resolvedPath);
+            res.json({
+                path: resolvedPath,
+                parent: parent !== resolvedPath ? parent : null,
+                directories,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Could not list directories.';
+            res.status(400).json({ error: message });
+        }
+    });
+}

package/apps/server/dist/http/routes/system-routes.js

@@ -0,0 +1,16 @@
+import { HOME_DIR, getDefaultProvider } from '../../runtime-config.js';
+export function registerSystemRoutes(app, options) {
+    const { defaultCwd, configStore } = options;
+    app.get('/health', (_req, res) => {
+        res.json({ ok: true });
+    });
+    app.get('/api/info', (_req, res) => {
+        const config = configStore.getConfig();
+        res.json({
+            cwd: defaultCwd,
+            home: HOME_DIR,
+            providers: Object.entries(config.providers).map(([id, entry]) => ({ id, label: entry.label })),
+            defaultProvider: getDefaultProvider(config),
+        });
+    });
+}

package/apps/server/dist/http/static-assets.js

@@ -0,0 +1,12 @@
+import express from 'express';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export function registerStaticAssets(app, staticDir) {
+    if (!existsSync(staticDir)) {
+        return;
+    }
+    app.use(express.static(staticDir));
+    app.get('*', (_req, res) => {
+        res.sendFile(path.join(staticDir, 'index.html'));
+    });
+}

package/apps/server/dist/http/types.js

@@ -0,0 +1 @@
+export {};

package/apps/server/dist/http-routes.js

@@ -0,0 +1,15 @@
+import { registerLocalOnlyMiddleware } from './http/local-only-middleware.js';
+import { registerConfigRoutes } from './http/routes/config-routes.js';
+import { registerFilesystemRoutes } from './http/routes/filesystem-routes.js';
+import { registerSystemRoutes } from './http/routes/system-routes.js';
+import { registerStaticAssets } from './http/static-assets.js';
+export function registerHttpRoutes(options) {
+    const { app, defaultCwd, staticDir, localOnly, configStore } = options;
+    if (localOnly) {
+        registerLocalOnlyMiddleware(app);
+    }
+    registerSystemRoutes(app, { defaultCwd, configStore });
+    registerConfigRoutes(app, configStore);
+    registerFilesystemRoutes(app, defaultCwd);
+    registerStaticAssets(app, staticDir);
+}

package/apps/server/dist/index.js

@@ -0,0 +1,54 @@
+import express from 'express';
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import { DEFAULT_HOST, DEFAULT_PORT, assertSafeHostBinding, displayHost, isAllowedOrigin, isLoopbackAddress, resolveConfigPath, resolveStaticDir, } from './runtime-config.js';
+import { createConfigStore } from './config-store.js';
+import { registerHttpRoutes } from './http-routes.js';
+import { createPtySpawner } from './pty-spawner.js';
+import { createSessionRuntime } from './session-runtime.js';
+import { closeServerRuntime, getListeningPort, listenHttpServer } from './server-lifecycle.js';
+export { assertSafeHostBinding, resolveConfigPath };
+export { getDefaultConfigPath } from './runtime-config.js';
+export async function startServer(options = {}) {
+    const host = options.host ?? process.env.HOST ?? DEFAULT_HOST;
+    const port = options.port ?? Number(process.env.PORT ?? DEFAULT_PORT);
+    const defaultCwd = options.workdir ?? process.env.WORKDIR ?? process.cwd();
+    const configPath = resolveConfigPath(options.configPath, options.preferUserConfig, options.preferRepoConfig ?? process.env.TERMSPEAK_PREFER_REPO_CONFIG === '1');
+    const staticDir = resolveStaticDir(options.staticDir);
+    const allowRemote = options.allowRemote ?? process.env.TERMSPEAK_ALLOW_REMOTE === '1';
+    const localOnly = options.localOnly ?? !allowRemote;
+    const configStore = createConfigStore(configPath);
+    assertSafeHostBinding(host, allowRemote);
+    const app = express();
+    app.use(express.json());
+    const server = http.createServer(app);
+    const wss = new WebSocketServer({ server, path: '/ws' });
+    const spawnPty = createPtySpawner();
+    const sessionRuntime = createSessionRuntime({
+        defaultCwd,
+        localOnly,
+        getConfig: configStore.getConfig,
+        isAllowedOrigin,
+        isLoopbackAddress,
+        spawnPty,
+    });
+    registerHttpRoutes({
+        app,
+        configStore,
+        defaultCwd,
+        localOnly,
+        staticDir,
+    });
+    wss.on('connection', sessionRuntime.handleConnection);
+    await listenHttpServer(server, port, host);
+    const actualPort = getListeningPort(server, port);
+    const url = `http://${displayHost(host)}:${actualPort}`;
+    return {
+        host,
+        port: actualPort,
+        url,
+        configPath,
+        staticDir,
+        close: () => closeServerRuntime({ server, wss, beforeClose: sessionRuntime.closeAll }),
+    };
+}

package/apps/server/dist/main.js

@@ -0,0 +1,8 @@
+import { startServer } from './index.js';
+void startServer().then(({ url }) => {
+    console.log(`TermSpeak server running at ${url}`);
+}).catch((error) => {
+    const message = error instanceof Error ? error.message : 'Unknown server error.';
+    console.error(`[term-speak] ${message}`);
+    process.exitCode = 1;
+});

package/apps/server/dist/pty-spawner.js

@@ -0,0 +1,72 @@
+import pty from 'node-pty';
+import path from 'node:path';
+import { HOME_DIR } from './runtime-config.js';
+export function expandTilde(value) {
+    return value.startsWith('~/') ? path.join(HOME_DIR, value.slice(2)) : value;
+}
+function quoteShellArg(value) {
+    if (value.length === 0)
+        return "''";
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function formatSpawnError(entry, error) {
+    if (entry.executionMode === 'direct' &&
+        error &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === 'ENOENT') {
+        return new Error(`Could not start "${entry.label}". Command "${entry.command}" was not found in PATH. Install it or switch this provider to Shell command if it depends on a shell wrapper.`);
+    }
+    if (error instanceof Error) {
+        return new Error(`Could not start "${entry.label}": ${error.message}`);
+    }
+    return new Error(`Could not start "${entry.label}".`);
+}
+export function resolveProviderCommand(config, providerId, userShell = process.env.SHELL || '/bin/bash') {
+    const entry = config.providers[providerId];
+    if (!entry)
+        throw new Error(`Provider "${providerId}" not found`);
+    const envOverrides = {};
+    for (const [key, val] of Object.entries(entry.env)) {
+        envOverrides[key] = expandTilde(val);
+    }
+    if (entry.executionMode === 'direct') {
+        return {
+            executionMode: 'direct',
+            file: entry.command,
+            args: entry.args,
+            envOverrides,
+        };
+    }
+    const fullCmd = [entry.command, ...entry.args].map(quoteShellArg).join(' ');
+    return {
+        executionMode: 'shell',
+        file: userShell,
+        args: ['-ic', fullCmd],
+        envOverrides,
+    };
+}
+export function createPtySpawner(options = {}) {
+    const baseEnv = Object.fromEntries(Object.entries(options.env ?? process.env).filter((entry) => typeof entry[1] === 'string'));
+    const spawn = options.spawn ?? pty.spawn;
+    const shell = options.shell ?? process.env.SHELL ?? '/bin/bash';
+    return ({ provider, cwd, config }) => {
+        const entry = config.providers[provider];
+        const command = resolveProviderCommand(config, provider, shell);
+        try {
+            return spawn(command.file, command.args, {
+                name: 'xterm-256color',
+                cols: 120,
+                rows: 30,
+                cwd,
+                env: {
+                    ...baseEnv,
+                    ...command.envOverrides,
+                },
+            });
+        }
+        catch (error) {
+            throw formatSpawnError(entry, error);
+        }
+    };
+}

package/apps/server/dist/runtime-config.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configSchema } from '../../../packages/shared/dist/index.js';
+const HOME_DIR = homedir();
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const MODULE_PATH = fileURLToPath(import.meta.url);
+const MODULE_DIR = path.dirname(MODULE_PATH);
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 3001;
+const DEFAULT_STATIC_DIR = path.resolve(MODULE_DIR, '../../web/dist');
+const REPO_CONFIG_PATH = path.resolve(MODULE_DIR, '../../../config.json');
+const USER_CONFIG_PATH = path.join(HOME_DIR, '.term-speak', 'config.json');
+export { HOME_DIR, DEFAULT_HOST, DEFAULT_PORT };
+export function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+export function isLocalHostValue(host) {
+    if (!host)
+        return false;
+    return LOCAL_HOSTS.has(host.toLowerCase());
+}
+export function isAllowedHostHeader(hostHeader) {
+    if (!hostHeader)
+        return false;
+    const host = hostHeader.startsWith('[')
+        ? hostHeader.slice(0, hostHeader.indexOf(']') + 1).toLowerCase()
+        : hostHeader.split(':')[0]?.toLowerCase();
+    if (!host)
+        return false;
+    return LOCAL_HOSTS.has(host);
+}
+export function isAllowedOrigin(origin) {
+    if (!origin)
+        return true;
+    try {
+        const parsed = new URL(origin);
+        return LOCAL_HOSTS.has(parsed.hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+export function getDefaultConfigPath() {
+    return USER_CONFIG_PATH;
+}
+export function getRepoConfigPath() {
+    return REPO_CONFIG_PATH;
+}
+export function resolveConfigPath(customPath, preferUserConfig = false, preferRepoConfig = false) {
+    if (customPath)
+        return path.resolve(customPath);
+    if (process.env.TERMSPEAK_CONFIG_PATH)
+        return path.resolve(process.env.TERMSPEAK_CONFIG_PATH);
+    if (preferUserConfig)
+        return USER_CONFIG_PATH;
+    if (preferRepoConfig)
+        return REPO_CONFIG_PATH;
+    if (existsSync(REPO_CONFIG_PATH))
+        return REPO_CONFIG_PATH;
+    return USER_CONFIG_PATH;
+}
+export function resolveStaticDir(customPath) {
+    if (customPath)
+        return path.resolve(customPath);
+    if (process.env.TERMSPEAK_STATIC_DIR)
+        return path.resolve(process.env.TERMSPEAK_STATIC_DIR);
+    return DEFAULT_STATIC_DIR;
+}
+export function loadConfig(configPath) {
+    if (!existsSync(configPath)) {
+        return { providers: {} };
+    }
+    try {
+        const parsed = configSchema.safeParse(JSON.parse(readFileSync(configPath, 'utf-8')));
+        if (!parsed.success) {
+            console.warn('[term-speak] invalid config file, ignoring it:', parsed.error.issues);
+            return { providers: {} };
+        }
+        return parsed.data;
+    }
+    catch (error) {
+        console.warn('[term-speak] could not read config file, ignoring it:', error);
+        return { providers: {} };
+    }
+}
+export function getProviderIds(config) {
+    return Object.keys(config.providers);
+}
+export function getDefaultProvider(config) {
+    const ids = getProviderIds(config);
+    return config.defaultProvider && ids.includes(config.defaultProvider) ? config.defaultProvider : ids[0] ?? '';
+}
+export function displayHost(host) {
+    if (host === '0.0.0.0')
+        return '127.0.0.1';
+    if (host === '::')
+        return 'localhost';
+    return host;
+}
+export function assertSafeHostBinding(host, allowRemote = false) {
+    if (!isLocalHostValue(host) && !allowRemote) {
+        throw new Error(`Refusing to bind to non-local host "${host}" without explicit remote access opt-in. Use --allow-remote only if you understand the security risks.`);
+    }
+}