opencode-idea 0.0.15 → 0.0.17

package/src/plugin.js

@@ -9,9 +9,9 @@
 //      in IntelliJ IDEA (reusing a running instance), loads the IDE
 //      capabilities immediately, and marks the project as an IDEA project;
 //      `/close-in-idea` clears that mark;
-//   3. registers the `idea-run-config` skill (marked projects only), which
-//      teaches the model how to manage `.run/*.run.xml` run configurations — a
-//      capability the IDE MCP server does not expose.
+//   3. registers the `idea-standalone` skill (marked projects only), which
+//      pins the project's local-run discipline: every app starts from an IDEA
+//      run configuration, and starting or restarting one is the user's call.
 //
 // A project that was never marked is left untouched. Everything is manual:
 // setup does NOT probe or connect the IDE. `/open-in-idea` probes, opens the
@@ -51,8 +51,11 @@ import {
   findIdePort,
   serverConfig,
 } from './mcp/idea.js';
+import { servingRunLifecycleTools } from './mcp/enhance.js';
+import { applyIdeaToolDefaults, hideForcedArguments } from './mcp/idea-tool-defaults.js';
 import { currentProjectPath } from './project.js';
 import {
+  autoLaunchSupported,
   createLaunchGuard,
   openInIde,
   resolveIdeApp,
@@ -116,18 +119,29 @@ const IDEA_TOOL_PREFIX = 'idea_';
  * - Inspection KTS MCP: inspection.kts authoring helpers (PSI tree, API docs,
  *   examples, run). Also IntelliJ Platform plugin-development only.
  * - Python Environment MCP: Python interpreter detection and configuration.
- *   Hidden; project commands run through the IDE terminal instead, which is
- *   already launched with the IDE's real environment.
- * - Database data sources: connections are configured by the user in the IDE,
- *   so the AI only reads and queries them; create/edit stay hidden.
- *
- * NOT hidden: `idea_execute_terminal_command`. Project commands must run with
- * the SDKs the user configured in the IDE (JDK, Node, Python, ...), so the model
- * uses the IDE's integrated terminal for them. `executeInShell: true` runs the
- * command in the user's real shell (`zsh`/`bash`), which inherits the IDE
- * environment — including version managers such as fnm / SDKMAN whose selection
- * lives in shell init and cannot be reconstructed from a handful of variables.
- * Requires Brave Mode in the IDE; without it the IDE asks for confirmation.
+ *   Hidden; a project's interpreter is chosen in the IDE's own settings, and the
+ *   model has no business reconfiguring it.
+ * - Database: the connection tools (`create` / `edit`) stay hidden because the
+ *   user configures data sources in the IDE. The query tools are hidden too —
+ *   the IDE is not this plugin's idea of a database client, and a model that
+ *   wants to inspect a database should be told to use a real one.
+ * - Plain file access: `idea_search_text` / `idea_search_regex` /
+ *   `idea_search_file` / `idea_apply_patch` / `idea_create_new_file` each have a
+ *   native tool that does the job (`grep` / `grep -E` / `glob` / `edit` /
+ *   `write`); routing them through the IDE only adds a hop. `idea_read_file` is
+ *   NOT hidden — it is the only way to read a file inside a jar (`<jar>!/<entry>`)
+ *   or the JDK's `jrt://` image, so the guidance keeps it for exactly that and
+ *   sends ordinary reads to the native tool.
+ * - IDE terminal: `idea_execute_terminal_command` does NOT inherit the project's
+ *   environment. It was exposed on the assumption that it ran with the SDKs the
+ *   user configured in the IDE (JDK, Node, Python, ...), but measured against a
+ *   real IDE it brings no environment a native `shell` call does not already
+ *   have — so it is a strictly worse shell, and hiding it removes an entire
+ *   class of "why is it using an old JDK" confusion. Which tool to use instead
+ *   is a routing decision, and it is made in `ide-guidance.js`: commands that
+ *   need the project's environment go through a RUN CONFIGURATION (the IDE
+ *   launches those with exactly the configured SDK), everything else goes
+ *   through the native shell.
  */
 export const HIDDEN_IDEA_TOOLS = [
   // VCS
@@ -135,6 +149,8 @@ export const HIDDEN_IDEA_TOOLS = [
   'idea_get_repositories',
   // Router
   'idea_execute_tool',
+  // IDE terminal: no advantage over the native shell (see the note above).
+  'idea_execute_terminal_command',
   // Debugger
   'idea_xdebug_control_session',
   'idea_xdebug_evaluate_expression',
@@ -164,10 +180,29 @@ export const HIDDEN_IDEA_TOOLS = [
   // Python Environment MCP
   'idea_configure_python_interpreter',
   'idea_get_python_environment',
-  // Database data sources: the user configures them in the IDE, the AI only
-  // reads and queries them.
+  // Database: connections are the user's, and the IDE is not this plugin's
+  // database client.
   'idea_create_database_connection',
   'idea_edit_database_connection',
+  'idea_list_database_connections',
+  'idea_test_database_connection',
+  'idea_list_database_schemas',
+  'idea_list_schema_object_kinds',
+  'idea_list_schema_objects',
+  'idea_introspect_schema',
+  'idea_get_database_object_description',
+  'idea_execute_sql_query',
+  'idea_fetch_query_result',
+  'idea_preview_table_data',
+  'idea_list_recent_sql_queries',
+  'idea_cancel_sql_query',
+  // Plain file access with a native equivalent (`idea_read_file` stays: only it
+  // can read inside a jar or the jrt:// image).
+  'idea_search_text',
+  'idea_search_regex',
+  'idea_search_file',
+  'idea_apply_patch',
+  'idea_create_new_file',
 ];
 
 /**
@@ -296,7 +331,17 @@ function rewriteToolError(event, message) {
 
 /**
  * @typedef {{
- *   status: 'connected' | 'tools-loading' | 'mcp-unavailable' | 'launch-failed' | 'disabled' | 'closed',
+ *   status:
+ *     | 'connected'
+ *     | 'tools-loading'
+ *     | 'mcp-unavailable'
+ *     | 'launch-failed'
+ *     | 'disabled'
+ *     | 'manual-launch'
+ *     | 'closed',
+ *   // `manual-launch` = this platform has no launcher at all (the user must
+ *   // open the IDE by hand); `disabled` = the user turned launching off. Both
+ *   // mean "no app to open", so only `autoLaunchSupported()` tells them apart.
  *   port?: number,
  *   opened?: boolean,
  *   unavailableNoticeSent?: boolean
@@ -332,6 +377,8 @@ export function ideFeedback(result) {
       return '无法拉起 IntelliJ IDEA(未找到应用或启动失败)。请确认已安装 IDEA,或手动打开后重试 /open-in-idea。';
     case 'disabled':
       return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IntelliJ IDEA,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-idea。';
+    case 'manual-launch':
+      return '当前系统不支持自动打开 IDE(仅 macOS 实现了启动)。请手动打开 IntelliJ IDEA,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后再次执行 /open-in-idea。';
     case 'closed':
       return '已关闭当前项目的 IDEA 接入:已注销 IDE MCP 并清除项目标记。如需重新接入,请再次执行 /open-in-idea。';
     default:
@@ -402,10 +449,19 @@ export default {
    *   tool?: {
    *     list?: () => Promise<ReadonlyArray<{ id?: string }>>,
    *     reload?: () => Promise<void>,
+   *     transform?: (cb: (editor: {
+   *       list: () => ReadonlyArray<{ id?: string, input?: unknown }>,
+   *       get: (id: string) => ({ id?: string, input?: unknown } | undefined),
+   *       add: (definition: unknown) => void,
+   *       update: (id: string, update: (tool: { input?: unknown, description?: string }) => void) => void,
+   *       remove: (id: string) => void,
+   *     }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
    *     hook?: (name: string, cb: (event: {
    *       tool?: string,
    *       sessionID?: string,
+   *       input?: Record<string, unknown>,
    *       status?: string,
+   *       result?: unknown,
    *       error?: unknown,
    *     }) => void | Promise<void>) => Promise<{ dispose: () => Promise<void> | void }>,
    *   },
@@ -451,13 +507,16 @@ export default {
     let sessionRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let toolRegistration;
+    let toolBeforeRegistration;
+    let toolTransformRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let promptRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let commandRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let skillRegistration;
-    let skillsRegistered = false;
+    /** Ids of the skills currently registered, so a sync can tell "unchanged". */
+    let registeredSkillIds = [];
     let disposed = false;
 
     // Latches when a request showed the `idea_*` tools are gone. It is cleared
@@ -516,8 +575,7 @@ export default {
       // The skill lifecycle follows the mark: marking the project registers the
       // IDEA skills, clearing the mark removes them again. Same semantics as the
       // reconnect behavior, so the two can never disagree.
-      if (marked) await ensureSkills();
-      else await removeSkills();
+      await syncSkills();
     };
 
     // Resolve the mark once, so the request hooks can read it synchronously.
@@ -558,7 +616,11 @@ export default {
       // Without this, a session that already captured a snapshot keeps the old
       // tool list until the session is reopened.
       if (typeof ctx.tool?.reload === 'function') await ctx.tool.reload();
-      return waitForIdeaTools();
+      const ready = await waitForIdeaTools();
+      // The catalog decides which of the shipped skills may be offered, so this
+      // is the first moment that question has an answer; see `syncSkills`.
+      await syncSkills();
+      return ready;
     };
 
     const activateIde = async (port) => {
@@ -692,7 +754,11 @@ export default {
           }
           return { status: 'connected', port: serving, unavailableNoticeSent: false };
         }
-        if (!ideApp) return { status: 'disabled' };
+        // No app to open. Either the user turned launching off, or this platform
+        // has no launcher — say which, so the notice is actionable.
+        if (!ideApp) {
+          return { status: autoLaunchSupported() ? 'disabled' : 'manual-launch' };
+        }
         if (guard.exhausted()) {
           await reportUnavailable(false);
           return { status: 'mcp-unavailable', opened: false, unavailableNoticeSent: launchNoticeSent };
@@ -813,41 +879,101 @@ export default {
       }
     };
 
+    /**
+     * The IDEA tools this project's IDE is serving right now.
+     *
+     * Empty is the honest answer for "does the IDE serve X?" before anything has
+     * connected — and it fails that way on error too, because the alternative
+     * (assuming a tool exists) is the one mistake that cannot be walked back
+     * after the model has seen it.
+     *
+     * @returns {Promise<Set<string>>}
+     */
+    const servedIdeaToolNames = async () => {
+      if (typeof ctx.tool?.list !== 'function') return new Set();
+      try {
+        return new Set(toolIds(await ctx.tool.list()));
+      } catch {
+        return new Set();
+      }
+    };
+
+    /** Same ids in the same order — `readSkills()` sorts, so the order is stable. */
+    const isSameSkillSet = (skills, ids) =>
+      skills.length === ids.length && skills.every((skill, index) => skill.id === ids[index]);
+
     // The shipped skills are static knowledge (`skills/<id>/SKILL.md`), e.g. the
-    // run-configuration workflow: where `.run/*.run.xml` live, how to bootstrap a
-    // schema from a real example, and how to verify a write. Registered only for
-    // a project that has been marked as an IDEA project, so unrelated projects
-    // never see an IDEA-specific skill.
+    // standalone-mode discipline (every app starts from an IDEA run
+    // configuration, and starting one is the user's call, so the skill has to be
+    // there to write the project's own rules). They pass two independent gates,
+    // because a skill can be wrong twice over:
+    //
+    //   * the project mark — an unrelated project never sees an IDEA skill;
+    //   * the tools the IDE actually serves — a skill that teaches a call the
+    //     model cannot make is not knowledge, it is a failed call waiting to
+    //     happen. `idea-standalone` drives `idea_rerun_run_configuration`, which
+    //     only the companion plugin `idea-mcp-enhance` serves, so a stock IDE must
+    //     not see it at all. Each skill declares its own dependency in its
+    //     frontmatter (`requires:`), so this stays a data question.
+    //
+    // The catalog is unknown at setup: the mark is read from storage offline,
+    // before anything has connected to the IDE. So this is a reconcile rather
+    // than a one-shot — every catalog refresh re-runs it, and it offers exactly
+    // what is justified right now. Until the IDE has answered, the gated skills
+    // simply do not exist.
     //
     // Deliberately NOT wrapped in a catch: these are core features of the plugin,
     // so a rejected definition must fail loudly. Swallowing it would ship a
     // silently incomplete plugin — which is exactly how 0.0.6 lost
     // `/open-in-idea` without anyone noticing until the command was gone.
-    const ensureSkills = async () => {
-      if (skillsRegistered || typeof ctx.skill?.transform !== 'function') return;
-      skillsRegistered = true;
-      // Read the documents before the transform: callbacks must stay synchronous.
-      const skills = readSkills();
+    const syncSkillsOnce = async () => {
+      if (typeof ctx.skill?.transform !== 'function') return;
+
+      const served = await servedIdeaToolNames();
+      const wanted = (markCache === true ? readSkills() : [])
+        .filter(({ requires }) => requires.every((name) => served.has(name)))
+        .map(({ skill }) => skill);
+      if (isSameSkillSet(wanted, registeredSkillIds)) return;
+
+      // Tear down and register again, the same way the MCP server is
+      // re-registered: a transform that only ever adds would leave a stale skill
+      // behind, and one that only removes could never bring it back.
+      registeredSkillIds = [];
+      const previous = skillRegistration;
+      skillRegistration = undefined;
+      if (previous) {
+        try {
+          await previous.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      if (wanted.length === 0) return;
       skillRegistration = await ctx.skill.transform((editor) => {
-        for (const skill of skills) editor.add(skill);
+        for (const skill of wanted) editor.add(skill);
       });
+      registeredSkillIds = wanted.map((skill) => skill.id);
     };
-    /** Remove the IDEA skills again when the project is unmarked. */
-    const removeSkills = async () => {
-      if (!skillsRegistered || !skillRegistration) return;
-      skillsRegistered = false;
-      const registration = skillRegistration;
-      skillRegistration = undefined;
-      try {
-        await registration.dispose();
-      } catch {
-        // best effort
-      }
+
+    // Serialized like the reconciler, and for the same reason: one call disposes
+    // a registration before it makes the next, so two overlapping calls would
+    // leak one of them. That overlap is easy to reach — `/close-in-idea` can land
+    // while a reconnect is still in flight. With the chain in place, callers may
+    // fire this without awaiting.
+    let skillSyncChain = Promise.resolve();
+    const syncSkills = () => {
+      const run = () => syncSkillsOnce();
+      const next = skillSyncChain.then(run, run);
+      skillSyncChain = next.then(
+        () => {},
+        () => {},
+      );
+      return next;
     };
-    // A project marked in an earlier run gets its skills at setup; a project
-    // marked for the first time gets them when `/open-in-idea` runs (both paths
-    // go through `setMark` / this setup hook).
-    if (markCache === true) await ensureSkills();
+    // A project marked in an earlier run gets its skills as soon as the IDE has
+    // answered; a project marked for the first time gets them when
+    // `/open-in-idea` runs (both paths go through `setMark` / this setup hook).
+    await syncSkills();
 
     // `/open-in-idea`: manual, re-entrant trigger that also loads the IDE
     // capabilities immediately, and marks the project so later messages keep the
@@ -932,11 +1058,25 @@ export default {
         if (markCache === true || serving) {
           appendIdeRecoveryGuidance(event?.system, { marked: markCache === true, serving });
         }
+        // A skill follows its tools in both directions, and this is the one place
+        // that sees the answer change WITHOUT a reconnect: a request that has
+        // lost the enhance tools must not keep the skill that drives them. Fired,
+        // not awaited — the hook is synchronous, and the chain in `syncSkills`
+        // makes that safe. `refreshIdeTools` covers the other direction.
+        //
+        // Skipped when there is nothing it could change, so a project that never
+        // touched the IDE does not pay a catalog read on every request.
+        if (markCache === true || registeredSkillIds.length > 0) void syncSkills();
         if (!injectGuidance) return;
         // Guidance promises tools the model can call, so it only goes out when
         // they are actually in this request.
         if (!serving) return;
-        appendIdeGuidance(event?.system, projectPath);
+        // Same rule for the run-lifecycle tools: they come from the companion
+        // IDEA plugin `idea-mcp-enhance`, so a stock IDE has none of them and
+        // naming them would promise calls that can only fail.
+        appendIdeGuidance(event?.system, projectPath, {
+          runLifecycleTools: servingRunLifecycleTools(tools),
+        });
       });
 
       // 自愈入口(钩子型)。OpenCode 会 await `prompt`,所以在这里修好的连接会在
@@ -971,6 +1111,27 @@ export default {
         if (registrations.length > 0) needsRebuild = false;
       });
 
+      // The IDE's tool-catalog policy, in two halves that must stay in sync:
+      // an argument this plugin always overwrites must not also be advertised,
+      // or the model sets it, reasons about it, and is wrong. The schema half
+      // runs first, so a request never sees a knob that is already decided; see
+      // `mcp/idea-tool-defaults.js` for the measurements and for why this is a
+      // narrow exception to "never touch tool definitions".
+      //
+      // Both halves are deliberately unconditional on the project mark: they are
+      // properties of the tool call, not of whether this project is IDE-connected.
+      if (typeof ctx.tool?.transform === 'function') {
+        toolTransformRegistration = await ctx.tool.transform((editor) => {
+          hideForcedArguments(editor);
+        });
+      }
+      if (typeof ctx.tool?.hook === 'function') {
+        toolBeforeRegistration = await ctx.tool.hook('execute.before', (event) => {
+          if (typeof event?.tool !== 'string') return;
+          applyIdeaToolDefaults(event.tool, event.input);
+        });
+      }
+
       // The only self-initiated action: when an `idea_*` call fails in a way
       // that means the IDE MCP is not usable, run the open flow again. The
       // failure is classified — a plain business error (a bad path, a missing
@@ -983,9 +1144,14 @@ export default {
           if (!(await readMark())) return;
           const kind = classifyIdeaFailure(event.error);
           if (kind === 'none') return;
-          if (kind === 'project' && ideApp) {
-            // The IDE is up; the project simply is not open in it. Ask the IDE
-            // to open the project again, and tell the model to retry.
+          if (kind === 'project') {
+            // The IDE is up and answering; only the PROJECT is missing. That is
+            // never a connection problem, so this must never fall through to
+            // the reconnect below — on a platform with no launcher there is
+            // nothing to call, and falling through would report "reconnected"
+            // and send the model round after round after a call that can only
+            // fail. Leave the IDE's own message, which names the real cause.
+            if (!ideApp) return;
             await openInIde(projectPath, { app: ideApp });
             rewriteToolError(event, '该项目已在 IDEA 中重新打开,请重试刚才的操作。');
             return;
@@ -1013,6 +1179,20 @@ export default {
           // best effort
         }
       }
+      if (toolBeforeRegistration) {
+        try {
+          await toolBeforeRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
+      if (toolTransformRegistration) {
+        try {
+          await toolTransformRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
       if (promptRegistration) {
         try {
           await promptRegistration.dispose();

package/src/skill/loader.js

@@ -21,6 +21,12 @@
 //
 // The frontmatter reader below handles only the flat `key: value` form this
 // package writes. It is not a YAML engine and must not grow into one.
+//
+// One frontmatter key is the loader's own rather than OpenCode's: `requires`, a
+// comma-separated list of the tools the skill is written around. It is read here
+// and deliberately kept OUT of the registered definition — the caller filters on
+// it instead (see `readSkills`), because a skill whose tools are absent must not
+// be registered at all.
 
 import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -67,6 +73,20 @@ export function parseSkillFrontmatter(text, source) {
   return fields;
 }
 
+/**
+ * Split a frontmatter list value: `a, b` -> `['a', 'b']`.
+ *
+ * @param {string | undefined} value
+ * @returns {string[]}
+ */
+function splitList(value) {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '');
+}
+
 /**
  * Load one skill directory into a `Skill.Info`-shaped definition.
  *
@@ -74,6 +94,20 @@ export function parseSkillFrontmatter(text, source) {
  * @returns {{ id: string, name: string, description: string, path: string, content: string }}
  */
 export function readSkill(id) {
+  return readSkillPackage(id).skill;
+}
+
+/**
+ * A skill plus the tools it needs before it is worth offering.
+ *
+ * The two are kept apart on purpose: `skill` must satisfy `Skill.Info` exactly,
+ * while `requires` is this package's own metadata and must NOT be registered —
+ * it is what the caller filters on.
+ *
+ * @param {string} id Directory name, used as the skill id.
+ * @returns {{ skill: { id: string, name: string, description: string, path: string, content: string }, requires: string[] }}
+ */
+export function readSkillPackage(id) {
   const file = new URL(`${id}/${SKILL_FILE_NAME}`, SKILLS_DIR);
   const source = `skills/${id}/${SKILL_FILE_NAME}`;
   const text = readFileSync(file, 'utf8');
@@ -83,23 +117,26 @@ export function readSkill(id) {
     throw new Error(`${source}: frontmatter needs a "description", otherwise the skill is never offered`);
   }
   return {
-    id,
-    name: fields.name || id,
-    description,
-    path: fileURLToPath(file),
-    content: text.replace(FRONTMATTER, '').replace(/^\s+/, '').trimEnd(),
+    skill: {
+      id,
+      name: fields.name || id,
+      description,
+      path: fileURLToPath(file),
+      content: text.replace(FRONTMATTER, '').replace(/^\s+/, '').trimEnd(),
+    },
+    requires: splitList(fields.requires),
   };
 }
 
 /**
- * Every shipped skill, sorted by id.
+ * Every shipped skill, sorted by id, each with the tools it requires.
  *
- * @returns {Array<{ id: string, name: string, description: string, path: string, content: string }>}
+ * @returns {Array<{ skill: { id: string, name: string, description: string, path: string, content: string }, requires: string[] }>}
  */
 export function readSkills() {
   return readdirSync(SKILLS_DIR, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
     .sort()
-    .map((id) => readSkill(id));
+    .map((id) => readSkillPackage(id));
 }

package/src/template.js

@@ -0,0 +1,94 @@
+// The smallest template renderer that makes a prompt document reviewable.
+//
+// WHY NOT A REAL ENGINE (handlebars / ejs / nunjucks / velocity):
+//
+//   * HTML escaping is the default in all of them, and it is WRONG here. This
+//     renders Markdown for a model: `\`code\``, `<jar>!/<entry>` and `j2k<` must
+//     come out byte-for-byte. Configuring that off is possible, but the default
+//     is the trap, and the failure is silent mangling of the text a model reads.
+//   * It would be the package's first runtime dependency. This plugin ships to
+//     npm and is otherwise dependency-free at runtime.
+//   * Each engine brings its own whitespace rules, and whitespace IS structure
+//     here: one blank line separates sections, and a conditional that renders
+//     empty must not leave a gap behind.
+//
+// What is actually needed is tiny: a variable, and if/else. So that is all this
+// does, and the template file stays readable as the document it produces.
+//
+// DIRECTIVES MUST OCCUPY A WHOLE LINE. A directive line emits nothing at all, so
+// "that line is there" and "that line is not there" is the only difference a
+// flag makes — no stray blank line, no half-eaten indentation. A directive that
+// is not alone on its line is a mistake, and this throws rather than guessing.
+
+const DIRECTIVE = /^\{\{\s*(#if\s+([A-Za-z0-9_]+)|else|\/if)\s*\}\}$/;
+// Any control tag anywhere, used to catch a directive that is not alone on its
+// line: that line would otherwise be emitted verbatim, silently changing which
+// text a model reads.
+const CONTROL_TAG = /\{\{\s*(#[^}]*|\/[^}]*|else\s*)\}\}/;
+const VARIABLE = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g;
+
+/**
+ * Render a template against a data record.
+ *
+ * Supported: `{{name}}`, `{{#if name}}…{{/if}}`, `{{#if name}}…{{else}}…{{/if}}`.
+ * Nesting works. Unknown variables render as empty; unknown directives throw,
+ * because a typo in a directive silently changes which text a model sees.
+ *
+ * @param {string} template
+ * @param {Record<string, unknown>} data
+ * @returns {string}
+ */
+export function renderTemplate(template, data) {
+  const out = [];
+  /** @type {Array<{ active: boolean, taken: boolean }>} */
+  const stack = [];
+  const emitting = () => stack.every((frame) => frame.active);
+
+  // A trailing newline in the file is not part of the document.
+  const lines = template.replace(/\n$/, '').split('\n');
+
+  for (const [index, line] of lines.entries()) {
+    const match = DIRECTIVE.exec(line.trim());
+
+    if (!match) {
+      if (CONTROL_TAG.test(line)) {
+        throw new Error(`template line ${index + 1}: a directive must occupy the whole line`);
+      }
+      if (emitting()) out.push(substitute(line, data));
+      continue;
+    }
+
+    const directive = match[1];
+    if (directive.startsWith('#if')) {
+      stack.push({ active: Boolean(data[match[2]]), taken: Boolean(data[match[2]]) });
+      continue;
+    }
+    if (directive === 'else') {
+      if (stack.length === 0) throw new Error(`template line ${index + 1}: {{else}} outside {{#if}}`);
+      const frame = stack[stack.length - 1];
+      // An `{{else}}` after a taken branch stays off: `if/else` is exclusive even
+      // when both sides are truthy.
+      frame.active = !frame.taken;
+      frame.taken = true;
+      continue;
+    }
+    // `{{/if}}`
+    if (stack.length === 0) throw new Error(`template line ${index + 1}: {{/if}} without {{#if}}`);
+    stack.pop();
+  }
+
+  if (stack.length > 0) throw new Error('template: {{#if}} was never closed');
+
+  return out.join('\n');
+}
+
+/**
+ * Replace `{{name}}` with its value. Values are inserted verbatim — see the file
+ * header for why nothing is escaped.
+ */
+function substitute(line, data) {
+  return line.replace(VARIABLE, (_whole, name) => {
+    const value = data[name];
+    return value === undefined || value === null ? '' : String(value);
+  });
+}