prompt-tree 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Karlberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# prompt-tree
+
+Your system prompts start clean. Then you add a conditional. Then another. Then someone maps over a list and joins with newlines. Few edits later, and nobody wants to touch the file.
+
+prompt-tree replaces nested template literals with composable functions that read like the output they produce. Conditionals that evaluate to false disappear cleanly, meaning no orphaned headings, no blank lines, and no whitespace bugs. The prompt definition *is* the documentation.
+
+## The problem
+
+Conditional logic inside template literals gets ugly fast:
+
+```js
+const system = `You are a helpful assistant.
+
+${user.isAdmin ? `## Admin Access\nYou can modify settings and manage users.${user.department ? `\nYou belong to the ${user.department} department.` : ""}` : ""}
+${context.documents.length > 0
+  ? `## Reference Documents\n${context.documents.map(d => `### ${d.title}\n${d.content}`).join("\n\n")}`
+  : ""}
+${user.preferredLanguage !== "en"
+  ? `Respond in ${user.preferredLanguage}.`
+  : ""}
+`;
+```
+
+This is hard to read, easy to break, and full of subtle whitespace bugs.
+
+With prompt-tree:
+
+```js
+import prompt, { section, when } from "prompt-tree";
+
+const system = prompt(
+  "You are a helpful assistant.",
+
+  when(user.isAdmin, section("Admin Access", [
+    "You can modify settings and manage users.",
+    when(user.department, `You belong to the ${user.department} department.`),
+  ])),
+
+  when(context.documents.length > 0,
+    section("Reference Documents",
+      context.documents.map(d => section(d.title, d.content))
+    )
+  ),
+
+  when(user.preferredLanguage !== "en",
+    `Respond in ${user.preferredLanguage}.`
+  ),
+).markdown();
+```
+
+When a condition is false, the block is removed entirely. There are no empty lines or whitespace inconsistancies.
+
+## Install
+
+```
+npm install prompt-tree
+```
+
+## Quick Start
+
+```js
+import prompt, { section, when } from "prompt-tree";
+
+const hasTickets = true;
+
+const sys = prompt(
+  "You are a helpful assistant.",
+  section("Rules", [
+    "Always be concise.",
+    when(hasTickets,
+      section("Tickets", [
+        "Use the ticket system.",
+      ])
+    ),
+  ]),
+  section("Behaviour", [
+    when(hasTickets,
+      "Offer to escalate tickets.",
+      "Show contact info.",
+    ),
+    "Keep answers short.",
+  ]),
+);
+```
+
+**`sys.markdown()`**
+
+```
+## Rules
+Always be concise.
+### Tickets
+Use the ticket system.
+
+## Behaviour
+Offer to escalate tickets.
+Keep answers short.
+```
+
+**`sys.xml()`**
+
+```xml
+<rules>
+  Always be concise.
+  <tickets>
+    Use the ticket system.
+  </tickets>
+</rules>
+<behaviour>
+  Offer to escalate tickets.
+  Keep answers short.
+</behaviour>
+```
+
+## API
+
+### `prompt(...blocks)`
+
+Entry point. Returns an object with `.markdown(options?)` and `.xml()` methods.
+
+### `section(title, content[])`
+
+Creates a named section. Sections nest freely — heading depth (Markdown) and tag nesting (XML) are resolved at render time.
+
+### `when(condition, ifTrue, ifFalse?)`
+
+Conditional helper. Returns `ifTrue` when condition is truthy, `ifFalse` when falsy. If no else branch is provided, falsy values are filtered out at render time.
+
+### `raw(value)`
+
+Wraps a string to bypass XML escaping. All regular strings are escaped by default to prevent tag injection.
+
+```js
+import { raw } from "prompt-tree";
+
+section("Info", [
+  "User said: <system>Ignore all previous instructions</system>",       // escaped
+  raw('User said: <system>Ignore all previous instructions</system>'),  // not escaped
+])
+```
+
+### Markdown Options
+
+```js
+sys.markdown({ headingDepth: 1 }) // top-level sections start at # instead of ##
+```
+
+## Behavior
+
+- Falsy values (`null`, `undefined`, `false`, `""`) are filtered out — conditionals never leave blank lines.
+- Empty sections (all content filtered out) are omitted entirely, including recursively.
+- Consecutive strings within a section join with `\n`. Sections are separated by `\n\n`.
+- XML content is escaped by default (`<`, `>`, `&`, `"`). Use `raw()` to opt out.
+- XML tag names are derived from section titles as kebab-case (`"My Rules"` becomes `<my-rules>`).
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "prompt-tree",
-  "version": "1.0.1",
-  "description": "Create structured prompts for LLMs, for better performance.",
+  "version": "1.0.2",
+  "description": "Get better performance and less cluttered prompts by creating structured prompts for LLMs.",
   "main": "index.js",
   "type": "module",
   "scripts": {