@anythingai/teleprompt 0.1.1 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # teleprompt
 
-Compose LLM system prompts from discrete sections instead of monolithic template literals.
+Composable, section-based LLM system prompts.
 
-Conditional logic, variants, and prompt changes stay co-located with their content. Adding a new flag is one section in one file, not a boolean threaded through 15 function signatures.
+Each section owns its content and conditional logic. Sections can be reused across prompt variants, conditionally included, and rendered as plain text or XML.
 
 ```bash
 pnpm add @anythingai/teleprompt
@@ -11,35 +11,30 @@ pnpm add @anythingai/teleprompt
 ## Quick Start
 
 ```ts
-import { PromptBuilder, type PromptContext, type PromptSection } from '@anythingai/teleprompt';
+import { PromptBuilder, section, type PromptContext } from '@anythingai/teleprompt';
 
 // Define your context shape
 type MyFlags = { webSearchEnabled: boolean };
 type MyVars = { assistantName: string };
 type MyContext = PromptContext<MyFlags, MyVars>;
 
-// Sections are objects with an id and a render function
-const identity: PromptSection<MyContext> = {
-  id: 'identity',
-  render: (ctx) => `You are ${ctx.vars.assistantName}, a helpful AI assistant.`,
-};
-
-// This is a static section with no context dependencies
-const guidelines: PromptSection<MyContext> = {
-  id: 'guidelines',
-  render: () => `# Guidelines
+// Static section — no context needed, no type parameter
+const guidelines = section('guidelines', () => `# Guidelines
 - Be concise and direct.
 - Cite sources when making factual claims.
-- Ask for clarification when a request is ambiguous.`,
-};
+- Ask for clarification when a request is ambiguous.`);
 
-// Conditional logic lives in the section, not threaded through function signatures
-const webSearch: PromptSection<MyContext> = {
-  id: 'web-search',
-  when: (ctx) => ctx.flags.webSearchEnabled,
-  render: () => `You have access to web search. Use it when the user asks about
-current events or information that may have changed after your training cutoff.`,
-};
+// Dynamic section — uses context
+const identity = section('identity', (ctx: MyContext) =>
+  `You are ${ctx.vars.assistantName}, a helpful AI assistant.`
+);
+
+// Conditional section — return null to exclude
+const webSearch = section('web-search', (ctx: MyContext) => {
+  if (!ctx.flags.webSearchEnabled) return null;
+  return `You have access to web search. Use it when the user asks about
+current events or information that may have changed after your training cutoff.`;
+});
 
 // Compose and build
 const prompt = new PromptBuilder<MyContext>()
@@ -54,21 +49,60 @@ const prompt = new PromptBuilder<MyContext>()
 
 ## Sections
 
-A section has an `id`, a `render` function, and optionally a `when` guard:
+`section(id, render)` takes an id and a render function. Return a string to include, `null` to exclude:
 
 ```ts
-const citation: PromptSection<MyContext> = {
-  id: 'citation',
-  when: (ctx) => ctx.flags.citationEnabled,   // excluded when false
-  render: () => 'Always include citations with links when referencing external sources.',
-};
+// Always included
+const rules = section('rules', () => 'Be helpful and concise.');
+
+// Conditional — null means excluded
+const citation = section('citation', (ctx: MyContext) => {
+  if (!ctx.flags.citationEnabled) return null;
+  return 'Always include citations with links when referencing external sources.';
+});
 ```
 
 Sections render in the order you call `.use()`. To reorder, change the call order.
 
+Static sections (no type parameter) work in any builder:
+
+```ts
+const disclaimer = section('disclaimer', () => 'Responses are not legal advice.');
+
+// Works in any builder regardless of context type
+new PromptBuilder<MyContext>().use(disclaimer)
+new PromptBuilder<OtherContext>().use(disclaimer)
+```
+
+## Context
+
+Sections receive a typed context with boolean flags and arbitrary variables:
+
+```ts
+type MyFlags = {
+  webSearchEnabled: boolean;
+  citationEnabled: boolean;
+};
+
+type MyVars = {
+  assistantName: string;
+  language: string;
+};
+
+type MyContext = PromptContext<MyFlags, MyVars>;
+```
+
+`PromptContext` and `PromptBuilder` have defaults, so the type parameter is optional:
+
+```ts
+const builder = new PromptBuilder();
+```
+
+Build the context once and pass it to `.build(ctx)`. Every section receives the same object.
+
 ## Forking
 
-Create variants without duplicating prompt code:
+Create variants from a shared base:
 
 ```ts
 const base = new PromptBuilder<MyContext>()
@@ -91,50 +125,96 @@ const codeAssistant = base.fork()
 
 Each fork is independent. Modifying one doesn't affect the others.
 
-## Context
+## XML Format
 
-Sections receive a typed context with boolean flags and arbitrary variables:
+Both Claude and Gemini recommend structuring prompts with XML tags. Pass `{ format: 'xml' }` to `.build()` to wrap each section in `<id>` tags:
 
 ```ts
-type MyFlags = {
-  webSearchEnabled: boolean;
-  citationEnabled: boolean;
-};
+builder.build(ctx, { format: 'xml' })
+```
 
-type MyVars = {
-  assistantName: string;
-  language: string;
-};
+The section id becomes the tag name. Content is left as-is inside the tags.
 
-type MyContext = PromptContext<MyFlags, MyVars>;
+## Groups
+
+Group related sections together. In text mode, groups are transparent. In XML mode, they wrap children in tags:
+
+```ts
+const prompt = new PromptBuilder<MyContext>()
+  .use(identity)
+  .group('tools', b => b
+    .use(webSearch)
+    .use(calculator)
+  )
+  .use(guidelines)
+  .build(ctx, { format: 'xml' });
 ```
 
-You build the context once and pass it to `.build(ctx)`. Every section receives the same object — no threading booleans through function signatures.
+```xml
+<identity>
+You are Daniel, a helpful AI assistant.
+</identity>
+
+<tools>
+<web-search>
+You have access to web search...
+</web-search>
+
+<calculator>
+You can evaluate math expressions...
+</calculator>
+</tools>
+
+<guidelines>
+# Guidelines
+...
+</guidelines>
+```
 
-## Builder API
+Groups can be nested:
 
 ```ts
-new PromptBuilder<MyContext>()
-  // append a section (replaces if same id exists)
-  .use(section)
+builder.group('capabilities', b => b
+  .group('tools', b => b
+    .use(webSearch)
+    .use(calculator)
+  )
+  .group('integrations', b => b
+    .use(slack)
+    .use(linear)
+  )
+)
+```
 
-  // remove by section object or string id
-  .without(section)
+## Mutually Exclusive Sections
 
-  // check existence by section object or string id
-  .has(section)
+Use `.useOneOf()` when exactly one of several sections should render. The first candidate that returns a non-empty string wins:
 
-  // list all section ids
-  .ids()
+```ts
+const hasTasks = section('has-tasks', (ctx: MyContext) => {
+  if (ctx.vars.tasks.length === 0) return null;
+  return `## Active Tasks\n\n${ctx.vars.tasks.map(t => `- ${t.title}`).join('\n')}`;
+});
 
-  // independent copy
-  .fork()
+const noTasks = section('no-tasks', () => '## Active Tasks\n\nNo tasks currently running.');
 
-  // render to string
-  .build(ctx)
+builder.useOneOf(hasTasks, noTasks);
+```
 
-  // render + debug info: { included: string[], excluded: string[] }
-  .buildWithMeta(ctx)        
+## Builder API
+
+```ts
+new PromptBuilder<MyContext>()
+  .use(section)                      // append (replaces if same id)
+  .useOneOf(sectionA, sectionB)      // first match wins
+  .group('name', b => b.use(...))    // named group (XML wrapper)
+  .without(section)                  // remove by object or string id
+  .has(section)                      // check existence
+  .ids()                             // list all section ids
+  .fork()                            // independent copy
+  .build(ctx)                        // render to string
+  .build(ctx, { format: 'xml' })     // render with XML tags
+  .buildWithMeta(ctx)                // render + { included, excluded }
 ```
 
 ## Testing

package/dist/index.cjs

@@ -1,95 +1,238 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); var _class;// src/builder.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;// src/builder.ts
 var PromptBuilder = (_class = class _PromptBuilder {constructor() { _class.prototype.__init.call(this); }
-  __init() {this.sections = []}
+  __init() {this.nodes = []}
+  /** Replaces an existing section with the same id. */
+  use(section2) {
+    const idx = this.nodes.findIndex((n) => !isOneOf(n) && n.id === section2.id);
+    if (idx >= 0) {
+      this.nodes[idx] = section2;
+    } else {
+      this.nodes.push(section2);
+    }
+    return this;
+  }
   /**
-   * Add a section to the prompt.
+   * First candidate that renders a non-empty string wins.
    *
-   * If a section with the same `id` already exists, it is replaced.
-   * This makes `.use()` idempotent — you can safely call it multiple
-   * times with the same section without creating duplicates.
+   * @example
+   * ```ts
+   * builder.useOneOf(activeTasks, noActiveTasks)
+   * ```
    */
-  use(section) {
-    const existingIdx = this.sections.findIndex((s) => s.id === section.id);
-    if (existingIdx >= 0) {
-      this.sections[existingIdx] = section;
+  useOneOf(...candidates) {
+    this.nodes.push({ candidates });
+    return this;
+  }
+  /**
+   * In `xml` format, wraps children in `<id>` tags. Transparent in `text` format.
+   *
+   * @example
+   * ```ts
+   * builder.group('tools', b => b
+   *   .use(bashSection)
+   *   .use(gitSection)
+   * )
+   * ```
+   */
+  group(id, configure) {
+    const inner = new _PromptBuilder();
+    configure(inner);
+    const group = { id, children: inner.nodes };
+    const idx = this.nodes.findIndex((n) => !isOneOf(n) && n.id === id);
+    if (idx >= 0) {
+      this.nodes[idx] = group;
     } else {
-      this.sections.push(section);
+      this.nodes.push(group);
     }
     return this;
   }
-  /** Remove a section. Accepts an id string or a section object. */
+  /** Searches recursively into groups and oneOf candidates. */
   without(ref) {
     const id = typeof ref === "string" ? ref : ref.id;
-    this.sections = this.sections.filter((s) => s.id !== id);
+    this.nodes = removeNode(this.nodes, id);
     return this;
   }
-  /** Check if a section exists. Accepts an id string or a section object. */
+  /** Searches recursively into groups and oneOf candidates. */
   has(ref) {
     const id = typeof ref === "string" ? ref : ref.id;
-    return this.sections.some((s) => s.id === id);
+    return hasNode(this.nodes, id);
   }
-  /** Get the ids of all registered sections (in insertion order). */
   ids() {
-    return this.sections.map((s) => s.id);
+    return collectIds(this.nodes);
   }
   /**
-   * Create an independent copy of this builder.
-   *
-   * Use this to create mode-specific or model-specific variants
-   * without mutating the base builder.
+   * Creates an independent copy. Modifications to the fork don't affect the original.
    *
    * @example
    * ```ts
    * const base = new PromptBuilder().use(a).use(b);
-   * const variant = base.fork().use(c); // base is unchanged
+   * const variant = base.fork().use(c);
    * ```
    */
   fork() {
     const forked = new _PromptBuilder();
-    forked.sections = [...this.sections];
+    forked.nodes = deepCopy(this.nodes);
     return forked;
   }
-  /**
-   * Build the final prompt string.
-   *
-   * 1. Filters out sections whose `when` guard returns false
-   * 2. Renders each section
-   * 3. Filters out empty strings
-   * 4. Joins with separator and trims
-   */
-  build(ctx) {
-    return this.buildWithMeta(ctx).prompt;
+  build(ctx, options) {
+    return this.buildWithMeta(ctx, options).prompt;
   }
-  /**
-   * Build the prompt and return metadata about which sections were
-   * included/excluded. Useful for debugging and logging.
-   *
-   * A section is "excluded" if its `when` guard returns false.
-   * A section is "included" only if it passes the guard and renders
-   * a non-empty string.
-   */
-  buildWithMeta(ctx) {
+  /** Like `build`, but also returns which section ids were included/excluded. */
+  buildWithMeta(ctx, options) {
     const included = [];
     const excluded = [];
-    const rendered = this.sections.filter((s) => {
-      if (s.when && !s.when(ctx)) {
-        excluded.push(s.id);
-        return false;
+    const format = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _ => _.format]), () => ( "text"));
+    const parts = renderNodes(this.nodes, ctx, format, included, excluded);
+    const prompt = parts.join("\n\n").trim();
+    return { prompt, included, excluded };
+  }
+}, _class);
+function isSection(node) {
+  return "render" in node;
+}
+function isGroup(node) {
+  return "children" in node;
+}
+function isOneOf(node) {
+  return "candidates" in node;
+}
+function assertNever(value) {
+  throw new Error(`Unexpected format: ${value}`);
+}
+function formatSection(id, content, format) {
+  switch (format) {
+    case "text":
+      return content;
+    case "xml":
+      return `<${id}>
+${content}
+</${id}>`;
+    default:
+      return assertNever(format);
+  }
+}
+function formatGroup(id, childParts, format) {
+  switch (format) {
+    case "text":
+      return childParts;
+    case "xml":
+      return [`<${id}>
+${childParts.join("\n\n")}
+</${id}>`];
+    default:
+      return assertNever(format);
+  }
+}
+function renderSection(section2, ctx, format, parts, included, excluded) {
+  if (section2.when && !section2.when(ctx)) {
+    excluded.push(section2.id);
+    return false;
+  }
+  const output = section2.render(ctx);
+  if (output) {
+    included.push(section2.id);
+    parts.push(formatSection(section2.id, output, format));
+    return true;
+  }
+  excluded.push(section2.id);
+  return false;
+}
+function renderOneOf(node, ctx, format, parts, included, excluded) {
+  let found = false;
+  for (const candidate of node.candidates) {
+    if (found) {
+      excluded.push(candidate.id);
+      continue;
+    }
+    if (renderSection(candidate, ctx, format, parts, included, excluded)) {
+      found = true;
+    }
+  }
+}
+function renderNodes(nodes, ctx, format, included, excluded) {
+  const parts = [];
+  for (const node of nodes) {
+    if (isSection(node)) {
+      renderSection(node, ctx, format, parts, included, excluded);
+    } else if (isGroup(node)) {
+      const childParts = renderNodes(node.children, ctx, format, included, excluded);
+      if (childParts.length > 0) {
+        parts.push(...formatGroup(node.id, childParts, format));
       }
-      return true;
-    }).map((s) => {
-      const output = s.render(ctx);
-      if (output) {
-        included.push(s.id);
-      } else {
-        excluded.push(s.id);
+    } else {
+      renderOneOf(node, ctx, format, parts, included, excluded);
+    }
+  }
+  return parts;
+}
+function hasNode(nodes, id) {
+  for (const node of nodes) {
+    if (isSection(node)) {
+      if (node.id === id) return true;
+    } else if (isGroup(node)) {
+      if (node.id === id) return true;
+      if (hasNode(node.children, id)) return true;
+    } else {
+      for (const c of node.candidates) {
+        if (c.id === id) return true;
       }
-      return output;
-    }).filter(Boolean).join("\n\n").trim();
-    return { prompt: rendered, included, excluded };
+    }
   }
-}, _class);
+  return false;
+}
+function removeNode(nodes, id) {
+  const result = [];
+  for (const n of nodes) {
+    if (isSection(n)) {
+      if (n.id !== id) result.push(n);
+    } else if (isGroup(n)) {
+      if (n.id !== id) {
+        result.push({ ...n, children: removeNode(n.children, id) });
+      }
+    } else {
+      const remaining = n.candidates.filter((c) => c.id !== id);
+      if (remaining.length > 0) {
+        result.push({ candidates: remaining });
+      }
+    }
+  }
+  return result;
+}
+function collectIds(nodes) {
+  const ids = [];
+  for (const node of nodes) {
+    if (isSection(node)) {
+      ids.push(node.id);
+    } else if (isGroup(node)) {
+      ids.push(node.id);
+      ids.push(...collectIds(node.children));
+    } else {
+      ids.push(...node.candidates.map((c) => c.id));
+    }
+  }
+  return ids;
+}
+function deepCopy(nodes) {
+  return nodes.map((n) => {
+    if (isGroup(n)) {
+      return { ...n, children: deepCopy(n.children) };
+    }
+    if (isOneOf(n)) {
+      return { candidates: [...n.candidates] };
+    }
+    return n;
+  });
+}
+
+// src/section.ts
+function section(id, render) {
+  return {
+    id,
+    render: (ctx) => _nullishCoalesce(render(ctx), () => ( ""))
+  };
+}
+
 
 
-exports.PromptBuilder = PromptBuilder;
+exports.PromptBuilder = PromptBuilder; exports.section = section;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/asurve/dev/teleprompt/dist/index.cjs","../src/builder.ts"],"names":[],"mappings":"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","file":"/Users/asurve/dev/teleprompt/dist/index.cjs","sourcesContent":[null,"import type { PromptContext, PromptSection } from './types';\n\n/**\n * Declarative, composable prompt builder.\n *\n * Prompts are composed from discrete {@link PromptSection}s that are\n * independently testable pure functions. The builder handles ordering,\n * conditional inclusion, and final assembly.\n *\n * @example\n * ```ts\n * const prompt = new PromptBuilder()\n *   .use(identitySection)\n *   .use(rulesSection)\n *   .use(featureSection)\n *   .build(ctx);\n * ```\n */\nexport class PromptBuilder<\n  TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>,\n> {\n  private sections: PromptSection<TCtx>[] = [];\n\n  /**\n   * Add a section to the prompt.\n   *\n   * If a section with the same `id` already exists, it is replaced.\n   * This makes `.use()` idempotent — you can safely call it multiple\n   * times with the same section without creating duplicates.\n   */\n  use(section: PromptSection<TCtx>): this {\n    const existingIdx = this.sections.findIndex((s) => s.id === section.id);\n    if (existingIdx >= 0) {\n      this.sections[existingIdx] = section;\n    } else {\n      this.sections.push(section);\n    }\n    return this;\n  }\n\n  /** Remove a section. Accepts an id string or a section object. */\n  without(ref: string | { id: string }): this {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    this.sections = this.sections.filter((s) => s.id !== id);\n    return this;\n  }\n\n  /** Check if a section exists. Accepts an id string or a section object. */\n  has(ref: string | { id: string }): boolean {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    return this.sections.some((s) => s.id === id);\n  }\n\n  /** Get the ids of all registered sections (in insertion order). */\n  ids(): string[] {\n    return this.sections.map((s) => s.id);\n  }\n\n  /**\n   * Create an independent copy of this builder.\n   *\n   * Use this to create mode-specific or model-specific variants\n   * without mutating the base builder.\n   *\n   * @example\n   * ```ts\n   * const base = new PromptBuilder().use(a).use(b);\n   * const variant = base.fork().use(c); // base is unchanged\n   * ```\n   */\n  fork(): PromptBuilder<TCtx> {\n    const forked = new PromptBuilder<TCtx>();\n    forked.sections = [...this.sections];\n    return forked;\n  }\n\n  /**\n   * Build the final prompt string.\n   *\n   * 1. Filters out sections whose `when` guard returns false\n   * 2. Renders each section\n   * 3. Filters out empty strings\n   * 4. Joins with separator and trims\n   */\n  build(ctx: TCtx): string {\n    return this.buildWithMeta(ctx).prompt;\n  }\n\n  /**\n   * Build the prompt and return metadata about which sections were\n   * included/excluded. Useful for debugging and logging.\n   *\n   * A section is \"excluded\" if its `when` guard returns false.\n   * A section is \"included\" only if it passes the guard and renders\n   * a non-empty string.\n   */\n  buildWithMeta(ctx: TCtx): {\n    prompt: string;\n    included: string[];\n    excluded: string[];\n  } {\n    const included: string[] = [];\n    const excluded: string[] = [];\n\n    const rendered = this.sections\n      .filter((s) => {\n        if (s.when && !s.when(ctx)) {\n          excluded.push(s.id);\n          return false;\n        }\n        return true;\n      })\n      .map((s) => {\n        const output = s.render(ctx);\n        if (output) {\n          included.push(s.id);\n        } else {\n          excluded.push(s.id);\n        }\n        return output;\n      })\n      .filter(Boolean)\n      .join('\\n\\n')\n      .trim();\n\n    return { prompt: rendered, included, excluded };\n  }\n}\n"]}
+{"version":3,"sources":["/Users/asurve/dev/teleprompt/main/dist/index.cjs","../src/builder.ts","../src/section.ts"],"names":["section"],"mappings":"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","file":"/Users/asurve/dev/teleprompt/main/dist/index.cjs","sourcesContent":[null,"import type { PromptContext, PromptSection } from './types';\n\nexport type PromptFormat = 'text' | 'xml';\n\nexport interface BuildOptions {\n  /**\n   * - `'text'` (default) — sections joined with `\\n\\n`, groups are transparent.\n   * - `'xml'` — each section wrapped in `<id>...</id>` tags, groups\n   *   wrapped in `<id>...</id>` containing their children.\n   */\n  format?: PromptFormat;\n}\n\n/**\n * @example\n * ```ts\n * const prompt = new PromptBuilder()\n *   .use(identitySection)\n *   .use(rulesSection)\n *   .use(featureSection)\n *   .build(ctx);\n * ```\n */\nexport class PromptBuilder<TCtx extends PromptContext = PromptContext> {\n  private nodes: PromptNode<TCtx>[] = [];\n\n  /** Replaces an existing section with the same id. */\n  use(section: PromptSection<TCtx>): this {\n    const idx = this.nodes.findIndex((n) => !isOneOf(n) && n.id === section.id);\n    if (idx >= 0) {\n      this.nodes[idx] = section;\n    } else {\n      this.nodes.push(section);\n    }\n    return this;\n  }\n\n  /**\n   * First candidate that renders a non-empty string wins.\n   *\n   * @example\n   * ```ts\n   * builder.useOneOf(activeTasks, noActiveTasks)\n   * ```\n   */\n  useOneOf(...candidates: PromptSection<TCtx>[]): this {\n    this.nodes.push({ candidates });\n    return this;\n  }\n\n  /**\n   * In `xml` format, wraps children in `<id>` tags. Transparent in `text` format.\n   *\n   * @example\n   * ```ts\n   * builder.group('tools', b => b\n   *   .use(bashSection)\n   *   .use(gitSection)\n   * )\n   * ```\n   */\n  group(id: string, configure: (builder: PromptBuilder<TCtx>) => void): this {\n    const inner = new PromptBuilder<TCtx>();\n    configure(inner);\n    const group: PromptGroup<TCtx> = { id, children: inner.nodes };\n    const idx = this.nodes.findIndex((n) => !isOneOf(n) && n.id === id);\n    if (idx >= 0) {\n      this.nodes[idx] = group;\n    } else {\n      this.nodes.push(group);\n    }\n    return this;\n  }\n\n  /** Searches recursively into groups and oneOf candidates. */\n  without(ref: string | { id: string }): this {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    this.nodes = removeNode(this.nodes, id);\n    return this;\n  }\n\n  /** Searches recursively into groups and oneOf candidates. */\n  has(ref: string | { id: string }): boolean {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    return hasNode(this.nodes, id);\n  }\n\n  ids(): string[] {\n    return collectIds(this.nodes);\n  }\n\n  /**\n   * Creates an independent copy. Modifications to the fork don't affect the original.\n   *\n   * @example\n   * ```ts\n   * const base = new PromptBuilder().use(a).use(b);\n   * const variant = base.fork().use(c);\n   * ```\n   */\n  fork(): PromptBuilder<TCtx> {\n    const forked = new PromptBuilder<TCtx>();\n    forked.nodes = deepCopy(this.nodes);\n    return forked;\n  }\n\n  build(ctx: TCtx, options?: BuildOptions): string {\n    return this.buildWithMeta(ctx, options).prompt;\n  }\n\n  /** Like `build`, but also returns which section ids were included/excluded. */\n  buildWithMeta(\n    ctx: TCtx,\n    options?: BuildOptions,\n  ): {\n    prompt: string;\n    included: string[];\n    excluded: string[];\n  } {\n    const included: string[] = [];\n    const excluded: string[] = [];\n    const format = options?.format ?? 'text';\n\n    const parts = renderNodes(this.nodes, ctx, format, included, excluded);\n    const prompt = parts.join('\\n\\n').trim();\n\n    return { prompt, included, excluded };\n  }\n}\n\ninterface PromptGroup<TCtx extends PromptContext> {\n  id: string;\n  children: PromptNode<TCtx>[];\n}\n\ninterface PromptOneOf<TCtx extends PromptContext> {\n  candidates: PromptSection<TCtx>[];\n}\n\ntype PromptNode<TCtx extends PromptContext> =\n  | PromptSection<TCtx>\n  | PromptGroup<TCtx>\n  | PromptOneOf<TCtx>;\n\nfunction isSection<TCtx extends PromptContext>(\n  node: PromptNode<TCtx>,\n): node is PromptSection<TCtx> {\n  return 'render' in node;\n}\n\nfunction isGroup<TCtx extends PromptContext>(node: PromptNode<TCtx>): node is PromptGroup<TCtx> {\n  return 'children' in node;\n}\n\nfunction isOneOf<TCtx extends PromptContext>(node: PromptNode<TCtx>): node is PromptOneOf<TCtx> {\n  return 'candidates' in node;\n}\n\nfunction assertNever(value: never): never {\n  throw new Error(`Unexpected format: ${value}`);\n}\n\nfunction formatSection(id: string, content: string, format: PromptFormat): string {\n  switch (format) {\n    case 'text':\n      return content;\n    case 'xml':\n      return `<${id}>\\n${content}\\n</${id}>`;\n    default:\n      return assertNever(format);\n  }\n}\n\nfunction formatGroup(id: string, childParts: string[], format: PromptFormat): string[] {\n  switch (format) {\n    case 'text':\n      return childParts;\n    case 'xml':\n      return [`<${id}>\\n${childParts.join('\\n\\n')}\\n</${id}>`];\n    default:\n      return assertNever(format);\n  }\n}\n\nfunction renderSection<TCtx extends PromptContext>(\n  section: PromptSection<TCtx>,\n  ctx: TCtx,\n  format: PromptFormat,\n  parts: string[],\n  included: string[],\n  excluded: string[],\n): boolean {\n  if (section.when && !section.when(ctx)) {\n    excluded.push(section.id);\n    return false;\n  }\n  const output = section.render(ctx);\n  if (output) {\n    included.push(section.id);\n    parts.push(formatSection(section.id, output, format));\n    return true;\n  }\n  excluded.push(section.id);\n  return false;\n}\n\nfunction renderOneOf<TCtx extends PromptContext>(\n  node: PromptOneOf<TCtx>,\n  ctx: TCtx,\n  format: PromptFormat,\n  parts: string[],\n  included: string[],\n  excluded: string[],\n): void {\n  let found = false;\n  for (const candidate of node.candidates) {\n    if (found) {\n      excluded.push(candidate.id);\n      continue;\n    }\n    if (renderSection(candidate, ctx, format, parts, included, excluded)) {\n      found = true;\n    }\n  }\n}\n\nfunction renderNodes<TCtx extends PromptContext>(\n  nodes: PromptNode<TCtx>[],\n  ctx: TCtx,\n  format: PromptFormat,\n  included: string[],\n  excluded: string[],\n): string[] {\n  const parts: string[] = [];\n\n  for (const node of nodes) {\n    if (isSection(node)) {\n      renderSection(node, ctx, format, parts, included, excluded);\n    } else if (isGroup(node)) {\n      const childParts = renderNodes(node.children, ctx, format, included, excluded);\n      if (childParts.length > 0) {\n        parts.push(...formatGroup(node.id, childParts, format));\n      }\n    } else {\n      renderOneOf(node, ctx, format, parts, included, excluded);\n    }\n  }\n\n  return parts;\n}\n\nfunction hasNode<TCtx extends PromptContext>(nodes: PromptNode<TCtx>[], id: string): boolean {\n  for (const node of nodes) {\n    if (isSection(node)) {\n      if (node.id === id) return true;\n    } else if (isGroup(node)) {\n      if (node.id === id) return true;\n      if (hasNode(node.children, id)) return true;\n    } else {\n      for (const c of node.candidates) {\n        if (c.id === id) return true;\n      }\n    }\n  }\n  return false;\n}\n\nfunction removeNode<TCtx extends PromptContext>(\n  nodes: PromptNode<TCtx>[],\n  id: string,\n): PromptNode<TCtx>[] {\n  const result: PromptNode<TCtx>[] = [];\n  for (const n of nodes) {\n    if (isSection(n)) {\n      if (n.id !== id) result.push(n);\n    } else if (isGroup(n)) {\n      if (n.id !== id) {\n        result.push({ ...n, children: removeNode(n.children, id) });\n      }\n    } else {\n      const remaining = n.candidates.filter((c) => c.id !== id);\n      if (remaining.length > 0) {\n        result.push({ candidates: remaining });\n      }\n    }\n  }\n  return result;\n}\n\nfunction collectIds<TCtx extends PromptContext>(nodes: PromptNode<TCtx>[]): string[] {\n  const ids: string[] = [];\n  for (const node of nodes) {\n    if (isSection(node)) {\n      ids.push(node.id);\n    } else if (isGroup(node)) {\n      ids.push(node.id);\n      ids.push(...collectIds(node.children));\n    } else {\n      ids.push(...node.candidates.map((c) => c.id));\n    }\n  }\n  return ids;\n}\n\nfunction deepCopy<TCtx extends PromptContext>(nodes: PromptNode<TCtx>[]): PromptNode<TCtx>[] {\n  return nodes.map((n) => {\n    if (isGroup(n)) {\n      return { ...n, children: deepCopy(n.children) };\n    }\n    if (isOneOf(n)) {\n      return { candidates: [...n.candidates] };\n    }\n    return n;\n  });\n}\n","import type { PromptContext, PromptSection } from './types';\n\n/**\n * Create a prompt section. Return a string to include, `null` to exclude.\n *\n * @example\n * ```ts\n * section('identity', () => 'You are Coworker.')\n *\n * section('prod', (ctx: SandboxCtx) => {\n *   if (ctx.vars.prodContext == null) return null;\n *   return `## Prod\\n\\n${ctx.vars.prodContext}`;\n * })\n * ```\n */\nexport function section<TCtx extends PromptContext = PromptContext>(\n  id: string,\n  render: (ctx: TCtx) => string | null,\n): PromptSection<TCtx> {\n  return {\n    id,\n    render: (ctx) => render(ctx) ?? '',\n  };\n}\n"]}