mu-coding 0.2.0 → 0.5.0

package/src/runtime/pluginLoader.ts

@@ -0,0 +1,109 @@
+import { readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import type { Plugin, PluginRegistry } from 'mu-agents';
+import { getDataDir, getPluginsDir, parseBareNpmSpec } from '../config/index';
+import type { InkUIService } from '../tui/plugins/InkUIService';
+
+export function discoverPluginFiles(): string[] {
+  const dir = getPluginsDir();
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.ts'))
+      .map((f) => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+function formatPluginError(name: string, err: unknown): string {
+  const parts: string[] = [`Plugin "${name}" failed`];
+  let current: unknown = err;
+  while (current) {
+    if (current instanceof Error) {
+      parts.push(current.message);
+      current = current.cause;
+    } else {
+      parts.push(String(current));
+      break;
+    }
+  }
+  return parts.join(': ');
+}
+
+function resolveNpmPlugin(specifier: string): string {
+  const { name } = parseBareNpmSpec(specifier.slice(4));
+  const dataDir = getDataDir();
+  try {
+    const require = createRequire(resolve(dataDir, 'package.json'));
+    return require.resolve(name);
+  } catch (err) {
+    throw new Error(`Cannot resolve "${name}" from ${dataDir}/node_modules — is it installed?`, { cause: err });
+  }
+}
+
+function isPluginShape(value: unknown): value is Plugin {
+  return typeof value === 'object' && value !== null && 'name' in value && typeof (value as Plugin).name === 'string';
+}
+
+/**
+ * Extract a plugin from a loaded module. Tries (in order):
+ *   1. `module.default` as a factory function
+ *   2. `module.createPlugin` as a factory function
+ *   3. `module.default` as a Plugin object
+ *   4. `module` as a Plugin object
+ *
+ * Returns `null` if no plugin shape matches; the caller should report this
+ * with the list of available exports for debugging.
+ */
+function extractPlugin(mod: Record<string, unknown>, pluginConfig: Record<string, unknown>): Plugin | null {
+  const factory = (mod.default ?? mod.createPlugin) as unknown;
+  if (typeof factory === 'function') {
+    const result = (factory as (cfg: Record<string, unknown>) => unknown)(pluginConfig);
+    return isPluginShape(result) ? result : null;
+  }
+  if (isPluginShape(mod.default)) {
+    return mod.default;
+  }
+  if (isPluginShape(mod)) {
+    return mod;
+  }
+  return null;
+}
+
+export async function loadConfiguredPlugin(
+  registry: PluginRegistry,
+  name: string,
+  pluginConfig?: Record<string, unknown>,
+  uiService?: InkUIService,
+): Promise<void> {
+  const config = pluginConfig ?? {};
+  let target: string;
+  try {
+    target = name.startsWith('npm:') ? resolveNpmPlugin(name) : name;
+  } catch (err) {
+    uiService?.notify(formatPluginError(name, err), 'error');
+    return;
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(target)) as Record<string, unknown>;
+  } catch (err) {
+    uiService?.notify(formatPluginError(name, err), 'error');
+    return;
+  }
+
+  const plugin = extractPlugin(mod, config);
+  if (!plugin) {
+    const exportKeys = Object.keys(mod).join(', ') || '(none)';
+    uiService?.notify(`Plugin "${name}": no plugin export found. Exports: [${exportKeys}]`, 'error');
+    return;
+  }
+
+  try {
+    await registry.register(plugin);
+  } catch (err) {
+    uiService?.notify(formatPluginError(name, err), 'error');
+  }
+}

package/src/sessions/index.test.ts

@@ -0,0 +1,66 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { clearSessionCache, listSessionsAsync, loadSession, saveSession } from './index';
+
+let tmpRoot: string;
+let originalDataHome: string | undefined;
+
+beforeAll(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'mu-sessions-'));
+  originalDataHome = process.env.XDG_DATA_HOME;
+  process.env.XDG_DATA_HOME = tmpRoot;
+});
+
+afterAll(() => {
+  if (originalDataHome === undefined) {
+    delete process.env.XDG_DATA_HOME;
+  } else {
+    process.env.XDG_DATA_HOME = originalDataHome;
+  }
+  clearSessionCache();
+});
+
+describe('saveSession / loadSession', () => {
+  it('round-trips messages as JSONL', async () => {
+    const path = join(tmpRoot, 'roundtrip.jsonl');
+    const messages = [
+      { role: 'user' as const, content: 'hi' },
+      { role: 'assistant' as const, content: 'hello' },
+    ];
+    await saveSession(path, messages);
+
+    const raw = readFileSync(path, 'utf-8');
+    expect(raw.split('\n').filter(Boolean)).toHaveLength(2);
+
+    const loaded = loadSession(path);
+    expect(loaded).toEqual(messages);
+  });
+
+  it('returns [] for missing files', () => {
+    expect(loadSession(join(tmpRoot, 'does-not-exist.jsonl'))).toEqual([]);
+  });
+
+  it('skips malformed JSONL lines', () => {
+    const path = join(tmpRoot, 'partial.jsonl');
+    writeFileSync(path, '{"role":"user","content":"ok"}\n{not json}\n{"role":"assistant","content":"yo"}\n');
+    const loaded = loadSession(path);
+    expect(loaded).toHaveLength(2);
+    expect(loaded[0].role).toBe('user');
+    expect(loaded[1].role).toBe('assistant');
+  });
+
+  it('writes empty content for empty arrays', async () => {
+    const path = join(tmpRoot, 'empty.jsonl');
+    await saveSession(path, []);
+    expect(readFileSync(path, 'utf-8')).toBe('');
+  });
+});
+
+describe('listSessionsAsync', () => {
+  it('returns [] when no project sessions exist', async () => {
+    const list = await listSessionsAsync();
+    expect(Array.isArray(list)).toBe(true);
+  });
+});

package/src/sessions/index.ts

@@ -0,0 +1,190 @@
+import { createReadStream, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { ChatMessage } from 'mu-provider';
+import { getDataDir } from '../config/index';
+import { getProjectId, getProjectName } from './project';
+
+function getProjectSessionsDir(): string {
+  return join(getDataDir(), 'sessions', getProjectId());
+}
+
+function getSortedSessionFiles(): string[] {
+  try {
+    const dir = getProjectSessionsDir();
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .sort()
+      .reverse();
+  } catch {
+    return [];
+  }
+}
+
+export interface SessionInfo {
+  path: string;
+  name: string;
+  date: Date;
+  messageCount: number;
+  preview: string;
+  project: string;
+}
+
+export function generateSessionPath(): string {
+  const dir = getProjectSessionsDir();
+  mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  return join(dir, `${ts}.jsonl`);
+}
+
+/**
+ * Persist `messages` as JSONL. Async to avoid blocking the event loop on
+ * large sessions; callers should `await` to apply backpressure.
+ */
+export async function saveSession(path: string, messages: ChatMessage[]): Promise<void> {
+  const content = messages.length > 0 ? `${messages.map((m) => JSON.stringify(m)).join('\n')}\n` : '';
+  await writeFile(path, content, 'utf-8');
+}
+
+export function loadSession(path: string): ChatMessage[] {
+  try {
+    const content = readFileSync(path, 'utf-8').trim();
+    if (!content) {
+      return [];
+    }
+    return content
+      .split('\n')
+      .map((line) => {
+        try {
+          return JSON.parse(line) as ChatMessage;
+        } catch {
+          return null;
+        }
+      })
+      .filter((msg): msg is ChatMessage => msg !== null);
+  } catch {
+    return [];
+  }
+}
+
+interface SessionPeek {
+  messageCount: number;
+  preview: string;
+}
+
+const PREVIEW_LENGTH = 80;
+const NO_USER_PREVIEW = '(no user message)';
+const EMPTY_PEEK: SessionPeek = { messageCount: 0, preview: '(empty)' };
+
+/**
+ * In-memory cache of session metadata, keyed by absolute path. Entries are
+ * invalidated when the file's mtime changes (a fresh `saveSession` after a
+ * new message bumps mtime). Lifetime is the process — no on-disk index.
+ */
+const peekCache = new Map<string, { mtimeMs: number; peek: SessionPeek }>();
+
+function extractUserPreview(line: string): string | null {
+  try {
+    const msg = JSON.parse(line) as ChatMessage;
+    if (msg && msg.role === 'user' && typeof msg.content === 'string') {
+      return msg.content.slice(0, PREVIEW_LENGTH).replace(/\n/g, ' ');
+    }
+  } catch {
+    // Skip malformed lines.
+  }
+  return null;
+}
+
+/**
+ * Stream a session file line-by-line so memory use is bounded regardless of
+ * file size, and we can stop expensive `JSON.parse` work as soon as we've
+ * captured the first user message.
+ */
+async function peekSessionStreaming(path: string): Promise<SessionPeek> {
+  return new Promise((resolve) => {
+    const stream = createReadStream(path, { encoding: 'utf-8', highWaterMark: 64 * 1024 });
+    const rl = createInterface({ input: stream });
+    let messageCount = 0;
+    let preview: string | null = null;
+
+    const finish = (): void => {
+      resolve({ messageCount, preview: preview ?? NO_USER_PREVIEW });
+    };
+
+    rl.on('line', (line) => {
+      if (!line) return;
+      messageCount++;
+      if (preview !== null) return;
+      preview = extractUserPreview(line);
+    });
+    rl.on('close', finish);
+    stream.on('error', () => resolve(EMPTY_PEEK));
+  });
+}
+
+async function peekSessionCached(path: string, mtimeMs: number): Promise<SessionPeek> {
+  const cached = peekCache.get(path);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.peek;
+  }
+  const peek = await peekSessionStreaming(path);
+  peekCache.set(path, { mtimeMs, peek });
+  return peek;
+}
+
+/** Test/maintenance helper — drop the in-memory peek cache. */
+export function clearSessionCache(): void {
+  peekCache.clear();
+}
+
+export function getLatestSession(): string | null {
+  const files = getSortedSessionFiles();
+  return files.length ? join(getProjectSessionsDir(), files[0]) : null;
+}
+
+/**
+ * Resolve session metadata for the picker. Each file is peeked concurrently
+ * (typically just a few hundred bytes per file), and successive picker opens
+ * hit the in-memory cache keyed by mtime.
+ */
+export async function listSessionsAsync(): Promise<SessionInfo[]> {
+  let dir: string;
+  try {
+    dir = getProjectSessionsDir();
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return [];
+  }
+  const files = getSortedSessionFiles();
+  const project = getProjectName();
+
+  const results = await Promise.all(
+    files.map(async (file) => {
+      const path = join(dir, file);
+      try {
+        const fileStat = await stat(path);
+        const peek = await peekSessionCached(path, fileStat.mtimeMs);
+        return {
+          path,
+          name: file.replace('.jsonl', ''),
+          date: fileStat.mtime,
+          messageCount: peek.messageCount,
+          preview: peek.preview,
+          project,
+        } satisfies SessionInfo;
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  return results.filter((s): s is SessionInfo => s !== null);
+}
+
+// Sync helper preserved for legacy/test callers — wraps the same data path
+// without the streaming optimization. New code should prefer `listSessionsAsync`.
+export function saveSessionSync(path: string, messages: ChatMessage[]): void {
+  const content = messages.length > 0 ? `${messages.map((m) => JSON.stringify(m)).join('\n')}\n` : '';
+  writeFileSync(path, content, 'utf-8');
+}

package/src/sessions/peek.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Verifies the streaming `listSessionsAsync` end-to-end against a tmp data
+ * directory laid out exactly like a real `~/.local/share/mu/sessions/<proj>`.
+ * The cache is exercised by listing twice and confirming we get the same
+ * structural result without re-reading.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { clearSessionCache, listSessionsAsync } from './index';
+import { getProjectId } from './project';
+
+const PROJECT_ID = getProjectId();
+
+let tmpRoot: string;
+let sessionsDir: string;
+
+beforeAll(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'mu-peek-'));
+  process.env.XDG_DATA_HOME = tmpRoot;
+  sessionsDir = join(tmpRoot, 'mu', 'sessions', PROJECT_ID);
+  mkdirSync(sessionsDir, { recursive: true });
+});
+
+afterEach(() => {
+  clearSessionCache();
+});
+
+function writeSession(name: string, messages: Array<{ role: string; content: string }>): string {
+  const path = join(sessionsDir, name);
+  writeFileSync(path, `${messages.map((m) => JSON.stringify(m)).join('\n')}\n`);
+  return path;
+}
+
+describe('listSessionsAsync', () => {
+  it('captures message count and the first user preview', async () => {
+    writeSession('2026-01-01.jsonl', [
+      { role: 'user', content: 'hello world' },
+      { role: 'assistant', content: 'hi back' },
+      { role: 'user', content: 'a follow-up' },
+    ]);
+
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-01');
+    expect(entry).toBeDefined();
+    expect(entry?.messageCount).toBe(3);
+    expect(entry?.preview).toBe('hello world');
+  });
+
+  it('handles malformed lines without crashing', async () => {
+    writeSession('2026-01-02.jsonl', [{ role: 'user', content: 'ok' }]);
+    // Append a junk line outside the structured writer.
+    const broken = join(sessionsDir, '2026-01-03.jsonl');
+    writeFileSync(broken, '{"role":"user","content":"valid"}\n{not-json\n');
+
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-03');
+    expect(entry?.messageCount).toBe(2);
+    expect(entry?.preview).toBe('valid');
+  });
+
+  it('reports a placeholder when no user message is present', async () => {
+    writeSession('2026-01-04.jsonl', [{ role: 'assistant', content: 'no user here' }]);
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-04');
+    expect(entry?.preview).toBe('(no user message)');
+  });
+
+  it('truncates long previews to PREVIEW_LENGTH and replaces newlines', async () => {
+    const longMessage = `line one\n${'x'.repeat(200)}`;
+    writeSession('2026-01-05.jsonl', [{ role: 'user', content: longMessage }]);
+    const list = await listSessionsAsync();
+    const entry = list.find((s) => s.name === '2026-01-05');
+    expect(entry?.preview).not.toContain('\n');
+    expect(entry?.preview.length).toBe(80);
+  });
+
+  it('serves cached results on the second call (same mtime)', async () => {
+    writeSession('2026-01-06.jsonl', [{ role: 'user', content: 'cached' }]);
+    const first = await listSessionsAsync();
+    const second = await listSessionsAsync();
+    const a = first.find((s) => s.name === '2026-01-06');
+    const b = second.find((s) => s.name === '2026-01-06');
+    expect(a?.preview).toBe(b?.preview);
+    expect(a?.messageCount).toBe(b?.messageCount);
+  });
+});

package/src/sessions/project.ts

@@ -0,0 +1,51 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+function findGitRoot(from: string): string | null {
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: from,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return root || null;
+  } catch {
+    return null;
+  }
+}
+
+// The project root is determined once per process — `process.cwd()` doesn't
+// move during a TUI session and shelling out to git on every save is wasteful.
+let cachedRoot: string | null = null;
+
+function getProjectRoot(): string {
+  if (cachedRoot !== null) {
+    return cachedRoot;
+  }
+  const cwd = process.cwd();
+  cachedRoot = findGitRoot(cwd) ?? cwd;
+  return cachedRoot;
+}
+
+let cachedId: string | null = null;
+let cachedName: string | null = null;
+
+export function getProjectId(): string {
+  if (cachedId !== null) {
+    return cachedId;
+  }
+  const root = getProjectRoot();
+  const hash = createHash('sha256').update(root).digest('hex').slice(0, 12);
+  const name = root.split('/').pop() || 'unknown';
+  cachedId = `${name}-${hash}`;
+  return cachedId;
+}
+
+export function getProjectName(): string {
+  if (cachedName !== null) {
+    return cachedName;
+  }
+  const root = getProjectRoot();
+  cachedName = root.split('/').pop() || root;
+  return cachedName;
+}

package/src/tui/{context/chat.ts → chat/ChatContext.ts}

@@ -1,5 +1,5 @@
 import { createContext, useContext } from 'react';
-import type { ChatContextValue } from '../useChat';
+import type { ChatContextValue } from './useChat';
 
 export const ChatContext = createContext<ChatContextValue | null>(null);
 

package/src/tui/chat/ToolDisplayContext.ts

@@ -0,0 +1,33 @@
+import type { PluginRegistry, ToolDisplayHint } from 'mu-agents';
+import { createContext, useContext, useMemo } from 'react';
+
+type ToolDisplayMap = Map<string, ToolDisplayHint>;
+
+const ToolDisplayContext = createContext<ToolDisplayMap>(new Map());
+
+export const ToolDisplayProvider = ToolDisplayContext.Provider;
+
+/** Hook used by tool renderers to look up rendering hints for a tool name. */
+export function useToolDisplay(name: string): ToolDisplayHint | undefined {
+  const map = useContext(ToolDisplayContext);
+  return map.get(name);
+}
+
+/**
+ * Build a lookup table from the registry, keyed by tool function name. Tools
+ * without a `display` hint are omitted; the renderer falls back to a generic
+ * preview block. Memoized on the registry reference — registration is
+ * effectively startup-only today, but the dependency makes the contract
+ * explicit if hot-loading lands later.
+ */
+export function useToolDisplayMap(registry: PluginRegistry): ToolDisplayMap {
+  return useMemo(() => {
+    const map: ToolDisplayMap = new Map();
+    for (const tool of registry.getTools()) {
+      if (tool.display) {
+        map.set(tool.definition.function.name, tool.display);
+      }
+    }
+    return map;
+  }, [registry]);
+}

package/src/tui/{useAbort.ts → chat/useAbort.ts}

@@ -1,4 +1,5 @@
 import { useCallback, useRef, useState } from 'react';
+import { restoreTerminal, type ShutdownFn } from '../../app/shutdown';
 
 function useDoublePress(timeoutMs: number) {
   const [warning, setWarning] = useState(false);
@@ -38,6 +39,7 @@ export function useAbort(
   controllerRef: React.RefObject<AbortController | null>,
   exit: () => void,
   timeoutMs: number,
+  shutdown?: ShutdownFn,
 ): AbortState {
   const { warning: quitWarning, confirm: onCtrlC } = useDoublePress(timeoutMs);
   const { warning: abortWarning, confirm: onEsc } = useDoublePress(timeoutMs);
@@ -48,14 +50,21 @@ export function useAbort(
       controllerRef.current = null;
       return;
     }
-    if (onCtrlC()) {
-      exit();
-      setTimeout(() => {
-        process.stdout.write('\x1b[<u');
-        process.exit(0);
-      }, 100);
+    if (!onCtrlC()) {
+      return;
+    }
+    // Restore the terminal first so even a hanging shutdown leaves a usable
+    // prompt, then unmount Ink (fires `useScroll`/etc. cleanups), then run
+    // the registry shutdown which `process.exit`s when complete.
+    restoreTerminal();
+    exit();
+    if (shutdown) {
+      void shutdown(0);
+    } else {
+      // Fallback for callers that didn't wire a shutdown function.
+      setTimeout(() => process.exit(0), 500);
     }
-  }, [streaming, onCtrlC, exit, controllerRef]);
+  }, [streaming, onCtrlC, exit, controllerRef, shutdown]);
 
   const handleEsc = useCallback(() => {
     if (!(streaming && controllerRef.current)) {

package/src/tui/chat/useAttachment.ts

@@ -0,0 +1,74 @@
+import type { ImageAttachment } from 'mu-provider';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { readClipboardImage } from '../../utils/clipboard';
+
+const ERROR_TIMEOUT_MS = 3000;
+
+export interface AttachmentState {
+  attachment: ImageAttachment | null;
+  attachmentError: string | null;
+  onPaste: () => void;
+  clear: () => void;
+}
+
+export function useAttachment(): AttachmentState {
+  const [attachment, setAttachment] = useState<ImageAttachment | null>(null);
+  const [attachmentError, setAttachmentError] = useState<string | null>(null);
+  const errorTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelErrorTimer = useCallback(() => {
+    if (errorTimerRef.current) {
+      clearTimeout(errorTimerRef.current);
+      errorTimerRef.current = null;
+    }
+  }, []);
+
+  // Cancel any pending error-clear timer if the component unmounts.
+  useEffect(() => cancelErrorTimer, [cancelErrorTimer]);
+
+  const onPaste = useCallback(() => {
+    cancelErrorTimer();
+    const img = readClipboardImage();
+    if (img) {
+      setAttachment(img);
+      setAttachmentError(null);
+      return;
+    }
+    setAttachmentError('No image on clipboard');
+    errorTimerRef.current = setTimeout(() => {
+      setAttachmentError(null);
+      errorTimerRef.current = null;
+    }, ERROR_TIMEOUT_MS);
+  }, [cancelErrorTimer]);
+
+  const clear = useCallback(() => {
+    cancelErrorTimer();
+    setAttachment(null);
+    setAttachmentError(null);
+  }, [cancelErrorTimer]);
+
+  return { attachment, attachmentError, onPaste, clear };
+}
+
+type PickerKind = 'model' | 'sessions' | null;
+
+export interface TogglesState {
+  showModelPicker: boolean;
+  showSessionPicker: boolean;
+  onTogglePicker: () => void;
+  onToggleSessionPicker: () => void;
+}
+
+/**
+ * At most one picker is visible at a time. Toggling on a picker while the
+ * other is open swaps to the new one rather than stacking modals.
+ */
+export function useToggles(): TogglesState {
+  const [picker, setPicker] = useState<PickerKind>(null);
+  return {
+    showModelPicker: picker === 'model',
+    showSessionPicker: picker === 'sessions',
+    onTogglePicker: useCallback(() => setPicker((p) => (p === 'model' ? null : 'model')), []),
+    onToggleSessionPicker: useCallback(() => setPicker((p) => (p === 'sessions' ? null : 'sessions')), []),
+  };
+}