mini-coder 0.7.4 → 0.8.1

package/src/session.ts

@@ -1,91 +1,146 @@
-import { mkdir } from "node:fs/promises";
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
-import type { Message } from "@earendil-works/pi-ai";
-import { Value } from "typebox/value";
-import { SESSIONS_DIR } from "./shared";
-import { type Session, SessionSchema } from "./types";
+import type { Message, Tool } from "@earendil-works/pi-ai";
 
-export async function ensureSessionsDir(): Promise<void> {
-  await mkdir(SESSIONS_DIR, { recursive: true });
+interface SessionHeader {
+  type: "session";
+  version: 1;
+  id: string;
+  cwd: string;
+  createdAt: string;
+  title: string;
 }
 
-export async function getSession(id: string): Promise<Session | undefined> {
-  const file = Bun.file(join(SESSIONS_DIR, `${id}.json`));
+interface RequestRecord {
+  type: "request";
+  at: string;
+  provider: string;
+  model: string;
+  api: string;
+  thinkingEffort: string;
+  systemPrompt: string;
+  tools: Tool[];
+}
 
-  if (!(await file.exists())) {
-    return;
-  }
+interface MessageRecord {
+  type: "message";
+  at: string;
+  message: Message;
+}
 
-  try {
-    const sessionJson = await file.text();
-    const parsed = JSON.parse(sessionJson) as unknown;
-    const valid = Value.Check(SessionSchema, parsed);
+type SessionRecord = SessionHeader | RequestRecord | MessageRecord;
 
-    if (valid) return parsed;
-  } catch {
-    return;
-  }
+function slugify(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/, "");
+  return slug || "session";
+}
+
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
 
-  return;
+function shortId(): string {
+  const bytes = randomBytes(6);
+  let out = "";
+  for (let i = 0; i < 6; i++) out += ALPHABET[bytes[i] % 36];
+  return out;
 }
 
-function latestMessageTimestamp(session: Session): number {
-  return Math.max(0, ...session.messages.map((message) => message.timestamp));
+function timestamp(date: Date): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return (
+    `${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}` +
+    `-${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}`
+  );
 }
 
-export async function listSessionsForCwd(): Promise<Session[]> {
-  const sessions: Session[] = [];
-  const sessionFiles = new Bun.Glob("*.json");
-  const cwd = process.cwd();
+function titleFor(message: Message): string {
+  if (message.role !== "user") return "session";
+  const text = typeof message.content === "string"
+    ? message.content
+    : message.content.map((block) => (block.type === "text" ? block.text : "")).join(" ");
+  return slugify(text);
+}
 
-  try {
-    for await (const entry of sessionFiles.scan({
-      cwd: SESSIONS_DIR,
-      dot: true,
-    })) {
-      try {
-        const sessionJson = await Bun.file(join(SESSIONS_DIR, entry)).text();
-        const parsed = JSON.parse(sessionJson) as unknown;
-
-        if (Value.Check(SessionSchema, parsed) && cwd === parsed.cwd) {
-          sessions.push(parsed);
-        }
-      } catch {
-        // Ignore invalid session files.
-      }
-    }
-  } catch {
-    return [];
+export class Session {
+  private readonly sessionsDir: string;
+  private readonly cwd: string;
+  id: string | null = null;
+  private fd: number | null = null;
+  private closed = false;
+
+  constructor(sessionsDir: string, cwd: string) {
+    this.sessionsDir = sessionsDir;
+    this.cwd = cwd;
   }
 
-  return sessions.sort(
-    (a, b) => latestMessageTimestamp(b) - latestMessageTimestamp(a),
-  );
-}
+  appendMessage(message: Message): void {
+    if (this.closed) return;
+    this.ensure(titleFor(message));
+    this.write({
+      type: "message",
+      at: new Date().toISOString(),
+      message,
+    });
+  }
 
-export async function saveSession(s: Session) {
-  await ensureSessionsDir();
-  const file = Bun.file(join(SESSIONS_DIR, `${s.id}.json`));
-  await Bun.write(file, JSON.stringify(s));
-}
+  appendRequest(input: Omit<RequestRecord, "type" | "at">): void {
+    if (this.closed) return;
+    this.ensure("session");
+    this.write({ type: "request", at: new Date().toISOString(), ...input });
+  }
 
-export async function updateSession(id: string, messages: Message[]) {
-  const existing = await getSession(id);
-  if (existing) {
-    // Only append new messages, so we don't save compacted messages.
-    if (existing.messages.length < messages.length) {
-      const newMessages = messages.slice(existing.messages.length);
-      existing.messages = [...existing.messages, ...newMessages];
-      await saveSession(existing);
+  close(): void {
+    this.closed = true;
+    if (this.fd !== null) {
+      closeSync(this.fd);
+      this.fd = null;
     }
-    return;
   }
 
-  const s = {
-    id,
-    cwd: process.cwd(),
-    messages,
-  };
+  private ensure(title: string): void {
+    if (this.fd !== null) return;
+    mkdirSync(this.sessionsDir, { recursive: true });
+    const stamp = timestamp(new Date());
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const name = `${stamp}-${title}-${shortId()}`;
+      const dir = join(this.sessionsDir, name);
+      try {
+        mkdirSync(dir);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+        throw error;
+      }
+      this.id = name;
+      const logPath = join(dir, "session.jsonl");
+      this.fd = openSync(logPath, "a");
+      const header: SessionHeader = {
+        type: "session",
+        version: 1,
+        id: name,
+        cwd: this.cwd,
+        createdAt: new Date().toISOString(),
+        title,
+      };
+      this.write(header);
+      return;
+    }
+    throw new Error(`session: could not create a unique directory in ${this.sessionsDir}`);
+  }
 
-  await saveSession(s);
+  private write(record: SessionRecord): void {
+    if (this.fd === null) throw new Error("session: append before create");
+    writeSync(this.fd, JSON.stringify(record) + "\n");
+    fsyncSync(this.fd);
+  }
 }

package/src/tools/bash.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+import { Type, type Static } from "@earendil-works/pi-ai";
+import type { ToolContext, ToolResult } from "./common.ts";
+
+export const BASH_PARAMS = Type.Object(
+  { command: Type.String({ description: "Command to run" }) },
+  { additionalProperties: false },
+);
+type BashArgs = Static<typeof BASH_PARAMS>;
+
+const MAX_HEAD = 10_000;
+const MAX_TAIL = 6_000;
+const TRUNCATED = "\n\n... output truncated ...\n\n";
+
+export function bash(args: BashArgs, ctx: ToolContext): Promise<ToolResult> {
+  return new Promise((resolve) => {
+    const child = spawn("bash", ["-c", args.command], {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let head = "";
+    let tail = "";
+    let omitted = 0;
+    const append = (chunk: Buffer) => {
+      let text = chunk.toString();
+      ctx.onOutput?.(text);
+      if (head.length < MAX_HEAD) {
+        const take = Math.min(MAX_HEAD - head.length, text.length);
+        head += text.slice(0, take);
+        text = text.slice(take);
+      }
+      if (text === "") return;
+      tail += text;
+      if (tail.length > MAX_TAIL) {
+        omitted += tail.length - MAX_TAIL;
+        tail = tail.slice(tail.length - MAX_TAIL);
+      }
+    };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+
+    let settled = false;
+    const finish = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      ctx.signal.removeEventListener("abort", onAbort);
+      clearTimeout(killTimer);
+      const exit = code ?? (ctx.signal.aborted ? "aborted" : "unknown");
+      const truncated = omitted > 0;
+      const body = truncated ? head + TRUNCATED + tail : head + tail;
+      const text = body + (body.endsWith("\n") || body === "" ? "" : "\n") + `exit code: ${exit}`;
+      resolve({
+        text,
+        isError: code !== 0,
+        details: truncated
+          ? { truncated: true, omittedChars: omitted, totalChars: head.length + tail.length + omitted }
+          : undefined,
+      });
+    };
+
+    let killTimer: NodeJS.Timeout | undefined;
+    const kill = (signal: NodeJS.Signals): void => {
+      try {
+        process.kill(-child.pid!, signal);
+      } catch {
+        /* already gone */
+      }
+    };
+    const onAbort = () => {
+      if (!child.pid) return;
+      kill("SIGTERM");
+      killTimer = setTimeout(() => kill("SIGKILL"), 300);
+    };
+
+    if (ctx.signal.aborted) onAbort();
+    else ctx.signal.addEventListener("abort", onAbort, { once: true });
+
+    child.on("error", (error) => {
+      append(Buffer.from(`${head || tail ? "\n" : ""}bash failed: ${error.message}\n`));
+      finish(null);
+    });
+    child.on("close", (code) => finish(code));
+  });
+}

package/src/tools/common.ts

@@ -0,0 +1,32 @@
+import type { ImageContent, Static, TSchema } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+export interface ToolContext {
+  signal: AbortSignal;
+  /** Whether the current model accepts image input. */
+  supportsImages: boolean;
+  onOutput?: (chunk: string) => void;
+}
+
+export interface ToolDetails {
+  truncated: boolean;
+  omittedChars: number;
+  totalChars: number;
+}
+
+export interface ToolResult {
+  text: string;
+  isError: boolean;
+  details?: ToolDetails;
+  /** Image blocks appended to the tool result, after `text`. */
+  images?: ImageContent[];
+}
+
+export function parseArgs<T extends TSchema>(schema: T, value: unknown): Static<T> {
+  try {
+    return Value.Parse(schema, value);
+  } catch {
+    const first = [...Value.Errors(schema, value)][0];
+    throw new Error(first ? `${first.instancePath || "/"} ${first.message}` : "invalid arguments");
+  }
+}

package/src/tools/edit.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { Type, type Static } from "@earendil-works/pi-ai";
+import { createTwoFilesPatch } from "diff";
+import type { ToolResult } from "./common.ts";
+
+export const EDIT_PARAMS = Type.Object(
+  {
+    path: Type.String({ description: "File path" }),
+    oldText: Type.String({ description: "Exact text to replace; empty to create a file" }),
+    newText: Type.String({ description: "Replacement text" }),
+  },
+  { additionalProperties: false },
+);
+type EditArgs = Static<typeof EDIT_PARAMS>;
+
+export function edit(args: EditArgs, signal: AbortSignal): ToolResult {
+  const { path, oldText, newText } = args;
+  const exists = existsSync(path);
+
+  if (oldText === "") {
+    if (exists) return { text: `edit failed: ${path} already exists`, isError: true };
+    if (signal.aborted) return { text: "edit cancelled", isError: true };
+    writeFileSync(path, newText);
+    return { text: `created ${path}\n${unified(path, "", newText)}`, isError: false };
+  }
+
+  if (!exists) return { text: `edit failed: ${path} does not exist`, isError: true };
+  const before = readFileSync(path, "utf8");
+  const count = before.split(oldText).length - 1;
+  if (count === 0) return { text: `edit failed: oldText not found in ${path}`, isError: true };
+  if (count > 1) return { text: `edit failed: oldText matches ${count} times in ${path}`, isError: true };
+
+  const after = before.replace(oldText, newText);
+  if (signal.aborted) return { text: "edit cancelled", isError: true };
+  writeFileSync(path, after);
+  return { text: `edited ${path}\n${unified(path, before, after)}`, isError: false };
+}
+
+function unified(path: string, before: string, after: string): string {
+  return createTwoFilesPatch(path, path, before, after, "", "", { context: 3 });
+}

package/src/tools/index.ts

@@ -0,0 +1,47 @@
+import type { Api, Model, Tool, ToolCall } from "@earendil-works/pi-ai";
+import type { ToolName } from "../config.ts";
+import { parseArgs, type ToolContext, type ToolResult } from "./common.ts";
+import { BASH_PARAMS, bash } from "./bash.ts";
+import { EDIT_PARAMS, edit } from "./edit.ts";
+import { READ_PARAMS, read } from "./read.ts";
+
+export type { ToolDetails, ToolResult } from "./common.ts";
+
+/** Whether a model accepts image input. Drives `read`'s description and results. */
+export function acceptsImages(model: Model<Api>): boolean {
+  return model.input.includes("image");
+}
+
+const READ_DESCRIPTION = "Read a file. Returns its text. Prefer bash for search, ranges, or binary files.";
+const READ_IMAGE_DESCRIPTION =
+  "Read a file. Returns its text, or the image itself when the file is a png, jpg, or webp. " +
+  "Prefer bash for search, ranges, or binary files.";
+
+export function toolSchemas(names: ToolName[], withImages: boolean): Tool[] {
+  const tools: Record<ToolName, Tool> = {
+    edit: {
+      name: "edit",
+      description:
+        "Edit a file by exact text replacement. oldText must occur exactly once. " +
+        "With empty oldText, create a new file (fails if it exists).",
+      parameters: EDIT_PARAMS,
+    },
+    read: {
+      name: "read",
+      description: withImages ? READ_IMAGE_DESCRIPTION : READ_DESCRIPTION,
+      parameters: READ_PARAMS,
+    },
+    bash: {
+      name: "bash",
+      description: "Run a bash command in the current working directory.",
+      parameters: BASH_PARAMS,
+    },
+  };
+  return names.map((name) => tools[name]);
+}
+
+export async function executeTool(call: ToolCall, ctx: ToolContext): Promise<ToolResult> {
+  if (call.name === "edit") return edit(parseArgs(EDIT_PARAMS, call.arguments), ctx.signal);
+  if (call.name === "read") return read(parseArgs(READ_PARAMS, call.arguments), ctx);
+  return bash(parseArgs(BASH_PARAMS, call.arguments), ctx);
+}

package/src/tools/read.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { Type, type Static } from "@earendil-works/pi-ai";
+import type { ToolContext, ToolResult } from "./common.ts";
+
+export const READ_PARAMS = Type.Object(
+  { path: Type.String({ description: "File path" }) },
+  { additionalProperties: false },
+);
+type ReadArgs = Static<typeof READ_PARAMS>;
+
+const IMAGE_MIME: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+};
+
+const MAX_TEXT_CHARS = 100_000;
+/** Cap on the base64 payload sent to the provider, where the file inflates by 4/3. */
+const MAX_IMAGE_BASE64_BYTES = 5 * 1024 * 1024;
+
+export function read(args: ReadArgs, ctx: ToolContext): ToolResult {
+  const { path } = args;
+
+  let data: Buffer;
+  try {
+    data = readFileSync(path);
+  } catch (error) {
+    return { text: `read failed: ${(error as Error).message}`, isError: true };
+  }
+
+  const mime = IMAGE_MIME[extname(path).slice(1).toLowerCase()];
+  if (mime !== undefined) {
+    if (!ctx.supportsImages) {
+      return { text: `read failed: ${path} is an image and the current model does not accept image input`, isError: true };
+    }
+    const base64 = data.toString("base64");
+    if (base64.length > MAX_IMAGE_BASE64_BYTES) {
+      return {
+        text: `read failed: ${path} encodes to ${base64.length} bytes, over the ${MAX_IMAGE_BASE64_BYTES} byte image limit`,
+        isError: true,
+      };
+    }
+    return {
+      text: `read ${path} (${mime}, ${data.length} bytes)`,
+      isError: false,
+      images: [{ type: "image", data: base64, mimeType: mime }],
+    };
+  }
+
+  if (data.subarray(0, 8000).includes(0)) {
+    return { text: `read failed: ${path} is binary; use bash (file, xxd)`, isError: true };
+  }
+
+  const text = data.toString("utf8");
+  if (text.length > MAX_TEXT_CHARS) {
+    return {
+      text: text.slice(0, MAX_TEXT_CHARS) + `\n\n... truncated ... ${path} is ${text.length} characters\n`,
+      isError: false,
+    };
+  }
+  return { text, isError: false };
+}

package/src/tui/commands.ts

@@ -0,0 +1,199 @@
+import {
+  getSupportedThinkingLevels,
+  type Api,
+  type AuthEvent,
+  type AuthPrompt,
+  type AuthType,
+  type Model,
+  type ModelThinkingLevel,
+  type Models,
+} from "@earendil-works/pi-ai";
+import { saveConfig } from "../config.ts";
+import { dim, red } from "./styles.ts";
+import { commonPrefix } from "./complete.ts";
+
+export interface CommandContext {
+  /** The collection the running command may reach, e.g. to start a login. */
+  models: Models;
+  /** The model the session is currently running. */
+  model: Model<Api>;
+  /** Switches the running session to `model`. */
+  select(model: Model<Api>): void;
+  /** Sets the running session's thinking level. */
+  setThinking(level: ModelThinkingLevel): void;
+  /** Aborts when the running command is cancelled (Ctrl+C). */
+  signal: AbortSignal;
+  /** Appends already-styled lines to scrollback. */
+  write(lines: string[]): void;
+  /** Asks the user a question and resolves with the next submitted line. */
+  prompt(prompt: AuthPrompt): Promise<string>;
+  /** Reports a login event as styled scrollback lines. */
+  notify(event: AuthEvent): void;
+}
+
+export interface Command {
+  name: string; // no leading slash, lowercase
+  description: string; // one line, shown by /help
+  run(ctx: CommandContext, args: string): void | Promise<void>;
+}
+
+/** The keybindings the TUI accepts, in the order `/help` prints them. */
+const KEYBINDINGS: [string, string][] = [
+  ["Enter", "submit"],
+  ["Shift+Enter", "newline (Ctrl+J also works)"],
+  ["Esc", "pause the turn at the next step boundary"],
+  ["Ctrl+C", "cancel the turn"],
+  ["Ctrl+D", "exit on an empty draft"],
+  ["Tab", "complete command or path"],
+];
+
+/** One aligned `key  description` block; the key column is dimmed. */
+function keyed(rows: [string, string][], width: number): string[] {
+  return rows.map(([key, description]) => `  ${dim(key.padEnd(width))}  ${description}`);
+}
+
+const help: Command = {
+  name: "help",
+  description: "list commands and keybindings",
+  run(ctx): void {
+    const names = COMMANDS.map((command): [string, string] => [`/${command.name}`, command.description]);
+    const width = Math.max(...names.map(([key]) => key.length), ...KEYBINDINGS.map(([key]) => key.length));
+    ctx.write(["commands", ...keyed(names, width), "", "keybindings", ...keyed(KEYBINDINGS, width)]);
+  },
+};
+
+const login: Command = {
+  name: "login",
+  description: "authenticate a provider",
+  async run(ctx, args): Promise<void> {
+    const providers = ctx.models
+      .getProviders()
+      .filter((provider) => provider.auth.oauth?.login !== undefined || provider.auth.apiKey?.login !== undefined);
+    const providerId =
+      args.trim() ||
+      (await ctx.prompt({
+        type: "select",
+        message: "Select a provider",
+        options: providers.map((provider) => ({ id: provider.id, label: provider.name })),
+      }));
+    const provider = ctx.models.getProvider(providerId);
+    if (provider === undefined) throw new Error(`unknown provider: ${providerId}`);
+
+    const oauth = provider.auth.oauth;
+    const apiKey = provider.auth.apiKey;
+    const types: { id: AuthType; label: string }[] = [];
+    if (oauth?.login !== undefined) {
+      types.push({ id: "oauth", label: oauth.loginLabel ?? oauth.name });
+    }
+    if (apiKey?.login !== undefined) types.push({ id: "api_key", label: apiKey.name });
+    if (types.length === 0) throw new Error(`provider "${providerId}" has no login flow`);
+    const type =
+      types.length === 1
+        ? types[0].id
+        : ((await ctx.prompt({
+            type: "select",
+            message: `How would you like to authenticate with ${provider.name}?`,
+            options: types,
+          })) as AuthType);
+
+    try {
+      await ctx.models.login(providerId, type, {
+        signal: ctx.signal,
+        prompt: (prompt) => ctx.prompt(prompt),
+        notify: (event) => ctx.notify(event),
+      });
+    } catch (error) {
+      if (ctx.signal.aborted) {
+        ctx.write([red("! cancelled")]);
+        return;
+      }
+      throw error;
+    }
+    const source = (await ctx.models.getAuth(providerId))?.source;
+    ctx.write([`logged in to ${provider.name}${source === undefined ? "" : ` (${source})`}`]);
+  },
+};
+
+const provider: Command = {
+  name: "provider",
+  description: "choose the provider and model",
+  async run(ctx): Promise<void> {
+    const available = await ctx.models.getAvailable(undefined, { signal: ctx.signal });
+    const ids = [...new Set(available.map((m) => m.provider))];
+    if (ids.length === 0) throw new Error("no authenticated providers");
+    const providerId = await ctx.prompt({
+      type: "select",
+      message: "Select a provider",
+      options: ids.map((id) => ({ id, label: ctx.models.getProvider(id)?.name ?? id })),
+    });
+    const models = available.filter((m) => m.provider === providerId);
+    if (models.length === 0) throw new Error(`no models for provider "${providerId}"`);
+    const name = ctx.models.getProvider(providerId)?.name ?? providerId;
+    const modelId = await ctx.prompt({
+      type: "select",
+      message: `Select a model for ${name}`,
+      options: models.map((m) => ({ id: m.id, label: m.name ?? m.id })),
+    });
+    const chosen = models.find((m) => m.id === modelId);
+    if (chosen === undefined) throw new Error(`unknown model: ${modelId}`);
+    saveConfig({ provider: providerId, model: modelId });
+    ctx.select(chosen);
+  },
+};
+
+const thinking: Command = {
+  name: "thinking",
+  description: "set the thinking level",
+  async run(ctx): Promise<void> {
+    const levels = getSupportedThinkingLevels(ctx.model);
+    const level = (await ctx.prompt({
+      type: "select",
+      message: "Select a thinking level",
+      options: levels.map((l) => ({ id: l, label: l })),
+    })) as ModelThinkingLevel;
+    saveConfig({ thinkingEffort: level });
+    ctx.setThinking(level);
+  },
+};
+
+const model: Command = {
+  name: "model",
+  description: "choose a model for the current provider",
+  async run(ctx): Promise<void> {
+    const providerId = ctx.model.provider;
+    const models = await ctx.models.getAvailable(providerId, { signal: ctx.signal });
+    if (models.length === 0) throw new Error(`no models for provider "${providerId}"`);
+    const name = ctx.models.getProvider(providerId)?.name ?? providerId;
+    const modelId = await ctx.prompt({
+      type: "select",
+      message: `Select a model for ${name}`,
+      options: models.map((m) => ({ id: m.id, label: m.name ?? m.id })),
+    });
+    const chosen = models.find((m) => m.id === modelId);
+    if (chosen === undefined) throw new Error(`unknown model: ${modelId}`);
+    saveConfig({ provider: providerId, model: modelId });
+    ctx.select(chosen);
+  },
+};
+
+const COMMANDS: Command[] = [help, login, provider, model, thinking];
+
+/** `/name` for a known `name`, else null; unknown slash text stays a message. */
+export function findCommand(text: string): { command: Command; args: string } | null {
+  const match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(text);
+  if (match === null) return null;
+  const command = COMMANDS.find((candidate) => candidate.name === match[1]);
+  return command === undefined ? null : { command, args: match[2] ?? "" };
+}
+
+/** Tab completion for a half-typed command name; null leaves the draft alone. */
+export function completeCommand(draft: string): string | null {
+  if (!draft.startsWith("/") || /\s/.test(draft)) return null;
+  const typed = draft.slice(1);
+  const matches = COMMANDS.filter((command) => command.name.startsWith(typed));
+  if (matches.length === 0) return null;
+  if (matches.length === 1) return `/${matches[0].name}`;
+  const shared = matches.map((command) => command.name).reduce(commonPrefix);
+  return shared === typed ? null : `/${shared}`;
+}
+