@boxxy/prompt-template 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/prompt-template</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/prompt-template"><img src="https://img.shields.io/npm/v/@boxxy/prompt-template" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+The launch prompt template of a boxxy recipe: its placeholders, its load check and its render.
+
+A recipe's prompt is a [Liquid](https://liquidjs.com/) template. The rules loader checks each
+template when it loads the rules, and dispatch renders it when it claims an attempt.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/prompt-template) with Bun:
+
+```bash
+bun add @boxxy/prompt-template
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `promptPlaceholders`, the names a template may use.
+- `findPromptTemplateFault`, which returns why a template cannot render, or `null` when it can.
+- `renderPromptTemplate`, which renders a template with a value for each placeholder.
+
+## Documentation
+
+[The launch prompt](../../docs/design/boxxy/v1.md#the-launch-prompt) lists the placeholders and
+their values.

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const promptPlaceholders: readonly ['ticket', 'title', 'outcome', 'body', 'acceptance', 'design', 'findings', 'notes', 'repo', 'attempt_id', 'input'];
+export declare const promptTags: readonly ['if', 'unless', 'case', 'for', 'raw', 'comment', '#'];
+export declare const promptFilters: readonly ['escape', 'xml_escape', 'escape_once', 'newline_to_br', 'strip_html', 'abs', 'at_least', 'at_most', 'ceil', 'divided_by', 'floor', 'minus', 'plus', 'modulo', 'times', 'round', 'slugify', 'join', 'last', 'first', 'reverse', 'sort', 'sort_natural', 'size', 'map', 'sum', 'compact', 'concat', 'push', 'unshift', 'pop', 'shift', 'slice', 'uniq', 'lstrip', 'downcase', 'upcase', 'remove', 'remove_first', 'remove_last', 'rstrip', 'split', 'strip', 'strip_newlines', 'squish', 'capitalize', 'replace', 'replace_first', 'replace_last', 'truncate', 'truncatewords', 'normalize_whitespace', 'number_of_words', 'array_to_sentence_string', 'base64_encode', 'sha256', 'hmac_sha256', 'default', 'raw', 'jsonify', 'to_integer', 'json', 'inspect'];

package/dist/find-prompt-template-fault.d.ts

@@ -0,0 +1 @@
+export declare function findPromptTemplateFault(template: string): string | null;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { promptPlaceholders } from './constants.ts';
+export { findPromptTemplateFault } from './find-prompt-template-fault.ts';
+export { renderPromptTemplate } from './render-prompt-template.ts';
+export type { PromptPlaceholder, PromptValues } from './types.ts';

package/dist/prompt-engine.d.ts

@@ -0,0 +1,2 @@
+import { Liquid } from 'liquidjs';
+export declare const promptEngine: Liquid;

package/dist/render-prompt-template.d.ts

@@ -0,0 +1,2 @@
+import type { PromptValues } from './types.ts';
+export declare function renderPromptTemplate(template: string, values: PromptValues): string;

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+import type { promptPlaceholders } from './constants.ts';
+export type PromptPlaceholder = (typeof promptPlaceholders)[number];
+export type PromptValues = Readonly<Record<PromptPlaceholder, string>>;

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@boxxy/prompt-template",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "description": "The launch prompt template of a boxxy recipe: its placeholders, its load check and its render",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/libs/prompt-template#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "libs/prompt-template"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "liquidjs": "10.30.1",
+    "tiny-invariant": "1.3.3"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,87 @@
+// The names a launch prompt template may use. The loader rejects a template that names any other.
+export const promptPlaceholders = [
+  'ticket',
+  'title',
+  'outcome',
+  'body',
+  'acceptance',
+  'design',
+  'findings',
+  'notes',
+  'repo',
+  'attempt_id',
+  'input',
+] as const;
+
+// The tags a template may use. A tag that binds a name, such as `assign`, would let a branch that
+// did not run leave a name unbound, and the render would throw at claim.
+export const promptTags = ['if', 'unless', 'case', 'for', 'raw', 'comment', '#'] as const;
+
+// The filters a template may use: each renders any text with any arguments. Liquid's other
+// filters read the clock or a random number, read a field by name, check their argument count at
+// render, or throw on some text, such as `url_decode` on `100%`.
+export const promptFilters = [
+  'escape',
+  'xml_escape',
+  'escape_once',
+  'newline_to_br',
+  'strip_html',
+  'abs',
+  'at_least',
+  'at_most',
+  'ceil',
+  'divided_by',
+  'floor',
+  'minus',
+  'plus',
+  'modulo',
+  'times',
+  'round',
+  'slugify',
+  'join',
+  'last',
+  'first',
+  'reverse',
+  'sort',
+  'sort_natural',
+  'size',
+  'map',
+  'sum',
+  'compact',
+  'concat',
+  'push',
+  'unshift',
+  'pop',
+  'shift',
+  'slice',
+  'uniq',
+  'lstrip',
+  'downcase',
+  'upcase',
+  'remove',
+  'remove_first',
+  'remove_last',
+  'rstrip',
+  'split',
+  'strip',
+  'strip_newlines',
+  'squish',
+  'capitalize',
+  'replace',
+  'replace_first',
+  'replace_last',
+  'truncate',
+  'truncatewords',
+  'normalize_whitespace',
+  'number_of_words',
+  'array_to_sentence_string',
+  'base64_encode',
+  'sha256',
+  'hmac_sha256',
+  'default',
+  'raw',
+  'jsonify',
+  'to_integer',
+  'json',
+  'inspect',
+] as const;

package/src/find-prompt-template-fault.ts

@@ -0,0 +1,151 @@
+import { ForTag, TypeGuards, Value, toValueSync } from 'liquidjs';
+import type { Filter, Template, ValueToken } from 'liquidjs';
+import { promptPlaceholders } from './constants.ts';
+import { promptEngine } from './prompt-engine.ts';
+
+const known: ReadonlySet<string> = new Set(promptPlaceholders);
+
+// Why the template cannot render, or null when it can: a syntax error, a tag or filter the engine
+// does not have, a name that is no placeholder or is read from a value, a for loop over anything
+// but a bare placeholder, a range, or a field read on any value.
+export function findPromptTemplateFault(template: string): string | null {
+  const parsed = parseTemplate(template);
+
+  if (typeof parsed === 'string') {
+    return parsed;
+  }
+
+  const templates = collectTemplates(parsed);
+
+  // Liquid reads `[title]` as the variable whose name is the value of `title`. Its static analysis
+  // reports that read as `title`, so the check walks the tokens itself.
+  const tokens = templates
+    .flatMap((item) => (item.arguments ? [...item.arguments()] : []))
+    .flatMap((argument) => collectValueTokens(argument))
+    .flatMap((token) => collectNestedTokens(token));
+
+  if (tokens.some((token) => isNameFromValue(token))) {
+    return 'the template reads a variable whose name is a value, such as [title]; write the name out, as {{ title }}';
+  }
+
+  const unknown = [
+    ...new Set(
+      promptEngine.globalVariableSegmentsSync(parsed).map((segments) => String(segments[0])),
+    ),
+  ].filter((name) => !known.has(name));
+
+  if (unknown.length > 0) {
+    return `the template names ${formatNames(unknown)}, which is not a placeholder; the placeholders are ${promptPlaceholders.join(', ')}`;
+  }
+
+  const loops = templates.filter((item) => item instanceof ForTag);
+
+  // The for tag keeps its own `forloop` object under that name, and a loop variable of the same
+  // name replaces it, so the tag throws on its next turn.
+  if (loops.some((loop) => loop.variable === 'forloop')) {
+    return 'the template names a loop variable "forloop", which the for tag uses itself';
+  }
+
+  // The for tag drops the filters after its list without running them.
+  if (loops.some((loop) => loop.token.args.includes('|'))) {
+    return 'the template filters the list of a for loop, which the for tag ignores';
+  }
+
+  const collections = loops
+    .map((loop) => loop.collection)
+    .filter((collection) => !isBareName(collection));
+
+  if (collections.length > 0) {
+    return `the template loops over ${formatNames(collections.map((collection) => collection.getText()))}, but a for loop loops only over a placeholder`;
+  }
+
+  // Liquid builds a range as a list in memory, so `(1..10000000000)` runs out of memory at claim.
+  if (tokens.some((token) => TypeGuards.isRangeToken(token))) {
+    return 'the template builds a range, such as (1..3), which a prompt has no use for';
+  }
+
+  // Under `strictVariables` a missing field throws. Each value is a string, and a loop over a
+  // string yields that string, so no field is safe to read.
+  const fields = promptEngine
+    .variableSegmentsSync(parsed)
+    .filter((segments) => segments.length > 1);
+
+  if (fields.length > 0) {
+    return `the template reads ${formatNames(fields.map((segments) => segments.join('.')))}, but each value is plain text with no fields`;
+  }
+
+  return null;
+}
+
+function parseTemplate(template: string): Template[] | string {
+  try {
+    return promptEngine.parse(template);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    return `the template does not parse: ${message}`;
+  }
+}
+
+function collectTemplates(templates: readonly Template[]): Template[] {
+  return templates.flatMap((template) => {
+    const children = template.children ? toValueSync(template.children(false, true)) : [];
+
+    return [template, ...collectTemplates(children)];
+  });
+}
+
+function collectValueTokens(argument: Value | ValueToken): ValueToken[] {
+  if (!(argument instanceof Value)) {
+    return [argument];
+  }
+
+  return [
+    ...argument.initial.postfix.filter((token) => TypeGuards.isValueToken(token)),
+    ...argument.filters.flatMap((filter) => filter.args.flatMap((arg) => toArgTokens(arg))),
+  ];
+}
+
+function toArgTokens(arg: Filter['args'][number]): ValueToken[] {
+  if (!Array.isArray(arg)) {
+    return [arg];
+  }
+
+  return arg[1] ? [arg[1]] : [];
+}
+
+function collectNestedTokens(token: ValueToken): ValueToken[] {
+  const children: ValueToken[] = [];
+
+  if (TypeGuards.isRangeToken(token)) {
+    children.push(token.lhs, token.rhs);
+  } else if (TypeGuards.isFilteredValueToken(token)) {
+    children.push(
+      ...token.initial.postfix.filter((item) => TypeGuards.isValueToken(item)),
+      ...token.filters.flatMap((filter) => filter.args.flatMap((arg) => toArgTokens(arg))),
+    );
+  } else if (TypeGuards.isPropertyAccessToken(token)) {
+    children.push(...token.props.filter((prop) => TypeGuards.isPropertyAccessToken(prop)));
+  }
+
+  return [token, ...children.flatMap((child) => collectNestedTokens(child))];
+}
+
+function isNameFromValue(token: ValueToken): boolean {
+  return (
+    TypeGuards.isPropertyAccessToken(token) && TypeGuards.isPropertyAccessToken(token.props[0])
+  );
+}
+
+function formatNames(names: readonly string[]): string {
+  return names.map((name) => `"${name}"`).join(', ');
+}
+
+function isBareName(collection: ForTag['collection']): boolean {
+  return (
+    TypeGuards.isPropertyAccessToken(collection) &&
+    collection.variable === undefined &&
+    collection.props.length === 1 &&
+    TypeGuards.isWordToken(collection.props[0])
+  );
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { promptPlaceholders } from './constants.ts';
+export { findPromptTemplateFault } from './find-prompt-template-fault.ts';
+export { renderPromptTemplate } from './render-prompt-template.ts';
+export type { PromptPlaceholder, PromptValues } from './types.ts';

package/src/prompt-engine.ts

@@ -0,0 +1,23 @@
+import { Liquid } from 'liquidjs';
+import { promptFilters, promptTags } from './constants.ts';
+
+// An empty `templates` map keeps Liquid off the file system. `jsTruthy` makes the empty string
+// false, as Liquid's own truthiness counts only nil and false as false. No `outputEscape`: a
+// prompt is plain text, so a value reaches the agent as written.
+export const promptEngine = new Liquid({
+  templates: {},
+  jsTruthy: true,
+  strictVariables: true,
+  strictFilters: true,
+});
+
+const tags: ReadonlySet<string> = new Set(promptTags);
+const filters: ReadonlySet<string> = new Set(promptFilters);
+
+for (const tag of Object.keys(promptEngine.tags).filter((name) => !tags.has(name))) {
+  Reflect.deleteProperty(promptEngine.tags, tag);
+}
+
+for (const filter of Object.keys(promptEngine.filters).filter((name) => !filters.has(name))) {
+  Reflect.deleteProperty(promptEngine.filters, filter);
+}

package/src/render-prompt-template.ts

@@ -0,0 +1,13 @@
+import invariant from 'tiny-invariant';
+import { promptEngine } from './prompt-engine.ts';
+import type { PromptValues } from './types.ts';
+
+// Liquid writes each value as text and never parses it again, so a value that holds `{{ }}` or
+// `{% %}` reaches the agent as written.
+export function renderPromptTemplate(template: string, values: PromptValues): string {
+  const rendered: unknown = promptEngine.parseAndRenderSync(template, values);
+
+  invariant(typeof rendered === 'string', 'a Liquid render returns text');
+
+  return rendered;
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+import type { promptPlaceholders } from './constants.ts';
+
+export type PromptPlaceholder = (typeof promptPlaceholders)[number];
+
+// Each value is plain text. An empty section is the empty string, which `{% if %}` reads as false.
+export type PromptValues = Readonly<Record<PromptPlaceholder, string>>;