@markbrutx/promptbook-core 0.1.0

package/dist/resolve-book.js

@@ -0,0 +1,195 @@
+import { interpolate } from "./interpolate.js";
+/**
+ * Pure resolver over an already-loaded {@link PromptBook}. No filesystem, no
+ * YAML, no Node builtins — the entire dependency footprint is {@link interpolate}
+ * and type-only imports. This is the determinism boundary: given the same book
+ * and context, the returned `text` is byte-for-byte stable, and the module
+ * bundles to a self-contained artifact for edge runtimes (see `edge.ts`).
+ *
+ * Conflict strategy: rules apply in declaration order, later wins (cascade).
+ * `forbid` is the one exception — it is applied as a final filter and always
+ * wins, so a forbidden id never reaches the output even if added earlier.
+ */
+export function resolveBook(book, prompt, context) {
+    const composition = book.compositions.get(prompt);
+    if (!composition) {
+        const available = [...book.compositions.keys()].sort().join(", ") || "(none)";
+        throw new Error(`Unknown prompt "${prompt}". Available compositions: ${available}.`);
+    }
+    const warnings = [...book.warnings];
+    const ruleTraces = [];
+    const replaced = [];
+    const added = [];
+    const forbidden = [];
+    const forbiddenIds = new Set();
+    const working = [...composition.base];
+    let orderOverride = composition.order ? [...composition.order] : undefined;
+    for (const rule of composition.rules) {
+        const match = matchWhen(rule.when, context);
+        const trace = {
+            index: rule.index,
+            action: rule.action,
+            when: rule.when,
+            fired: match.fired,
+        };
+        if (!match.fired) {
+            trace.reason = match.reason;
+            ruleTraces.push(trace);
+            continue;
+        }
+        switch (rule.action) {
+            case "replace": {
+                const effects = [];
+                for (const [from, to] of Object.entries(rule.replace ?? {})) {
+                    const at = working.indexOf(from);
+                    if (at === -1) {
+                        warnings.push(`Rule #${rule.index} cannot replace "${from}": it is not present in "${prompt}".`);
+                        continue;
+                    }
+                    working[at] = to;
+                    replaced.push({ from, to, ruleIndex: rule.index });
+                    effects.push(`${from} -> ${to}`);
+                }
+                trace.effect = `replace ${effects.join(", ")}`;
+                break;
+            }
+            case "add": {
+                const ids = rule.add ?? [];
+                const after = rule.after;
+                const at = insertionPoint(working, after, rule.index, prompt, warnings);
+                working.splice(at, 0, ...ids);
+                for (const id of ids) {
+                    added.push(after !== undefined ? { id, after, ruleIndex: rule.index } : { id, ruleIndex: rule.index });
+                }
+                trace.effect = `add ${ids.join(", ")}${after !== undefined ? ` after ${after}` : ""}`;
+                break;
+            }
+            case "forbid": {
+                const ids = rule.forbid ?? [];
+                for (const id of ids) {
+                    forbiddenIds.add(id);
+                    forbidden.push({ id, ruleIndex: rule.index });
+                }
+                trace.effect = `forbid ${ids.join(", ")}`;
+                break;
+            }
+            case "order": {
+                orderOverride = [...(rule.order ?? [])];
+                trace.effect = `order ${orderOverride.join(", ")}`;
+                break;
+            }
+        }
+        ruleTraces.push(trace);
+    }
+    const ordered = applyOrder(working, orderOverride);
+    const selected = ordered.filter((id) => !forbiddenIds.has(id));
+    const parts = [];
+    const finalOrder = [];
+    for (const id of selected) {
+        const fragment = book.fragments.get(id);
+        if (!fragment) {
+            warnings.push(`Fragment "${id}" referenced by "${prompt}" was not found.`);
+            continue;
+        }
+        parts.push(interpolate(fragment.body, context, (key) => {
+            warnings.push(`Missing variable "${key}" while rendering fragment "${id}".`);
+        }));
+        finalOrder.push(id);
+    }
+    const trace = {
+        prompt,
+        context,
+        rules: ruleTraces,
+        finalOrder,
+        replaced,
+        added,
+        forbidden,
+        unmatchedAxes: computeUnmatchedAxes(composition, context),
+        warnings,
+    };
+    return { text: parts.join("\n\n"), trace };
+}
+function matchWhen(when, context) {
+    for (const [key, expected] of Object.entries(when)) {
+        const actual = context[key];
+        if (actual === undefined) {
+            return { fired: false, reason: `context.${key} is unset, rule expects "${expected}"` };
+        }
+        if (!valuesEqual(expected, actual)) {
+            return { fired: false, reason: `context.${key}="${actual}" does not equal expected "${expected}"` };
+        }
+    }
+    return { fired: true };
+}
+export function valuesEqual(a, b) {
+    return String(a) === String(b);
+}
+/**
+ * Decide where an `add` inserts. With `after`, just past that id; without it,
+ * before the last fragment (so trailing format/footer fragments stay last).
+ */
+function insertionPoint(working, after, ruleIndex, prompt, warnings) {
+    if (after === undefined) {
+        return Math.max(working.length - 1, 0);
+    }
+    const at = working.indexOf(after);
+    if (at === -1) {
+        warnings.push(`Rule #${ruleIndex} add anchor "${after}" not found in "${prompt}"; appending at end.`);
+        return working.length;
+    }
+    return at + 1;
+}
+/**
+ * Produce the final id sequence. With an `order` override, listed ids come
+ * first (those that are present), then any remaining working ids in their
+ * existing order. Without an override, the working order is used as-is.
+ * Duplicates are collapsed to their first occurrence.
+ */
+function applyOrder(working, orderOverride) {
+    const seen = new Set();
+    const result = [];
+    const push = (id) => {
+        if (!seen.has(id)) {
+            seen.add(id);
+            result.push(id);
+        }
+    };
+    if (orderOverride) {
+        const present = new Set(working);
+        for (const id of orderOverride) {
+            if (present.has(id)) {
+                push(id);
+            }
+        }
+    }
+    for (const id of working) {
+        push(id);
+    }
+    return result;
+}
+/**
+ * Find context axes that some rule referenced but matched none. This surfaces
+ * holes like `industry=zoo` where industry rules exist but none cover "zoo".
+ */
+function computeUnmatchedAxes(composition, context) {
+    const result = [];
+    for (const key of Object.keys(context)) {
+        let referenced = false;
+        let matched = false;
+        for (const rule of composition.rules) {
+            if (Object.hasOwn(rule.when, key)) {
+                referenced = true;
+                const expected = rule.when[key];
+                if (expected !== undefined && valuesEqual(expected, context[key])) {
+                    matched = true;
+                    break;
+                }
+            }
+        }
+        if (referenced && !matched) {
+            result.push({ key, value: context[key] });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=resolve-book.js.map

package/dist/resolve-book.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-book.js","sourceRoot":"","sources":["../src/resolve-book.ts"],"names":[],"mappings":"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"}

package/dist/resolve.d.ts

@@ -0,0 +1,13 @@
+import type { ResolveInput, ResolveResult } from "./types.js";
+/**
+ * Assemble a prompt for a context and return the text plus an explain trace.
+ *
+ * Loads the prompts folder (the one IO step), then delegates to the pure
+ * {@link resolveBook}. Given the same folder contents and input, the returned
+ * `text` is byte-for-byte stable.
+ *
+ * Each call re-reads the folder. For many resolves against the same folder,
+ * call {@link loadPrompts} once and reuse {@link resolveBook}.
+ */
+export declare function resolve(input: ResolveInput): Promise<ResolveResult>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAGzE"}

package/dist/resolve.js

@@ -0,0 +1,17 @@
+import { loadPrompts } from "./load.js";
+import { resolveBook } from "./resolve-book.js";
+/**
+ * Assemble a prompt for a context and return the text plus an explain trace.
+ *
+ * Loads the prompts folder (the one IO step), then delegates to the pure
+ * {@link resolveBook}. Given the same folder contents and input, the returned
+ * `text` is byte-for-byte stable.
+ *
+ * Each call re-reads the folder. For many resolves against the same folder,
+ * call {@link loadPrompts} once and reuse {@link resolveBook}.
+ */
+export async function resolve(input) {
+    const book = await loadPrompts(input.promptsDir, input.fs);
+    return resolveBook(book, input.prompt, input.context ?? {});
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAmB;IAC/C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3D,OAAO,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Public data model for the promptbook core.
+ *
+ * The core is domain-agnostic: it only selects, orders and interpolates
+ * fragments. Any computed value (digests, scores, sorted lists) must be
+ * supplied by the caller through {@link Context}.
+ */
+/** A scalar context value. The core never stores domain objects. */
+export type ContextValue = string | number | boolean;
+/** A flat bag of facts the caller knows at resolve time. */
+export type Context = Record<string, ContextValue>;
+/** A reusable micro-prompt (the WHAT). */
+export interface Fragment {
+    /** Unique id within a prompts folder. */
+    id: string;
+    /** Optional classification, e.g. "directive" or "format". */
+    kind?: string;
+    /** Optional free-form tags. */
+    tags?: string[];
+    /** Body text; may contain `${path}` placeholders. */
+    body: string;
+    /** Absolute/relative path the fragment was loaded from. */
+    sourceFile: string;
+}
+/** Equality conditions on context. An empty object always matches. */
+export type When = Record<string, ContextValue>;
+/** The single action a rule performs. */
+export type RuleAction = "add" | "replace" | "forbid" | "order";
+/**
+ * A declarative selection rule (the WHEN). Exactly one action field is set,
+ * matching {@link RuleAction}.
+ */
+export interface Rule {
+    /** Position in the composition's `rules` list; drives the cascade. */
+    index: number;
+    /** Match conditions. Empty = always fires. */
+    when: When;
+    /** Which action this rule performs. */
+    action: RuleAction;
+    /** ids to insert (action "add"). */
+    add?: string[];
+    /** Optional anchor: insert added ids after this id. */
+    after?: string;
+    /** Map of old id to new id (action "replace"). */
+    replace?: Record<string, string>;
+    /** ids to remove from the result (action "forbid"). */
+    forbid?: string[];
+    /** Explicit final order of ids (action "order"). */
+    order?: string[];
+}
+/** A full system prompt assembled from fragments under one context. */
+export interface Composition {
+    /** Lookup name, e.g. "assistant". */
+    name: string;
+    /** Ordered base list of fragment ids. */
+    base: string[];
+    /** Optional explicit order override declared on the composition. */
+    order?: string[];
+    /** Ordered selection rules. */
+    rules: Rule[];
+    /** File the composition was loaded from. */
+    sourceFile: string;
+}
+/**
+ * A captured snapshot of a builder-backed prompt's output. The core never
+ * runs the builder; it only stores the frozen text so the registry can show it.
+ */
+export interface CodePromptSample {
+    /** Label identifying the sample, e.g. a scenario name. */
+    label: string;
+    /** Optional context the sample was captured under. */
+    context?: Context;
+    /** The captured builder output, stored verbatim. */
+    output: string;
+}
+/**
+ * A builder-backed prompt registered in the book (the HOW lives in code, not in
+ * rules). The core holds metadata plus captured {@link CodePromptSample}s and
+ * **never executes the builder** — it stays dumb and deterministic. This lets a
+ * book index every prompt of a domain, computed ones included, as one menu.
+ */
+export interface CodePrompt {
+    /** Lookup name, e.g. "digest-table". */
+    name: string;
+    /** Optional human description. */
+    description?: string;
+    /** Captured output samples (snapshots, not live executions). */
+    samples: CodePromptSample[];
+    /** Manifest file the code-prompt was loaded from. */
+    sourceFile: string;
+}
+/** A loaded prompts folder: fragments + compositions + code-prompts + load-time warnings. */
+export interface PromptBook {
+    fragments: Map<string, Fragment>;
+    compositions: Map<string, Composition>;
+    /** Builder-backed prompts registered with snapshot output (never executed). */
+    codePrompts: Map<string, CodePrompt>;
+    warnings: string[];
+}
+/** Per-rule entry in the explain trace. */
+export interface RuleTrace {
+    index: number;
+    action: RuleAction;
+    when: When;
+    /** Whether the rule's `when` matched the context. */
+    fired: boolean;
+    /** When `fired` is false, why (which key failed). */
+    reason?: string;
+    /** When `fired` is true, a human-readable summary of the effect. */
+    effect?: string;
+}
+export interface ReplaceTrace {
+    from: string;
+    to: string;
+    ruleIndex: number;
+}
+export interface AddTrace {
+    id: string;
+    after?: string;
+    ruleIndex: number;
+}
+export interface ForbidTrace {
+    id: string;
+    ruleIndex: number;
+}
+/** A context axis that rules referenced but none matched its value. */
+export interface UnmatchedAxis {
+    key: string;
+    value: ContextValue;
+}
+/** The explain trace: everything needed to see why the prompt looks as it does. */
+export interface Trace {
+    /** Composition name that was resolved. */
+    prompt: string;
+    /** Context the resolution ran against. */
+    context: Context;
+    /** Every rule, in declaration order, with fired/why. */
+    rules: RuleTrace[];
+    /** Final fragment ids in join order (only fragments that rendered). */
+    finalOrder: string[];
+    /** Replacements applied. */
+    replaced: ReplaceTrace[];
+    /** Additions applied. */
+    added: AddTrace[];
+    /** Forbids applied. */
+    forbidden: ForbidTrace[];
+    /** Axes present in context that no rule matched (e.g. unknown industry). */
+    unmatchedAxes: UnmatchedAxis[];
+    /** Missing variables, missing fragment refs, and other non-fatal issues. */
+    warnings: string[];
+}
+/** The result of {@link resolve}. */
+export interface ResolveResult {
+    text: string;
+    trace: Trace;
+}
+/** Injectable filesystem so the core stays runtime-agnostic (Node/Deno/Bun). */
+export interface FsAdapter {
+    readFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+}
+/** Input to {@link resolve}. */
+export interface ResolveInput {
+    /** Folder containing `fragments/` and `rules/`. */
+    promptsDir: string;
+    /** Composition name to assemble. */
+    prompt: string;
+    /** Facts to match rules against and interpolate into bodies. */
+    context?: Context;
+    /** Optional filesystem adapter; defaults to a lazy Node adapter. */
+    fs?: FsAdapter;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Public data model for the promptbook core.
+ *
+ * The core is domain-agnostic: it only selects, orders and interpolates
+ * fragments. Any computed value (digests, scores, sorted lists) must be
+ * supplied by the caller through {@link Context}.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@markbrutx/promptbook-core",
+  "version": "0.1.0",
+  "description": "Agnostic, deterministic core for composing prompts from reusable fragments via declarative rules.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./edge": {
+      "types": "./dist/edge.d.ts",
+      "import": "./dist/edge/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && npm run build:edge",
+    "build:edge": "node scripts/build-edge.mjs",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "vitest --run",
+    "check": "biome check ."
+  },
+  "dependencies": {
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/node": "^20.14.0",
+    "esbuild": "^0.21.5",
+    "@typescript/native-preview": "latest",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.6"
+  }
+}

package/src/annotations.ts

@@ -0,0 +1,100 @@
+/**
+ * The viewer→agent feedback queue: the annotation data shape plus the JSONL
+ * (de)serialization both ends share. The on-disk file is the cross-process
+ * contract — the viewer writes it, an agent's CLI reads and clears it — so the
+ * schema lives in one place. These helpers are pure and deterministic; the
+ * non-deterministic parts (id/timestamp generation, disk IO) live in the
+ * writer, not here.
+ */
+import type { Context } from "./types.js";
+
+/** Queue directory, relative to the prompts folder — the cross-process contract. */
+export const ANNOTATION_QUEUE_DIR = ".annotations";
+/** Queue file inside {@link ANNOTATION_QUEUE_DIR}, one annotation per line. */
+export const ANNOTATION_QUEUE_FILE = "inbox.jsonl";
+
+/** An annotation is open until an agent resolves it. */
+export type AnnotationStatus = "open" | "resolved";
+
+/** What an annotation points at: a composition variant or a standalone fragment. */
+export interface AnnotationTarget {
+  /** Composition the annotated variant was assembled from. */
+  prompt?: string;
+  /** Context the variant was resolved under (present alongside `prompt`). */
+  context?: Context;
+  /** A fragment id, when annotating a fragment directly rather than a variant. */
+  fragmentId?: string;
+  /** Source file of the fragment/composition, to help the agent locate it. */
+  sourceFile?: string;
+}
+
+/** Where, inside the source text, the comment is anchored. */
+export interface AnnotationAnchor {
+  /** Fragment whose body carries the selected text. */
+  fragmentId: string;
+  /** The exact text the user selected. */
+  anchorText: string;
+  /** Optional character offset within the fragment body, for disambiguation. */
+  offset?: number;
+}
+
+/** One queued piece of human feedback, waiting for an agent to act on it. */
+export interface Annotation {
+  id: string;
+  /** ISO-8601 creation time. */
+  createdAt: string;
+  target: AnnotationTarget;
+  anchor: AnnotationAnchor;
+  comment: string;
+  status: AnnotationStatus;
+}
+
+/** True when `value` has the minimal required shape of an {@link Annotation}. */
+function isAnnotation(value: unknown): value is Annotation {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  const anchor = record.anchor as Record<string, unknown> | undefined;
+  return (
+    typeof record.id === "string" &&
+    typeof record.comment === "string" &&
+    typeof anchor === "object" &&
+    anchor !== null &&
+    typeof anchor.fragmentId === "string"
+  );
+}
+
+/**
+ * Parse the inbox JSONL: one annotation per non-empty line. Malformed lines are
+ * skipped rather than thrown — the queue must never crash on data, so a single
+ * bad line cannot block the rest.
+ */
+export function parseInbox(text: string): Annotation[] {
+  const annotations: Annotation[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      continue;
+    }
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (isAnnotation(parsed)) {
+        annotations.push(parsed);
+      }
+    } catch {
+      // skip a malformed line; the rest of the queue stays usable
+    }
+  }
+  return annotations;
+}
+
+/** Serialize one annotation as a single append-safe JSONL line (with newline). */
+export function serializeAnnotationLine(annotation: Annotation): string {
+  return `${JSON.stringify(annotation)}\n`;
+}
+
+/** Serialize a whole queue back to JSONL, used when removing/rewriting entries. */
+export function serializeInbox(annotations: Annotation[]): string {
+  return annotations.map(serializeAnnotationLine).join("");
+}