@mistralys/persona-builder 2.3.0 → 2.4.1

package/README.md

@@ -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
@@ -71,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:

package/dist/cli.cjs

@@ -131,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;
@@ -140,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) {
@@ -367,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
@@ -422,18 +451,49 @@ function buildContext(personaMeta, sharedMeta, agentMap = {}, target, registry)
   }
   return merged;
 }
+function validateSubagentRefs(persona, agentMap) {
+  const subagents = persona.subagents;
+  if (!Array.isArray(subagents) || subagents.length === 0) return [];
+  const results = [];
+  for (const slug of subagents) {
+    const key = `agent_slug_${slug.replace(/-/g, "_")}`;
+    if (!(key in agentMap)) {
+      results.push({
+        severity: "error",
+        message: `Persona '${persona.name}' declares subagent '${slug}' but no persona with that slug exists in any configured suite.`
+      });
+    }
+  }
+  return results;
+}
 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);
@@ -444,7 +504,10 @@ async function buildPersona(personaYamlPath, suiteName, suiteConfig, sharedMeta,
 ${body}
 `);
   output = runPostRender(plugins, output, personaMetaTyped, target);
-  const validationResults = runValidate(plugins, personaMetaTyped, suiteConfig, target);
+  const validationResults = [
+    ...runValidate(plugins, personaMetaTyped, suiteConfig, target),
+    ...validateSubagentRefs(personaMetaTyped, agentMap)
+  ];
   const def = registry.has(target) ? registry.get(target) : void 0;
   const outputDir = resolveOutputDir(target, suiteConfig, def);
   const fnKey = def?.filenameContextKey;
@@ -471,7 +534,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) };
   }
@@ -481,6 +544,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) {