@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/server/routes/worktrees/routes.test.ts

@@ -0,0 +1,326 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `/api/worktrees` routes, end to end over a real repository.
+ *
+ * What a unit test on the modules cannot show, and what these cases are for:
+ *
+ *  - the LIST payload carries every fact a row draws, from one read;
+ *  - a create answers with the worktree it made, and the next list shows it —
+ *    the topology cache invalidation is what makes "next list" true;
+ *  - a DELETE takes the path in its BODY (a path has separators) and answers the
+ *    branch verdict rather than a bare success;
+ *  - MOCK refuses, because a demo install has no repository to make one in.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getDb } from '@/server/db.server';
+import { loader as listLoader } from '@/server/routes/worktrees/list';
+import { action as createAction, validateAction } from '@/server/routes/worktrees/create';
+import { action as removeAction } from '@/server/routes/worktrees/remove';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { removeDir } from '@/test-support/remove-dir';
+
+const GIT_ENV = {
+  ...Bun.env,
+  GIT_EDITOR: 'true',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@example.invalid',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@example.invalid',
+};
+
+function git(cwd: string, ...args: string[]): string {
+  return Bun.spawnSync({ cmd: ['git', ...args], cwd, env: GIT_ENV }).stdout.toString();
+}
+
+let workRoot: string;
+let repo: string;
+/** Where the session files live, so a count can be observed without omp. */
+let sessionsRoot: string;
+const saved = {
+  MOCK: Bun.env.MOCK,
+  SYNC_WORKSPACE: Bun.env.SYNC_WORKSPACE,
+  agentDir: Bun.env.PI_CODING_AGENT_DIR,
+  xdg: Bun.env.XDG_DATA_HOME,
+  dataDir: Bun.env.KABMO_DATA_DIR,
+};
+
+/**
+ * Call a route module the way the adapter does — with `params`, which every
+ * Remix-shaped handler declares even when its path has no parameter.
+ */
+async function call(
+  handler: (args: { request: Request; params: Record<string, string> }) => unknown,
+  url: string,
+  init?: RequestInit,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const response = (await handler({ request: new Request(url, init), params: {} })) as Response;
+  return { status: response.status, body: (await response.json()) as Record<string, unknown> };
+}
+
+/** Put an env var back, or unset it when the file started without one. */
+function restoreEnv(name: string, value: string | undefined): void {
+  if (value === undefined) delete Bun.env[name];
+  else Bun.env[name] = value;
+}
+
+/** One session file whose cwd is `cwd`, as the agent would record it. */
+function writeSession(id: string, cwd: string): void {
+  const lines = [
+    JSON.stringify({ type: 'session', id, cwd, timestamp: '2026-10-23T00:00:00.000Z' }),
+    JSON.stringify({
+      type: 'message',
+      id: `${id}-m1`,
+      parentId: null,
+      timestamp: '2026-10-23T00:00:01.000Z',
+      message: { role: 'user', content: 'where am I' },
+    }),
+  ];
+  writeFileSync(join(sessionsRoot, 'project', `${id}.jsonl`), `${lines.join('\n')}\n`);
+}
+
+/** The `worktrees` array of a list payload, narrowed once. */
+function worktreesOf(body: Record<string, unknown>): Array<Record<string, unknown>> {
+  const list = body.worktrees;
+  return Array.isArray(list) ? (list as Array<Record<string, unknown>>) : [];
+}
+
+const base = (): string => `http://localhost/api/worktrees?root=${encodeURIComponent(repo)}`;
+
+beforeAll(() => {
+  workRoot = mkdtempSync(join(tmpdir(), 'kabmo-worktree-routes-'));
+  repo = join(workRoot, 'repo');
+  mkdirSync(repo, { recursive: true });
+  writeFileSync(join(repo, '.gitignore'), 'node_modules\n');
+  mkdirSync(join(repo, 'node_modules', 'dep'), { recursive: true });
+  writeFileSync(join(repo, 'node_modules', 'dep', 'index.js'), 'module.exports = {};\n');
+  writeFileSync(join(repo, 'readme.md'), 'hello\n');
+  git(repo, 'init', '-q', '-b', 'main', '.');
+  git(repo, 'add', '-A');
+  git(repo, 'commit', '-q', '-m', 'base');
+
+  // A sessions root of this file's own: the worktree count reads it, and
+  // without the override it would scan the developer's real `~/.omp/agent`.
+  const agent = join(workRoot, 'agent');
+  sessionsRoot = join(agent, 'sessions');
+  mkdirSync(join(sessionsRoot, 'project'), { recursive: true });
+  Bun.env.PI_CODING_AGENT_DIR = agent;
+  // XDG would redirect the sessions dir to $XDG_DATA_HOME/omp when it exists.
+  delete Bun.env.XDG_DATA_HOME;
+  // A worktree's default location is `<data>/worktrees/<projectId>/<name>`, so
+  // without this the suite writes into the developer's own `~/.kabmo`.
+  Bun.env.KABMO_DATA_DIR = join(workRoot, 'data');
+});
+
+beforeEach(async () => {
+  await isolateDb();
+  Bun.env.MOCK = 'false';
+  Bun.env.SYNC_WORKSPACE = 'false';
+  const db = await getDb();
+  await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', repo]);
+});
+
+afterEach(async () => {
+  await invalidateWorktreeTopology();
+  // The session-file caches are keyed on `globalThis` and this file writes
+  // session files, so a case that leaves one behind would be counted by the next.
+  clearSessionFileCaches();
+  await releaseDb();
+});
+
+afterAll(() => {
+  removeDir(workRoot);
+  // Explicitly mapped: the record's keys are not the env names, and an
+  // `Object.entries` restore would silently leave `PI_CODING_AGENT_DIR` pointed
+  // at a directory this file just deleted.
+  restoreEnv('MOCK', saved.MOCK);
+  restoreEnv('SYNC_WORKSPACE', saved.SYNC_WORKSPACE);
+  restoreEnv('PI_CODING_AGENT_DIR', saved.agentDir);
+  restoreEnv('XDG_DATA_HOME', saved.xdg);
+  restoreEnv('KABMO_DATA_DIR', saved.dataDir);
+});
+
+describe('GET /api/worktrees', () => {
+  test('lists the checkout with the facts a row draws', async () => {
+    const { status, body } = await call(listLoader, base());
+    expect(status).toBe(200);
+    expect(body.isRepo).toBe(true);
+    expect(String(body.base)).toContain('worktrees');
+    const primary = worktreesOf(body)[0] as Record<string, unknown>;
+    expect(primary.isPrimary).toBe(true);
+    expect(primary.branch).toBe('main');
+    expect(String(primary.head).length).toBeGreaterThan(0);
+    expect(primary.dirty).toBe(0);
+  });
+
+  test('a folder that is not a repository answers isRepo:false, not a failure', async () => {
+    // A notes folder bound as a workspace: it can never hold a worktree, and
+    // the composer must read that as "no control here" rather than as a broken
+    // feature. The route used to 500 here, because the identity read throws for
+    // a directory with no root commit.
+    const plain = join(workRoot, 'plain-notes');
+    mkdirSync(plain, { recursive: true });
+    writeFileSync(join(plain, 'todo.md'), '- buy milk\n');
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['plain', plain]);
+
+    const { status, body } = await call(listLoader, `http://localhost/api/worktrees?root=${encodeURIComponent(plain)}`);
+    expect(status).toBe(200);
+    expect(body.isRepo).toBe(false);
+    expect(worktreesOf(body)).toEqual([]);
+  });
+
+  test('counts a session running in a worktree that lives OUTSIDE the repository', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-counted' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+    // The default location is under the data directory, not inside the checkout
+    // — which is the case a `primaryRoot` prefix test counted zero for.
+    expect(path.startsWith(repo)).toBe(false);
+
+    writeSession('route-counted-session', path);
+
+    const listed = await call(listLoader, base());
+    const row = worktreesOf(listed.body).find((entry) => entry.path === path);
+    // The number the delete dialog warns with: a chat is running here.
+    expect(row?.sessions).toBe(1);
+  });
+
+  test('a folder with no project binding is refused, not answered for the app root', async () => {
+    const { status, body } = await call(listLoader, 'http://localhost/api/worktrees');
+    expect(status).toBe(400);
+    expect(body.code).toBe('not_a_repo');
+  });
+
+  test('MOCK refuses — a demo install has no repository to read', async () => {
+    Bun.env.MOCK = 'true';
+    const { status, body } = await call(listLoader, base());
+    expect(status).toBe(409);
+    expect(body.code).toBe('mock_mode');
+  });
+});
+
+describe('POST /api/worktrees', () => {
+  test('creates one, carries the ignored build folder, and the next list shows it', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-created' }),
+    });
+
+    expect(created.status).toBe(200);
+    const worktree = created.body.worktree as Record<string, unknown>;
+    expect(worktree.branch).toBe('wt/route-created');
+    // The carry is the one capability git does not provide; without it the new
+    // checkout cannot run the project.
+    const carried = worktree.carried as { copied: string[] };
+    expect(carried.copied).toContain('node_modules');
+
+    const listed = await call(listLoader, base());
+    const row = worktreesOf(listed.body).find((entry) => entry.branch === 'wt/route-created');
+    expect(row).toBeDefined();
+    expect(row?.isPrimary).toBe(false);
+    expect(row?.startRef).toBe('HEAD');
+  });
+
+  test('a refusal answers its code and field, so the dialog can mark the input', async () => {
+    const refused = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'existing', branch: 'main' }),
+    });
+    expect(refused.status).toBe(400);
+    expect(refused.body.code).toBe('branch_in_use');
+    expect(refused.body.field).toBe('branch');
+  });
+
+  test('validate answers the same refusal without creating anything', async () => {
+    const result = await call(validateAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'has space' }),
+    });
+    expect(result.status).toBe(400);
+    expect(result.body.ok).toBe(false);
+    const failures = result.body.failures as Array<{ code: string }>;
+    expect(failures[0]?.code).toBe('invalid_name');
+
+    // Nothing was created: the fixture repository is shared by this file, so the
+    // assertion names the branch rather than a count (a count would also pin how
+    // many earlier tests happened to leave behind).
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.branch === 'has-space')).toBe(false);
+    expect(worktreesOf(listed.body).some((entry) => entry.branch === 'has space')).toBe(false);
+  });
+});
+
+describe('DELETE /api/worktrees', () => {
+  test('removes the worktree and its branch, and the list no longer shows it', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-remove' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+
+    const removed = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path, deleteBranch: true }),
+    });
+    expect(removed.status).toBe(200);
+    expect(removed.body.removed).toBe(true);
+    expect(removed.body.branchDeleted).toBe(true);
+
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.path === path)).toBe(false);
+  });
+
+  test('a missing path is refused by name, not by a crash', async () => {
+    const refused = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(refused.status).toBe(400);
+    expect(refused.body.code).toBe('invalid_name');
+  });
+
+  test('a dirty worktree is refused with 409 and its count, so a caller can tell a retry from a bad request', async () => {
+    const created = await call(createAction, base(), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ mode: 'new', branch: 'wt/route-dirty' }),
+    });
+    const path = String((created.body.worktree as Record<string, unknown>).path);
+    writeFileSync(join(path, 'scratch.txt'), 'not committed\n');
+
+    const refused = await call(removeAction, base(), {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path, deleteBranch: true }),
+    });
+    // 409: the request is well-formed and the tree is the obstacle — the same
+    // distinction `mock_mode` draws. A 400 here reads as "fix your request".
+    expect(refused.status).toBe(409);
+    expect(refused.body.code).toBe('dirty');
+    expect(Number(refused.body.count)).toBeGreaterThan(0);
+
+    // A refusal is not a partial removal.
+    const listed = await call(listLoader, base());
+    expect(worktreesOf(listed.body).some((entry) => entry.path === path)).toBe(true);
+  });
+});

package/src/server/routes/worktrees/shared.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The worktree routes' shared plumbing: resolve the project, refuse in MOCK, and
+ * turn a `WorktreeError` into the JSON envelope the client already understands.
+ *
+ * Root resolution goes through `resolveRoot`, the security boundary every fs
+ * route uses — a client-supplied `root` is only honoured when it is the app
+ * root, a registered `project_path`, or (this feature) a worktree of one.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import { isMockMode } from '@/server/mock.server';
+import { getDb } from '@/server/db.server';
+import { resolveRoot } from '@/server/lib/fs/root';
+import { asWorktreeFailure } from '@/server/lib/fs/worktree/errors';
+import type { WorktreeFailure } from '@/shared/lib/workspace/worktree/types';
+
+/** A registered workspace's `project_path`, or null when the folder is unbound. */
+export async function projectPathForFolder(folderId: number | string | null): Promise<string | null> {
+  if (folderId === null || folderId === '') return null;
+  try {
+    const db = await getDb();
+    const row = await db.get<{ project_path: string | null }>(
+      'SELECT project_path FROM workspace_folders WHERE id = ?',
+      [Number(folderId)],
+    );
+    return row?.project_path ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The project a request names: its own `root`, else the folder's binding. */
+export async function resolveWorktreeProject(
+  rawRoot: string | null | undefined,
+  folderId: string | null,
+): Promise<{ root: string | null; error?: Response }> {
+  const fromFolder = await projectPathForFolder(folderId);
+  const root = await resolveRoot(rawRoot || fromFolder, '');
+  if (!root) {
+    return {
+      root: null,
+      error: json(
+        {
+          error: 'Pick a workspace bound to a Git repository first.',
+          code: 'not_a_repo',
+        },
+        { status: 400 },
+      ),
+    };
+  }
+  return { root };
+}
+
+/**
+ * A worktree mutation in demo mode is refused rather than simulated: MOCK has no
+ * repository on disk, so a "successful" create would promise a folder that does
+ * not exist.
+ */
+export function mockRefusal(): Response {
+  return json(
+    { error: 'Worktrees need a real Git repository; Kabmo is running in demo mode.', code: 'mock_mode' },
+    { status: 409 },
+  );
+}
+
+/**
+ * A refusal's HTTP status, from what the refusal MEANS.
+ *
+ * `dirty` is a conflict with the tree's current state rather than a malformed
+ * request — the same distinction `session_not_running` and `mock_mode` draw with
+ * 409 — and a caller that retries after committing needs to tell the two apart
+ * without parsing the message.
+ */
+const REFUSAL_STATUS: Partial<Record<WorktreeFailure['code'], number>> = {
+  dirty: 409,
+};
+
+export function worktreeFailureResponse(error: unknown, status = 400): Response {
+  const failure = asWorktreeFailure(error);
+  return json({ error: failure.message, ...failure }, { status: REFUSAL_STATUS[failure.code] ?? status });
+}
+
+export function isMock(): boolean {
+  return isMockMode();
+}

package/src/shared/lib/chat/timeline/omp-callbacks.test.ts

@@ -55,6 +55,8 @@ function makeCallbacks(overrides: Partial<OmpAgentCallbacksDeps> = {}): OmpAgent
     appSettings: {},
     enqueueExtensionDialog: () => {},
     withdrawExtensionDialog: () => {},
+    reloadMessages: () => {},
+    needsReloadRef: { current: false },
     ...overrides,
   };
   return createOmpAgentCallbacks(deps);
@@ -133,6 +135,40 @@ describe('createOmpAgentCallbacks run boundaries', () => {
     expect(verbs).toEqual(['Thinking']);
   });
 
+  test('a run that lost frames re-reads its transcript when it settles', () => {
+    // A reconnect while the run was STILL streaming cannot reload: its rows are
+    // the stream's, and replacing them mid-turn is the lagging-snapshot bug.
+    // But the segments that finished during the outage have no other way back —
+    // their `message_end` went into the dead socket, and `agent_end` only
+    // materializes turns that stopped abnormally. So the loss is remembered and
+    // the read happens at the settle.
+    const reads: number[] = [];
+    const needsReloadRef = { current: true };
+    const callbacks = recordingCallbacks({
+      reloadMessages: () => { reads.push(1); },
+      needsReloadRef,
+    });
+
+    callbacks.onAgentEnd?.({});
+
+    expect(reads.length).toBe(1);
+    // Consumed: a later run end must not re-read a transcript nothing lost.
+    expect(needsReloadRef.current).toBe(false);
+    callbacks.onAgentEnd?.({});
+    expect(reads.length).toBe(1);
+  });
+
+  test('an ordinary run end does NOT re-read the transcript', () => {
+    // The read is a full parse of the session JSONL; a run that never lost a
+    // frame must not pay it.
+    const reads: number[] = [];
+    const callbacks = recordingCallbacks({ reloadMessages: () => { reads.push(1); } });
+
+    callbacks.onAgentEnd?.({});
+
+    expect(reads).toEqual([]);
+  });
+
   test('a real omp frame sequence drives the boundary once per run', () => {
     const callbacks = recordingCallbacks();
     const deps = makeFoldDeps(callbacks);

package/src/shared/lib/chat/timeline/omp-callbacks.ts

@@ -51,6 +51,14 @@ export interface OmpAgentCallbacksDeps {
   enqueueExtensionDialog: (request: ExtensionUiDialogRequest) => void;
   /** Drop a queued request omp withdrew (`method: 'cancel'`). */
   withdrawExtensionDialog: (targetId: string) => void;
+  /** Re-read the committed transcript (see `lost-run.ts`). Used at `agent_end`
+   *  when frames were lost mid-run: the segments that finished during the
+   *  outage have no other way back. */
+  reloadMessages: () => void;
+  /** Set when a run lost frames while STILL STREAMING. Its earlier segments can
+   *  only be recovered by a full read, which is safe only once the run is over —
+   *  so the read happens here, at the settle. */
+  needsReloadRef: { current: boolean };
 }
 
 export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCallbacks {
@@ -70,6 +78,8 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
     appSettings,
     enqueueExtensionDialog,
     withdrawExtensionDialog,
+    reloadMessages,
+    needsReloadRef,
   } = deps;
 
   bindStreamingCoalescer(setLocalMessages, () => scrollToBottom('smooth'));
@@ -245,6 +255,14 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       // placeholder until the realtime scan surfaces the row.
       const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
       if (sid) refreshSessionMeta(sid);
+      // A run that lost frames while still streaming: its earlier segments (a
+      // tool card, a thinking block, an earlier answer) have no other way back.
+      // Read now — the run is over, so a full transcript read cannot clobber a
+      // live row — and `reloadMessages` retries while omp has not flushed.
+      if (needsReloadRef.current) {
+        needsReloadRef.current = false;
+        reloadMessages();
+      }
     },
     onModelChanged: () => {
       // omp's model_changed frame carries no payload — re-read the session

package/src/shared/lib/chat/timeline/run-signals.test.ts

@@ -56,6 +56,8 @@ function deps(overrides: Partial<OmpAgentCallbacksDeps> = {}): OmpAgentCallbacks
     appSettings: {},
     enqueueExtensionDialog: () => {},
     withdrawExtensionDialog: () => {},
+    reloadMessages: () => {},
+    needsReloadRef: { current: false },
     ...overrides,
   };
 }

package/src/shared/lib/code/editor/comment-syntax.test.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The comment tokens `toggleComment` reads out of `languageData`.
+ *
+ * A wrong token is not a cosmetic bug: `//` inserted into YAML is a syntax
+ * error, and a `//` inserted into CSS comments out nothing while breaking the
+ * rule it was added to. The three shapes are asserted, plus the default that
+ * every C-family grammar relies on.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { commentSyntaxFor } from '@/shared/lib/code/editor/comment-syntax';
+
+describe('commentSyntaxFor', () => {
+  test('defaults to a line comment for the C-family', () => {
+    expect(commentSyntaxFor('typescript')).toEqual({ line: '//' });
+    expect(commentSyntaxFor('rust')).toEqual({ line: '//' });
+    expect(commentSyntaxFor('not-a-language')).toEqual({ line: '//' });
+  });
+
+  test('names the languages whose line comment is not `//`', () => {
+    expect(commentSyntaxFor('python')).toEqual({ line: '#' });
+    expect(commentSyntaxFor('yaml')).toEqual({ line: '#' });
+    expect(commentSyntaxFor('sql')).toEqual({ line: '--' });
+  });
+
+  test('wraps the languages that have only block comments', () => {
+    expect(commentSyntaxFor('css')).toEqual({ block: ['/*', '*/'] });
+    expect(commentSyntaxFor('html')).toEqual({ block: ['<!--', '-->'] });
+    expect(commentSyntaxFor('markdown')).toEqual({ block: ['<!--', '-->'] });
+  });
+});

package/src/shared/lib/code/editor/comment-syntax.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * How each language writes a line comment.
+ *
+ * The only thing the editor still needs from the old text-command layer:
+ * CodeMirror's `toggleComment` reads its tokens out of the `languageData` facet
+ * and needs no syntax tree, so this table IS the whole of the comment feature.
+ * Everything else the old module did (line moves, duplicates, deletes, inserts,
+ * indent, occurrences, edit replication) is a CM6 command now.
+ *
+ * The default is `//`, which is right for every C-family grammar. The exceptions
+ * are the ones a wrong token would visibly break — `#` in YAML is a syntax
+ * error, not a comment — and a language that has ONLY block comments gets the
+ * wrapper, because a `//` inserted into CSS comments out nothing and breaks the
+ * rule it was added to.
+ */
+
+/** A line-comment syntax: a prefix per line, or a wrapper for block-only languages. */
+export type CommentSyntax = { line: string } | { block: readonly [string, string] };
+
+const COMMENT_SYNTAX: Record<string, CommentSyntax> = {
+  python: { line: '#' },
+  bash: { line: '#' },
+  yaml: { line: '#' },
+  toml: { line: '#' },
+  ruby: { line: '#' },
+  perl: { line: '#' },
+  r: { line: '#' },
+  makefile: { line: '#' },
+  dockerfile: { line: '#' },
+  ini: { line: '#' },
+  properties: { line: '#' },
+  elixir: { line: '#' },
+  graphql: { line: '#' },
+  nix: { line: '#' },
+  sql: { line: '--' },
+  lua: { line: '--' },
+  haskell: { line: '--' },
+  css: { block: ['/*', '*/'] },
+  scss: { block: ['/*', '*/'] },
+  less: { block: ['/*', '*/'] },
+  sass: { block: ['/*', '*/'] },
+  stylus: { block: ['/*', '*/'] },
+  html: { block: ['<!--', '-->'] },
+  xml: { block: ['<!--', '-->'] },
+  markdown: { block: ['<!--', '-->'] },
+};
+
+export function commentSyntaxFor(language: string): CommentSyntax {
+  return COMMENT_SYNTAX[language] ?? { line: '//' };
+}