@getfamiliar/shared 0.1.15 → 0.1.16

package/build/ChatInput.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parsing of one line a user typed into a chat (cli-chat, web-chat):
+ * a builtin command of the chat client, a direct handler call
+ * (`/topic/sub …`) or a plain message.
+ */
+/**
+ * Result of {@link parseChatInput}.
+ *
+ * A `handler` arm covers both the plain message (no topic — the chat
+ * plugin's own topic applies) and the `/topic/sub/handler …` direct call,
+ * whose path is the handler's topic.
+ */
+export type ParsedChatInput<Builtin extends string = string> = {
+    readonly kind: "handler";
+    readonly topic?: string;
+    readonly prompt: string;
+    /**
+     * Trimmed raw input line, before slash-command parsing. For direct
+     * calls this is what the chat persists as the `role='user'`
+     * chatmessage (`NewEvent.userChatMessage`), so later chat turns see
+     * exactly what the user typed. For plain messages it equals `prompt`.
+     */
+    readonly rawInput: string;
+} | {
+    readonly kind: "builtin";
+    readonly command: Builtin;
+};
+/**
+ * Parse one raw input line.
+ *
+ * Rules:
+ * - A line whose first word is one of `builtins` → builtin.
+ * - `/a/b … rest` (any other `/` path) → handler call with topic `a:b`;
+ *   anything after the first space is the prompt.
+ * - Anything else (and a bare `/`) → plain message, the trimmed line is
+ *   the prompt.
+ *
+ * @param raw The typed line.
+ * @param builtins The chat client's own commands (e.g. `["/exit", "/clear"]`).
+ * @returns The parsed input.
+ */
+export declare function parseChatInput<Builtin extends string>(raw: string, builtins: readonly Builtin[]): ParsedChatInput<Builtin>;

package/build/ChatInput.js

@@ -0,0 +1,45 @@
+/**
+ * Parsing of one line a user typed into a chat (cli-chat, web-chat):
+ * a builtin command of the chat client, a direct handler call
+ * (`/topic/sub …`) or a plain message.
+ */
+/**
+ * Parse one raw input line.
+ *
+ * Rules:
+ * - A line whose first word is one of `builtins` → builtin.
+ * - `/a/b … rest` (any other `/` path) → handler call with topic `a:b`;
+ *   anything after the first space is the prompt.
+ * - Anything else (and a bare `/`) → plain message, the trimmed line is
+ *   the prompt.
+ *
+ * @param raw The typed line.
+ * @param builtins The chat client's own commands (e.g. `["/exit", "/clear"]`).
+ * @returns The parsed input.
+ */
+export function parseChatInput(raw, builtins) {
+    const line = raw.trim();
+    if (!line.startsWith("/")) {
+        return { kind: "handler", prompt: line, rawInput: line };
+    }
+    const spaceIdx = line.indexOf(" ");
+    const commandPart = spaceIdx === -1 ? line : line.slice(0, spaceIdx);
+    const messagePart = spaceIdx === -1 ? "" : line.slice(spaceIdx + 1).trim();
+    if (builtins.includes(commandPart)) {
+        return { kind: "builtin", command: commandPart };
+    }
+    // Empty segments (trailing `/` or `//`) produce no topic words.
+    const segments = commandPart
+        .slice(1)
+        .split("/")
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return { kind: "handler", prompt: line, rawInput: line };
+    }
+    return {
+        kind: "handler",
+        topic: segments.join(":"),
+        prompt: messagePart,
+        rawInput: line,
+    };
+}

package/build/ChatMessage.d.ts

@@ -41,6 +41,17 @@ export interface NewChatMessage {
     readonly role: ChatRole;
     readonly textContent: string;
 }
+/** Largest page {@link ChatHistoryQuery.limit} accepts. */
+export declare const MAX_CHAT_HISTORY_PAGE = 200;
+/** Query for one page of a channel's chat history (`ctx.chat.listMessages`). */
+export interface ChatHistoryQuery {
+    /** Channel id (matched against the parent event's `preferred_chat_channel_id`). */
+    readonly channelId: string;
+    /** Only messages with a smaller id (cursor for paging backwards); omit for the newest page. */
+    readonly beforeId?: string;
+    /** Page size, 1 … {@link MAX_CHAT_HISTORY_PAGE}. */
+    readonly limit: number;
+}
 /** Filter for {@link import("./ChatMessageBus").ChatMessageBus.subscribe}. */
 export interface ChatFilter {
     /**

package/build/ChatMessage.js

@@ -8,4 +8,5 @@
  * keeps the container side channel-blind: the agent's `send_chat` tool
  * only needs to know the originating event id, never the channel.
  */
-export {};
+/** Largest page {@link ChatHistoryQuery.limit} accepts. */
+export const MAX_CHAT_HISTORY_PAGE = 200;

package/build/ChatMessageBus.d.ts

@@ -1,4 +1,4 @@
-import type { ChatFilter, ChatMessage, NewChatMessage } from "./ChatMessage.js";
+import type { ChatFilter, ChatHistoryQuery, ChatMessage, NewChatMessage } from "./ChatMessage.js";
 import type { Logger } from "./logging/Logger.js";
 import type { PostgresConnection } from "./PostgresConnection.js";
 /**
@@ -68,6 +68,16 @@ export declare class ChatMessageBus {
      * thread to attach to).
      */
     fetchHistoryForEvent(eventId: string): Promise<ChatMessage[]>;
+    /**
+     * One page of a channel's chat history: the newest `limit` messages
+     * on `channelId` (joined via `events.preferred_chat_channel_id`)
+     * older than `beforeId`, returned oldest first. Page backwards by
+     * passing the first returned id as the next `beforeId`.
+     *
+     * @param query Channel, optional cursor and page size.
+     * @returns Up to `limit` messages in chronological order.
+     */
+    listByChannel(query: ChatHistoryQuery): Promise<ChatMessage[]>;
     /**
      * Subscribe to chat messages matching `filter`. Returns an
      * unsubscribe function.

package/build/ChatMessageBus.js

@@ -85,6 +85,32 @@ export class ChatMessageBus {
              ORDER BY cm.created_at ASC, cm.id ASC`, [eventId]);
         return result.rows.map(mapRow);
     }
+    /**
+     * One page of a channel's chat history: the newest `limit` messages
+     * on `channelId` (joined via `events.preferred_chat_channel_id`)
+     * older than `beforeId`, returned oldest first. Page backwards by
+     * passing the first returned id as the next `beforeId`.
+     *
+     * @param query Channel, optional cursor and page size.
+     * @returns Up to `limit` messages in chronological order.
+     */
+    async listByChannel(query) {
+        const values = [query.channelId, query.limit];
+        const cursor = query.beforeId === undefined ? "" : "AND cm.id < $3";
+        if (query.beforeId !== undefined) {
+            values.push(query.beforeId);
+        }
+        const result = await this.connection.getPool().query(`SELECT * FROM (
+               SELECT cm.*
+               FROM chatmessages cm
+               JOIN events e ON e.id = cm.event_id
+               WHERE e.preferred_chat_channel_id = $1 ${cursor}
+               ORDER BY cm.id DESC
+               LIMIT $2
+             ) page
+             ORDER BY page.id ASC`, values);
+        return result.rows.map(mapRow);
+    }
     /**
      * Subscribe to chat messages matching `filter`. Returns an
      * unsubscribe function.

package/build/Plugin.d.ts

@@ -2,7 +2,7 @@ import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { CommandDef } from "citty";
 import type { AgentRunRow } from "./AgentRun.js";
 import type { CalendarApi } from "./Calendar.js";
-import type { ChatFilter } from "./ChatMessage.js";
+import type { ChatFilter, ChatHistoryQuery, ChatMessage } from "./ChatMessage.js";
 import type { ChatHandler, ChatUnsubscribe } from "./ChatMessageBus.js";
 import type { ConfigService } from "./Config.js";
 import type { EventFile, EventRow, NewEvent } from "./Event.js";
@@ -10,10 +10,14 @@ import type { Logger } from "./logging/Logger.js";
 import type { MailApi } from "./Mail.js";
 import type { MailStyleTemplate } from "./MailStyleTemplate.js";
 import type { ModelMetaData, ModelProviderDescriptor } from "./ModelMetaData.js";
+import type { ScratchFile } from "./Scratch.js";
 import type { StepResultRow } from "./StepResult.js";
 import type { StorageApi } from "./Storage.js";
 import type { ToolLevel } from "./ToolLevel.js";
 import type { ToolRunContext } from "./ToolRunner.js";
+import type { WebApi, WebUi } from "./WebAuth.js";
+import type { WebMenuContribution } from "./WebMenu.js";
+import type { WebPluginUi } from "./WebPlugin.js";
 import type { WorkspaceWatcherApi } from "./WorkspaceFile.js";
 export type { ChatHandler, Client as McpClient };
 /**
@@ -234,6 +238,25 @@ export interface HostContext {
          * can deadlock the input-event watcher's claim.
          */
         appendAssistantMessage(eventId: string, text: string): Promise<void>;
+        /**
+         * Insert a chatmessage of either role attached to `eventId`, for
+         * recording a conversation that happened outside the agent — e.g.
+         * the transcript of a voice call. Channel is resolved via the
+         * event's `preferred_chat_channel_id`. The same rule as for
+         * {@link appendAssistantMessage} applies: only for events that
+         * are already settled — typically a record-only event emitted
+         * with `state: "done"`, which no handler ever runs for.
+         */
+        appendMessage(eventId: string, role: "user" | "assistant", text: string): Promise<void>;
+        /**
+         * Read one page of a channel's history (both roles), oldest first:
+         * the newest `limit` messages before `beforeId`. For chat UIs that
+         * show scrollback; the same per-channel history the model sees for
+         * that channel's chat events.
+         *
+         * @throws {Error} When `limit` is outside 1 … `MAX_CHAT_HISTORY_PAGE`.
+         */
+        listMessages(query: ChatHistoryQuery): Promise<readonly ChatMessage[]>;
     };
     /**
      * Per-event scratch directory operations. Each event the bus
@@ -262,6 +285,23 @@ export interface HostContext {
          * caller is responsible for unique names.
          */
         addFiles(eventId: string, files: readonly EventFile[]): Promise<readonly string[]>;
+        /**
+         * The regular files directly in `/scratch/<eventId>/` (no
+         * subdirectories), hidden ones included — filter them with
+         * `isHiddenScratchFile` before showing files to users. Sorted
+         * by name; empty when the folder does not exist.
+         *
+         * @throws {Error} When `eventId` is not a numeric event id.
+         */
+        listFiles(eventId: string): Promise<readonly ScratchFile[]>;
+        /**
+         * Host path of `/scratch/<eventId>/<name>`, for reading or
+         * streaming the file. The file may not exist.
+         *
+         * @throws {Error} When `eventId` is not a numeric event id or
+         *   `name` is not a plain basename (same rules as `addFiles`).
+         */
+        resolveFile(eventId: string, name: string): string;
     };
     /**
      * The pino-style {@link Logger} for the plugin. Use `.info` for the
@@ -271,6 +311,14 @@ export interface HostContext {
      * plugin doing anything.
      */
     readonly logger: Logger;
+    /**
+     * Whether the daemon runs in dev mode (`FAMILIAR_DEV=1`, set by the
+     * monorepo's `npm run dev` launcher). Lets plugins enable developer
+     * conveniences such as the web UI's hot module reloading.
+     */
+    readonly isDevMode: boolean;
+    /** Version of the running familiar host (the `@getfamiliar/host` package version, e.g. `0.4.2`). */
+    readonly familiarVersion: string;
     /**
      * Absolute host path of the project's `data/` directory.
      *
@@ -399,6 +447,14 @@ export interface HostContext {
      * which maps the user's configured mounts onto providers.
      */
     readonly storage: StorageApi;
+    /**
+     * Core webserver hooks. A plugin that fronts the webserver with its
+     * own reverse proxy registers it during **`prepare()`** via
+     * `ctx.web.registerTrustedProxy({ secret, userHeader })`, the same
+     * contract a user-configured `webserver.auth.trustedProxies` entry
+     * follows (see {@link WebApi}).
+     */
+    readonly web: WebApi;
     /**
      * Read the per-mailbox style template the user (or the
      * extract-style handler) wrote at `data/mail/templates/<mailbox>/<name>.json`.
@@ -694,6 +750,52 @@ export interface PluginHostManifest {
      * call.
      */
     tools?(ctx: HostContext): readonly PluginTool[];
+    /**
+     * Provide the web UI: return its root controller, a Hono app mounted
+     * at `/` of the core webserver, and optionally a renderer for the
+     * login-flow pages ({@link WebUi.renderAuthPage}). Called after `start()` resolves (at
+     * boot and after every restart), so closures over `start`-time state
+     * (e.g. a dev server) are safe; a restart swaps the controller
+     * without rebinding the socket.
+     *
+     * Authentication stays in the core: every request reaching the
+     * controller passed the auth middleware, `c.get("principal")` is the
+     * signed-in user. The core routes `/login`, `/login/:token` and
+     * `/logout` take precedence over the controller's routes; the core
+     * decides what they do and only lets the UI render their markup.
+     *
+     * When several plugins provide a UI, `webserver.uiPlugin` picks one;
+     * without any, the webserver serves a plain page asking to install
+     * one (e.g. `@getfamiliar/plugin-web-ui`).
+     *
+     * Synchronous, side-effect-free: just build and return the app.
+     */
+    webUi?(ctx: HostContext): WebUi;
+    /**
+     * Contribute items to the web UI's sidebar menu: direct links or
+     * collapsible groups with sub-entries (icon, label, routes), plus a
+     * weight positioning this plugin's items among the others. Called
+     * after `start()` (at boot and after every restart); a disabled
+     * plugin contributes nothing. The core validates the items (lucide
+     * icon id, non-empty labels, routes starting with `/`) and disables
+     * the plugin in phase `webMenu` when they are malformed.
+     *
+     * Synchronous, side-effect-free: derive the items from constants and
+     * `ctx.config`.
+     */
+    webMenu?(ctx: HostContext): WebMenuContribution;
+    /**
+     * Serve HTTP routes and, optionally, a page in the web UI: return a
+     * controller (mounted at `/plugins/<plugin-id>/` behind the core
+     * authentication, concrete routes only, no catch-all) and an optional
+     * page module the web UI loads for browser routes under
+     * `/plugins/<plugin-id>` (see {@link WebPluginUi}). Called after
+     * `start()` (at boot and after every restart); a throw disables the
+     * plugin in phase `webPlugin`.
+     *
+     * Synchronous, side-effect-free: just build and return.
+     */
+    webPlugin?(ctx: HostContext): WebPluginUi;
     /**
      * Supply {@link ModelMetaData} for a model the default (models.dev)
      * database does not cover. The host calls this on every plugin that

package/build/PromptTemplate.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Maximum nesting of template sources (includes and template-valued
+ * placeholders like `HANDLER_CONTENT`) below the top-level template.
+ */
+export declare const MAX_TEMPLATE_DEPTH = 3;
+/** One node of a parsed template. */
+export type TemplateNode = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "placeholder";
+    readonly name: string;
+} | {
+    readonly type: "include";
+    readonly path: string;
+    readonly children: readonly TemplateNode[];
+} | {
+    readonly type: "source";
+    readonly name: string;
+    readonly children: readonly TemplateNode[];
+};
+/** A placeholder reference found while parsing, with its position relative to the marker. */
+export interface PlaceholderUse {
+    readonly name: string;
+    /** `true` when the reference ends up in the system prompt (before `{CACHE_MARKER}`). */
+    readonly isBeforeMarker: boolean;
+}
+/** Result of {@link parseTemplate}. */
+export interface ParsedTemplate {
+    /** Nodes rendered into the system prompt. */
+    readonly systemNodes: readonly TemplateNode[];
+    /** Nodes rendered into the head of the current user message. */
+    readonly userHeadNodes: readonly TemplateNode[];
+    /** Every placeholder reference, in template order (duplicates kept). */
+    readonly uses: readonly PlaceholderUse[];
+    /** Workspace files pulled in via `{path.md}`, in template order. */
+    readonly includes: readonly string[];
+    /** Problems found while parsing, phrased for a log line. */
+    readonly warnings: readonly string[];
+}
+/** Inputs to {@link parseTemplate}. */
+export interface ParseTemplateOptions {
+    /** Human-readable name of the template, used in warnings (e.g. `PROMPT.md`). */
+    readonly templateName: string;
+    /**
+     * Read a workspace-relative include. Returns the (already truncated)
+     * text, or `null` when the file does not exist.
+     */
+    readonly readInclude: (relativePath: string) => string | null;
+    /**
+     * Placeholders whose value is itself template text (workspace
+     * markdown, e.g. `HANDLER_CONTENT`). They are expanded like includes
+     * but not redacted.
+     */
+    readonly templateSources: Readonly<Record<string, string>>;
+}
+/** Rendered output of {@link renderTemplate}. */
+export interface RenderedTemplate {
+    readonly system: string;
+    readonly userHead: string;
+}
+/**
+ * Parse a prompt template into nodes, expanding workspace includes and
+ * template-valued placeholders recursively.
+ *
+ * Only workspace markdown is template: the top-level template, files it
+ * includes, and {@link ParseTemplateOptions.templateSources}. Values
+ * produced by code or plugins are inserted later by
+ * {@link renderTemplate} and never scanned for tokens, so text from an
+ * event (a mail containing `{SOUL.md}`) cannot pull files into the
+ * prompt.
+ *
+ * The first `{CACHE_MARKER}` in the top-level template splits system
+ * prompt from user-message head. A marker anywhere else (an include, the
+ * handler body, a second one) is dropped with a warning.
+ *
+ * Problems never throw: an invalid include path, a missing include, a
+ * cycle or excessive nesting leave a warning and keep the token
+ * verbatim (or empty, for a missing file) so the run still proceeds.
+ *
+ * @param source The top-level template text.
+ * @param options Include reader, template sources and naming.
+ * @returns The parsed template.
+ */
+export declare function parseTemplate(source: string, options: ParseTemplateOptions): ParsedTemplate;
+/**
+ * Render a parsed template with resolved placeholder values. A
+ * placeholder without a value stays as its literal `{NAME}` token.
+ *
+ * @param parsed The parsed template.
+ * @param values Resolved value per placeholder name.
+ * @param shouldRedactIncludes When `true`, each `{path.md}` include is
+ *   rendered as `<content of file path>` instead of its body — used for
+ *   the audit-log copy under `core.logSystemPrompt: non-static`.
+ * @returns System prompt and user-message head, each trimmed.
+ */
+export declare function renderTemplate(parsed: ParsedTemplate, values: ReadonlyMap<string, string>, shouldRedactIncludes?: boolean): RenderedTemplate;
+/**
+ * Whether an include path stays inside the workspace: relative, no
+ * `..` segment, no empty segment.
+ *
+ * @param includePath The path inside the braces.
+ * @returns `true` when the path is acceptable.
+ */
+export declare function isSafeIncludePath(includePath: string): boolean;

package/build/PromptTemplate.js

@@ -0,0 +1,194 @@
+import { CACHE_MARKER_PLACEHOLDER } from "./PromptPlaceholders.js";
+/**
+ * Matches one template token: `{NAME}` (upper-case placeholder) or
+ * `{path.md}` (workspace include). Anything else in braces — JSON
+ * examples, `{lowercase}` prose — is left untouched.
+ */
+const TOKEN_PATTERN = /\{([A-Z][A-Z0-9_]*|[\w./-]+\.md)\}/g;
+/**
+ * Maximum nesting of template sources (includes and template-valued
+ * placeholders like `HANDLER_CONTENT`) below the top-level template.
+ */
+export const MAX_TEMPLATE_DEPTH = 3;
+/**
+ * Parse a prompt template into nodes, expanding workspace includes and
+ * template-valued placeholders recursively.
+ *
+ * Only workspace markdown is template: the top-level template, files it
+ * includes, and {@link ParseTemplateOptions.templateSources}. Values
+ * produced by code or plugins are inserted later by
+ * {@link renderTemplate} and never scanned for tokens, so text from an
+ * event (a mail containing `{SOUL.md}`) cannot pull files into the
+ * prompt.
+ *
+ * The first `{CACHE_MARKER}` in the top-level template splits system
+ * prompt from user-message head. A marker anywhere else (an include, the
+ * handler body, a second one) is dropped with a warning.
+ *
+ * Problems never throw: an invalid include path, a missing include, a
+ * cycle or excessive nesting leave a warning and keep the token
+ * verbatim (or empty, for a missing file) so the run still proceeds.
+ *
+ * @param source The top-level template text.
+ * @param options Include reader, template sources and naming.
+ * @returns The parsed template.
+ */
+export function parseTemplate(source, options) {
+    const state = {
+        options,
+        uses: [],
+        includes: [],
+        warnings: [],
+        isMarkerSeen: false,
+        systemNodes: [],
+        userHeadNodes: [],
+    };
+    parseInto(source, 0, [options.templateName], state, true);
+    return {
+        systemNodes: state.systemNodes,
+        userHeadNodes: state.userHeadNodes,
+        uses: state.uses,
+        includes: state.includes,
+        warnings: state.warnings,
+    };
+}
+/**
+ * Render a parsed template with resolved placeholder values. A
+ * placeholder without a value stays as its literal `{NAME}` token.
+ *
+ * @param parsed The parsed template.
+ * @param values Resolved value per placeholder name.
+ * @param shouldRedactIncludes When `true`, each `{path.md}` include is
+ *   rendered as `<content of file path>` instead of its body — used for
+ *   the audit-log copy under `core.logSystemPrompt: non-static`.
+ * @returns System prompt and user-message head, each trimmed.
+ */
+export function renderTemplate(parsed, values, shouldRedactIncludes = false) {
+    return {
+        system: renderNodes(parsed.systemNodes, values, shouldRedactIncludes).trim(),
+        userHead: renderNodes(parsed.userHeadNodes, values, shouldRedactIncludes).trim(),
+    };
+}
+/**
+ * Parse `source` and append its nodes to the active top-level list (or
+ * to `into`, for nested sources).
+ *
+ * @param source Text to parse.
+ * @param depth Nesting depth; 0 is the top-level template.
+ * @param chain Names of the sources currently being expanded, for cycle
+ *   detection and warning context.
+ * @param state Shared parse state.
+ * @param isTopLevel Whether nodes go to the top-level lists (`true`) or
+ *   are returned for a nested node.
+ * @returns The nodes parsed from a nested source (empty at top level).
+ */
+function parseInto(source, depth, chain, state, isTopLevel) {
+    const nested = [];
+    const push = (node) => {
+        if (!isTopLevel) {
+            nested.push(node);
+            return;
+        }
+        (state.isMarkerSeen ? state.userHeadNodes : state.systemNodes).push(node);
+    };
+    const where = chain[chain.length - 1];
+    let cursor = 0;
+    for (const match of source.matchAll(TOKEN_PATTERN)) {
+        const index = match.index ?? 0;
+        if (index > cursor) {
+            push({ type: "text", text: source.slice(cursor, index) });
+        }
+        cursor = index + match[0].length;
+        const token = match[1] ?? "";
+        if (token === CACHE_MARKER_PLACEHOLDER) {
+            if (depth === 0 && !state.isMarkerSeen) {
+                state.isMarkerSeen = true;
+                continue;
+            }
+            state.warnings.push(depth === 0
+                ? `${where}: second {${CACHE_MARKER_PLACEHOLDER}} ignored — only the first one splits the prompt`
+                : `${where}: {${CACHE_MARKER_PLACEHOLDER}} ignored — it only works in the top-level template`);
+            continue;
+        }
+        if (token.endsWith(".md")) {
+            push(parseInclude(token, match[0], depth, chain, state));
+            continue;
+        }
+        const templateSource = state.options.templateSources[token];
+        if (templateSource !== undefined) {
+            if (depth >= MAX_TEMPLATE_DEPTH || chain.includes(`{${token}}`)) {
+                state.warnings.push(`${where}: {${token}} not expanded — nested too deep or recursive (${chain.join(" → ")})`);
+                push({ type: "text", text: match[0] });
+                continue;
+            }
+            const children = parseInto(templateSource, depth + 1, [...chain, `{${token}}`], state, false);
+            push({ type: "source", name: token, children });
+            continue;
+        }
+        state.uses.push({ name: token, isBeforeMarker: !state.isMarkerSeen });
+        push({ type: "placeholder", name: token });
+    }
+    if (cursor < source.length) {
+        push({ type: "text", text: source.slice(cursor) });
+    }
+    return nested;
+}
+/**
+ * Build the node for one `{path.md}` token, reading and recursively
+ * parsing the file.
+ */
+function parseInclude(includePath, literal, depth, chain, state) {
+    const where = chain[chain.length - 1];
+    if (!isSafeIncludePath(includePath)) {
+        state.warnings.push(`${where}: include {${includePath}} rejected — use a workspace-relative path without ".."`);
+        return { type: "text", text: literal };
+    }
+    if (depth >= MAX_TEMPLATE_DEPTH || chain.includes(includePath)) {
+        state.warnings.push(`${where}: include {${includePath}} not expanded — nested too deep or recursive (${[...chain, includePath].join(" → ")})`);
+        return { type: "text", text: literal };
+    }
+    const body = state.options.readInclude(includePath);
+    if (body === null) {
+        state.warnings.push(`${where}: include {${includePath}} not found in the workspace`);
+        return { type: "include", path: includePath, children: [] };
+    }
+    state.includes.push(includePath);
+    const children = parseInto(body, depth + 1, [...chain, includePath], state, false);
+    return { type: "include", path: includePath, children };
+}
+/**
+ * Whether an include path stays inside the workspace: relative, no
+ * `..` segment, no empty segment.
+ *
+ * @param includePath The path inside the braces.
+ * @returns `true` when the path is acceptable.
+ */
+export function isSafeIncludePath(includePath) {
+    if (includePath.startsWith("/")) {
+        return false;
+    }
+    return includePath.split("/").every((segment) => segment !== ".." && segment.length > 0);
+}
+/** Concatenate the rendered text of `nodes`. */
+function renderNodes(nodes, values, shouldRedactIncludes) {
+    let out = "";
+    for (const node of nodes) {
+        switch (node.type) {
+            case "text":
+                out += node.text;
+                break;
+            case "placeholder":
+                out += values.get(node.name) ?? `{${node.name}}`;
+                break;
+            case "include":
+                out += shouldRedactIncludes
+                    ? `<content of file ${node.path}>`
+                    : renderNodes(node.children, values, shouldRedactIncludes);
+                break;
+            case "source":
+                out += renderNodes(node.children, values, shouldRedactIncludes);
+                break;
+        }
+    }
+    return out;
+}