mu-coding 0.2.0 → 0.5.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

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,27 @@
 {
   "name": "mu-coding",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Minimal terminal AI assistant for local models",
   "type": "module",
   "bin": {
     "mu": "./bin/mu.js"
   },
+  "exports": {
+    "./config": "./src/config/index.ts"
+  },
+  "files": [
+    "bin",
+    "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.2.0",
-    "mu-provider": "0.2.0",
+    "mu-agents": "0.5.0",
+    "mu-provider": "0.5.0",
     "react": "^19.2.5"
   }
 }

package/src/app/shutdown.ts

@@ -0,0 +1,94 @@
+import type { PluginRegistry } from 'mu-agents';
+
+/**
+ * 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,40 @@
+import type { PluginRegistry } from 'mu-agents';
+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 { renderApp } from '../tui/renderApp';
+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 registry = await createRegistry({ cwd: process.cwd(), config, uiService, shutdown });
+  registryRef = registry;
+
+  renderApp({
+    config,
+    initialMessages: resolveInitialMessages(cliArgs),
+    registry,
+    uiService,
+    shutdown,
+  });
+}
+
+export function startApp(): void {
+  runApp().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/cli/args.ts

@@ -0,0 +1,128 @@
+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-provider';
+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
+  ↑ / ↓   Navigate input history
+  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,51 @@
+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);
+  });
+});

package/src/config/index.ts

@@ -0,0 +1,181 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { ProviderConfig } from 'mu-provider';
+
+// ─── XDG Path Helpers ─────────────────────────────────────────────────────────
+//
+// Path resolution lives alongside config because the config module owns the
+// "where do mu's files live?" question end-to-end (config.json, SYSTEM.md,
+// sessions, plugin caches). Resolved lazily so tests can stub the env after
+// module import; production callers pay only one `process.env` lookup per call.
+//
+// Other workspace packages (e.g. `mu-pi-compat`) import these via the
+// `mu-coding/config` subpath export — see `mu-coding/package.json`.
+
+const HOME = homedir();
+
+export function getConfigDir(): string {
+  return process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, 'mu') : join(HOME, '.config', 'mu');
+}
+
+export function getDataDir(): string {
+  return process.env.XDG_DATA_HOME ? join(process.env.XDG_DATA_HOME, 'mu') : join(HOME, '.local', 'share', 'mu');
+}
+
+export function getCacheDir(): string {
+  return process.env.XDG_CACHE_HOME ? join(process.env.XDG_CACHE_HOME, 'mu') : join(HOME, '.cache', 'mu');
+}
+
+export function getPluginsDir(): string {
+  return join(getConfigDir(), 'plugins');
+}
+
+// ─── npm: specifier parsing ───────────────────────────────────────────────────
+//
+// Plugin specifiers stored in `config.plugins` use the form `npm:<bare>` where
+// `<bare>` is a bun/npm package spec — possibly versioned (`foo@1.2.3`,
+// `@scope/foo@^1.0.0`). Multiple call sites need to split this consistently:
+// `mu install`/`mu uninstall` use it for canonicalization & version stripping;
+// the runtime plugin loader uses it to resolve from
+// `~/.local/share/mu/node_modules/<name>`. Centralized here so the rules
+// can never drift between install-time and load-time.
+
+/**
+ * Parsed npm specifier: package name (always present, scope preserved) and an
+ * optional install-time version range. Examples:
+ *
+ *   foo               → { name: "foo" }
+ *   foo@1.2.3         → { name: "foo",         version: "1.2.3" }
+ *   @scope/foo        → { name: "@scope/foo" }
+ *   @scope/foo@^1.0.0 → { name: "@scope/foo",  version: "^1.0.0" }
+ */
+export interface ParsedNpmSpec {
+  name: string;
+  version?: string;
+}
+
+/** Strip the leading `@` for scoped names before searching for the version `@`. */
+export function parseBareNpmSpec(bare: string): ParsedNpmSpec {
+  const scoped = bare.startsWith('@');
+  const at = bare.indexOf('@', scoped ? 1 : 0);
+  if (at === -1) return { name: bare };
+  return { name: bare.slice(0, at), version: bare.slice(at + 1) };
+}
+
+/**
+ * Canonical form stored in `config.plugins`: `npm:<package-name>` with the
+ * version stripped, so `npm:foo@1.2.3` and `npm:foo` deduplicate correctly.
+ */
+export function canonicalNpmSpecifier(bare: string): string {
+  return `npm:${parseBareNpmSpec(bare).name}`;
+}
+
+export interface AppConfig extends ProviderConfig {
+  plugins?: Array<string | { name: string; config?: Record<string, unknown> }>;
+}
+
+/**
+ * Keys that `loadConfig`/`saveConfig` know how to materialize from `AppConfig`.
+ * Used as an allow-list when seeding a fresh config.json. On `saveConfig` we
+ * preserve every key already present in the file so users can keep custom
+ * fields (or fields added by future versions) without losing them on round-trip.
+ */
+const CONFIG_FILE_KEYS = [
+  'baseUrl',
+  'model',
+  'maxTokens',
+  'temperature',
+  'streamTimeoutMs',
+  'systemPrompt',
+  'plugins',
+] as const;
+
+function configPath(): string {
+  return join(getConfigDir(), 'config.json');
+}
+
+function systemPromptPath(): string {
+  return join(getConfigDir(), 'SYSTEM.md');
+}
+
+function tryRead(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf-8').trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function tryParseJson(text: string | undefined): Partial<AppConfig> {
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+function envInt(key: string): number | undefined {
+  const v = process.env[key];
+  if (!v) {
+    return undefined;
+  }
+  const n = Number.parseInt(v, 10);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+function envFloat(key: string): number | undefined {
+  const v = process.env[key];
+  if (!v) {
+    return undefined;
+  }
+  const n = Number.parseFloat(v);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+export function loadConfig(cliModel?: string): AppConfig {
+  const path = configPath();
+  const file = tryParseJson(tryRead(path));
+
+  const config: AppConfig = {
+    baseUrl: process.env.MU_BASE_URL || file.baseUrl || 'http://localhost:8080/v1',
+    model: cliModel || process.env.MU_MODEL || file.model,
+    maxTokens: envInt('MU_MAX_TOKENS') ?? file.maxTokens ?? 4096,
+    temperature: envFloat('MU_TEMPERATURE') ?? file.temperature ?? 0.7,
+    streamTimeoutMs: envInt('MU_STREAM_TIMEOUT') ?? file.streamTimeoutMs ?? 60_000,
+    systemPrompt: process.env.MU_SYSTEM_PROMPT || file.systemPrompt || tryRead(systemPromptPath()),
+    plugins: file.plugins,
+  };
+
+  if (!existsSync(path)) {
+    mkdirSync(getConfigDir(), { recursive: true });
+    const fileConfig = Object.fromEntries(
+      CONFIG_FILE_KEYS.filter((k) => file[k] !== undefined).map((k) => [k, file[k]]),
+    ) as Partial<AppConfig>;
+    writeFileSync(path, JSON.stringify(fileConfig, null, 2), 'utf-8');
+  }
+
+  return config;
+}
+
+/**
+ * Persist `updates` to config.json, preserving any keys (known or unknown)
+ * that are already present in the file. Only `undefined` values are stripped.
+ */
+export function saveConfig(updates: Partial<AppConfig>): void {
+  const path = configPath();
+  const file = tryParseJson(tryRead(path)) as Record<string, unknown>;
+  const merged: Record<string, unknown> = { ...file };
+  for (const [key, value] of Object.entries(updates)) {
+    if (value === undefined) {
+      delete merged[key];
+    } else {
+      merged[key] = value;
+    }
+  }
+  mkdirSync(getConfigDir(), { recursive: true });
+  writeFileSync(path, JSON.stringify(merged, null, 2), 'utf-8');
+}

package/src/main.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { startApp } from './app/startApp';
+
+startApp();

package/src/runtime/createRegistry.ts

@@ -0,0 +1,58 @@
+import { createBuiltinPlugin, PluginRegistry } from 'mu-agents';
+import type { ShutdownFn } from '../app/shutdown';
+import type { AppConfig } from '../config/index';
+import type { InkUIService } from '../tui/plugins/InkUIService';
+import { discoverPluginFiles, loadConfiguredPlugin } from './pluginLoader';
+
+interface CreateRegistryOptions {
+  cwd: string;
+  config: AppConfig;
+  uiService: InkUIService;
+  /**
+   * Host shutdown is forwarded to plugins via PluginContext so a plugin (or
+   * Pi extension via mu-pi-compat) calling shutdown gets the same graceful
+   * path as Ctrl+C — terminal restored, plugins deactivated.
+   *
+   * Optional because some callers (tests, single-shot) don't have one.
+   */
+  shutdown?: ShutdownFn;
+}
+
+/**
+ * Build the plugin config object passed into a plugin's factory.
+ * Every plugin (configured or locally discovered) gets the UI service and
+ * (when available) the host shutdown so tools can prompt, toast, set status
+ * segments, or trigger graceful exit without extra plumbing.
+ */
+function buildPluginConfig(
+  uiService: InkUIService,
+  shutdown: ShutdownFn | undefined,
+  base?: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = base ? { ...base } : {};
+  merged.ui = uiService;
+  if (shutdown) merged.shutdown = shutdown;
+  return merged;
+}
+
+export async function createRegistry(options: CreateRegistryOptions): Promise<PluginRegistry> {
+  const { cwd, config, uiService, shutdown } = options;
+  const registry = new PluginRegistry({ cwd, config: {}, ui: uiService, shutdown });
+
+  await registry.register(createBuiltinPlugin());
+
+  // Locally dropped plugins (~/.config/mu/plugins/*.ts) go through the same
+  // loader as configured ones so they receive `{ ui, shutdown }` and get
+  // consistent error reporting.
+  for (const filePath of discoverPluginFiles()) {
+    await loadConfiguredPlugin(registry, filePath, buildPluginConfig(uiService, shutdown), uiService);
+  }
+
+  for (const entry of config.plugins ?? []) {
+    const name = typeof entry === 'string' ? entry : entry.name;
+    const pluginConfig = typeof entry === 'string' ? undefined : entry.config;
+    await loadConfiguredPlugin(registry, name, buildPluginConfig(uiService, shutdown, pluginConfig), uiService);
+  }
+
+  return registry;
+}