mu-coding 0.4.0 → 0.8.0

package/README.md

@@ -12,8 +12,6 @@ npm install -g mu-coding
 
 ```bash
 mu                    # Start interactive chat
-mu -p "prompt"        # Single-shot prompt, then exit
-mu -m model -p "p"    # Single-shot with specific model
 mu -m model           # Interactive with specific model
 mu -c                 # Continue most recent session
 mu --session <path>   # Resume a specific session file
@@ -42,16 +40,61 @@ Config files follow XDG conventions:
 }
 ```
 
+### Theming
+
+The `theme` field selects the UI palette. Either name a built-in preset:
+
+```json
+{ "theme": "solarized-dark" }
+```
+
+Built-in presets: `dark` (default), `light`, `solarized-dark`, `monochrome`.
+
+Or pass an object to override individual leaves on top of a preset:
+
+```json
+{
+  "theme": {
+    "preset": "dark",
+    "input":  { "background": "#1e1e2e", "cursor": "#f5c2e7" },
+    "user":   { "border": "magenta" },
+    "common": { "accent": "#89dceb" }
+  }
+}
+```
+
+Color values accept Ink's named colors (`red`, `green`, `cyan`, `yellow`,
+`magenta`, `blue`, `white`, `black`, `gray`) or hex strings (`#1a1a1a`).
+
+Sections available: `input`, `user`, `assistant`, `tool`, `reasoning`,
+`modal`, `toast`, `dropdown`, `dialog`, `diff`, `status`, `common`. See
+`src/tui/theme/types.ts` for the full leaf list.
+
 ## Keyboard Shortcuts
 
+### Input editing
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Move cursor one character |
+| `Ctrl+←` / `Ctrl+→` (or `Alt+←/→`) | Move cursor by word |
+| `Home` / `End` (or `Ctrl+A` / `Ctrl+E`) | Jump to start / end of line |
+| `↑` / `↓` | Move cursor between lines (multi-line buffer); navigate history at edges |
+| `Backspace` | Delete char before cursor |
+| `Delete` | Delete char under cursor |
+| `Ctrl+W` | Delete previous word |
+| `Ctrl+U` | Delete from start of line to cursor |
+| `Ctrl+K` | Delete from cursor to end of line |
+
+### Submission & app
+
 | Key | Action |
 |-----|--------|
 | `Enter` | Send message |
-| `Shift+Enter` | New line |
+| `Shift+Enter` (or `Ctrl+J`) | New line |
 | `Ctrl+S` | Send message |
 | `Ctrl+C` | Abort / Quit (press twice) |
 | `Esc` | Stop generation (press twice) |
-| `↑` / `↓` | Navigate input history |
 | `Ctrl+N` | New conversation |
 | `Ctrl+M` | Cycle models |
 | `Ctrl+O` | Model picker |
@@ -71,7 +114,8 @@ Config files follow XDG conventions:
 
 - Streams responses with live token/s display
 - Multi-turn tool calling (bash, read, write, edit files)
-- Code indexing via `mu-repomap` plugin (auto-loaded)
+- Optional code indexing via the `mu-repomap` plugin (enable via `config.plugins`)
+- Optional default agents (build/plan/explore/review) via `mu-coding-agents` (enable via `config.plugins`)
 - Image attachment support
 - Session persistence and resume
 - Mouse wheel scrolling

package/bin/mu.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env bun
-import '../src/main.tsx';
+import '../src/main.ts';

package/package.json

@@ -1,19 +1,32 @@
 {
   "name": "mu-coding",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "description": "Minimal terminal AI assistant for local models",
   "type": "module",
   "bin": {
     "mu": "./bin/mu.js"
   },
+  "exports": {
+    ".": "./src/plugin.ts",
+    "./config": "./src/config/index.ts",
+    "./tools": "./src/runtime/codingTools/index.ts",
+    "./loader": "./src/runtime/pluginLoader.ts"
+  },
+  "files": [
+    "bin",
+    "prompts",
+    "src"
+  ],
   "scripts": {
     "dev": "bun --watch bin/mu.js",
-    "start": "bun bin/mu.js"
+    "start": "bun bin/mu.js",
+    "test": "bun test"
   },
   "dependencies": {
     "ink": "^7.0.1",
-    "mu-agents": "0.4.0",
-    "mu-provider": "0.4.0",
+    "mu-agents": "0.8.0",
+    "mu-core": "0.8.0",
+    "mu-openai-provider": "0.8.0",
     "react": "^19.2.5"
   }
 }

package/prompts/SYSTEM.md

@@ -0,0 +1,16 @@
+You are mu, a terminal coding agent. Be concise, direct, accurate.
+
+## Working style
+- Investigate before editing; don't guess at APIs.
+- Issue independent tool calls in parallel.
+- Ask only when genuinely ambiguous; otherwise proceed.
+- After non-trivial edits, run the project's check command if known (e.g. `bun run check`).
+
+## Output
+- Plain terminal text. Backticks for `paths`, `commands`, `identifiers`.
+- Reference code as `path/to/file.ts:LINE`.
+- No filler. Lead with the result or next action.
+
+## Safety
+- Never run destructive commands (`rm -rf`, force-push, history rewrites) without explicit request.
+- Never commit, amend, or push unless asked.

package/src/app/shutdown.ts

@@ -0,0 +1,94 @@
+import type { PluginRegistry } from 'mu-core';
+
+/**
+ * Escape sequences to disable every SGR mouse-tracking mode the TUI may have
+ * enabled (or inherited from a stale prior session). Disabling already-off
+ * modes is a no-op, so we send all three defensively to avoid leaking mouse
+ * tracking into the parent shell after abort.
+ *  - 1000 = X10/normal (press+release)         ← what `useScroll` enables
+ *  - 1002 = button-event tracking (press+drag) ← legacy, prior versions
+ *  - 1003 = any-event tracking (all motion)    ← belt-and-suspenders
+ *  - 1006 = SGR-encoded coordinates extension
+ */
+const DISABLE_MOUSE_MODE = '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l';
+
+/** Restore the kitty keyboard protocol stack — symmetric with renderApp's enable. */
+const POP_KITTY_KEYBOARD = '\x1b[<u';
+
+export type ShutdownFn = (code?: number) => Promise<void>;
+
+let registered = false;
+
+/**
+ * Install graceful-shutdown handlers and return a `shutdown` function the TUI
+ * can invoke directly when the user requests a quit.
+ *
+ * Coverage:
+ *  - terminal close / external kill (SIGHUP, SIGTERM)
+ *  - normal Node shutdown via `beforeExit`
+ *  - uncaught exceptions / unhandled rejections (best-effort terminal restore)
+ *  - explicit quit from `useAbort` (calls the returned `shutdown` directly)
+ *
+ * SIGINT is intentionally NOT trapped: Ink owns Ctrl+C through the `useInput`
+ * hook (`exitOnCtrlC: false` in renderApp) and `useAbort` implements the
+ * double-press quit UX, calling the returned function on confirmation.
+ *
+ * The function is idempotent — concurrent invocations resolve to the same
+ * outcome and the handlers fire only once.
+ *
+ * `getRegistry` is a thunk so the shutdown handle can be created BEFORE the
+ * registry (the registry consumes `shutdown` in its plugin context, creating
+ * a cycle if both were eager).
+ */
+export function registerShutdown(getRegistry: () => PluginRegistry | null): ShutdownFn {
+  let shuttingDown: Promise<void> | null = null;
+
+  const shutdown: ShutdownFn = (code = 0) => {
+    if (shuttingDown) {
+      return shuttingDown;
+    }
+    shuttingDown = (async () => {
+      try {
+        const registry = getRegistry();
+        if (registry) {
+          await registry.shutdown();
+        }
+      } catch (err) {
+        console.error('Shutdown error:', err instanceof Error ? err.message : err);
+      } finally {
+        restoreTerminal();
+        // `process.exit` from inside an `async` function still terminates
+        // synchronously after the current microtask queue drains.
+        process.exit(code);
+      }
+    })();
+    return shuttingDown;
+  };
+
+  if (!registered) {
+    registered = true;
+    process.once('SIGTERM', () => void shutdown(143));
+    process.once('SIGHUP', () => void shutdown(129));
+    process.once('beforeExit', (code) => void shutdown(code));
+    process.once('uncaughtException', (err) => {
+      restoreTerminal();
+      console.error(err);
+      process.exit(1);
+    });
+    process.once('unhandledRejection', (err) => {
+      restoreTerminal();
+      console.error(err);
+      process.exit(1);
+    });
+  }
+
+  return shutdown;
+}
+
+export function restoreTerminal(): void {
+  try {
+    process.stdout.write(`${DISABLE_MOUSE_MODE}${POP_KITTY_KEYBOARD}`);
+  } catch {
+    // stdout may already be closed during teardown — nothing to do.
+  }
+}

package/src/app/startApp.ts

@@ -0,0 +1,43 @@
+import type { PluginRegistry } from 'mu-core';
+import { parseArgs, resolveInitialMessages } from '../cli/args';
+import { handleSubcommand } from '../cli/subcommands';
+import { loadConfig } from '../config/index';
+import { createRegistry } from '../runtime/createRegistry';
+import { InkUIService } from '../tui/plugins/InkUIService';
+import { registerShutdown } from './shutdown';
+
+async function runApp(): Promise<void> {
+  if (await handleSubcommand()) return;
+
+  const cliArgs = parseArgs();
+  const config = loadConfig(cliArgs.model);
+  const uiService = new InkUIService();
+
+  // Create the shutdown handle BEFORE the registry so we can pass it into the
+  // plugin context. The registry is bound through a thunk, filled in once
+  // construction completes.
+  let registryRef: PluginRegistry | null = null;
+  const shutdown = registerShutdown(() => registryRef);
+
+  const initialMessages = resolveInitialMessages(cliArgs);
+  const { registry, channels } = await createRegistry({
+    cwd: process.cwd(),
+    config,
+    uiService,
+    initialMessages,
+    shutdown,
+  });
+  registryRef = registry;
+
+  // The TUI is registered as a `Channel` by `createCodingPlugin`. Starting
+  // it mounts Ink with the same options that were captured at activation
+  // time (config, initialMessages, registry, messageBus, uiService, shutdown).
+  await channels.startAll();
+}
+
+export function startApp(): void {
+  runApp().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/cli/args.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs as nodeParseArgs } from 'node:util';
+import type { ChatMessage } from 'mu-core';
+import { getLatestSession, loadSession } from '../sessions/index';
+
+interface CliArgs {
+  model?: string;
+  continueSession?: boolean;
+  sessionPath?: string;
+}
+
+function printHelp(): never {
+  console.log(`mu — minimal terminal AI assistant
+
+Usage:
+  mu                            Start interactive chat
+  mu -m, --model <model>        Interactive with specific model
+  mu -c, --continue             Continue most recent session
+  mu --session <path>           Resume a specific session file
+  mu install npm:<package>      Install a plugin from npm
+  mu uninstall npm:<package>    Remove an installed plugin
+  mu -v, --version              Print version and exit
+  mu -h, --help                 Show this help
+
+Config (XDG):
+  ~/.config/mu/config.json    — configuration (baseUrl, model, streamTimeoutMs)
+  ~/.config/mu/SYSTEM.md      — system prompt
+  ~/.local/share/mu/sessions/ — saved conversation sessions (JSONL)
+  ~/.cache/mu/repomap/        — code index cache
+
+Keyboard shortcuts (interactive):
+  Ctrl+C        Abort / Quit (press twice)
+  Esc           Stop generation (press twice while streaming)
+  Enter         Send message
+  Shift+Enter   New line
+  Ctrl+S        Send message
+  ← / →         Move cursor (Ctrl/Alt+arrow: by word)
+  Home/End      Start/end of line (or Ctrl+A / Ctrl+E)
+  ↑ / ↓         Move between lines; navigate history at edges
+  Backspace/Del Delete around cursor (Ctrl+W word, Ctrl+U/K line)
+  Ctrl+N        New conversation
+  Ctrl+M        Cycle models
+  Ctrl+O        Model picker
+  Ctrl+V        Paste image from clipboard`);
+  process.exit(0);
+}
+
+function printVersion(): never {
+  // Walk up from this file to find mu-coding's package.json. Works whether
+  // the file is loaded from `src/cli/args.ts` (bun --watch) or `dist/cli/args.js`.
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join(here, '..', '..', 'package.json'), join(here, '..', 'package.json')];
+  for (const path of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, 'utf-8'));
+      if (pkg?.name === 'mu-coding') {
+        console.log(`mu ${pkg.version}`);
+        process.exit(0);
+      }
+    } catch {
+      // Try next candidate.
+    }
+  }
+  console.log('mu (version unknown)');
+  process.exit(0);
+}
+
+export function parseArgs(): CliArgs {
+  let parsed: ReturnType<typeof nodeParseArgs>;
+  try {
+    parsed = nodeParseArgs({
+      options: {
+        model: { type: 'string', short: 'm' },
+        continue: { type: 'boolean', short: 'c' },
+        session: { type: 'string' },
+        version: { type: 'boolean', short: 'v' },
+        help: { type: 'boolean', short: 'h' },
+      },
+      // Subcommands like `install`/`uninstall` are routed before parseArgs(),
+      // so we shouldn't see them here. Allow positionals just in case the
+      // user passes stray args (we ignore them rather than erroring).
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    console.error('Run `mu --help` for usage.');
+    process.exit(1);
+  }
+
+  if (parsed.values.help) {
+    printHelp();
+  }
+  if (parsed.values.version) {
+    printVersion();
+  }
+
+  return {
+    model: typeof parsed.values.model === 'string' ? parsed.values.model : undefined,
+    continueSession: parsed.values.continue === true,
+    sessionPath: typeof parsed.values.session === 'string' ? parsed.values.session : undefined,
+  };
+}
+
+export function resolveInitialMessages(cliArgs: CliArgs): ChatMessage[] | undefined {
+  if (cliArgs.sessionPath) {
+    const msgs = loadSession(cliArgs.sessionPath);
+    if (msgs.length === 0) {
+      console.error(`Error: session file is empty or not found: ${cliArgs.sessionPath}`);
+      process.exit(1);
+    }
+    return msgs;
+  }
+  if (cliArgs.continueSession) {
+    const latest = getLatestSession();
+    if (!latest) {
+      console.error('Error: no sessions found');
+      process.exit(1);
+    }
+    const msgs = loadSession(latest);
+    if (msgs.length === 0) {
+      console.error('Error: latest session is empty');
+      process.exit(1);
+    }
+    console.log(`Resuming session: ${latest}`);
+    return msgs;
+  }
+  return undefined;
+}

package/src/{install.ts → cli/install.ts}

@@ -1,7 +1,7 @@
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getDataDir, loadConfig, saveConfig } from './config';
+import { canonicalNpmSpecifier, getDataDir, loadConfig, parseBareNpmSpec, saveConfig } from '../config/index';
 
 const INIT_PACKAGE_JSON = JSON.stringify({ private: true, dependencies: {} }, null, 2);
 
@@ -37,22 +37,24 @@ export async function runInstall(args: string[]): Promise<void> {
 
   for (const specifier of args) {
     const bare = stripNpmPrefix(specifier);
+    const canonical = canonicalNpmSpecifier(bare);
 
     console.log(`Installing ${bare}...`);
     try {
-      execSync(`bun add ${bare}`, { cwd: dataDir, stdio: 'inherit' });
-    } catch {
-      console.error(`Failed to install ${bare}`);
+      execFileSync('bun', ['add', bare], { cwd: dataDir, stdio: 'inherit' });
+    } catch (err) {
+      console.error(`Failed to install ${bare}: ${err instanceof Error ? err.message : err}`);
       process.exit(1);
     }
 
-    // Add to plugins if not already present
-    const existing = plugins.some((p) => (typeof p === 'string' ? p : p.name) === specifier);
+    // Add to plugins if not already present (compare by canonical form so
+    // `npm:foo` and `npm:foo@1.2.3` deduplicate correctly).
+    const existing = plugins.some((p) => (typeof p === 'string' ? p : p.name) === canonical);
     if (!existing) {
-      plugins.push(specifier);
+      plugins.push(canonical);
     }
 
-    console.log(`✓ ${specifier}`);
+    console.log(`✓ ${canonical}`);
   }
 
   saveConfig({ plugins });
@@ -70,18 +72,20 @@ export async function runUninstall(args: string[]): Promise<void> {
 
   for (const specifier of args) {
     const bare = stripNpmPrefix(specifier);
+    const canonical = canonicalNpmSpecifier(bare);
+    const { name } = parseBareNpmSpec(bare);
 
-    console.log(`Removing ${bare}...`);
+    console.log(`Removing ${name}...`);
     try {
-      execSync(`bun remove ${bare}`, { cwd: dataDir, stdio: 'inherit' });
-    } catch {
-      console.error(`Failed to remove ${bare}`);
+      execFileSync('bun', ['remove', name], { cwd: dataDir, stdio: 'inherit' });
+    } catch (err) {
+      console.error(`Failed to remove ${name}: ${err instanceof Error ? err.message : err}`);
       process.exit(1);
     }
 
-    plugins = plugins.filter((p) => (typeof p === 'string' ? p : p.name) !== specifier);
+    plugins = plugins.filter((p) => (typeof p === 'string' ? p : p.name) !== canonical);
 
-    console.log(`✓ Removed ${specifier}`);
+    console.log(`✓ Removed ${canonical}`);
   }
 
   saveConfig({ plugins });

package/src/config/index.test.ts

@@ -0,0 +1,77 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Important: stub XDG_CONFIG_HOME *before* importing './index' so the module
+// captures the test paths in its top-level constants. Bun resolves dynamic
+// imports per-call, so we use `await import` inside each test.
+let tmpRoot: string;
+let configPath: string;
+let originalConfigHome: string | undefined;
+
+beforeAll(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'mu-config-'));
+  originalConfigHome = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmpRoot;
+  mkdirSync(join(tmpRoot, 'mu'), { recursive: true });
+  configPath = join(tmpRoot, 'mu', 'config.json');
+});
+
+afterAll(() => {
+  if (originalConfigHome === undefined) {
+    delete process.env.XDG_CONFIG_HOME;
+  } else {
+    process.env.XDG_CONFIG_HOME = originalConfigHome;
+  }
+});
+
+describe('saveConfig', () => {
+  it('preserves unknown keys in config.json', async () => {
+    const { saveConfig } = await import('./index');
+
+    // Seed with a custom key the loader doesn't know about.
+    writeFileSync(configPath, JSON.stringify({ baseUrl: 'http://x', customKey: 42 }, null, 2));
+
+    saveConfig({ model: 'qwen' });
+
+    const persisted = JSON.parse(readFileSync(configPath, 'utf-8'));
+    expect(persisted.customKey).toBe(42);
+    expect(persisted.model).toBe('qwen');
+    expect(persisted.baseUrl).toBe('http://x');
+  });
+
+  it('removes a key when explicitly set to undefined', async () => {
+    const { saveConfig } = await import('./index');
+    writeFileSync(configPath, JSON.stringify({ model: 'before' }));
+    saveConfig({ model: undefined });
+    const persisted = JSON.parse(readFileSync(configPath, 'utf-8'));
+    expect('model' in persisted).toBe(false);
+  });
+});
+
+describe('loadConfig theme', () => {
+  it('reads the theme field from config.json', async () => {
+    const { loadConfig } = await import('./index');
+    writeFileSync(
+      configPath,
+      JSON.stringify({ baseUrl: 'http://x', theme: { preset: 'light', input: { cursor: '#abcdef' } } }),
+    );
+    const cfg = loadConfig();
+    expect(cfg.theme).toEqual({ preset: 'light', input: { cursor: '#abcdef' } });
+  });
+
+  it('accepts a preset name string', async () => {
+    const { loadConfig } = await import('./index');
+    writeFileSync(configPath, JSON.stringify({ baseUrl: 'http://x', theme: 'solarized-dark' }));
+    const cfg = loadConfig();
+    expect(cfg.theme).toBe('solarized-dark');
+  });
+
+  it('omits theme when not present', async () => {
+    const { loadConfig } = await import('./index');
+    writeFileSync(configPath, JSON.stringify({ baseUrl: 'http://x' }));
+    const cfg = loadConfig();
+    expect(cfg.theme).toBeUndefined();
+  });
+});