@mistralys/persona-builder 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # AI Persona Builder
 
-Build AI persona instruction files for **VS Code Chat** and **Claude Code** from YAML metadata and Markdown templates — with zero configuration friction.
+Build AI persona instruction files for **VS Code Chat**, **Claude Code** and **LangGraph Deep Agents** from YAML metadata and Markdown templates — with zero configuration friction.
 
 Define your personas once as simple YAML + Markdown sources, and the library generates correctly formatted instruction files for both IDEs. A plugin system lets you inject custom frontmatter, run validators, or post-process output without touching the core engine.
 
@@ -10,6 +10,8 @@ Define your personas once as simple YAML + Markdown sources, and the library gen
 - **Extensible target registry** — register custom targets via `TargetRegistry` without touching core code; each target declares its own output key, frontmatter template, and context flags
 - **YAML + Markdown templating** — separate metadata from content; merge them at build time with `{{variables}}`, `{{> partials}}`, and `{{#if}}` conditionals
 - **Shared + per-suite partials** — reuse content fragments across personas with local overrides
+- **Custom variables** — inject global or per-suite template variables via `BuildConfig.variables` and `SuiteConfig.variables` without touching persona YAML files
+- **Dynamic partials** — supply inline partials via `BuildConfig.partials`, or override them at suite or per-persona level through the `onPartials` and `onPersonaPartials` plugin hooks
 - **Plugin architecture** — hook into context building, post-rendering, validation, and frontmatter generation
 - **CI-friendly** — `--check` mode renders without writing; `--strict` exits non-zero on warnings
 - **Programmatic & CLI** — use the `build()` API in scripts or run `persona-build` from the command line
@@ -25,6 +27,9 @@ Define your personas once as simple YAML + Markdown sources, and the library gen
 npm install @mistralys/persona-builder
 ```
 
+- View on NPM: https://www.npmjs.com/package/@mistralys/persona-builder
+- View on Github: https://github.com/Mistralys/ai-persona-builder
+
 ### Programmatic API
 
 ```ts
@@ -68,6 +73,7 @@ See the [CLI docs](docs/cli.md) for config file format and all flags.
 | [Getting Started](docs/getting-started.md) | Step-by-step tutorial — build your first persona from scratch |
 | [Directory Convention](docs/directory-convention.md) | Expected source layout (`meta/`, `content/`, `partials/`) |
 | [Template Syntax](docs/template-syntax.md) | Variables, partials, conditionals, and built-in context variables |
+| [Custom Variables & Dynamic Partials](docs/dynamic-partials.md) | Inject build-time variables and partial content at global, suite, or per-persona level |
 | [Plugins](docs/plugins.md) | `PersonaBuildPlugin` interface and examples |
 
 **Reference** — look-up material:
@@ -100,7 +106,7 @@ MIT
 
 ## Release Workflow
 
-1. Add changelog entries
+1. Add changelog entries (do not change package.json version)
 2. `npm version 0.0.0` - Updates package and lock versions + commit
 3. `npm publish` - Publish version on NPM
 4. `git push origin 0.0.0` - Add the tag in GIT

package/dist/cli.cjs

@@ -27,10 +27,30 @@ function resolvePartials(text, partialsMap, depth = 0) {
 }
 
 // src/engine/conditionals.ts
+var NO_NESTED_IF = String.raw`(?:(?!\{\{#if\b)[\s\S])*?`;
+var ELSE_IF_PATTERN = new RegExp(
+  String.raw`\{\{else if (\w+)\}\}(${NO_NESTED_IF})\{\{\/if\}\}`,
+  "g"
+);
+function resolveElseIf(text) {
+  if (!text.includes("{{else if ")) {
+    return text;
+  }
+  let result = text;
+  let prev;
+  do {
+    prev = result;
+    result = result.replace(
+      ELSE_IF_PATTERN,
+      (_match, flag, content) => `{{else}}{{#if ${flag}}}${content}{{/if}}{{/if}}`
+    );
+  } while (result !== prev);
+  return result;
+}
 function resolveConditionals(text, context) {
-  const noNestedIf = String.raw`(?:(?!\{\{#if\b)[\s\S])*?`;
+  const normalized = resolveElseIf(text);
   const pattern = new RegExp(
-    String.raw`\n*\{\{#if (\w+)\}\}(${noNestedIf})` + String.raw`(?:\{\{else\}\}(${noNestedIf}))?\{\{\/if\}\}\n*`,
+    String.raw`\n*\{\{#if (\w+)\}\}(${NO_NESTED_IF})` + String.raw`(?:\{\{else\}\}(${NO_NESTED_IF}))?\{\{\/if\}\}\n*`,
     "g"
   );
   const resolve = (_match, flag, inner, elseInner) => {
@@ -42,7 +62,7 @@ function resolveConditionals(text, context) {
     }
     return "\n";
   };
-  let result = text;
+  let result = normalized;
   let prev;
   do {
     prev = result;
@@ -111,7 +131,7 @@ function runBuildContext(plugins, ctx, persona, suite, target) {
   let accumulated = ctx;
   for (const plugin of plugins) {
     if (typeof plugin.onBuildContext === "function") {
-      accumulated = plugin.onBuildContext(accumulated, persona, suite, target);
+      accumulated = plugin.onBuildContext(accumulated, persona, suite, target) ?? accumulated;
     }
   }
   return accumulated;
@@ -120,11 +140,29 @@ function runPostRender(plugins, rendered, persona, target) {
   let output = rendered;
   for (const plugin of plugins) {
     if (typeof plugin.onPostRender === "function") {
-      output = plugin.onPostRender(output, persona, target);
+      output = plugin.onPostRender(output, persona, target) ?? output;
     }
   }
   return output;
 }
+function runPartials(plugins, partialsMap, suiteName, suite) {
+  let accumulated = partialsMap;
+  for (const plugin of plugins) {
+    if (typeof plugin.onPartials === "function") {
+      accumulated = plugin.onPartials(accumulated, suiteName, suite) ?? accumulated;
+    }
+  }
+  return accumulated;
+}
+function runPersonaPartials(plugins, partialsMap, persona, context, suite, target) {
+  let accumulated = partialsMap;
+  for (const plugin of plugins) {
+    if (typeof plugin.onPersonaPartials === "function") {
+      accumulated = plugin.onPersonaPartials(accumulated, persona, context, suite, target) ?? accumulated;
+    }
+  }
+  return accumulated;
+}
 function runValidate(plugins, persona, suite, target) {
   const results = [];
   for (const plugin of plugins) {
@@ -347,9 +385,20 @@ async function buildAgentNameMap(config) {
   }
   return agentMap;
 }
-function buildContext(personaMeta, sharedMeta, agentMap = {}, target, registry) {
+function buildContext(options) {
+  const {
+    personaMeta,
+    sharedMeta,
+    agentMap = {},
+    target,
+    registry,
+    configVariables,
+    suiteVariables
+  } = options;
   const version = typeof personaMeta["version"] === "string" ? personaMeta["version"] : typeof sharedMeta["default_version"] === "string" ? sharedMeta["default_version"] : "0.0.0";
   const merged = {
+    ...configVariables ?? {},
+    ...suiteVariables ?? {},
     ...sharedMeta,
     ...personaMeta,
     version
@@ -404,16 +453,32 @@ function buildContext(personaMeta, sharedMeta, agentMap = {}, target, registry)
 }
 async function buildPersona(personaYamlPath, suiteName, suiteConfig, sharedMeta, partialsMap, config, plugins, target, agentMap = {}, registry = defaultRegistry) {
   const personaMeta = await loadPersonaYaml(personaYamlPath);
-  let context = buildContext(personaMeta, sharedMeta, agentMap, target, registry);
+  let context = buildContext({
+    personaMeta,
+    sharedMeta,
+    agentMap,
+    target,
+    registry,
+    configVariables: config.variables,
+    suiteVariables: suiteConfig.variables
+  });
   const personaMetaTyped = personaMeta;
   context = runBuildContext(plugins, context, personaMetaTyped, suiteConfig, target);
+  const personaPartialsMap = runPersonaPartials(
+    plugins,
+    { ...partialsMap },
+    personaMetaTyped,
+    context,
+    suiteConfig,
+    target
+  );
   const fmTemplate = resolveFrontmatterTemplate(target, plugins, config.frontmatter, registry);
   const contentBasename = path2__default.default.basename(personaYamlPath, ".yaml") + ".md";
   const frontmatter = renderFrontmatter(fmTemplate, context, contentBasename);
   const contentSubdir = suiteConfig.contentSubdir ?? "content";
   const contentPath = path2__default.default.join(suiteConfig.srcDir, contentSubdir, contentBasename);
   const bodyTemplate = normalizeNewlines(await promises.readFile(contentPath, "utf8"));
-  let body = resolvePartials(bodyTemplate, partialsMap);
+  let body = resolvePartials(bodyTemplate, personaPartialsMap);
   body = resolveConditionals(body, context);
   body = resolveVariables(body, context, contentBasename);
   body = collapseBlankLines(body);
@@ -451,7 +516,7 @@ async function buildSuite(suiteName, suiteConfig, config, plugins, target, agent
   const metaSubdir = suiteConfig.metaSubdir ?? "meta";
   const sharedYamlPath = path2__default.default.join(suiteConfig.srcDir, metaSubdir, "_shared.yaml");
   const sharedMeta = await loadRawYaml(sharedYamlPath);
-  let partialsMap = {};
+  let partialsMap = { ...config.partials ?? {} };
   if (config.sharedPartialsDir && fs.existsSync(config.sharedPartialsDir)) {
     partialsMap = { ...partialsMap, ...await loadPartials(config.sharedPartialsDir) };
   }
@@ -461,6 +526,7 @@ async function buildSuite(suiteName, suiteConfig, config, plugins, target, agent
     partialsMap = { ...partialsMap, ...await loadPartials(suitePartialsDir) };
   }
   runSuiteInit(plugins, suiteConfig, sharedMeta);
+  partialsMap = runPartials(plugins, partialsMap, suiteName, suiteConfig);
   const personaYamlPaths = await discoverSuitePersonaYamls(suiteConfig);
   const results = [];
   for (const yamlPath of personaYamlPaths) {