@hienlh/ppm 0.20.10 → 0.21.0

package/src/web/lib/lsp/register-providers.ts

@@ -0,0 +1,458 @@
+/**
+ * Monaco's language providers, answered by a real language server.
+ *
+ * Monaco's provider interfaces and LSP's requests were designed from the same
+ * model, so each function here is mostly a position conversion, one request,
+ * and a shape conversion back. The interesting decisions:
+ *
+ * - **Registered once per Monaco language, not per editor.** Monaco calls every
+ *   registered provider and merges the results, so registering on each mount
+ *   would ask the server the same question once per open tab and show every
+ *   suggestion N times.
+ * - **A provider never throws.** Monaco treats a rejected provider promise as a
+ *   broken language and can stop asking. A server that is missing, still
+ *   starting, or slow has to look like "no result", so every provider swallows
+ *   its failure and returns empty.
+ * - **The language is decided by the model, not the registration.** A model with
+ *   no registered document (an untitled buffer, a diff pane) gets nothing.
+ */
+import type * as MonacoType from "monaco-editor";
+import { lspDocumentFor, type LspDocument } from "./lsp-documents";
+import {
+  abortSignalFor,
+  fromLspRange,
+  highlightKind,
+  toLspPosition,
+  toLspRange,
+  toMarkdown,
+  type LspMarkup,
+  type LspRange,
+  type LspTextEdit,
+} from "./lsp-monaco";
+import {
+  toMonacoCompletion,
+  toMonacoSymbols,
+  toMonacoWorkspaceEdit,
+  toResolvableLocations,
+  type LspCompletionItem,
+  type LspDocumentSymbol,
+  type LspLocation,
+  type LspLocationLink,
+  type LspWorkspaceEdit,
+  type ResolvableItem,
+} from "./lsp-responses";
+
+/** Monaco language ids that a language server may serve. */
+const REGISTERED_LANGUAGES = [
+  "typescript", "javascript", "python", "html", "css", "scss", "less",
+  "json", "yaml", "shell", "go", "rust", "cpp", "c", "php", "ruby", "lua",
+];
+
+/** Registered languages, so a second editor does not double every suggestion. */
+const registered = new Set<string>();
+let executeCommandId: string | null = null;
+
+/**
+ * Ask the server, or give up quietly.
+ *
+ * `null` means "no answer" for every caller here, which is what a provider
+ * turns into an empty result. The alternative — letting the rejection through —
+ * makes Monaco log an error per keystroke and can make it stop asking.
+ *
+ * `token` is Monaco's, and passing it is not a nicety. A language server answers one request
+ * at a time, so a superseded completion does not stop costing anything — it sits in front of
+ * the one the user is waiting for. Monaco cancels the moment the next keystroke arrives; what
+ * that has to reach is `$/cancelRequest`, at the far end of the bridge.
+ */
+async function ask<T>(
+  document: LspDocument,
+  method: string,
+  params: unknown,
+  token?: MonacoType.CancellationToken,
+): Promise<T | null> {
+  try {
+    return await document.connection.request<T>(document.path, method, params, { signal: abortSignalFor(token) });
+  } catch {
+    return null;
+  }
+}
+
+/** True when the server said it can answer this. */
+function supports(document: LspDocument, capability: string): boolean {
+  const status = document.connection.statusOf(document.path);
+  if (status?.state !== "ready") return false;
+  return Boolean(status.capabilities[capability]);
+}
+
+/**
+ * The characters *this* server asked to be woken on.
+ *
+ * Monaco reads `triggerCharacters` once, at registration, and the provider is registered
+ * before any server is known — so the registered set has to be the union of what every server
+ * PPM can start might want. The per-server set can only be applied here.
+ */
+function triggerCharacters(document: LspDocument): string[] {
+  const status = document.connection.statusOf(document.path);
+  if (status?.state !== "ready") return [];
+  const provider = status.capabilities.completionProvider as { triggerCharacters?: unknown } | undefined;
+  const characters = provider?.triggerCharacters;
+  return Array.isArray(characters) ? characters.filter((c): c is string => typeof c === "string") : [];
+}
+
+// ── Registration ───────────────────────────────────────────────────────────
+
+/**
+ * Register every provider, once per Monaco language.
+ *
+ * Safe to call on every editor mount; subsequent calls for a language already
+ * registered do nothing.
+ */
+export function registerLspProviders(monaco: typeof MonacoType): void {
+  if (!executeCommandId) {
+    // Server-side commands (an "organize imports" action that is a command
+    // rather than an edit) need somewhere to be executed. One forwarder covers
+    // all of them.
+    executeCommandId = "ppm.lsp.executeCommand";
+    monaco.editor.registerCommand(executeCommandId, async (_accessor, args: { model?: unknown; command?: string; arguments?: unknown[] }) => {
+      const model = args?.model as MonacoType.editor.ITextModel | undefined;
+      const document = model ? lspDocumentFor(model) : undefined;
+      if (!document || !args?.command) return;
+      await ask(document, "workspace/executeCommand", { command: args.command, arguments: args.arguments ?? [] });
+    });
+  }
+
+  for (const language of REGISTERED_LANGUAGES) {
+    if (registered.has(language)) continue;
+    registered.add(language);
+    registerForLanguage(monaco, language);
+  }
+}
+
+function registerForLanguage(monaco: typeof MonacoType, language: string): void {
+  monaco.languages.registerCompletionItemProvider(language, {
+    // The characters that should open the list without a keystroke. This is a union across
+    // servers, because the provider is registered before any server is known; which of them
+    // this server actually asked for is checked below.
+    triggerCharacters: [".", ":", ">", "<", "\"", "'", "/", "@", "#", "$", "-", " "],
+
+    async provideCompletionItems(model, position, context, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "completionProvider")) return { suggestions: [] };
+
+      // A character this server did not ask for is not a trigger at all, and answering one
+      // anyway is what put the suggest widget on screen at every press of the space bar —
+      // in every string and every comment, for every server, because one server somewhere
+      // wants it. Ctrl+Space still works: that arrives as an invocation, not a character.
+      const byCharacter = context.triggerKind === monaco.languages.CompletionTriggerKind.TriggerCharacter;
+      if (byCharacter && !triggerCharacters(document).includes(context.triggerCharacter ?? "")) {
+        return { suggestions: [] };
+      }
+
+      const result = await ask<{ items?: LspCompletionItem[]; isIncomplete?: boolean } | LspCompletionItem[]>(
+        document,
+        "textDocument/completion",
+        {
+          textDocument: { uri: model.uri.toString() },
+          position: toLspPosition(position),
+          context: {
+            triggerKind: byCharacter ? 2 : 1,
+            triggerCharacter: byCharacter ? context.triggerCharacter : undefined,
+          },
+        },
+        token,
+      );
+      if (!result) return { suggestions: [] };
+
+      const items = Array.isArray(result) ? result : (result.items ?? []);
+      return {
+        suggestions: items.map((item) => toMonacoCompletion(monaco, model, position, item, document)),
+        // An incomplete list must be re-requested as the user keeps typing, or
+        // the suggestions freeze at whatever the first prefix matched.
+        incomplete: Array.isArray(result) ? false : Boolean(result.isIncomplete),
+      };
+    },
+
+    async resolveCompletionItem(item, token) {
+      const original = (item as ResolvableItem).__lsp;
+      // Resolve is where the documentation and the auto-import edit arrive; asking for them
+      // up front would make the whole list slow. The document came with the item, so a
+      // suggestion is always resolved against the server that issued it — and a document
+      // whose editor has closed since answers "not ready", which `ask` turns into no answer.
+      const document = (item as ResolvableItem).__document;
+      if (!original || !document) return item;
+
+      const resolved = await ask<LspCompletionItem>(document, "completionItem/resolve", original, token);
+      if (!resolved) return item;
+
+      return {
+        ...item,
+        detail: resolved.detail ?? item.detail,
+        documentation: toMarkdown(resolved.documentation) ?? item.documentation,
+        additionalTextEdits: resolved.additionalTextEdits?.map((e) => ({
+          range: fromLspRange(e.range),
+          text: e.newText,
+        })) ?? item.additionalTextEdits,
+      };
+    },
+  });
+
+  monaco.languages.registerHoverProvider(language, {
+    async provideHover(model, position, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "hoverProvider")) return null;
+
+      const result = await ask<{ contents?: LspMarkup | LspMarkup[]; range?: LspRange }>(
+        document,
+        "textDocument/hover",
+        { textDocument: { uri: model.uri.toString() }, position: toLspPosition(position) },
+        token,
+      );
+      const markdown = toMarkdown(result?.contents);
+      if (!markdown?.value) return null;
+
+      return {
+        contents: [markdown],
+        range: result?.range ? fromLspRange(result.range) : undefined,
+      };
+    },
+  });
+
+  monaco.languages.registerSignatureHelpProvider(language, {
+    signatureHelpTriggerCharacters: ["(", ","],
+    signatureHelpRetriggerCharacters: [")"],
+
+    async provideSignatureHelp(model, position, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "signatureHelpProvider")) return null;
+
+      const result = await ask<{
+        signatures?: Array<{ label: string; documentation?: LspMarkup; parameters?: Array<{ label: string | [number, number]; documentation?: LspMarkup }> }>;
+        activeSignature?: number;
+        activeParameter?: number;
+      }>(document, "textDocument/signatureHelp", {
+        textDocument: { uri: model.uri.toString() },
+        position: toLspPosition(position),
+      }, token);
+      if (!result?.signatures?.length) return null;
+
+      return {
+        value: {
+          signatures: result.signatures.map((signature) => ({
+            label: signature.label,
+            documentation: toMarkdown(signature.documentation),
+            parameters: (signature.parameters ?? []).map((parameter) => ({
+              label: parameter.label,
+              documentation: toMarkdown(parameter.documentation),
+            })),
+          })),
+          activeSignature: result.activeSignature ?? 0,
+          activeParameter: result.activeParameter ?? 0,
+        },
+        dispose: () => {},
+      };
+    },
+  });
+
+  const locationProvider = (method: string, capability: string) =>
+    async (model: MonacoType.editor.ITextModel, position: MonacoType.Position, token: MonacoType.CancellationToken) => {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, capability)) return [];
+      const result = await ask<LspLocation | LspLocation[] | LspLocationLink[]>(document, method, {
+        textDocument: { uri: model.uri.toString() },
+        position: toLspPosition(position),
+      }, token);
+      return toResolvableLocations(monaco, document, result);
+    };
+
+  monaco.languages.registerDefinitionProvider(language, {
+    provideDefinition: locationProvider("textDocument/definition", "definitionProvider"),
+  });
+  monaco.languages.registerTypeDefinitionProvider(language, {
+    provideTypeDefinition: locationProvider("textDocument/typeDefinition", "typeDefinitionProvider"),
+  });
+  monaco.languages.registerImplementationProvider(language, {
+    provideImplementation: locationProvider("textDocument/implementation", "implementationProvider"),
+  });
+
+  monaco.languages.registerReferenceProvider(language, {
+    async provideReferences(model, position, context, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "referencesProvider")) return [];
+      const result = await ask<LspLocation[]>(document, "textDocument/references", {
+        textDocument: { uri: model.uri.toString() },
+        position: toLspPosition(position),
+        context: { includeDeclaration: context.includeDeclaration },
+      }, token);
+      return toResolvableLocations(monaco, document, result);
+    },
+  });
+
+  monaco.languages.registerDocumentHighlightProvider(language, {
+    async provideDocumentHighlights(model, position, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "documentHighlightProvider")) return [];
+      const result = await ask<Array<{ range: LspRange; kind?: number }>>(document, "textDocument/documentHighlight", {
+        textDocument: { uri: model.uri.toString() },
+        position: toLspPosition(position),
+      }, token);
+      return (result ?? []).map((highlight) => ({
+        range: fromLspRange(highlight.range),
+        kind: highlightKind(monaco, highlight.kind),
+      }));
+    },
+  });
+
+  monaco.languages.registerDocumentSymbolProvider(language, {
+    async provideDocumentSymbols(model, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "documentSymbolProvider")) return [];
+      const result = await ask<LspDocumentSymbol[]>(document, "textDocument/documentSymbol", {
+        textDocument: { uri: model.uri.toString() },
+      }, token);
+      return toMonacoSymbols(monaco, result ?? []);
+    },
+  });
+
+  monaco.languages.registerRenameProvider(language, {
+    async provideRenameEdits(model, position, newName, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "renameProvider")) {
+        return { edits: [], rejectReason: "This language server cannot rename." };
+      }
+      const result = await ask<LspWorkspaceEdit>(document, "textDocument/rename", {
+        textDocument: { uri: model.uri.toString() },
+        position: toLspPosition(position),
+        newName,
+      }, token);
+      if (!result) return { edits: [], rejectReason: "The language server could not rename this." };
+      return toMonacoWorkspaceEdit(monaco, result);
+    },
+
+    async resolveRenameLocation(model, position, token) {
+      const document = lspDocumentFor(model);
+      if (!document) return { range: emptyRangeAt(position), text: "" };
+
+      // Without prepareRename a rename on a keyword or a string literal is
+      // accepted and then silently does nothing.
+      const prepare = await ask<{ range?: LspRange; placeholder?: string } | LspRange>(
+        document,
+        "textDocument/prepareRename",
+        { textDocument: { uri: model.uri.toString() }, position: toLspPosition(position) },
+        token,
+      );
+      if (!prepare) {
+        const word = model.getWordAtPosition(position);
+        if (!word) return { range: emptyRangeAt(position), text: "", rejectReason: "There is nothing here to rename." };
+        return {
+          range: {
+            startLineNumber: position.lineNumber, startColumn: word.startColumn,
+            endLineNumber: position.lineNumber, endColumn: word.endColumn,
+          },
+          text: word.word,
+        };
+      }
+      const range = "range" in prepare && prepare.range ? prepare.range : (prepare as LspRange);
+      const monacoRange = fromLspRange(range);
+      return {
+        range: monacoRange,
+        text: ("placeholder" in prepare && prepare.placeholder) || model.getValueInRange(monacoRange),
+      };
+    },
+  });
+
+  monaco.languages.registerDocumentFormattingEditProvider(language, {
+    async provideDocumentFormattingEdits(model, options, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "documentFormattingProvider")) return [];
+      const result = await ask<LspTextEdit[]>(document, "textDocument/formatting", {
+        textDocument: { uri: model.uri.toString() },
+        options: { tabSize: options.tabSize, insertSpaces: options.insertSpaces },
+      }, token);
+      // Monaco applies a returned edit set as one transaction, so the order it
+      // is given in does not matter here the way it does for a manual apply.
+      return (result ?? []).map((edit) => ({ range: fromLspRange(edit.range), text: edit.newText }));
+    },
+  });
+
+  monaco.languages.registerDocumentRangeFormattingEditProvider(language, {
+    async provideDocumentRangeFormattingEdits(model, range, options, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "documentRangeFormattingProvider")) return [];
+      const result = await ask<LspTextEdit[]>(document, "textDocument/rangeFormatting", {
+        textDocument: { uri: model.uri.toString() },
+        range: toLspRange(range),
+        options: { tabSize: options.tabSize, insertSpaces: options.insertSpaces },
+      }, token);
+      return (result ?? []).map((edit) => ({ range: fromLspRange(edit.range), text: edit.newText }));
+    },
+  });
+
+  monaco.languages.registerCodeActionProvider(language, {
+    async provideCodeActions(model, range, context, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "codeActionProvider")) return { actions: [], dispose: () => {} };
+
+      const result = await ask<Array<{
+        title: string;
+        kind?: string;
+        isPreferred?: boolean;
+        edit?: LspWorkspaceEdit;
+        command?: { title: string; command: string; arguments?: unknown[] } | string;
+      }>>(document, "textDocument/codeAction", {
+        textDocument: { uri: model.uri.toString() },
+        range: toLspRange(range),
+        context: {
+          diagnostics: [],
+          only: context.only ? [context.only] : undefined,
+        },
+      }, token);
+
+      const actions: MonacoType.languages.CodeAction[] = (result ?? []).map((action) => {
+        const command = typeof action.command === "object" ? action.command : undefined;
+        return {
+          title: action.title,
+          kind: action.kind,
+          isPreferred: action.isPreferred,
+          edit: action.edit ? toMonacoWorkspaceEdit(monaco, action.edit) : undefined,
+          // A command-only action does its work on the server, so it is
+          // forwarded rather than turned into an edit.
+          command: command && executeCommandId
+            ? { id: executeCommandId, title: command.title, arguments: [{ model, command: command.command, arguments: command.arguments }] }
+            : undefined,
+        };
+      });
+
+      return { actions, dispose: () => {} };
+    },
+  });
+
+  monaco.languages.registerInlayHintsProvider(language, {
+    async provideInlayHints(model, range, token) {
+      const document = lspDocumentFor(model);
+      if (!document || !supports(document, "inlayHintProvider")) return { hints: [], dispose: () => {} };
+      const result = await ask<Array<{ position: { line: number; character: number }; label: string | Array<{ value: string }>; kind?: number; paddingLeft?: boolean; paddingRight?: boolean }>>(
+        document,
+        "textDocument/inlayHint",
+        { textDocument: { uri: model.uri.toString() }, range: toLspRange(range) },
+        token,
+      );
+      return {
+        hints: (result ?? []).map((hint) => ({
+          position: { lineNumber: hint.position.line + 1, column: hint.position.character + 1 },
+          label: typeof hint.label === "string" ? hint.label : hint.label.map((part) => part.value).join(""),
+          kind: hint.kind === 1 ? monaco.languages.InlayHintKind.Type : monaco.languages.InlayHintKind.Parameter,
+          paddingLeft: hint.paddingLeft,
+          paddingRight: hint.paddingRight,
+        })),
+        dispose: () => {},
+      };
+    },
+  });
+}
+
+function emptyRangeAt(position: MonacoType.IPosition): MonacoType.IRange {
+  return {
+    startLineNumber: position.lineNumber, startColumn: position.column,
+    endLineNumber: position.lineNumber, endColumn: position.column,
+  };
+}

package/src/web/lib/monaco-diff-language.ts

@@ -0,0 +1,62 @@
+/**
+ * A `diff` language for Monaco, which does not ship one.
+ *
+ * Monaco's 91 basic languages have no `diff` — VS Code's comes from a bundled
+ * extension that standalone Monaco does not include. The consequence is quiet
+ * in exactly the way an unmapped semantic token is: a ```diff fenced block in a
+ * hover still renders, still runs through the tokenizer, and every line comes
+ * back as `mtk1` — the theme's default foreground. So the blame hover's diff
+ * looked like plain text where VS Code shows red and green.
+ *
+ * Registered from the editor rather than at module load, because it is only
+ * needed once a Monaco instance exists, and `registerDiffLanguage` is called
+ * from every editor mount.
+ *
+ * The colours live in `src/web/theme/diff-token-rules.ts`: a tokenizer without
+ * matching theme rules would be the same silent no-op again.
+ */
+import type * as MonacoType from "monaco-editor";
+
+export const DIFF_LANGUAGE_ID = "diff";
+
+let registered = false;
+
+export function registerDiffLanguage(monaco: typeof MonacoType): void {
+  if (registered) return;
+  // Monaco may already know it if a future version adds one; registering twice
+  // would stack tokenizers.
+  if (monaco.languages.getLanguages().some((l) => l.id === DIFF_LANGUAGE_ID)) {
+    registered = true;
+    return;
+  }
+
+  monaco.languages.register({ id: DIFF_LANGUAGE_ID, aliases: ["Diff", "patch"], extensions: [".diff", ".patch"] });
+  monaco.languages.setMonarchTokensProvider(DIFF_LANGUAGE_ID, {
+    // Line-oriented, so every rule is anchored and consumes the whole line.
+    // Order matters: `+++`/`---` are file headers and must be matched before
+    // the single-character `+`/`-` insert and delete rules, or a header would
+    // colour as an added line.
+    tokenizer: {
+      root: [
+        [/^diff .*$/, "meta.diff.header"],
+        [/^(index|similarity index|rename from|rename to|new file mode|deleted file mode|old mode|new mode) .*$/, "meta.diff.header"],
+        [/^(\+\+\+|---) .*$/, "meta.diff.header"],
+        [/^@@.*$/, "meta.diff.range"],
+        [/^\+.*$/, "inserted"],
+        [/^-.*$/, "deleted"],
+        // `` is metadata about the patch, not a
+        // comment and not content — the same class as the file headers. Calling
+        // it `comment` would have leant on a rule inherited from the base theme
+        // instead of one this feature actually declares.
+        [/^\\ .*$/, "meta.diff.header"],
+        [/^.*$/, ""],
+      ],
+    },
+  });
+  registered = true;
+}
+
+/** Test seam. */
+export function _resetDiffLanguage(): void {
+  registered = false;
+}

package/src/web/lib/monaco-dotenv-language.ts

@@ -0,0 +1,134 @@
+/**
+ * A `dotenv` language for Monaco, which does not ship one.
+ *
+ * Monaco has 82 basic languages and none of them is `.env` — VS Code has none
+ * either, it comes from an extension. So an env file opened in PPM was
+ * `plaintext`, and plaintext has exactly one colour: a commented-out line and a
+ * live one looked identical. In a file whose whole purpose is "which of these
+ * settings are on", that is the one distinction the editor has to make.
+ *
+ * Every token name here is one the base `vs`/`vs-dark` themes already colour
+ * (`comment`, `key`, `string`, `variable`, `keyword`, `delimiter`), and the
+ * theme adapter defines every PPM theme with `inherit: true` — so this needs no
+ * palette of its own and cannot drift from the app's themes. That is why there
+ * is no `dotenv-token-rules.ts` beside `diff-token-rules.ts`; the `diff`
+ * tokenizer had to invent `inserted`/`deleted`/`meta.diff.*`, which nothing
+ * inherited. `tests/unit/web/monaco-dotenv-language.test.ts` pins the pairing
+ * against Monaco's own theme table, because a token name with no rule anywhere
+ * is the silent no-op that shipped once already.
+ *
+ * Registered from `beforeMount` rather than `onMount`: the model is created
+ * with its language id before `onMount` runs, and a model created against an
+ * unregistered id is plaintext.
+ */
+import type * as MonacoType from "monaco-editor";
+import { basename } from "@/lib/utils";
+
+export const DOTENV_LANGUAGE_ID = "dotenv";
+
+/**
+ * Whether a path is an env file.
+ *
+ * Covers `.env`, every suffixed variant (`.env.local`, `.env.test.example`) and
+ * the `NAME.env` form.
+ *
+ * direnv's `.envrc` is a shell script and must not match — it does not, because
+ * the prefix test requires the separating dot (`.envrc`[4] is `r`). An explicit
+ * guard for it was dead code, which mutation testing is what found; the test
+ * pins the behaviour instead, so loosening the prefix test fails there.
+ *
+ * Call this *after* an extension lookup, never before: `.env.example.md`
+ * matches the prefix test but is markdown, and the extension map answers first.
+ */
+export function isDotenvFile(filename: string): boolean {
+  // Both separators: a Windows host hands this a path with backslashes, and
+  // splitting on "/" alone leaves the whole path as the basename, so
+  // C:\\src\\.env failed every one of the three tests below.
+  const base = basename(filename);
+  return base === ".env" || base.startsWith(".env.") || base.endsWith(".env");
+}
+
+let registered = false;
+
+export function registerDotenvLanguage(monaco: typeof MonacoType): void {
+  if (registered) return;
+  // A future Monaco version adding one would otherwise get a second tokenizer
+  // stacked on its own.
+  if (monaco.languages.getLanguages().some((l) => l.id === DOTENV_LANGUAGE_ID)) {
+    registered = true;
+    return;
+  }
+
+  monaco.languages.register({
+    id: DOTENV_LANGUAGE_ID,
+    aliases: ["Dotenv", "env"],
+    // Only `.env` itself can be expressed as an extension; the suffixed
+    // variants are matched by `isDotenvFile`, because Monaco's own resolution
+    // is not what picks the language here — the editor passes it explicitly.
+    extensions: [".env"],
+  });
+
+  monaco.languages.setLanguageConfiguration(DOTENV_LANGUAGE_ID, {
+    // What makes `Ctrl+/` comment a line out — the fastest way to answer the
+    // question this language exists for.
+    comments: { lineComment: "#" },
+    autoClosingPairs: [
+      { open: '"', close: '"' },
+      { open: "'", close: "'" },
+      { open: "${", close: "}" },
+    ],
+    surroundingPairs: [
+      { open: '"', close: '"' },
+      { open: "'", close: "'" },
+    ],
+  });
+
+  monaco.languages.setMonarchTokensProvider(DOTENV_LANGUAGE_ID, {
+    // One state, deliberately. The first version used a `@value` state entered
+    // on `=` and popped by a `/$/` rule — and Monarch never runs that rule,
+    // because its per-line loop stops as soon as the position reaches the end
+    // of the line. So the state was never left: from the first assignment on,
+    // *every* line in the file was tokenized as a value, including the
+    // commented-out ones. `#KEY=off` came back as a string — the exact case
+    // this language was written for. A line-oriented grammar has to do
+    // everything in `root`, the way Monaco's own `ini` does.
+    //
+    // The cost is that a quoted value is matched whole rather than piece by
+    // piece, so an interpolation inside quotes keeps the string colour. That is
+    // the trade for `#` inside a quoted value not reading as a comment, which
+    // needs the quotes to be one atomic match.
+    tokenizer: {
+      root: [
+        // The line this language exists for: dimmed, whole, and claimed before
+        // any other rule can take part of it. `#` with no space after it is the
+        // commonest way to switch a setting off, so it must not need one.
+        [/^[ \t]*#.*$/, "comment"],
+        // `export KEY=` and plain `KEY=`. Every character the regex matches is
+        // inside a group, which is what Monarch requires of a rule that emits
+        // more than one token.
+        [/^([ \t]*)(export)([ \t]+)([\w.-]+)([ \t]*)(=)/, ["", "keyword", "", "key", "", "delimiter"]],
+        [/^([ \t]*)([\w.-]+)([ \t]*)(=)/, ["", "key", "", "delimiter"]],
+        // An inline comment needs whitespace in front of it: `KEY=a#b` is the
+        // value `a#b` to every dotenv parser, so a bare `#` cannot end a value.
+        [/[ \t]+#.*$/, "comment"],
+        // Whole-quoted values. Single quotes are literal in dotenv, so an
+        // interpolation inside them is text and must not be coloured as one.
+        [/"(?:[^"\\]|\\.)*"/, "string"],
+        [/'[^']*'/, "string"],
+        [/\$\{[^}]*\}/, "variable"],
+        [/\$[A-Za-z_]\w*/, "variable"],
+        // A bare value, `#` included. An unterminated quote lands here too,
+        // which is why one cannot run away with the rest of the file.
+        [/[^\s$]+/, "string"],
+        [/[ \t]+/, ""],
+        [/./, ""],
+      ],
+    },
+  });
+  registered = true;
+}
+
+/** Test seam. */
+export function _resetDotenvLanguage(): void {
+  registered = false;
+}

package/src/web/lib/sidebar-tabs/tab-registry.ts

@@ -1,6 +1,15 @@
 import {
-  FolderOpen, GitBranch, Database, Search, Puzzle, Bug, Sparkles, BotMessageSquare, Globe, Users,
-} from "lucide-react";
+  FolderOpen,
+  GitBranch,
+  Database,
+  Search,
+  Puzzle,
+  Bug,
+  Sparkles,
+  BotMessageSquare,
+  Globe,
+  Users,
+} from "@/lib/icons";
 import type { SidebarActiveTab } from "@/stores/settings-store";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
 import type { ExtensionContributes } from "../../../types/extension";